engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/contracts/projection.py

@@ -0,0 +1,401 @@
+"""Deterministic, read-only projections from canonical EP evidence.
+
+The module intentionally opens SQLite in read-only mode.  It does not invoke
+Git, GitHub, providers, lifecycle transitions, migrations, or action execution.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import re
+import sqlite3
+
+from .models import (
+    ActionPolicyDecision,
+    AllowedAction,
+    CONTRACT_VERSION,
+    ContractVersionError,
+    EvidenceReference,
+    require_compatible_version,
+)
+from ..storage import EngineeringStorageError, database_path
+
+
+UNAVAILABLE = "UNAVAILABLE"
+PROJECTION_AUTHORITY = "DERIVED_FROM_CANONICAL_EVIDENCE"
+POLICY_VERSION = "1.0"
+_SAFE_OBJECTIVE_KEYS = frozenset({"objective_summary", "scope_summary", "constraints", "acceptance_summary", "prohibited_changes_summary"})
+_UNSAFE_OBJECTIVE_TEXT = re.compile(
+    r"(?i)(?:\b(?:api[_ -]?key|access[_ -]?token|refresh[_ -]?token|secret|cookie|authorization|password)\b|\bbearer\b|(?:^|\s)/(?:\S+)|\b[a-z]:[\\/])"
+)
+_READ_ACTIONS = (
+    ("run.inspect.context", "run.inspect.*", "READ_CANONICAL_EVIDENCE"),
+    ("delivery.inspect.status", "delivery.inspect.*", "READ_DELIVERY_EVIDENCE"),
+    ("repository.inspect.state", "repository.inspect.*", "READ_REPOSITORY_EVIDENCE"),
+    ("workspace.inspect.state", "workspace.inspect.*", "READ_WORKSPACE_EVIDENCE"),
+)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _readonly_connection(root: Path) -> sqlite3.Connection:
+    path = database_path(root)
+    if not path.is_file():
+        raise EngineeringStorageError("Engineering storage is unavailable.")
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def _json_object(value: object) -> dict[str, object]:
+    try:
+        parsed = json.loads(value) if isinstance(value, str) else {}
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _value(value: object) -> object:
+    return value if value is not None else UNAVAILABLE
+
+
+def _safe_objective(metadata: object) -> dict[str, object]:
+    raw = _json_object(metadata)
+    result: dict[str, object] = {}
+    for key in _SAFE_OBJECTIVE_KEYS:
+        value = raw.get(key)
+        if isinstance(value, str) and value and len(value) <= 500 and "\n" not in value and not _UNSAFE_OBJECTIVE_TEXT.search(value):
+            result[key] = value
+        elif isinstance(value, list) and len(value) <= 12 and all(isinstance(item, str) and len(item) <= 160 and "\n" not in item and not _UNSAFE_OBJECTIVE_TEXT.search(item) for item in value):
+            result[key] = value
+        else:
+            result[key] = UNAVAILABLE
+    return result
+
+
+def _snapshot_id(payload: dict[str, object]) -> str:
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode()
+    return f"snapshot:sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def _reference(source_type: str, subject: str, observed_at: object, snapshot: str, code: str, freshness: str = "CURRENT") -> dict[str, object]:
+    identity = hashlib.sha256(f"{source_type}:{subject}:{snapshot}".encode()).hexdigest()[:24]
+    return EvidenceReference(
+        id=f"evidence:{identity}", source_type=source_type,
+        authority="CANONICAL_EP_EVIDENCE", observed_at=str(_value(observed_at)),
+        freshness=freshness, subject=subject, snapshot_identity=snapshot,
+        safe_summary_code=code,
+    ).to_dict()
+
+
+def _current_checks(connection: sqlite3.Connection, run_id: str) -> dict[str, dict[str, object]]:
+    try:
+        rows = connection.execute(
+            "SELECT id,pr_number,pr_role,pr_state,merge_state,merge_commit,required_checks_state,evidence_ref,observed_at,currentness "
+            "FROM managed_pr_check_observations WHERE run_id=? ORDER BY id", (run_id,)
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return {}
+    result: dict[str, dict[str, object]] = {}
+    for row in rows:
+        role = str(row[2])
+        candidate = {"pr_number": row[1], "pr_state": row[3], "merge_state": row[4], "merge_commit": row[5], "required_checks_state": row[6], "observed_at": row[8], "currentness": row[9]}
+        if role not in result or (int(row[9]), int(row[0])) >= (int(result[role]["currentness"]), -1):
+            result[role] = candidate
+    return result
+
+
+def _validation_controls(connection: sqlite3.Connection, run_id: str, snapshot: str) -> list[dict[str, object]]:
+    """Select only the newest canonical observation per validation control."""
+    try:
+        rows = connection.execute(
+            "SELECT id,control,state,required,currentness,observed_at FROM managed_validation_observations WHERE run_id=? ORDER BY id",
+            (run_id,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+    current: dict[str, sqlite3.Row] = {}
+    for row in rows:
+        control = str(row[1])
+        if control not in current or (int(row[4]), int(row[0])) >= (int(current[control][4]), int(current[control][0])):
+            current[control] = row
+    return [{"control_id": control, "display_category_code": control, "state": row[2],
+             "execution_source": "MANAGED_VALIDATION_OBSERVATION", "required": bool(row[3]),
+             "observed_at": row[5], "evidence_reference": _reference("VALIDATION", f"run:{run_id}:{control}", row[5], snapshot, "VALIDATION_CONTROL", "BOUNDARY_SENSITIVE")}
+            for control, row in sorted(current.items())]
+
+
+def _qualification_evidence(connection: sqlite3.Connection, run_id: str) -> tuple[dict[str, object] | None, dict[str, object] | None]:
+    """Read only explicit v33 qualification evidence; never infer legacy facts."""
+    try:
+        lineage = connection.execute(
+            "SELECT submission_id,fresh_submission,retry_parent_run_id,resume_parent_run_id,recorded_at "
+            "FROM execution_run_qualification_context WHERE run_id=?", (run_id,)
+        ).fetchone()
+        profile = connection.execute(
+            "SELECT selected_validation_tier,validation_profile_version,required_validation_controls,recorded_at "
+            "FROM execution_validation_profiles WHERE run_id=?", (run_id,)
+        ).fetchone()
+        controls = connection.execute(
+            "SELECT validation_id,category,required_for_profile,execution_status,result,observed_at,currentness "
+            "FROM execution_validation_control_results WHERE run_id=? ORDER BY id", (run_id,)
+        ).fetchall()
+        commands = connection.execute(
+            "SELECT inv.validation_id,inv.category,inv.required_for_profile,'EXECUTED',"
+            "COALESCE(term.result,'UNAVAILABLE'),COALESCE(term.completed_at,inv.started_at),inv.currentness "
+            "FROM execution_validation_command_invocations inv LEFT JOIN execution_validation_command_terminals term "
+            "ON term.run_id=inv.run_id AND term.command_id=inv.command_id WHERE inv.run_id=? ORDER BY inv.started_at",
+            (run_id,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return None, None
+    lineage_projection = None if lineage is None else {
+        "submission_id": lineage[0], "fresh_submission": bool(lineage[1]),
+        "retry_parent": lineage[2], "resume_parent": lineage[3], "recorded_at": lineage[4],
+    }
+    if profile is None:
+        return lineage_projection, None
+    try:
+        payload = json.loads(profile[2])
+        required = payload.get("validation_ids", [])
+    except (AttributeError, TypeError, json.JSONDecodeError):
+        return lineage_projection, None
+    if not isinstance(required, list) or not all(isinstance(item, str) for item in required):
+        return lineage_projection, None
+    current: dict[str, sqlite3.Row] = {}
+    conflicts: set[str] = set()
+    for row in (*controls, *commands):
+        validation_id = str(row[0])
+        existing = current.get(validation_id)
+        if existing is None or int(row[6]) > int(existing[6]):
+            current[validation_id] = row
+        elif int(row[6]) == int(existing[6]) and row[4] != existing[4]:
+            conflicts.add(validation_id)
+    def result_for(validation_id: str) -> object:
+        if validation_id in conflicts:
+            return "UNRESOLVED"
+        row = current.get(validation_id)
+        return row[4] if row is not None else None
+    results = [result_for(validation_id) for validation_id in required]
+    required_state = "FAIL" if any(result == "FAIL" for result in results) else (
+        "PASS" if results and all(result == "PASS" for result in results) else "UNRESOLVED"
+    )
+    return lineage_projection, {
+        "selected_validation_tier": profile[0], "validation_profile_version": profile[1],
+        "profile_reference": payload.get("profile_reference", UNAVAILABLE),
+        "profile_selection_source": payload.get("profile_selection_source", UNAVAILABLE),
+        "required_validation_controls": required, "required_validation_state": required_state,
+        "control_bindings": payload.get("control_bindings", UNAVAILABLE),
+        "recorded_at": profile[3],
+        "controls": [
+            {"validation_id": validation_id, "category": row[1], "required_for_profile": bool(row[2]),
+             "execution_status": row[3], "result": result_for(validation_id), "observed_at": row[5]}
+            for validation_id, row in sorted(current.items())
+        ],
+    }
+
+
+def _lease_projection(connection: sqlite3.Connection, run_id: str) -> dict[str, object]:
+    try:
+        rows = connection.execute(
+            "SELECT run_id,host_identity,lease_state,last_heartbeat_at FROM execution_run_leases WHERE lease_state='ACTIVE' ORDER BY updated_at DESC"
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return {"workspace_state": UNAVAILABLE, "workspace_occupied": UNAVAILABLE, "active_owner_run_id": UNAVAILABLE,
+                "lease_state": UNAVAILABLE, "lease_owner_identity": UNAVAILABLE, "conflict_present": UNAVAILABLE,
+                "recovery_required": UNAVAILABLE, "last_verified_at": UNAVAILABLE}
+    foreign = next((row for row in rows if row[0] != run_id), None)
+    own = next((row for row in rows if row[0] == run_id), None)
+    active = foreign or own
+    return {"workspace_state": "OCCUPIED" if foreign else ("OWNED" if own else "AVAILABLE"),
+            "workspace_occupied": bool(foreign), "active_owner_run_id": foreign[0] if foreign else UNAVAILABLE,
+            "lease_state": own[2] if own else (foreign[2] if foreign else UNAVAILABLE),
+            "lease_owner_identity": active[1] if active else UNAVAILABLE, "conflict_present": bool(foreign),
+            "recovery_required": False, "last_verified_at": active[3] if active else UNAVAILABLE}
+
+
+def _usage_projection_unavailable() -> tuple[dict[str, object], dict[str, object]]:
+    unavailable = {"provider": UNAVAILABLE, "model": UNAVAILABLE, "model_authority": UNAVAILABLE, "provider_invocation_count": UNAVAILABLE,
+                   "reviewer_invocation_count": UNAVAILABLE, "run_cumulative_input": UNAVAILABLE, "cached_input": UNAVAILABLE,
+                   "uncached_input": UNAVAILABLE, "output": UNAVAILABLE, "provider_execution_time": UNAVAILABLE,
+                   "tool_output": UNAVAILABLE, "git_output": UNAVAILABLE, "github_output": UNAVAILABLE, "estimated_credits": UNAVAILABLE,
+                   "estimated_eur": UNAVAILABLE, "speed_state": UNAVAILABLE, "authority": "UNAVAILABLE", "availability": "UNAVAILABLE"}
+    return unavailable, {"selection_policy_result": UNAVAILABLE, "selected_reviewer_count": UNAVAILABLE, "roles": [], "reviewers": [], "independence_state": UNAVAILABLE}
+
+
+def _usage_projection(connection: sqlite3.Connection, run_id: str) -> tuple[dict[str, object], dict[str, object]]:
+    try:
+        rows = connection.execute(
+            "SELECT provider,model,role,duration_ms,input_tokens,cached_input_tokens,uncached_input_tokens,output_tokens,usage_authority,speed_state,estimated_credits,estimated_eur,churn FROM provider_invocations WHERE run_id=? ORDER BY ordinal",
+            (run_id,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        rows = []
+    if not rows:
+        return _usage_projection_unavailable()
+    def total(index: int) -> int:
+        return sum(value for row in rows if isinstance((value := row[index]), int))
+    primary = rows[-1]
+    reviewers = [row for row in rows if str(row[2]).casefold() == "reviewer"]
+    churn = _json_object(primary[12])
+    usage = {"provider": primary[0] or UNAVAILABLE, "model": primary[1] or UNAVAILABLE, "model_authority": primary[8], "provider_invocation_count": len(rows),
+             "reviewer_invocation_count": len(reviewers), "run_cumulative_input": total(5) + total(6), "cached_input": total(5), "uncached_input": total(6),
+             "output": total(7), "provider_execution_time": total(3), "tool_output": churn.get("tool_output_bytes", UNAVAILABLE),
+             "git_output": churn.get("git_output_bytes", UNAVAILABLE), "github_output": churn.get("github_output_bytes", UNAVAILABLE),
+             "estimated_credits": primary[10] if primary[10] is not None else UNAVAILABLE, "estimated_eur": primary[11] if primary[11] is not None else UNAVAILABLE,
+             "speed_state": primary[9], "authority": primary[8], "availability": "AVAILABLE"}
+    reviewer_projection = {"selection_policy_result": "AVAILABLE", "selected_reviewer_count": len(reviewers), "roles": sorted({str(row[2]) for row in rows}),
+                           "reviewers": [{"role": row[2], "state": "COMPLETE" if row[3] is not None else "ACTIVE", "duration": row[3] if row[3] is not None else UNAVAILABLE, "conclusion": UNAVAILABLE} for row in reviewers],
+                           "independence_state": "UNAVAILABLE"}
+    return usage, reviewer_projection
+
+
+def _phase_workflow(phase: object, terminal: object) -> dict[str, object]:
+    current = str(_value(phase))
+    state = current if terminal is True else "RUNNING"
+    expected = {
+        "EXECUTE_AGENT": "LOCAL_REPOSITORY_VALIDATION", "LOCAL_REPOSITORY_VALIDATION": "QUALITY_CONTROL_AGENT", "QUALITY_CONTROL_AGENT": "WAIT_FOR_OPERATOR_MERGE",
+        "REPAIR_AGENT": "QUALITY_CONTROL_AGENT", "WAIT_FOR_OPERATOR_MERGE": "FINALIZE_AGENT",
+        "FINALIZE_AGENT": "WAIT_FOR_FINALIZATION_MERGE", "WAIT_FOR_FINALIZATION_MERGE": "RECONCILE_AGENT",
+        "RECONCILE_AGENT": "REPOSITORY_CLEANUP", "REPOSITORY_CLEANUP": "COMPLETE",
+    }.get(current, UNAVAILABLE)
+    waiting = "EXPECTED_OPERATOR_MERGE_GATE" if current in {"WAIT_FOR_OPERATOR_MERGE", "WAIT_FOR_FINALIZATION_MERGE"} else UNAVAILABLE
+    return {"current_phase": current, "current_state": state, "previous_completed_phase": UNAVAILABLE,
+            "next_expected_lifecycle_boundary": expected, "waiting_reason": waiting,
+            "blocking_reason": UNAVAILABLE, "last_activity_at": UNAVAILABLE,
+            "last_verified_at": UNAVAILABLE, "expected_current_authority": "EP_LIFECYCLE"}
+
+
+def get_run_context(root: Path, run_id: str) -> dict[str, object]:
+    """Return one serializable run projection or an unavailable safe projection."""
+    generated_at = _now()
+    try:
+        connection = _readonly_connection(root)
+        try:
+            transaction = connection.execute("SELECT payload,phase,updated_at FROM engineering_transactions WHERE run_id=?", (run_id,)).fetchone()
+            run = connection.execute("SELECT execution_mode,producer_id,producer_type,execution_started_at,execution_finished_at,execution_seconds FROM execution_runs WHERE run_id=?", (run_id,)).fetchone()
+            submission = connection.execute("SELECT s.submission_id,s.producer_id,s.producer_type,s.prompt_metadata,s.received_at FROM execution_submissions AS s JOIN execution_submission_links AS l ON l.submission_id=s.submission_id WHERE l.run_id=?", (run_id,)).fetchone()
+            qualification_lineage, qualification_validation = _qualification_evidence(connection, run_id)
+            try:
+                row = connection.execute(
+                    "SELECT payload FROM execution_run_qualification_snapshots WHERE run_id=?", (run_id,)
+                ).fetchone()
+                qualification_snapshot = _json_object(row[0]) if row else None
+            except sqlite3.OperationalError:
+                qualification_snapshot = None
+            checks = _current_checks(connection, run_id)
+            validation_controls = _validation_controls(connection, run_id, "pending")
+            workspace = _lease_projection(connection, run_id)
+            usage, reviewers = _usage_projection(connection, run_id)
+        finally:
+            connection.close()
+    except (EngineeringStorageError, sqlite3.Error):
+        transaction = run = submission = qualification_lineage = qualification_validation = qualification_snapshot = None
+        checks = {}
+        validation_controls = []
+        workspace = {"workspace_state": UNAVAILABLE, "workspace_occupied": UNAVAILABLE, "active_owner_run_id": UNAVAILABLE,
+                     "lease_state": UNAVAILABLE, "lease_owner_identity": UNAVAILABLE, "conflict_present": UNAVAILABLE,
+                     "recovery_required": UNAVAILABLE, "last_verified_at": UNAVAILABLE}
+        usage, reviewers = _usage_projection_unavailable()
+    checkpoint = _json_object(transaction[0]) if transaction else {}
+    phase = transaction[1] if transaction else UNAVAILABLE
+    observed_at = transaction[2] if transaction else UNAVAILABLE
+    snapshot = _snapshot_id({"run_id": run_id, "checkpoint": checkpoint, "phase": phase, "checks": checks,
+                             "validation": validation_controls, "workspace": workspace, "usage": usage, "reviewers": reviewers})
+    # References embed the finalized snapshot identity, never an intermediate value.
+    validation_controls = [dict(item, evidence_reference=_reference("VALIDATION", f"run:{run_id}:{item['control_id']}", item["observed_at"], snapshot, "VALIDATION_CONTROL", "BOUNDARY_SENSITIVE")) for item in validation_controls]
+    evidence = [_reference("CHECKPOINT", f"run:{run_id}", observed_at, snapshot, "RUN_CHECKPOINT", "BOUNDARY_SENSITIVE")]
+    if checks:
+        evidence.append(_reference("GITHUB", f"run:{run_id}:checks", max(str(item.get("observed_at", "")) for item in checks.values()), snapshot, "PR_CHECKS", "BOUNDARY_SENSITIVE"))
+    terminal = checkpoint.get("terminal")
+    qualification_source = qualification_snapshot if isinstance(qualification_snapshot, dict) else {}
+    action_intent = qualification_source.get("action_intent", checkpoint.get("action_intent"))
+    execution_mode = qualification_source.get("execution_mode", run[0] if run else checkpoint.get("execution_mode"))
+    snapshot_checks = qualification_source.get("pr_checks", {}) if qualification_source else {}
+    implementation = snapshot_checks.get("IMPLEMENTATION", {}) if qualification_source and isinstance(snapshot_checks, dict) else checks.get("IMPLEMENTATION", {})
+    finalization = snapshot_checks.get("FINALIZATION", {}) if qualification_source and isinstance(snapshot_checks, dict) else checks.get("FINALIZATION", {})
+    objective = _safe_objective(submission[3] if submission else {})
+    validation_only = action_intent == "VALIDATION_ONLY"
+    persisted_required_validation = qualification_source.get("validation_profile", UNAVAILABLE) if qualification_source else qualification_validation or UNAVAILABLE
+    lineage_source = qualification_source if qualification_source else qualification_lineage
+    context: dict[str, object] = {
+        "contract_name": "run_context", "contract_version": CONTRACT_VERSION, "generated_at": generated_at,
+        "run_id": run_id, "evidence_version": snapshot, "projection_authority": PROJECTION_AUTHORITY,
+        "run": {"execution_mode": _value(execution_mode), "terminal": _value(terminal),
+                "current_execution_state": _value(phase), "current_phase": _value(phase),
+                "fresh_submission_state": "AVAILABLE" if lineage_source else UNAVAILABLE,
+                "fresh_submission": lineage_source["fresh_submission"] if lineage_source else UNAVAILABLE,
+                "retry_parent": lineage_source["retry_parent"] if lineage_source else UNAVAILABLE,
+                "resume_parent": lineage_source["resume_parent"] if lineage_source else UNAVAILABLE,
+                "producer": {"id": _value(submission[1] if submission else (run[1] if run else None)), "type": _value(submission[2] if submission else (run[2] if run else None))},
+                "execution_host": UNAVAILABLE, "lease_state": UNAVAILABLE, "recovery_required": False,
+                "active_blocking_predecessor": UNAVAILABLE},
+        "objective": objective,
+        "workflow": _phase_workflow(phase, terminal),
+        "blocker": {"blocker_present": phase in {"BLOCKED", "FAILED"} or workspace["workspace_occupied"] is True,
+                    "blocker_type": "WORKSPACE_OCCUPIED" if workspace["workspace_occupied"] is True else ("TERMINAL_RUN" if phase in {"BLOCKED", "FAILED"} else UNAVAILABLE),
+                    "summary_code": "WORKSPACE_OCCUPIED" if workspace["workspace_occupied"] is True else ("RUN_TERMINAL" if phase in {"BLOCKED", "FAILED"} else UNAVAILABLE),
+                    "evidence_references": evidence, "blocking_run_id": workspace["active_owner_run_id"] if workspace["workspace_occupied"] is True else UNAVAILABLE, "blocking_pr": UNAVAILABLE,
+                    "detected_at": _value(observed_at), "verified_at": _value(observed_at), "recoverability": UNAVAILABLE},
+        "delivery": {"action_intent": _value(action_intent),
+                     "implementation_pr": "NOT_REQUIRED" if validation_only else _value(qualification_source.get("implementation_pr") if qualification_source else checkpoint.get("implementation_pull_request") or checkpoint.get("pull_request") or implementation.get("pr_number")),
+                     "implementation_pr_current_state": "NOT_REQUIRED" if validation_only else _value(implementation.get("pr_state")), "implementation_merge_state": _value(implementation.get("merge_state")),
+                     "implementation_merge_commit": _value(implementation.get("merge_commit") if qualification_source else checkpoint.get("implementation_merge_commit") or implementation.get("merge_commit")),
+                     "implementation_required_checks_state": _value(implementation.get("required_checks_state")), "implementation_merge_gate": "EXPECTED_OPERATOR_GATE" if phase == "WAIT_FOR_OPERATOR_MERGE" else UNAVAILABLE,
+                     "finalization_pr": "NOT_REQUIRED" if validation_only else _value(qualification_source.get("finalization_pr") if qualification_source else checkpoint.get("finalization_pull_request") or finalization.get("pr_number")), "finalization_pr_current_state": "NOT_REQUIRED" if validation_only else _value(finalization.get("pr_state")),
+                     "finalization_merge_state": _value(finalization.get("merge_state")), "finalization_merge_commit": _value(finalization.get("merge_commit") if qualification_source else checkpoint.get("finalization_merge_commit") or finalization.get("merge_commit")),
+                     "finalization_required_checks_state": _value(finalization.get("required_checks_state")), "finalization_merge_gate": "EXPECTED_OPERATOR_GATE" if phase == "WAIT_FOR_FINALIZATION_MERGE" else UNAVAILABLE,
+                     "implementation_delivery": _value(qualification_source.get("implementation_delivery")),
+                     "finalization_delivery": _value(qualification_source.get("finalization_delivery")),
+                     "run_delivery_commit": _value(checkpoint.get("implementation_head_sha") or checkpoint.get("last_verified_sha")), "current_repository_head": _value(checkpoint.get("last_verified_sha")), "delivery_commit_head_relationship": UNAVAILABLE},
+        "validation": {"engineering_platform_qualification": UNAVAILABLE, "controls": validation_controls,
+                       "required_validation": persisted_required_validation,
+                       "run_qualification": qualification_snapshot.get("run_qualification", UNAVAILABLE) if qualification_snapshot else UNAVAILABLE,
+                       "qualification_snapshot": qualification_snapshot or UNAVAILABLE},
+        "repository": {"repository_identity": _value(checkpoint.get("repository")), "expected_branch": "main", "current_branch": _value(checkpoint.get("branch")), "worktree_state": qualification_snapshot.get("reconciliation_evidence", {}).get("worktree_state", UNAVAILABLE) if qualification_snapshot else UNAVAILABLE, "main_origin_relationship": qualification_snapshot.get("reconciliation_evidence", {}).get("main_origin_sync", UNAVAILABLE) if qualification_snapshot else UNAVAILABLE, "repository_state": qualification_snapshot.get("reconciliation_evidence", {}).get("repository_state", UNAVAILABLE) if qualification_snapshot else UNAVAILABLE, "delivery_commit_relationship": UNAVAILABLE, "last_verified_at": _value(observed_at)},
+        "workspace": workspace,
+        "timing": {"run_wall_time": _value(run[5] if run else None), "provider_execution_time": _value(checkpoint.get("agent_execution_seconds")), "reviewer_time": UNAVAILABLE, "validation_time": UNAVAILABLE, "external_wait_time": UNAVAILABLE, "ci_wait_time": UNAVAILABLE, "merge_gate_wait_time": _value(checkpoint.get("waiting_for_merge_since")), "finalization_time": UNAVAILABLE, "reconciliation_time": UNAVAILABLE, "last_activity_at": _value(observed_at)},
+        "usage": usage,
+        "reviewers": reviewers,
+        "historical_report": {"availability": UNAVAILABLE}, "current_projection": {"availability": "AVAILABLE", "projection_generated_at": generated_at, "projection_authority": PROJECTION_AUTHORITY},
+        "authority": {"merge_authority": "OPERATOR", "projection_authority": PROJECTION_AUTHORITY}, "evidence": evidence,
+    }
+    context["allowed_actions"] = get_allowed_actions(root, run_id, context=context)
+    return context
+
+
+def get_allowed_actions(root: Path, run_id: str, *, context: dict[str, object] | None = None) -> list[dict[str, object]]:
+    """Return only current EP policy descriptors; no mutating action is invented."""
+    context = context or get_run_context(root, run_id)
+    evidence_version = str(context.get("evidence_version", UNAVAILABLE))
+    known = context.get("run", {}).get("current_execution_state") != UNAVAILABLE if isinstance(context.get("run"), dict) else False
+    return [AllowedAction(action_id=action_id, action_namespace=namespace, run_id=run_id, allowed=known,
+                          reason_code="READ_ONLY_INSPECTION_AVAILABLE" if known else "RUN_EVIDENCE_UNAVAILABLE",
+                          evidence_version=evidence_version, expected_effect_code=effect,
+                          blocked_reason_code=None if known else "RUN_EVIDENCE_UNAVAILABLE").to_dict()
+            for action_id, namespace, effect in _READ_ACTIONS]
+
+
+def evaluate_action(root: Path, run_id: str, action: AllowedAction | dict[str, object]) -> dict[str, object]:
+    """Re-evaluate one descriptor against fresh evidence before any future action gateway use."""
+    descriptor = action.to_dict() if isinstance(action, AllowedAction) else dict(action) if isinstance(action, dict) else {}
+    context = get_run_context(root, run_id)
+    fresh = str(context["evidence_version"])
+    known_action_ids = {action_id for action_id, _, _ in _READ_ACTIONS}
+    action_id = str(descriptor.get("action_id")) if descriptor.get("action_id") in known_action_ids else UNAVAILABLE
+    try:
+        require_compatible_version(descriptor.get("contract_version"))
+    except ContractVersionError:
+        return ActionPolicyDecision(action_id=action_id, run_id=run_id, decision="UNAVAILABLE", reason_code="INCOMPATIBLE_CONTRACT_VERSION", policy_version=POLICY_VERSION, evaluated_at=_now(), evidence_version=fresh).to_dict()
+    if descriptor.get("run_id") != run_id or descriptor.get("evidence_version") != fresh:
+        return ActionPolicyDecision(action_id=action_id, run_id=run_id, decision="STALE_REVALIDATION_REQUIRED", reason_code="EVIDENCE_VERSION_CHANGED", policy_version=POLICY_VERSION, evaluated_at=_now(), evidence_version=fresh).to_dict()
+    permitted = {item["action_id"] for item in get_allowed_actions(root, run_id, context=context) if item["allowed"] is True}
+    decision = "ALLOWED" if action_id in permitted and descriptor.get("classification") == "READ_ONLY" else "DENIED"
+    return ActionPolicyDecision(action_id=action_id, run_id=run_id, decision=decision,
+                                reason_code="READ_ONLY_INSPECTION_AVAILABLE" if decision == "ALLOWED" else "ACTION_NOT_CURRENTLY_ALLOWED",
+                                policy_version=POLICY_VERSION, evaluated_at=_now(), evidence_version=fresh).to_dict()

engineering_platform/dashboard_browser_validation.py

@@ -0,0 +1,206 @@
+"""Run dashboard browser validation with local CI-parity and host safety."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import json
+
+from .component_lock import single_instance
+
+
+SHARDS = ("1/4", "2/4", "3/4", "4/4")
+PLAYWRIGHT_COMMAND = ("npx", "playwright", "test", "tests/engineering/dashboard.spec.mjs")
+LOCK_COMPONENT = "dashboard-browser-validation"
+LOCAL_BATCH_TIMEOUT_SECONDS = 300
+PROCESS_TERMINATION_TIMEOUT_SECONDS = 5
+EVIDENCE_RUN_ID_ENV = "ENGINEERING_PLATFORM_VALIDATION_RUN_ID"
+
+
+def _common_git_directory(root: Path) -> Path:
+    """Return the Git directory shared by every worktree of this repository."""
+    observed = subprocess.run(
+        ("git", "rev-parse", "--path-format=absolute", "--git-common-dir"),
+        cwd=root,
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    directory = observed.stdout.strip()
+    if observed.returncode or not directory:
+        raise RuntimeError("Dashboard browser validation requires a Git worktree.")
+    return Path(directory)
+
+
+def _command(*arguments: str) -> tuple[str, ...]:
+    return (*PLAYWRIGHT_COMMAND, "--workers=1", *arguments)
+
+
+def dashboard_evidence_path(root: Path, run_id: str) -> Path:
+    """Return the ignored, run-scoped shard evidence payload location."""
+    return root / ".engineering" / "validation" / "dashboard-browser" / f"{run_id}.json"
+
+
+def _write_evidence(root: Path, results: list[tuple[str, str, int | None]], *, cleanup: str) -> None:
+    """Write bounded structured shard facts only when the host supplied a run id."""
+    run_id = os.environ.get(EVIDENCE_RUN_ID_ENV)
+    if not run_id:
+        return
+    if not run_id.replace("-", "").isalnum():
+        return
+    path = dashboard_evidence_path(root, run_id)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    payload = {
+        "version": 1,
+        "expected_shard_count": len(SHARDS),
+        "actual_shard_count": len(results),
+        "workers_per_shard": 1,
+        "shards": [
+            {"shard": shard, "exit_code": result, "result": "PASS" if result == 0 else "FAIL" if result is not None else "UNAVAILABLE"}
+            for shard, _, result in results
+        ],
+        "cleanup": cleanup,
+    }
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def load_dashboard_evidence(root: Path, run_id: str) -> dict[str, object] | None:
+    """Load only a complete, fixed-topology dashboard shard payload."""
+    try:
+        payload = json.loads(dashboard_evidence_path(root, run_id).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict) or payload.get("version") != 1:
+        return None
+    shards = payload.get("shards")
+    if (
+        payload.get("expected_shard_count") != len(SHARDS)
+        or payload.get("actual_shard_count") != len(SHARDS)
+        or payload.get("workers_per_shard") != 1
+        or not isinstance(shards, list)
+        or len(shards) != len(SHARDS)
+        or tuple(item.get("shard") for item in shards if isinstance(item, dict)) != SHARDS
+    ):
+        return None
+    return payload
+
+
+def _run_ci(root: Path, arguments: tuple[str, ...]) -> int:
+    """Delegate one CI shard unchanged to Playwright."""
+    return subprocess.run(_command(*arguments), cwd=root, check=False).returncode
+
+
+def _terminate_process_groups(processes: list[tuple[str, Path, subprocess.Popen[bytes]]]) -> None:
+    """Stop every owned shard group, including descendants of a failed parent."""
+    # A Playwright shard can exit before the dashboard server it started in the
+    # same session. Signal every owned process group so that failure cleanup
+    # does not leave that server behind merely because its parent has exited.
+    for _, _, process in processes:
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+        except (PermissionError, ProcessLookupError):
+            # A shard can already have exited and its process-group identity
+            # may no longer be signalable on macOS. Cleanup is best-effort;
+            # it must not replace the authoritative shard exit result.
+            pass
+    active = [process for _, _, process in processes if process.poll() is None]
+    for process in active:
+        try:
+            process.wait(timeout=PROCESS_TERMINATION_TIMEOUT_SECONDS)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except (PermissionError, ProcessLookupError):
+                pass
+            try:
+                process.wait(timeout=PROCESS_TERMINATION_TIMEOUT_SECONDS)
+            except subprocess.TimeoutExpired:
+                pass
+
+
+def _read_results(
+    processes: list[tuple[str, Path, subprocess.Popen[bytes]]],
+) -> list[tuple[str, str, int | None]]:
+    """Return captured output after every owned shard has reached a terminal state."""
+    return [
+        (shard, output.read_text(encoding="utf-8", errors="replace"), process.poll())
+        for shard, output, process in processes
+    ]
+
+
+def _run_local_shards(root: Path) -> int:
+    """Run four isolated one-worker shards, refusing overlapping local batches."""
+    environment = {**os.environ, "CI": "1"}
+    common_git = _common_git_directory(root)
+    with single_instance(common_git, LOCK_COMPONENT):
+        with tempfile.TemporaryDirectory(prefix="engineering-platform-dashboard-shards-") as temporary:
+            directory = Path(temporary)
+            processes: list[tuple[str, Path, subprocess.Popen[bytes]]] = []
+            failed = False
+            timed_out = False
+            cleaned_up = False
+            cleanup_attempted = False
+            deadline = time.monotonic() + LOCAL_BATCH_TIMEOUT_SECONDS
+            try:
+                for index, shard in enumerate(SHARDS, start=1):
+                    output = directory / f"shard-{index}.log"
+                    with output.open("wb") as stream:
+                        process = subprocess.Popen(
+                            _command("--reporter=line", f"--shard={shard}", f"--output=test-results/dashboard-shard-{index}"),
+                            cwd=root,
+                            env=environment,
+                            stderr=subprocess.STDOUT,
+                            stdout=stream,
+                            start_new_session=True,
+                        )
+                    processes.append((shard, output, process))
+                for _, _, process in processes:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        timed_out = True
+                        break
+                    try:
+                        if process.wait(timeout=remaining) != 0:
+                            failed = True
+                    except subprocess.TimeoutExpired:
+                        timed_out = True
+                        break
+            except BaseException:
+                _terminate_process_groups(processes)
+                cleaned_up = True
+                raise
+            finally:
+                if not cleaned_up and (timed_out or any(process.poll() is None for _, _, process in processes)):
+                    _terminate_process_groups(processes)
+                    cleanup_attempted = True
+            results = _read_results(processes)
+    _write_evidence(root, results, cleanup="ATTEMPTED" if cleanup_attempted else "NOT_REQUIRED")
+    for shard, output, _ in results:
+        print(f"\n=== Dashboard browser shard {shard} ===")
+        print(output, end="" if output.endswith("\n") else "\n")
+    if timed_out:
+        print(f"Dashboard browser validation exceeded its {LOCAL_BATCH_TIMEOUT_SECONDS}-second local deadline.")
+        return 1
+    return 0 if not failed and all(result == 0 for _, _, result in results) else 1
+
+
+def main(arguments: tuple[str, ...] | None = None) -> int:
+    """Keep GitHub's one-worker shard contract and coordinate local parity runs."""
+    root = Path.cwd()
+    arguments = arguments if arguments is not None else tuple(sys.argv[1:])
+    if os.environ.get("CI"):
+        return _run_ci(root, arguments)
+    if arguments:
+        raise SystemExit("Local dashboard validation does not accept Playwright arguments; run the coordinated four-shard batch.")
+    return _run_local_shards(root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())