engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/execution_lifecycle.py

@@ -0,0 +1,447 @@
+"""Read-only, run-scoped execution lifecycle projection for the console.
+
+This module deliberately projects persisted Execution Host checkpoints only.  It
+does not coordinate transitions, repair, retry, resume, liveness, or telemetry.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .storage import EngineeringStorageError, load_run_qualification_snapshot, open_storage
+from .agent_state import TransactionState
+from .provider_recovery import load_recovery_state
+from .status_reconciliation import is_stale_rolling_status_block
+
+
+TERMINAL = frozenset({"COMPLETE", "BLOCKED", "FAILED"})
+_MANAGED_PATH = (
+    "START", "INITIALIZE", "CAPABILITY_REVIEW", "EXECUTE_AGENT", "LOCAL_REPOSITORY_VALIDATION", "QUALITY_CONTROL_AGENT", "REPAIR_AGENT",
+    "WAIT_FOR_OPERATOR_MERGE", "FINALIZE_AGENT", "WAIT_FOR_FINALIZATION_MERGE",
+    "RECONCILE_AGENT", "REPOSITORY_CLEANUP", "TERMINAL",
+)
+_FINALIZATION_REPAIR_PATH = (
+    "START", "INITIALIZE", "CAPABILITY_REVIEW", "EXECUTE_AGENT", "QUALITY_CONTROL_AGENT", "REPAIR_AGENT",
+    "WAIT_FOR_OPERATOR_MERGE", "FINALIZE_AGENT", "FINALIZATION_REPAIR_AGENT", "WAIT_FOR_FINALIZATION_MERGE",
+    "RECONCILE_AGENT", "REPOSITORY_CLEANUP", "TERMINAL",
+)
+# Genesis has no pull-request merge boundary.  This is presentation of the
+# existing mode contract, not a new execution sequence.
+_GENESIS_PATH = (
+    "START", "INITIALIZE", "CAPABILITY_REVIEW", "EXECUTE_AGENT", "QUALITY_CONTROL_AGENT", "REPAIR_AGENT",
+    "FINALIZE_AGENT", "REPOSITORY_CLEANUP", "TERMINAL",
+)
+# A reconciliation-only run remains part of the full delivery narrative.  Its
+# earlier delivery phases are explicitly skipped rather than silently omitted,
+# so the dashboard never renders a misleading half-workflow.
+_STATUS_RECONCILIATION_PATH = tuple(step for step in _MANAGED_PATH if step != "LOCAL_REPOSITORY_VALIDATION")
+
+# This is a presentation-only association. The Execution Host stays the
+# authority for phase timing; this projection only groups persisted evidence
+# under the corresponding visible lifecycle step.
+_STEP_PHASES = {
+    "START": frozenset({"QUEUE_WAIT", "SUBMISSION_CLAIM"}),
+    "INITIALIZE": frozenset({"INITIALIZATION", "HOST_PREFLIGHT", "WORKSPACE_PREFLIGHT", "CAPABILITY_PREFLIGHT"}),
+    "CAPABILITY_REVIEW": frozenset({"CAPABILITY_REVIEW"}),
+    "EXECUTE_AGENT": frozenset({"EXECUTION_PREPARATION", "PROVIDER_EXECUTION", "VALIDATION"}),
+    "LOCAL_REPOSITORY_VALIDATION": frozenset({"VALIDATION", "PROVIDER_EXECUTION"}),
+    "QUALITY_CONTROL_AGENT": frozenset({"QUALITY_CONTROL", "PROVIDER_EXECUTION", "VALIDATION"}),
+    "REPAIR_AGENT": frozenset({"REPAIR", "PROVIDER_EXECUTION", "VALIDATION"}),
+    "FINALIZATION_REPAIR_AGENT": frozenset({"REPAIR", "PROVIDER_EXECUTION", "VALIDATION"}),
+    "WAIT_FOR_OPERATOR_MERGE": frozenset({"PR_OR_MERGE", "EXTERNAL_CI_WAIT"}),
+    "FINALIZE_AGENT": frozenset({"REPOSITORY_FINALIZATION", "FINALIZATION"}),
+    "RECONCILE_AGENT": frozenset({"RECONCILIATION", "REPORT_GENERATION", "EVIDENCE_PERSISTENCE"}),
+    "REPOSITORY_CLEANUP": frozenset({"REPOSITORY_CLEANUP"}),
+    "TERMINAL": frozenset({"TOTAL_EXECUTION"}),
+}
+
+
+def intended_path(
+    execution_mode: object,
+    transaction_kind: object = "IMPLEMENTATION",
+    implementation_pull_request: object = None,
+) -> tuple[str, ...]:
+    """Return the canonical display path for one existing execution mode."""
+    if transaction_kind == "RECONCILIATION" or (
+        transaction_kind == "FINALIZATION" and implementation_pull_request is None
+    ):
+        return _STATUS_RECONCILIATION_PATH
+    if transaction_kind == "FINALIZATION":
+        return _FINALIZATION_REPAIR_PATH
+    return _GENESIS_PATH if execution_mode == "GENESIS" else _MANAGED_PATH
+
+
+def _checkpoint(value: object) -> dict[str, object]:
+    if not isinstance(value, str):
+        return {}
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _nonnegative_int(value: object) -> int:
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else 0
+
+
+def _pull_request_recorded(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+def _display_phase(phase: str, checkpoint: dict[str, object]) -> str:
+    """Map internal evidence polling onto its visible lifecycle boundary."""
+    # GitHub plus origin/main evidence has already proven this hand-off was
+    # merged.  The watcher owns the subsequent resume, but the console must
+    # not keep showing an obsolete operator action in that small interval.
+    if phase == "WAIT_FOR_OPERATOR_MERGE" and checkpoint.get("next_action") == "resume_verified_merge":
+        return "FINALIZE_AGENT" if checkpoint.get("transaction_kind") == "IMPLEMENTATION" else "RECONCILE_AGENT"
+    # Finalization has its own PR hand-off. Do not project it back onto the
+    # implementation merge once that implementation PR is already merged.
+    if phase == "WAIT_FOR_OPERATOR_MERGE" and checkpoint.get("transaction_kind") == "FINALIZATION":
+        return (
+            "WAIT_FOR_RECONCILIATION_MERGE"
+            if checkpoint.get("implementation_pull_request") is None
+            else "WAIT_FOR_FINALIZATION_MERGE"
+        )
+    if phase == "WAIT_FOR_OPERATOR_MERGE" and checkpoint.get("transaction_kind") == "RECONCILIATION":
+        return "WAIT_FOR_RECONCILIATION_MERGE"
+    if phase == "REPAIR_AGENT" and checkpoint.get("transaction_kind") == "FINALIZATION":
+        return "FINALIZATION_REPAIR_AGENT"
+    if phase != "WAIT_FOR_TERMINAL_EVIDENCE":
+        return phase
+    # Required-check polling happens before the operator merge hand-off.  It
+    # is not a completed merge, even though its PR timing evidence exists.
+    # A finalization transaction uses the same internal polling phase after
+    # the implementation merge, so it remains on its own visible step.
+    if checkpoint.get("transaction_kind") == "FINALIZATION":
+        return "RECONCILE_AGENT" if checkpoint.get("implementation_pull_request") is None else "FINALIZE_AGENT"
+    if checkpoint.get("transaction_kind") == "RECONCILIATION":
+        return "RECONCILE_AGENT"
+    return "WAIT_FOR_OPERATOR_MERGE"
+
+
+def projection(root: Path, run_id: str | None) -> dict[str, object]:
+    """Project persisted lifecycle evidence for exactly one ``run_id``.
+
+    Missing event history is explicitly represented as unavailable.  The
+    terminal checkpoint may still be shown, but no intermediate progress is
+    invented from reports, commits, timing or prompt content.
+    """
+    if not isinstance(run_id, str) or not run_id:
+        return {"run_id": run_id, "available": False, "steps": []}
+    try:
+        connection = open_storage(root, create=False)
+        try:
+            row = connection.execute(
+                "SELECT payload,phase FROM engineering_transactions WHERE run_id=?", (run_id,)
+            ).fetchone()
+            events = connection.execute(
+                "SELECT phase,checkpoint,recorded_at FROM execution_lifecycle_events WHERE run_id=? ORDER BY id",
+                (run_id,),
+            ).fetchall()
+            mode_row = connection.execute(
+                "SELECT execution_mode FROM execution_runs WHERE run_id=?", (run_id,)
+            ).fetchone()
+            phase_spans = connection.execute(
+                "SELECT phase_id,parent_phase_id,phase_name,attempt,started_at,completed_at,duration_ms,outcome,metadata "
+                "FROM execution_phase_spans WHERE run_id=? ORDER BY ordinal",
+                (run_id,),
+            ).fetchall()
+        finally:
+            connection.close()
+    except EngineeringStorageError:
+        return {"run_id": run_id, "available": False, "steps": []}
+    if row is None:
+        return {"run_id": run_id, "available": False, "steps": []}
+    checkpoint = _checkpoint(row[0])
+    phase = str(row[1])
+    mode = checkpoint.get("execution_mode") or (mode_row[0] if mode_row else None) or "MANAGED"
+    transaction_kind = checkpoint.get("transaction_kind") or "IMPLEMENTATION"
+    path = intended_path(mode, transaction_kind, checkpoint.get("implementation_pull_request"))
+    display_phase = _display_phase(phase, checkpoint)
+    observed: dict[str, dict[str, object]] = {}
+    repair_iterations = 0
+    implementation_merge_required = _pull_request_recorded(checkpoint.get("implementation_pull_request"))
+    finalization_merge_required = _pull_request_recorded(checkpoint.get("finalization_pull_request"))
+    reconciliation_merge_required = _pull_request_recorded(checkpoint.get("reconciliation_pull_request"))
+    recorded_pull_request = any(
+        _pull_request_recorded(checkpoint.get(field))
+        for field in ("pull_request", "implementation_pull_request", "finalization_pull_request", "reconciliation_pull_request")
+    )
+    if checkpoint.get("transaction_kind") == "FINALIZATION":
+        finalization_merge_required = finalization_merge_required or _pull_request_recorded(checkpoint.get("pull_request"))
+    if checkpoint.get("transaction_kind") == "RECONCILIATION":
+        reconciliation_merge_required = reconciliation_merge_required or _pull_request_recorded(checkpoint.get("pull_request"))
+    else:
+        implementation_merge_required = implementation_merge_required or _pull_request_recorded(checkpoint.get("pull_request"))
+    verified_merge_resume_kinds: set[str] = set()
+    if checkpoint.get("next_action") == "resume_verified_merge":
+        verified_merge_resume_kinds.add(str(transaction_kind))
+    for event_phase, event_checkpoint, recorded_at in events:
+        event = _checkpoint(event_checkpoint)
+        if event.get("next_action") == "resume_verified_merge":
+            verified_merge_resume_kinds.add(str(event.get("transaction_kind") or "IMPLEMENTATION"))
+        recorded_pull_request = recorded_pull_request or any(
+            _pull_request_recorded(event.get(field))
+            for field in ("pull_request", "implementation_pull_request", "finalization_pull_request", "reconciliation_pull_request")
+        )
+        event_step = _display_phase(str(event_phase), event)
+        if event_step in path and event_step not in {"START", "TERMINAL"}:
+            observed.setdefault(event_step, {"started_at": recorded_at})
+        if event_phase == "REPAIR_AGENT":
+            repair_iterations = max(repair_iterations, _nonnegative_int(event.get("repair_iterations")))
+        implementation_merge_required = (
+            implementation_merge_required or event_step == "WAIT_FOR_OPERATOR_MERGE"
+        )
+        finalization_merge_required = (
+            finalization_merge_required or event_step == "WAIT_FOR_FINALIZATION_MERGE"
+        )
+        reconciliation_merge_required = (
+            reconciliation_merge_required or event_step == "WAIT_FOR_RECONCILIATION_MERGE"
+        )
+    repair_iterations = max(repair_iterations, _nonnegative_int(checkpoint.get("repair_iterations")))
+    evidence_available = bool(events)
+    terminal_state = phase if phase in TERMINAL else None
+    try:
+        status_reconciliation_block = is_stale_rolling_status_block(
+            TransactionState.from_dict(checkpoint)
+        ) and not recorded_pull_request
+    except ValueError:
+        status_reconciliation_block = False
+    # Reaching the pull-request hand-off is not evidence that the pull request
+    # was merged. A later finalization step (or a successful terminal state)
+    # is the first lifecycle evidence that can make the merge node complete.
+    implementation_merge_completed = (
+        terminal_state == "COMPLETE"
+        or "FINALIZE_AGENT" in observed
+        or "REPOSITORY_CLEANUP" in observed
+        or "IMPLEMENTATION" in verified_merge_resume_kinds
+    )
+    finalization_merge_completed = (
+        terminal_state == "COMPLETE"
+        or "REPOSITORY_CLEANUP" in observed
+        or "FINALIZATION" in verified_merge_resume_kinds
+    )
+    reconciliation_merge_completed = (
+        terminal_state == "COMPLETE"
+        or "REPOSITORY_CLEANUP" in observed
+        or "RECONCILIATION" in verified_merge_resume_kinds
+    )
+    # The managed contract permits a no-PR path and a single implementation-PR
+    # path. A terminal pre-flight block is not merge evidence. Omit boundaries
+    # that have no persisted PR evidence instead of inventing an operator wait.
+    if mode != "GENESIS":
+        path = tuple(
+            step_id for step_id in path
+            if not (
+                step_id == "WAIT_FOR_OPERATOR_MERGE"
+                and (not implementation_merge_required or status_reconciliation_block)
+                and ("FINALIZE_AGENT" in observed or "REPOSITORY_CLEANUP" in observed or terminal_state == "COMPLETE" or status_reconciliation_block)
+            )
+            and not (
+                step_id == "WAIT_FOR_FINALIZATION_MERGE"
+                and (not finalization_merge_required or status_reconciliation_block)
+                and ("REPOSITORY_CLEANUP" in observed or terminal_state == "COMPLETE" or status_reconciliation_block)
+            )
+            and not (
+                step_id == "WAIT_FOR_RECONCILIATION_MERGE"
+                and (not reconciliation_merge_required or status_reconciliation_block)
+                and ("REPOSITORY_CLEANUP" in observed or terminal_state == "COMPLETE" or status_reconciliation_block)
+            )
+        )
+    quality_phase_ids = {
+        str(phase_id) for phase_id, _, phase_name, *_ in phase_spans
+        if phase_name == "QUALITY_CONTROL"
+    }
+    repair_phase_ids = {
+        str(phase_id) for phase_id, _, phase_name, *_ in phase_spans
+        if phase_name == "REPAIR"
+    }
+    parent_by_phase_id = {
+        str(phase_id): str(parent_phase_id)
+        for phase_id, parent_phase_id, *_ in phase_spans
+        if parent_phase_id is not None
+    }
+    metadata_by_phase_id = {
+        str(phase_id): _checkpoint(metadata)
+        for phase_id, *_, metadata in phase_spans
+    }
+
+    def is_nested_below(parent_phase_id: object, owner_phase_ids: set[str]) -> bool:
+        """Return whether a span is nested below a visible lifecycle owner."""
+        phase_id = str(parent_phase_id) if parent_phase_id is not None else None
+        seen: set[str] = set()
+        while phase_id and phase_id not in seen:
+            if phase_id in owner_phase_ids:
+                return True
+            seen.add(phase_id)
+            phase_id = parent_by_phase_id.get(phase_id)
+        return False
+
+    def is_local_validation_phase(phase_id: object, parent_phase_id: object) -> bool:
+        """Return whether a span belongs to the local-validation invocation."""
+        current_id = str(phase_id)
+        current_parent = parent_phase_id
+        seen: set[str] = set()
+        while current_id and current_id not in seen:
+            if metadata_by_phase_id.get(current_id, {}).get("lifecycle_step") == "LOCAL_REPOSITORY_VALIDATION":
+                return True
+            seen.add(current_id)
+            current_id = str(current_parent) if current_parent is not None else ""
+            current_parent = parent_by_phase_id.get(current_id)
+        return False
+
+    def belongs_to_step(step_id: str, phase_id: object, parent_phase_id: object, phase_name: object) -> bool:
+        """Keep nested provider timing with its visible lifecycle owner."""
+        name = str(phase_name)
+        nested_in_quality = is_nested_below(parent_phase_id, quality_phase_ids)
+        nested_in_repair = is_nested_below(parent_phase_id, repair_phase_ids)
+        local_validation = is_local_validation_phase(phase_id, parent_phase_id)
+        if step_id == "EXECUTE_AGENT":
+            return name in _STEP_PHASES[step_id] and not nested_in_quality and not nested_in_repair and not local_validation
+        if step_id == "LOCAL_REPOSITORY_VALIDATION":
+            return name in _STEP_PHASES[step_id] and local_validation
+        if step_id == "QUALITY_CONTROL_AGENT":
+            return name == "QUALITY_CONTROL" or nested_in_quality
+        if step_id in {"REPAIR_AGENT", "FINALIZATION_REPAIR_AGENT"}:
+            return name == "REPAIR" or nested_in_repair
+        return name in _STEP_PHASES.get(step_id, frozenset())
+
+    steps: list[dict[str, object]] = []
+    for order, step_id in enumerate(path):
+        state = "PENDING"
+        step: dict[str, object] = {
+            "id": step_id,
+            "order": order,
+            "presentation_key": (
+                "lifecycle.step.autonomous_quality_repair"
+                if mode == "GENESIS" and step_id == "REPAIR_AGENT"
+                else
+                "lifecycle.step.repair_agent"
+                if step_id == "FINALIZATION_REPAIR_AGENT"
+                else f"lifecycle.step.{step_id.lower()}"
+            ),
+            "state": state,
+        }
+        if step_id == "START":
+            step["state"] = "START"
+        elif step_id == "TERMINAL":
+            step["state"] = terminal_state or "PENDING"
+            if terminal_state:
+                step["terminal_outcome"] = terminal_state
+        elif step_id in {"WAIT_FOR_OPERATOR_MERGE", "WAIT_FOR_FINALIZATION_MERGE", "WAIT_FOR_RECONCILIATION_MERGE"} and step_id in observed:
+            step.update(observed[step_id])
+            merge_completed = (
+                implementation_merge_completed
+                if step_id == "WAIT_FOR_OPERATOR_MERGE"
+                else finalization_merge_completed if step_id == "WAIT_FOR_FINALIZATION_MERGE" else reconciliation_merge_completed
+            )
+            if merge_completed:
+                step["state"] = "COMPLETED"
+            elif display_phase == step_id and terminal_state is None:
+                step["state"] = "ACTIVE"
+            else:
+                # The PR exists, but it has not been merged. In particular,
+                # bounded validation repair must leave the merge visibly
+                # blocked and must not render a completion checkmark.
+                step["state"] = "BLOCKED"
+                if step_id == "WAIT_FOR_OPERATOR_MERGE" and display_phase == "REPAIR_AGENT":
+                    step["action_key"] = "state.repair_bounded_validation_failure"
+        elif step_id in observed:
+            step.update(observed[step_id])
+            step["state"] = "ACTIVE" if display_phase == step_id and terminal_state is None else "COMPLETED"
+        elif step_id == display_phase and terminal_state is None:
+            step["state"] = "ACTIVE"
+        if (
+            step_id == "WAIT_FOR_FINALIZATION_MERGE"
+            and display_phase == "FINALIZATION_REPAIR_AGENT"
+            and terminal_state is None
+        ):
+            step["state"] = "BLOCKED"
+            step["action_key"] = "state.repair_bounded_validation_failure"
+        if (
+            transaction_kind == "RECONCILIATION"
+            and step_id in {"EXECUTE_AGENT", "LOCAL_REPOSITORY_VALIDATION", "QUALITY_CONTROL_AGENT", "REPAIR_AGENT", "WAIT_FOR_OPERATOR_MERGE", "FINALIZE_AGENT", "WAIT_FOR_FINALIZATION_MERGE"}
+            and step_id not in observed
+        ):
+            step["state"] = "SKIPPED"
+            step["presentation_detail_key"] = "lifecycle.detail.not_part_of_reconciliation"
+        if step_id in {"REPAIR_AGENT", "FINALIZATION_REPAIR_AGENT"} and repair_iterations:
+            step["iteration_count"] = repair_iterations
+        if step_id in {"REPAIR_AGENT", "FINALIZATION_REPAIR_AGENT"} and step["state"] not in {"PENDING", "SKIPPED"}:
+            step["repair_evidence_key"] = (
+                "lifecycle.detail_autonomous_quality_repair_evidence"
+                if mode == "GENESIS" and step_id == "REPAIR_AGENT"
+                else "lifecycle.detail_repair_evidence"
+            )
+            audit = checkpoint.get("repair_audit")
+            if isinstance(audit, (list, tuple)) and audit:
+                step["repair_audit"] = list(audit)
+        if step_id == "QUALITY_CONTROL_AGENT" and step["state"] not in {"PENDING", "SKIPPED"}:
+            evidence = checkpoint.get("quality_evidence")
+            if isinstance(evidence, (list, tuple)) and evidence:
+                step["quality_evidence"] = list(evidence)
+        if step_id == "LOCAL_REPOSITORY_VALIDATION" and step["state"] not in {"PENDING", "SKIPPED"}:
+            audit = checkpoint.get("local_validation_audit")
+            if isinstance(audit, (list, tuple)) and audit:
+                step["repair_audit"] = list(audit)
+                step["iteration_count"] = checkpoint.get("local_validation_iterations", 0)
+        spans = [
+            {
+                "phase": phase_name,
+                "attempt": attempt,
+                "started_at": started_at,
+                "finished_at": completed_at,
+                "duration_ms": duration_ms,
+                "outcome": outcome,
+            }
+            for phase_id, parent_phase_id, phase_name, attempt, started_at, completed_at, duration_ms, outcome, _ in phase_spans
+            if belongs_to_step(step_id, phase_id, parent_phase_id, phase_name)
+        ]
+        # Timing is supporting evidence, not lifecycle authority.  In
+        # particular, admission can record a short reconciliation span before
+        # the end-reconciliation lifecycle step is ever reached.  Do not let
+        # that span invent start/end timestamps or a completed phase for a
+        # pending (or explicitly skipped) step.
+        if spans and step["state"] not in {"PENDING", "SKIPPED"}:
+            step["timing"] = {
+                "started_at": min(str(span["started_at"]) for span in spans if span["started_at"]),
+                "finished_at": max((str(span["finished_at"]) for span in spans if span["finished_at"]), default=None),
+                "spans": spans,
+            }
+        steps.append(step)
+    recovery = None
+    if status_reconciliation_block:
+        recovery = {"kind": "status_reconciliation", "run_id": run_id}
+    else:
+        # Provider recovery is durable SQLite evidence.  Do not consult the
+        # historical checkpoint ledger here: it can be stale after a host
+        # interruption, whereas this row is atomically advanced with the
+        # replacement provider receipt.
+        provider_recovery = load_recovery_state(root, run_id)
+        if provider_recovery is not None:
+            recovery = {
+                "kind": "provider_interruption",
+                "state": provider_recovery.get("state"),
+                "result": provider_recovery.get("result"),
+                "triggering_invocation_id": provider_recovery.get("triggering_invocation_id"),
+                "replacement_invocation_id": provider_recovery.get("replacement_invocation_id"),
+                "recovery_ordinal": provider_recovery.get("recovery_ordinal"),
+                "maximum_attempts": provider_recovery.get("maximum_attempts"),
+                "lifecycle_phase": provider_recovery.get("lifecycle_phase"),
+            }
+    qualification = load_run_qualification_snapshot(root, run_id) or {}
+    return {
+        "run_id": run_id,
+        "execution_mode": mode,
+        "available": evidence_available,
+        "terminal_state": terminal_state,
+        "current_step": display_phase if display_phase in path else None,
+        "steps": steps,
+        "recovery": recovery,
+        "qualification": {
+            "required_validation_state": qualification.get("required_validation_state", "UNAVAILABLE"),
+            "run_qualification": qualification.get("run_qualification", "UNAVAILABLE"),
+        },
+    }

engineering_platform/execution_models.py

@@ -0,0 +1,43 @@
+"""Provider-neutral execution domain models shared across host components."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RepositoryEvidence:
+    repository: str
+    branch: str
+    head_sha: str
+    clean: bool
+    main_contains_head: bool = False
+
+
+@dataclass(frozen=True)
+class PullRequestEvidence:
+    number: int
+    state: str
+    checks_terminal: bool
+    checks_passed: bool
+    merge_commit: str | None = None
+    is_draft: bool = False
+    failed_checks: tuple[str, ...] = ()
+    head_branch: str | None = None
+    base_branch: str | None = None
+    merge_state_status: str | None = None
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    terminal_state: str
+    branch: str | None = None
+    pull_request: int | None = None
+    terminal_condition: str = "repository_reconciled"
+    diagnostic: str | None = None
+    repository_path: str | None = None
+    commit_sha: str | None = None
+    validation_evidence: tuple[dict[str, str], ...] = ()
+    quality_evidence: tuple[dict[str, str], ...] = ()
+    # A failed validation never becomes a pass. This merely tells the host
+    # when a separate validation-environment recovery is warranted.
+    validation_disposition: str = "product_failure"

