engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/drift_diagnostics.py

@@ -0,0 +1,144 @@
+"""Immutable, read-only diagnostic evidence for failed host qualification checks.
+
+This module deliberately translates existing qualification results only.  It
+does not decide whether execution is admitted, retried, or resumed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import tempfile
+import uuid
+from typing import Iterable
+
+
+DRIFT_CATEGORIES = frozenset({
+    "Runtime Database", "Runtime Identity", "Runtime Schema",
+    "Execution Host Version", "Bootstrap Contract", "Checkpoint Format",
+    "Memory Format", "Report Format", "Configuration", "Workspace",
+    "Repository", "Capability", "Producer Contract", "Execution Policy",
+})
+
+
+@dataclass(frozen=True)
+class DriftEvidence:
+    drift_id: str
+    category: str
+    severity: str
+    expected_value: str
+    observed_value: str
+    resolution_recommendation: str
+    detection_timestamp: str
+    qualification_stage: str
+    affected_component: str
+    affected_repository: str
+    affected_runtime: str
+
+    def payload(self) -> dict[str, str]:
+        return asdict(self)
+
+
+def category_for(identifier: str, stage: str) -> str:
+    """Map stable check IDs to the canonical, extensible drift taxonomy."""
+    identifier = identifier.casefold()
+    if identifier in {"telemetry_storage", "storage_schema"}:
+        return "Runtime Database" if identifier == "telemetry_storage" else "Runtime Schema"
+    if identifier in {"host_identity", "workspace_identity", "target_repository_identity"}:
+        return "Runtime Identity"
+    if identifier in {"execution_host_version", "runner_version"}:
+        return "Execution Host Version"
+    if identifier == "bootstrap_contract":
+        return "Bootstrap Contract"
+    if identifier == "checkpoint_format":
+        return "Checkpoint Format"
+    if identifier == "memory_format":
+        return "Memory Format"
+    if identifier == "report_format":
+        return "Report Format"
+    if identifier == "configuration" or identifier == "configuration_schema":
+        return "Configuration"
+    if identifier in {"runtime_components", "provider_support", "required_capabilities"}:
+        return "Capability"
+    if "producer" in identifier:
+        return "Producer Contract"
+    if identifier == "execution_mode":
+        return "Execution Policy"
+    if stage == "Workspace Preflight":
+        return "Repository" if identifier.startswith(("git_", "worktree_", "managed_")) else "Workspace"
+    return "Capability" if stage == "Capability Preflight" else "Workspace"
+
+
+def evidence_for_checks(
+    checks: Iterable[object], *, stage: str, repository: str, runtime: str = "Engineering Platform"
+) -> tuple[DriftEvidence, ...]:
+    """Create deterministic evidence for every failed pre-existing check."""
+    now = datetime.now(timezone.utc).isoformat()
+    evidence: list[DriftEvidence] = []
+    for check in checks:
+        if getattr(check, "outcome", None) != "FAIL":
+            continue
+        identifier = str(getattr(check, "identifier", "unknown"))
+        reason = str(getattr(check, "reason", "Observed qualification check failed."))
+        recovery = str(getattr(check, "recovery", "Resolve the reported qualification drift."))
+        evidence.append(DriftEvidence(
+            drift_id=f"drift-{uuid.uuid4().hex}",
+            category=category_for(identifier, stage), severity="BLOCKING",
+            expected_value=f"{identifier}: PASS", observed_value=reason,
+            resolution_recommendation=recovery, detection_timestamp=now,
+            qualification_stage=stage, affected_component=identifier,
+            affected_repository=repository, affected_runtime=runtime,
+        ))
+    return tuple(evidence)
+
+
+def persist(root: Path, evidence: Iterable[DriftEvidence]) -> tuple[dict[str, str], ...]:
+    """Append immutable evidence documents; never rewrite a prior observation."""
+    items = tuple(evidence)
+    if not items:
+        return ()
+    directory = root / ".engineering" / "drift-evidence"
+    try:
+        directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        for item in items:
+            descriptor, temporary = tempfile.mkstemp(prefix=".drift-", dir=directory)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(item.payload(), sort_keys=True, separators=(",", ":")) + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, directory / f"{item.drift_id}.json")
+    except OSError:
+        # Existing fail-closed qualification remains authoritative if local
+        # diagnostic persistence is unavailable.
+        return tuple(item.payload() for item in items)
+    return tuple(item.payload() for item in items)
+
+
+def summary(evidence: Iterable[dict[str, object]]) -> str:
+    """Return one compact, operator-facing explanation without source inspection."""
+    items = list(evidence)
+    if not items:
+        return "No drift detected."
+    first = items[0]
+    return (
+        f"{first.get('qualification_stage', 'Qualification')} blocked by "
+        f"{first.get('affected_component', 'an unresolved component')} "
+        f"({first.get('category', 'Drift')}). Expected: {first.get('expected_value')}. "
+        f"Observed: {first.get('observed_value')}. Required action: "
+        f"{first.get('resolution_recommendation')}"
+    )
+
+
+def guidance(evidence: Iterable[dict[str, object]]) -> dict[str, object]:
+    """Read-only retry/resume advice; it does not change lifecycle authority."""
+    items = list(evidence)
+    action = items[0].get("resolution_recommendation") if items else "No action required."
+    return {
+        "retry_appropriate": bool(items),
+        "resume_appropriate": False if items else True,
+        "operator_intervention_required": bool(items),
+        "prerequisite": action,
+    }

engineering_platform/emergency_recovery.py

@@ -0,0 +1,268 @@
+"""Fail-closed emergency stop and workspace rollback for one live run."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import re
+import signal
+import sqlite3
+import time
+from dataclasses import replace
+from datetime import datetime, timezone
+
+from .agent_state import StateStore
+from .execution_lease import Lease, liveness, release
+from .execution_timing import complete_active_phase
+from .live_status import write_runner_process
+from .prompt_history import record_prompt_execution
+from .providers import GitProvider, LocalProcessProvider
+from .storage import EngineeringStorageError, load_projection, open_storage, record_emergency_recovery, record_execution_dismissal, store_projection
+
+
+RUN_ID_PATTERN = re.compile(r"inbox-[a-z0-9-]{6,64}$")
+BRANCH_PATTERN = re.compile(r"codex/[A-Za-z0-9._/-]+$")
+
+
+class EmergencyRecoveryError(RuntimeError):
+    """Raised when a destructive recovery cannot be proven safe."""
+
+
+@dataclass(frozen=True)
+class RecoveryPlan:
+    run_id: str
+    branch: str
+    baseline_branch: str
+    baseline_head: str
+    process_group: int | None
+    host_pid: int
+
+
+def _git(root: Path, *args: str) -> str:
+    result = GitProvider().execute(root, "git", *args)
+    if result.returncode:
+        raise EmergencyRecoveryError("De Git-werkmap kan niet veilig worden gecontroleerd.")
+    return result.stdout.strip()
+
+
+def _live(root: Path, run_id: str, *, central_database: Path | None = None) -> dict[str, object]:
+    live = load_projection(root, "live_status", central_database=central_database) or {}
+    if live.get("run_id") != run_id:
+        raise EmergencyRecoveryError("Deze uitvoering is niet de huidige uitvoering.")
+    if liveness(root, run_id, central_database=central_database).get("state") != "LIVE":
+        raise EmergencyRecoveryError("Deze uitvoering is niet meer actief; de noodactie is niet nodig.")
+    if live.get("execution_mode") != "MANAGED":
+        raise EmergencyRecoveryError("Noodherstel met rollback is alleen beschikbaar voor een beheerde uitvoering.")
+    return live
+
+
+def _runner(root: Path, run_id: str) -> tuple[int, int] | None:
+    try:
+        runner = json.loads((root / ".engineering" / "status" / "runner_process.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    pid, group = runner.get("pid"), runner.get("process_group")
+    if runner.get("run_id") != run_id:
+        return None
+    if not isinstance(pid, int) or pid <= 0 or not isinstance(group, int) or group <= 0:
+        raise EmergencyRecoveryError("De door deze uitvoering beheerde Codex-procesgroep is ongeldig.")
+    return pid, group
+
+
+def _host_pid(root: Path, run_id: str, *, central_database: Path | None = None) -> int:
+    connection = open_storage(root) if central_database is None else sqlite3.connect(central_database.resolve(), isolation_level=None)
+    try:
+        row = connection.execute(
+            "SELECT process_id FROM execution_run_leases WHERE run_id=? AND lease_state='ACTIVE' ORDER BY created_at DESC LIMIT 1",
+            (run_id,),
+        ).fetchone()
+    finally:
+        connection.close()
+    pid = row[0] if row else None
+    if not isinstance(pid, int) or pid <= 0:
+        raise EmergencyRecoveryError("De Execution Host van deze uitvoering is niet beschikbaar.")
+    return pid
+
+
+def _require_central_project_ownership(database: Path, project_id: str | None, run_id: str) -> None:
+    """Reject a dashboard action whose run is not owned by its selected project."""
+    if not isinstance(project_id, str) or not project_id:
+        raise EmergencyRecoveryError("Er is geen geldig project geselecteerd voor deze noodactie.")
+    try:
+        connection = sqlite3.connect(database.resolve(), isolation_level=None)
+        try:
+            row = connection.execute(
+                "SELECT project_id FROM ep_execution_runs WHERE run_id=?", (run_id,)
+            ).fetchone()
+        finally:
+            connection.close()
+    except sqlite3.Error as error:
+        raise EmergencyRecoveryError("De centrale uitvoeringstoestand is niet beschikbaar.") from error
+    if row is None or row[0] != project_id:
+        raise EmergencyRecoveryError("Deze uitvoering behoort niet tot het geselecteerde project.")
+
+
+def _process_command(root: Path, pid: int) -> str:
+    result = LocalProcessProvider().execute(root, ("ps", "-p", str(pid), "-o", "command="))
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _plan(
+    root: Path, run_id: str, *, central_database: Path | None = None, project_id: str | None = None,
+) -> RecoveryPlan:
+    if not RUN_ID_PATTERN.fullmatch(run_id):
+        raise EmergencyRecoveryError("De opgegeven run-ID is ongeldig.")
+    if central_database is not None:
+        _require_central_project_ownership(central_database, project_id, run_id)
+    live = _live(root, run_id, central_database=central_database)
+    state = StateStore(root / ".engineering" / "engineering-runs", central_database=central_database, emit_local_projection=central_database is None).load(run_id)
+    if state is None:
+        raise EmergencyRecoveryError("De actieve uitvoering heeft geen canoniek checkpoint.")
+    if any(
+        pull_request is not None
+        for pull_request in (
+            state.pull_request, state.implementation_pull_request,
+            state.finalization_pull_request, state.reconciliation_pull_request,
+        )
+    ):
+        raise EmergencyRecoveryError("Er is al een pull request geregistreerd; de noodknop verwijdert geen pull requests of hun branches.")
+    recovery = live.get("workspace_recovery")
+    if not isinstance(recovery, dict):
+        raise EmergencyRecoveryError("Deze uitvoering heeft geen veilige herstelbasis geregistreerd.")
+    baseline_branch = recovery.get("baseline_branch")
+    baseline_head = recovery.get("baseline_head")
+    preexisting = recovery.get("preexisting_branches")
+    if (
+        recovery.get("baseline_clean") is not True
+        or baseline_branch != "main"
+        or not isinstance(baseline_head, str)
+        or not re.fullmatch(r"[0-9a-f]{40}", baseline_head)
+        or not isinstance(preexisting, list)
+    ):
+        raise EmergencyRecoveryError("De uitvoering begon niet vanaf een aantoonbaar schone main-basis.")
+    branch = _git(root, "branch", "--show-current")
+    head = _git(root, "rev-parse", "HEAD")
+    if head != baseline_head:
+        raise EmergencyRecoveryError("Er zijn commits gemaakt; de noodknop verwijdert geen gecommitteerd werk of pull requests.")
+    if branch != "main" and (not BRANCH_PATTERN.fullmatch(branch) or branch in preexisting):
+        raise EmergencyRecoveryError("De actieve branch is niet aantoonbaar door deze uitvoering aangemaakt.")
+    runner = _runner(root, run_id)
+    host_pid = _host_pid(root, run_id, central_database=central_database)
+    runner_pid, group = runner if runner is not None else (None, None)
+    runner_command = _process_command(root, runner_pid) if runner_pid is not None else ""
+    host_command = _process_command(root, host_pid)
+    if runner_pid is not None and (not runner_command or "codex" not in runner_command.casefold()):
+        raise EmergencyRecoveryError("De geregistreerde Codex-runner is niet meer veilig identificeerbaar.")
+    if not host_command or ("execution_host" not in host_command and "engineering-execution-host" not in host_command):
+        raise EmergencyRecoveryError("De geregistreerde Execution Host is niet meer veilig identificeerbaar.")
+    return RecoveryPlan(run_id, branch, baseline_branch, baseline_head, group, host_pid)
+
+
+def preview(
+    root: Path, run_id: object, *, central_database: Path | None = None, project_id: str | None = None,
+) -> dict[str, object]:
+    """Return a display-safe, non-mutating emergency recovery eligibility view."""
+    if not isinstance(run_id, str):
+        return {"available": False}
+    try:
+        plan = _plan(root, run_id, central_database=central_database, project_id=project_id)
+    except (EmergencyRecoveryError, EngineeringStorageError, OSError):
+        return {"available": False}
+    return {
+        "available": True,
+        "run_id": plan.run_id,
+        "branch": plan.branch,
+        "baseline_branch": plan.baseline_branch,
+        "rollback_changes": True,
+        "remove_branch": plan.branch != plan.baseline_branch,
+    }
+
+
+def _stop(plan: RecoveryPlan, root: Path) -> None:
+    try:
+        if plan.process_group is not None:
+            try:
+                os.killpg(plan.process_group, signal.SIGTERM)
+            except ProcessLookupError:
+                # Codex can finish between preview and confirmation. The
+                # leased Execution Host is still the authoritative stop target.
+                pass
+        os.kill(plan.host_pid, signal.SIGTERM)
+    except ProcessLookupError as error:
+        raise EmergencyRecoveryError("De uitvoering stopte al voordat de noodactie kon worden uitgevoerd.") from error
+    deadline = time.monotonic() + 3
+    while time.monotonic() < deadline:
+        if not _process_command(root, plan.host_pid):
+            return
+        time.sleep(0.1)
+    raise EmergencyRecoveryError("De Execution Host reageert niet op de noodstop; er is niets teruggedraaid.")
+
+
+def _release_lease(root: Path, run_id: str, *, central_database: Path | None = None) -> None:
+    connection = open_storage(root) if central_database is None else sqlite3.connect(central_database.resolve(), isolation_level=None)
+    try:
+        row = connection.execute(
+            "SELECT lease_id,host_identity,host_instance_id,acquired_at,last_heartbeat_at,expires_at,lease_state FROM execution_run_leases WHERE run_id=? AND lease_state='ACTIVE' ORDER BY created_at DESC LIMIT 1",
+            (run_id,),
+        ).fetchone()
+    finally:
+        connection.close()
+    if not row:
+        return
+    release(root, Lease(row[0], run_id, row[1], row[2], row[3], row[4], row[5], row[6]), central_database=central_database)
+
+
+def execute(
+    root: Path, run_id: str, *, central_database: Path | None = None, project_id: str | None = None,
+) -> dict[str, object]:
+    """Stop exactly one verified host, then restore its clean local baseline."""
+    plan = _plan(root, run_id, central_database=central_database, project_id=project_id)
+    _stop(plan, root)
+    _release_lease(root, run_id, central_database=central_database)
+    _git(root, "restore", "--source", plan.baseline_head, "--staged", "--worktree", "--", ".")
+    _git(root, "clean", "-fd", "--", ".")
+    removed_branch: str | None = None
+    if plan.branch != plan.baseline_branch:
+        _git(root, "switch", plan.baseline_branch)
+        _git(root, "branch", "-D", "--", plan.branch)
+        removed_branch = plan.branch
+    if _git(root, "rev-parse", "HEAD") != plan.baseline_head or _git(root, "status", "--porcelain", "--untracked-files=all"):
+        raise EmergencyRecoveryError("De noodstop is uitgevoerd, maar de werkmap kon niet volledig worden teruggedraaid.")
+    write_runner_process(root, run_id, None)
+    try:
+        state = StateStore(root / ".engineering" / "engineering-runs", central_database=central_database, emit_local_projection=central_database is None).load(run_id)
+    except (EngineeringStorageError, ValueError) as error:
+        raise EmergencyRecoveryError("De annulering kon niet veilig als eindstatus worden vastgelegd.") from error
+    if state is None:
+        raise EmergencyRecoveryError("De actieve uitvoering heeft geen canoniek checkpoint.")
+    cancelled_at = datetime.now(timezone.utc).isoformat()
+    cancelled = replace(
+        state, phase="FAILED", terminal=True, next_action="operator_emergency_rollback",
+        terminal_condition="operator_emergency_rollback",
+        diagnostic="De operator heeft deze uitvoering via de noodstop geannuleerd en de lokale werkmap teruggedraaid.",
+    )
+    StateStore(root / ".engineering" / "engineering-runs", central_database=central_database, emit_local_projection=central_database is None).save(cancelled)
+    complete_active_phase(root, run_id, "TOTAL_EXECUTION", outcome="FAILED", central_database=central_database)
+    record_prompt_execution(
+        root, run_id=run_id, terminal_state="FAILED", prompt_title=Path(state.prompt_path).stem,
+        executed_at=cancelled_at, target_branch=plan.branch,
+        central_database=central_database,
+    )
+    record_execution_dismissal(
+        root, run_id=run_id, terminal_state="FAILED", dismissed_at=cancelled_at,
+        dismissed_by="dashboard_emergency_recovery",
+        central_database=central_database,
+    )
+    record_emergency_recovery(
+        root, run_id=run_id, cancelled_at=cancelled_at, rolled_back=True,
+        removed_branch=removed_branch,
+        central_database=central_database,
+    )
+    outcome = {"run_id": run_id, "stopped": True, "rolled_back": True, "removed_branch": removed_branch, "branch": plan.baseline_branch, "cancelled_at": cancelled_at}
+    connection = open_storage(root) if central_database is None else sqlite3.connect(central_database.resolve(), isolation_level=None)
+    try:
+        store_projection(connection, f"emergency_recovery:{run_id}", outcome, classification="RECOVERY_EXPORT")
+    finally:
+        connection.close()
+    return outcome

engineering_platform/engineering_memory.py

@@ -0,0 +1,139 @@
+"""Local, advisory Engineering Memory persistence.
+
+This module deliberately owns only bounded local memory.  The runner remains
+the lifecycle orchestrator and repository evidence remains authoritative.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from .agent_state import TransactionState
+
+
+def _memory_path(root: Path) -> Path:
+    return root / ".engineering" / "memory" / "engineering-memory.json"
+
+
+def load_engineering_memory(root: Path) -> dict[str, object]:
+    try:
+        raw = json.loads(_memory_path(root).read_text(encoding="utf-8"))
+        return raw if isinstance(raw, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def retrieve_engineering_memory(root: Path, prompt_path: Path) -> str:
+    """Return safe advisory metadata; repository evidence remains authoritative."""
+    try:
+        entries = load_engineering_memory(root).get("transactions", [])
+    except AttributeError:
+        return "\n\nEngineering Memory: no prior safe transaction metadata is available."
+    objective = prompt_path.stem.lower()
+    relevant = [
+        entry
+        for entry in entries[-10:]
+        if any(word in objective for word in entry.get("classification", "").split())
+    ]
+    return (
+        "\n\nEngineering Memory (advisory only; repository evidence overrides it): "
+        + json.dumps(relevant[-3:], sort_keys=True)
+    )
+
+
+def capture_engineering_memory(
+    root: Path, state: TransactionState, reviewer_records: tuple[dict[str, object], ...] = ()
+) -> None:
+    """Atomically store bounded metadata, never prompts, source content or credentials."""
+    path = _memory_path(root)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    raw = load_engineering_memory(root)
+    classification = " ".join(
+        part
+        for part in Path(state.prompt_path).stem.lower().replace("_", "-").split("-")
+        if part.isalpha()
+    )[:120]
+    entry = {
+        "classification": classification,
+        "repository": state.repository,
+        "outcome": state.phase,
+        "repair_iterations": state.repair_iterations,
+        "implementation_pr": state.implementation_pull_request,
+        "finalization_pr": state.finalization_pull_request,
+        "confidence": 1.0,
+        "usage_count": 0,
+        "last_successful_use": datetime.now(timezone.utc).isoformat(),
+    }
+    reviewer_index = {
+        item.get("reviewer"): dict(item)
+        for item in raw.get("reviewers", [])
+        if isinstance(item, dict) and isinstance(item.get("reviewer"), str)
+    }
+    for record in reviewer_records:
+        reviewer = record.get("reviewer")
+        if not isinstance(reviewer, str):
+            continue
+        previous = reviewer_index.get(reviewer, {})
+        usage = int(previous.get("usage_count", 0)) + 1
+        successful = int(previous.get("successful_outcomes", 0)) + (
+            0 if record.get("failed") else 1
+        )
+        accepted = int(previous.get("accepted_recommendations", 0)) + int(
+            record.get("accepted_recommendations", 0)
+        )
+        recommended = (
+            int(previous.get("recommendation_count", 0))
+            + int(record.get("accepted_recommendations", 0))
+            + int(record.get("rejected_recommendations", 0))
+        )
+        confidence = round(successful / usage, 2)
+        reviewer_index[reviewer] = {
+            "reviewer": reviewer,
+            "capability": record.get("capability", "engineering"),
+            "usage_count": usage,
+            "successful_outcomes": successful,
+            "accepted_recommendations": accepted,
+            "recommendation_count": recommended,
+            "recommendation_acceptance_rate": round(accepted / recommended, 2)
+            if recommended
+            else 0.0,
+            "average_duration": 0,
+            "last_successful_use": datetime.now(timezone.utc).isoformat()
+            if not record.get("failed")
+            else previous.get("last_successful_use"),
+            "future_confidence": confidence,
+        }
+    reviewers = list(reviewer_index.values())[-50:]
+    raw = {
+        "schema_version": 2,
+        "transactions": [item for item in raw.get("transactions", []) if isinstance(item, dict)][
+            -49:
+        ]
+        + [entry],
+        "reviewers": reviewers,
+        "capability_metrics": {
+            "most_frequently_used": max(reviewers, key=lambda item: item["usage_count"])["reviewer"]
+            if reviewers
+            else None,
+            "highest_value": max(reviewers, key=lambda item: item["future_confidence"])["reviewer"]
+            if reviewers
+            else None,
+            "repository_areas": sorted(
+                {str(item.get("capability", "engineering")) for item in reviewers}
+            ),
+        },
+    }
+    descriptor, temporary = tempfile.mkstemp(prefix=".memory.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(raw, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)