engineering_platform/execution_readiness.py

@@ -0,0 +1,166 @@
+"""Typed readiness profiles selected before an Execution Host lifecycle starts."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Callable
+from datetime import datetime, timezone
+
+
+class Requirement(StrEnum):
+    REQUIRED = "REQUIRED"
+    OPTIONAL = "OPTIONAL"
+    NOT_APPLICABLE = "NOT_APPLICABLE"
+
+
+@dataclass(frozen=True)
+class ReadinessProfile:
+    profile_id: str
+    version: int
+    execution_mode: str
+    repository: Requirement
+    remote: Requirement
+    upstream: Requirement
+    clean_worktree: Requirement
+    branch: Requirement
+    workspace_authorization: Requirement
+    host_qualification: Requirement
+    capability_qualification: Requirement
+    providers: Requirement
+    datastore: Requirement
+    active_run_lease: Requirement
+    producer_contract: Requirement
+    additional_constraints: tuple[str, ...] = ()
+
+
+PLATFORM_HOST = ReadinessProfile("platform_host", 1, "ANY", Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.REQUIRED, Requirement.NOT_APPLICABLE, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE)
+MANAGED_REPOSITORY = ReadinessProfile("managed_repository", 1, "MANAGED", Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED)
+GENESIS_TARGET = ReadinessProfile("genesis_target", 1, "GENESIS", Requirement.REQUIRED, Requirement.NOT_APPLICABLE, Requirement.NOT_APPLICABLE, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED, Requirement.REQUIRED)
+
+
+@dataclass(frozen=True)
+class ReadinessResult:
+    profile: ReadinessProfile
+    ready: bool
+    diagnostic: str | None = None
+
+
+@dataclass(frozen=True)
+class ReadinessFacts:
+    host_ready: bool
+    repository_present: bool
+    repository_clean: bool | None
+    lease_available: bool
+    remote_present: bool | None = None
+    upstream_present: bool | None = None
+    branch_present: bool | None = None
+    workspace_authorized: bool | None = None
+    capabilities_available: bool | None = None
+    providers_available: bool | None = None
+    datastore_healthy: bool | None = None
+    producer_contract_valid: bool | None = None
+
+    @classmethod
+    def from_preflight(cls, *, host: object, workspace: object, capability: object, lease_available: bool) -> "ReadinessFacts":
+        """Adapt already-observed preflight outcomes without performing any probe."""
+        def field(subject: object, name: str, default: object = None) -> object:
+            return subject.get(name, default) if isinstance(subject, dict) else getattr(subject, name, default)
+
+        def outcome(subject: object, identifier: str) -> bool | None:
+            for item in field(subject, "checks", ()):
+                if field(item, "identifier") == identifier:
+                    return field(item, "outcome") == "PASS"
+            return None
+
+        host_ready = field(host, "outcome") == "PASS"
+        repository_present = outcome(workspace, "target_repository") is True
+        staged, unstaged, untracked = (outcome(workspace, identifier) for identifier in ("worktree_staged", "worktree_unstaged", "worktree_untracked"))
+        repository_clean = (
+            outcome(workspace, "clean_worktree")
+            if None in {staged, unstaged, untracked}
+            else all((staged, unstaged, untracked))
+        )
+        capabilities_ready = field(capability, "outcome") == "PASS"
+        return cls(
+            host_ready,
+            repository_present,
+            repository_clean,
+            lease_available,
+            remote_present=outcome(workspace, "managed_remote"),
+            upstream_present=outcome(workspace, "managed_synchronization"),
+            branch_present=outcome(workspace, "managed_expected_branch")
+            if outcome(workspace, "managed_expected_branch") is not None
+            else outcome(workspace, "genesis_local_repository"),
+            workspace_authorized=outcome(workspace, "WORKSPACE_TARGET_AUTHORIZED"),
+            capabilities_available=capabilities_ready,
+            providers_available=outcome(capability, "provider_support"),
+            datastore_healthy=outcome(host, "telemetry_storage"),
+            producer_contract_valid=outcome(capability, "producer_contract"),
+        )
+
+
+@dataclass(frozen=True)
+class ReadinessDecision:
+    passed: bool
+    profile_id: str
+    profile_version: int
+    execution_mode: str
+    failed_requirements: tuple[str, ...]
+    facts: ReadinessFacts
+    evaluated_at: str
+    diagnostic: str | None = None
+
+
+def selected_profile(execution_mode: str) -> ReadinessProfile:
+    if execution_mode == "GENESIS":
+        return GENESIS_TARGET
+    if execution_mode == "MANAGED":
+        return MANAGED_REPOSITORY
+    raise ValueError(f"Unsupported execution readiness mode: {execution_mode}")
+
+
+def evaluate(
+    profile: ReadinessProfile,
+    *,
+    host_root: Path,
+    target_root: Path | None,
+    managed_clean: Callable[[Path], bool],
+    genesis_preflight: Callable[[Path | None], str | None],
+) -> ReadinessResult:
+    """Evaluate only the selected profile; never mix Genesis and Managed checks."""
+    if profile.profile_id == PLATFORM_HOST.profile_id:
+        return ReadinessResult(profile, host_root.is_dir(), None if host_root.is_dir() else "Execution Host repository is unavailable.")
+    if profile.profile_id == GENESIS_TARGET.profile_id:
+        diagnostic = genesis_preflight(target_root)
+        return ReadinessResult(profile, diagnostic is None, diagnostic)
+    if managed_clean(host_root):
+        return ReadinessResult(profile, True)
+    return ReadinessResult(profile, False, "working tree is not clean; unrelated work will not be touched")
+
+
+def decide(profile: ReadinessProfile, facts: ReadinessFacts) -> ReadinessDecision:
+    """Fail-closed policy evaluation over facts; it never probes the environment."""
+    failed: list[str] = []
+    requirements = (
+        ("host_qualification", profile.host_qualification, facts.host_ready),
+        ("repository", profile.repository, facts.repository_present),
+        ("remote", profile.remote, facts.remote_present),
+        ("upstream", profile.upstream, facts.upstream_present),
+        ("clean_worktree", profile.clean_worktree, facts.repository_clean),
+        ("branch", profile.branch, facts.branch_present),
+        ("workspace_authorization", profile.workspace_authorization, facts.workspace_authorized),
+        ("capability_qualification", profile.capability_qualification, facts.capabilities_available),
+        ("providers", profile.providers, facts.providers_available),
+        ("datastore", profile.datastore, facts.datastore_healthy),
+        ("active_run_lease", profile.active_run_lease, facts.lease_available),
+        ("producer_contract", profile.producer_contract, facts.producer_contract_valid),
+    )
+    for identifier, requirement, observed in requirements:
+        if requirement is Requirement.REQUIRED and observed is not True:
+            failed.append(identifier)
+    return ReadinessDecision(
+        not failed, profile.profile_id, profile.version, profile.execution_mode,
+        tuple(failed), facts, datetime.now(timezone.utc).isoformat(),
+        None if not failed else "Readiness requirements are not satisfied: " + ", ".join(failed),
+    )