engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/platform_bootstrap.py

@@ -0,0 +1,385 @@
+"""Idempotent repository bootstrap and workspace provisioning API."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import sqlite3
+
+from .platform_api import PlatformConfiguration, PlatformConfigurationError, shared_workspace_store
+
+
+WORKSPACE_DIRECTORY = ".engineering"
+LEGACY_WORKSPACE_DIRECTORY = ".djconnect"
+_AUTO_IDENTIFIER_TABLES = frozenset({
+    "engineering_artifacts",
+    "engineering_component_logs",
+    "execution_lease_events",
+    "execution_lifecycle_events",
+})
+
+
+class WorkspaceMigrationBlockedError(RuntimeError):
+    """A one-time workspace migration found a component that is still live."""
+
+    def __init__(self, component: str | None = None) -> None:
+        self.component = component or "another component"
+        super().__init__("Engineering workspace migration requires running components to stop first.")
+
+
+def _worktree_roots(root: Path) -> tuple[Path, ...]:
+    """Return accessible worktrees that share ``root``'s Git common directory."""
+    root = root.resolve()
+    shared = shared_workspace_store(root)
+    if shared == root / WORKSPACE_DIRECTORY:
+        return (root,)
+    common = shared.parent
+    roots = {common.parent.resolve(), root}
+    worktrees = common / "worktrees"
+    if worktrees.is_dir():
+        for entry in worktrees.iterdir():
+            marker = entry / "gitdir"
+            try:
+                worktree_git_marker = Path(marker.read_text(encoding="utf-8").strip())
+            except OSError:
+                continue
+            candidate = worktree_git_marker.parent.resolve()
+            if (candidate / ".git").exists():
+                roots.add(candidate)
+    return tuple(sorted(roots, key=lambda item: str(item)))
+
+
+def _history_count(workspace: Path) -> int:
+    """Use the immutable history index only to choose an initial store seed."""
+    database = workspace / "engineering.db"
+    if not database.is_file():
+        return 0
+    try:
+        with sqlite3.connect(f"file:{database}?mode=ro", uri=True) as connection:
+            return int(connection.execute("SELECT COUNT(*) FROM prompt_execution_history").fetchone()[0])
+    except (sqlite3.DatabaseError, OSError):
+        return 0
+
+
+def _database_tables(connection: sqlite3.Connection, schema: str) -> tuple[str, ...]:
+    return tuple(
+        row[0]
+        for row in connection.execute(
+            f"SELECT name FROM {schema}.sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        )
+    )
+
+
+def _merge_databases(source: Path, destination: Path) -> None:
+    """Merge independently written local evidence without discarding run history.
+
+    Engineering records are append-only by identity.  SQLite row ids are local
+    implementation details for log/event tables, so those are regenerated at
+    the destination while their durable content is retained.  Mutable status
+    projections take the newest timestamp.  Any incompatible schema fails
+    closed before either source evidence or the shared store is removed.
+    """
+    with sqlite3.connect(destination) as connection:
+        connection.execute("PRAGMA foreign_keys=OFF")
+        connection.execute("ATTACH DATABASE ? AS legacy", (str(source),))
+        in_transaction = False
+        try:
+            current_tables = _database_tables(connection, "main")
+            legacy_tables = _database_tables(connection, "legacy")
+            if current_tables != legacy_tables:
+                raise RuntimeError("Engineering workspace migration found incompatible database schemas.")
+            connection.execute("BEGIN IMMEDIATE")
+            in_transaction = True
+            for table in current_tables:
+                columns = [row[1] for row in connection.execute(f"PRAGMA main.table_info({table})")]
+                if table in _AUTO_IDENTIFIER_TABLES:
+                    columns = [column for column in columns if column != "id"]
+                if not columns:
+                    continue
+                column_list = ",".join(columns)
+                if table in {"engineering_status", "engineering_transactions"}:
+                    key = "name" if table == "engineering_status" else "run_id"
+                    for row in connection.execute(f"SELECT {column_list} FROM legacy.{table}"):
+                        values = dict(zip(columns, row, strict=True))
+                        current = connection.execute(
+                            f"SELECT updated_at FROM main.{table} WHERE {key}=?", (values[key],)
+                        ).fetchone()
+                        if current is None:
+                            placeholders = ",".join("?" for _ in columns)
+                            connection.execute(
+                                f"INSERT INTO main.{table}({column_list}) VALUES({placeholders})",
+                                tuple(values[column] for column in columns),
+                            )
+                        elif values["updated_at"] > current[0]:
+                            assignments = ["payload=?", "updated_at=?"]
+                            parameters: list[object] = [values["payload"], values["updated_at"]]
+                            if table == "engineering_transactions":
+                                assignments.insert(1, "phase=?")
+                                parameters.insert(1, values["phase"])
+                            parameters.append(values[key])
+                            connection.execute(
+                                f"UPDATE main.{table} SET {','.join(assignments)} WHERE {key}=?", parameters
+                            )
+                elif table == "daily_execution_statistics":
+                    # This is a rebuildable read model.  The next telemetry
+                    # update writes its fresh aggregate; never overwrite a
+                    # newer shared projection during migration.
+                    connection.execute(
+                        f"INSERT OR IGNORE INTO main.{table}({column_list}) SELECT {column_list} FROM legacy.{table}"
+                    )
+                else:
+                    connection.execute(
+                        f"INSERT OR IGNORE INTO main.{table}({column_list}) SELECT {column_list} FROM legacy.{table}"
+                    )
+            violations = connection.execute("PRAGMA foreign_key_check").fetchall()
+            if violations:
+                raise RuntimeError("Engineering workspace migration would violate datastore integrity.")
+            connection.execute("COMMIT")
+            in_transaction = False
+        except Exception:
+            if in_transaction:
+                connection.execute("ROLLBACK")
+            raise
+        finally:
+            connection.execute("DETACH DATABASE legacy")
+
+
+def _merge_workspace(source: Path, destination: Path) -> None:
+    """Merge one worktree's local evidence into the shared workspace."""
+    for child in tuple(source.iterdir()):
+        target = destination / child.name
+        if child.name == "engineering.db" and target.is_file():
+            _merge_databases(child, target)
+            child.unlink()
+        elif not target.exists():
+            shutil.move(str(child), str(target))
+        elif child.is_dir() and target.is_dir():
+            _merge_workspace(child, target)
+            child.rmdir()
+        elif child.is_file() and target.is_file() and child.read_bytes() == target.read_bytes():
+            child.unlink()
+        else:
+            raise RuntimeError(f"Engineering workspace migration conflict: {child.name}")
+
+
+def _link_workspace(worktree: Path, shared: Path) -> None:
+    """Expose the shared private store at the established worktree-local path."""
+    local = worktree / WORKSPACE_DIRECTORY
+    if local.is_symlink():
+        if local.resolve() != shared.resolve():
+            raise RuntimeError("Engineering workspace points to an unexpected shared store.")
+        return
+    if local.exists():
+        raise RuntimeError("Engineering workspace migration did not consume a local store.")
+    os.symlink(shared, local, target_is_directory=True)
+
+
+def _discard_inactive_component_locks(workspace: Path) -> None:
+    """Discard only stale process locks before relocating their directory.
+
+    A flock is meaningful only in the filesystem currently held by its owner;
+    copying that file into a shared workspace would create a false lock.  A
+    live owner therefore blocks the migration until the normal component
+    restart has stopped it.  Stale lock files are explicitly non-evidence and
+    may be recreated by their owning component after the migration.
+    """
+    locks = workspace / "locks"
+    if not locks.exists():
+        return
+    if locks.is_symlink() or not locks.is_dir():
+        raise RuntimeError("Engineering workspace migration found an invalid component-lock directory.")
+    for path in locks.glob("*.lock"):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            process_id = payload.get("pid") if isinstance(payload, dict) else None
+            if isinstance(process_id, int) and process_id > 0:
+                os.kill(process_id, 0)
+                component = payload.get("component") if isinstance(payload, dict) else None
+                raise WorkspaceMigrationBlockedError(component if isinstance(component, str) else None)
+        except ProcessLookupError:
+            continue
+        except PermissionError as error:
+            raise RuntimeError("Engineering workspace migration cannot verify a component lock owner.") from error
+        except (OSError, json.JSONDecodeError):
+            continue
+    shutil.rmtree(locks)
+
+
+def migrate_worktree_workspace(root: Path) -> Path:
+    """Create one durable Engineering store for every worktree of a repository."""
+    root = root.resolve()
+    shared = shared_workspace_store(root)
+    if shared == root / WORKSPACE_DIRECTORY:
+        return shared
+    candidates = [worktree / WORKSPACE_DIRECTORY for worktree in _worktree_roots(root)]
+    local_directories = [path for path in candidates if path.exists() and not path.is_symlink()]
+    if not shared.exists() and local_directories:
+        seed = max(local_directories, key=lambda path: (_history_count(path), str(path)))
+        shared.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        shutil.move(str(seed), str(shared))
+    shared.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if local_directories:
+        _discard_inactive_component_locks(shared)
+        for local in local_directories:
+            if local.exists():
+                _discard_inactive_component_locks(local)
+    for local in local_directories:
+        if not local.exists():
+            continue
+        _merge_workspace(local, shared)
+        local.rmdir()
+    for worktree in _worktree_roots(root):
+        _link_workspace(worktree, shared)
+    return shared.resolve()
+
+
+def _validate_legacy_merge(source: Path, destination: Path) -> None:
+    """Fail closed before moving evidence into an occupied canonical workspace."""
+    if source.is_symlink() or destination.is_symlink():
+        raise RuntimeError("Engineering workspace migration refuses symbolic links.")
+    if source.is_dir() != destination.is_dir():
+        raise RuntimeError(f"Engineering workspace migration conflict: {source.name}")
+    if source.is_dir():
+        for child in source.iterdir():
+            target = destination / child.name
+            if target.exists():
+                _validate_legacy_merge(child, target)
+        return
+    if source.read_bytes() != destination.read_bytes():
+        raise RuntimeError(f"Engineering workspace migration conflict: {source.name}")
+
+
+def _merge_legacy_workspace(source: Path, destination: Path) -> None:
+    """Move prevalidated legacy evidence, dropping only byte-identical duplicates."""
+    for child in source.iterdir():
+        target = destination / child.name
+        if not target.exists():
+            shutil.move(str(child), str(target))
+        elif child.is_dir():
+            _merge_legacy_workspace(child, target)
+            child.rmdir()
+        else:
+            child.unlink()
+
+
+def _move_legacy_logs(source: Path, workspace: Path) -> None:
+    """Preserve a conflicting historic log tail outside the live log files."""
+    destination = workspace / "logs" / "legacy"
+    if destination.exists():
+        _validate_legacy_merge(source, destination)
+        _merge_legacy_workspace(source, destination)
+        source.rmdir()
+    else:
+        destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        shutil.move(str(source), str(destination))
+
+
+def _archive_legacy_evidence(source: Path, workspace: Path) -> None:
+    """Keep a conflicting historic evidence category without replacing live data."""
+    destination = workspace / "legacy" / source.name
+    if destination.exists():
+        _validate_legacy_merge(source, destination)
+        _merge_legacy_workspace(source, destination)
+        source.rmdir()
+    else:
+        destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        shutil.move(str(source), str(destination))
+
+
+def migrate_legacy_workspace(root: Path) -> Path:
+    """Move `.djconnect` evidence to the sole canonical `.engineering` location."""
+    root = root.resolve()
+    workspace = migrate_worktree_workspace(root)
+    legacy = root / LEGACY_WORKSPACE_DIRECTORY
+    if not legacy.exists():
+        return workspace
+    if legacy.is_symlink() or not legacy.is_dir():
+        raise RuntimeError("Engineering workspace migration requires a local directory.")
+    workspace.mkdir(mode=0o700, parents=True, exist_ok=True)
+    archived_categories = {"logs", "qualification"}
+    for source in legacy.iterdir():
+        if source.name in archived_categories and (workspace / source.name).exists():
+            continue
+        target = workspace / source.name
+        if target.exists():
+            _validate_legacy_merge(source, target)
+    legacy_logs = legacy / "logs"
+    if legacy_logs.exists() and (workspace / "logs").exists():
+        _move_legacy_logs(legacy_logs, workspace)
+    legacy_qualification = legacy / "qualification"
+    if legacy_qualification.exists() and (workspace / "qualification").exists():
+        _archive_legacy_evidence(legacy_qualification, workspace)
+    _merge_legacy_workspace(legacy, workspace)
+    legacy.rmdir()
+    return workspace
+
+
+def provision_workspace(root: Path) -> dict[str, Path]:
+    """Provision only platform-owned local directories; safe to repeat."""
+    workspace = migrate_legacy_workspace(root)
+    return _provision_workspace_paths(root, workspace)
+
+
+def runtime_workspace(root: Path) -> Path:
+    """Return the already-valid shared store without starting a migration.
+
+    A long-running dashboard is allowed to coexist with a watcher or runner.
+    When this worktree already points to the canonical shared store, a normal
+    component start must not inspect or merge dormant legacy stores belonging
+    to another worktree.  Such a merge remains an explicit, fail-closed
+    migration through :func:`migrate_legacy_workspace`.
+    """
+    root = root.resolve()
+    shared = shared_workspace_store(root)
+    local = root / WORKSPACE_DIRECTORY
+    legacy = root / LEGACY_WORKSPACE_DIRECTORY
+    if (
+        shared != local
+        and local.is_symlink()
+        and local.resolve() == shared.resolve()
+        and shared.is_dir()
+        and not legacy.exists()
+    ):
+        return shared.resolve()
+    return migrate_legacy_workspace(root)
+
+
+def _provision_workspace_paths(root: Path, workspace: Path) -> dict[str, Path]:
+    """Create the repeatable directories for an already-selected workspace."""
+    PlatformConfiguration.load(root)
+    paths = {"workspace": workspace, "reports": workspace / "reports", "status": workspace / "status", "diagnostics": workspace / "logs", "inbox_processing": workspace / "inbox-processing"}
+    # A CENTRAL lifecycle must not even create the historical checkpoint
+    # directory.  Checkout directories retained here are physical temporary
+    # execution concerns, not operational truth.
+    if not os.environ.get("EP_CENTRAL_OPERATIONAL_DATABASE"):
+        paths["runs"] = workspace / "engineering-runs"
+    for path in paths.values():
+        path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return paths
+
+
+def provision_runtime_workspace(root: Path) -> dict[str, Path]:
+    """Provision a watcher, runner, or dashboard without implicit migration."""
+    return _provision_workspace_paths(root, runtime_workspace(root))
+
+
+def validate_repository(root: Path) -> PlatformConfiguration:
+    """Fail closed unless this repository is an explicit platform consumer."""
+    if not (root / "BOOTSTRAP.md").is_file() or not (root / ".git").exists():
+        raise PlatformConfigurationError("Repository bootstrap compatibility failed.")
+    return PlatformConfiguration.load(root)
+
+
+def render_template(destination: Path, replacements: dict[str, str]) -> Path:
+    """Create a deterministic config template without overwriting consumer data."""
+    if destination.exists():
+        return destination
+    template = Path(__file__).with_name("templates") / "workspace-config.json"
+    content = template.read_text(encoding="utf-8")
+    for key, value in sorted(replacements.items()):
+        content = content.replace(key, value)
+    json.loads(content)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(content + "\n", encoding="utf-8")
+    return destination

engineering_platform/platform_components.py

@@ -0,0 +1,65 @@
+"""The sole installed-Server inventory of supported Platform Components."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PlatformComponent:
+    """Stable product, health and logging identity for one Server component."""
+
+    id: str
+    name_key: str
+    kind: str
+    group: str
+    active_status: str
+    inactive_status: str
+    detail_code: str
+    startup_event: str
+    restart_supported: bool = False
+    critical: bool = False
+    lifecycle_label: str | None = None
+
+
+PLATFORM_COMPONENTS = (
+    PlatformComponent("ep_server", "component.ep_server", "DAEMON", "platform", "EP_SERVER_ACTIVE", "EP_SERVER_UNAVAILABLE", "EP_SERVER_ENDPOINT", "ep_server_started", False, True),
+    PlatformComponent("platform_database", "component.platform_database", "STORAGE", "platform", "PLATFORM_DATABASE_HEALTHY", "PLATFORM_DATABASE_UNAVAILABLE", "PLATFORM_DATABASE_STORAGE", "central_log_store_ready", False, True),
+    PlatformComponent("lifecycle_worker", "component.lifecycle_worker", "IN_PROCESS_COMPONENT", "platform", "LIFECYCLE_WORKER_ACTIVE", "LIFECYCLE_WORKER_UNAVAILABLE", "LIFECYCLE_WORKER_SERVER_HOSTED", "lifecycle_worker_started", False, True),
+    PlatformComponent("operations_console", "component.operations_console", "UI_SERVICE", "access", "OPERATIONS_CONSOLE_AVAILABLE", "OPERATIONS_CONSOLE_UNAVAILABLE", "OPERATIONS_CONSOLE_SERVER_NATIVE", "operations_console_available"),
+    PlatformComponent(
+        "dashboard_relay", "component.dashboard_relay", "UI_SERVICE", "access",
+        "DASHBOARD_RELAY_ACTIVE", "DASHBOARD_RELAY_UNAVAILABLE",
+        "DASHBOARD_RELAY_SERVER_NATIVE", "dashboard_relay_available",
+        restart_supported=True,
+        lifecycle_label="com.engineeringplatform.dashboard-relay",
+    ),
+    PlatformComponent("http_ingress", "transport.http", "TRANSPORT", "ingress", "HTTP_INGRESS_HEALTHY", "HTTP_INGRESS_DOWN", "CENTRAL_LISTENER_ENDPOINT", "http_ingress_available", False, True),
+    PlatformComponent("cli_ingress", "transport.cli", "TRANSPORT", "ingress", "CLI_INGRESS_AVAILABLE", "CLI_INGRESS_DEGRADED", "CANONICAL_SUBMISSION_COMPATIBILITY", "cli_ingress_available", False, True),
+    PlatformComponent("file_inbox_ingress", "transport.file", "TRANSPORT", "ingress", "FILE_INGRESS_RUNNING", "FILE_INGRESS_STOPPED", "FILE_INBOX_HEARTBEAT", "file_inbox_service_started"),
+    PlatformComponent("dependabot_producer", "component.dependabot_producer", "TRANSPORT", "ingress", "DEPENDABOT_READY", "DEPENDABOT_DEGRADED", "DEPENDABOT_HEARTBEAT", "dependabot_producer_started"),
+)
+PLATFORM_COMPONENT_BY_ID = {component.id: component for component in PLATFORM_COMPONENTS}
+PLATFORM_COMPONENT_IDS = frozenset(PLATFORM_COMPONENT_BY_ID)
+# The installed product has exactly these submission boundaries.  The Local
+# Consumer API is historical compatibility code, not a fourth ingress.
+SUPPORTED_SUBMISSION_INGRESSES = ("HTTP_JSON", "INSTALLED_CLI", "FILE_INBOX")
+SUPPORTED_SUBMISSION_INGRESS_COUNT = len(SUPPORTED_SUBMISSION_INGRESSES)
+# Route consumers import this value instead of duplicating a literal inventory.
+PLATFORM_COMPONENT_ROUTE_PATTERN = "(?:" + "|".join(component.id for component in PLATFORM_COMPONENTS) + ")"
+
+# These are retired *input* identifiers, not components and never aliases for
+# a supported component.  Keeping the bounded denial list beside the canonical
+# model prevents a compatibility parser or route from quietly turning one back
+# into lifecycle, logging or configuration authority.
+RETIRED_COMPONENT_ALIASES = frozenset({
+    "dashboard",
+    "dashboard_service",
+    "dashboard_watcher",
+    "finder",
+    "inbox",
+    "inbox_service",
+    "inbox_watcher",
+    "watcher",
+})
+RETIRED_COMPONENT_ALIAS_ROUTE_PATTERN = "(?:" + "|".join(sorted(RETIRED_COMPONENT_ALIASES)) + ")"

engineering_platform/platform_version.py

@@ -0,0 +1,171 @@
+"""Deterministic Engineering Platform manifest and compatibility validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+
+from .storage import ENGINEERING_STORAGE_SCHEMA_VERSION
+
+
+SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+CONTRACT = re.compile(r"^(\d{4})\.(0[1-9]|1[0-2])$")
+CURRENT_PLATFORM_VERSION = "2.2.0"
+MANIFEST_FIELDS = frozenset(
+    {
+        "platform_version",
+        "runner_version",
+        "bootstrap_contract",
+        "checkpoint_format",
+        "memory_format",
+        "report_format",
+        "minimum_codex_cli",
+        "watcher_version",
+        "inbox_protocol",
+        "dashboard_version",
+        "handoff_protocol",
+        "status_model",
+        "storage_schema",
+    }
+)
+
+
+class EngineeringPlatformCompatibilityError(ValueError):
+    """Raised when a repository's declared engineering contract is unsupported."""
+
+
+def _semver(value: str, field: str) -> tuple[int, int, int]:
+    match = SEMVER.fullmatch(value) if isinstance(value, str) else None
+    if not match:
+        raise EngineeringPlatformCompatibilityError(
+            f"Engineering Platform manifest field {field} must use MAJOR.MINOR.PATCH."
+        )
+    return tuple(int(part) for part in match.groups())
+
+
+def _contract(value: str, field: str) -> tuple[int, int]:
+    match = CONTRACT.fullmatch(value) if isinstance(value, str) else None
+    if not match:
+        raise EngineeringPlatformCompatibilityError(
+            f"Engineering Platform manifest field {field} must use YYYY.MM."
+        )
+    return tuple(int(part) for part in match.groups())
+
+
+@dataclass(frozen=True)
+class EngineeringPlatformManifest:
+    platform_version: str
+    runner_version: str
+    bootstrap_contract: str
+    checkpoint_format: int
+    memory_format: int
+    report_format: int
+    minimum_codex_cli: str
+    watcher_version: str
+    inbox_protocol: int
+    dashboard_version: str
+    handoff_protocol: int
+    status_model: int
+    storage_schema: int
+
+    @classmethod
+    def load(cls, path: Path) -> "EngineeringPlatformManifest":
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise EngineeringPlatformCompatibilityError(
+                "Engineering Platform manifest cannot be read."
+            ) from error
+        if not isinstance(raw, dict) or set(raw) != MANIFEST_FIELDS:
+            raise EngineeringPlatformCompatibilityError(
+                "Engineering Platform manifest fields are incompatible."
+            )
+        manifest = cls(**raw)
+        _semver(manifest.platform_version, "platform_version")
+        _semver(manifest.runner_version, "runner_version")
+        _semver(manifest.minimum_codex_cli, "minimum_codex_cli")
+        _semver(manifest.watcher_version, "watcher_version")
+        _semver(manifest.dashboard_version, "dashboard_version")
+        _contract(manifest.bootstrap_contract, "bootstrap_contract")
+        for field in (
+            "checkpoint_format",
+            "memory_format",
+            "report_format",
+            "inbox_protocol",
+            "handoff_protocol",
+            "status_model",
+            "storage_schema",
+        ):
+            if not isinstance(getattr(manifest, field), int) or getattr(manifest, field) < 1:
+                raise EngineeringPlatformCompatibilityError(
+                    f"Engineering Platform manifest field {field} must be a positive integer."
+                )
+        return manifest
+
+
+@dataclass(frozen=True)
+class RunnerCompatibility:
+    platform_version: str = CURRENT_PLATFORM_VERSION
+    runner_version: str = CURRENT_PLATFORM_VERSION
+    bootstrap_contract: str = "2026.12"
+    checkpoint_formats: frozenset[int] = frozenset({1})
+    memory_formats: frozenset[int] = frozenset({1, 2})
+    report_formats: frozenset[int] = frozenset({1, 2})
+    # New runners retain compatibility with prior local stores while accepting
+    # the current telemetry-capable schema.
+    storage_schemas: frozenset[int] = frozenset(
+        range(1, ENGINEERING_STORAGE_SCHEMA_VERSION + 1)
+    )
+
+
+def validate_compatibility(
+    manifest: EngineeringPlatformManifest, runner: RunnerCompatibility, detected_codex_cli: str
+) -> None:
+    """Fail closed unless this runner explicitly supports every repository contract."""
+    required_platform = _semver(manifest.platform_version, "platform_version")
+    actual_platform = _semver(runner.platform_version, "runner platform_version")
+    required_runner = _semver(manifest.runner_version, "runner_version")
+    actual_runner = _semver(runner.runner_version, "runner_version")
+    if required_platform[0] != actual_platform[0]:
+        raise EngineeringPlatformCompatibilityError(
+            f"Engineering Platform mismatch\nRepository requires: {manifest.platform_version}\nRunner: {runner.platform_version}\nBLOCKED\nEngineering Platform upgrade required."
+        )
+    if actual_runner < required_runner:
+        raise EngineeringPlatformCompatibilityError(
+            f"Runner version mismatch\nRepository requires: {manifest.runner_version}\nRunner: {runner.runner_version}\nBLOCKED\nRunner upgrade required."
+        )
+    required_contract = _contract(manifest.bootstrap_contract, "bootstrap_contract")
+    actual_contract = _contract(runner.bootstrap_contract, "runner bootstrap_contract")
+    if actual_contract < required_contract:
+        raise EngineeringPlatformCompatibilityError(
+            f"Bootstrap contract mismatch\nRepository requires: {manifest.bootstrap_contract}\nRunner: {runner.bootstrap_contract}\nBLOCKED\nEngineering Platform upgrade required."
+        )
+    for label, required, supported in (
+        ("Checkpoint format", manifest.checkpoint_format, runner.checkpoint_formats),
+        ("Engineering Memory format", manifest.memory_format, runner.memory_formats),
+        ("Report format", manifest.report_format, runner.report_formats),
+        ("Engineering storage schema", manifest.storage_schema, runner.storage_schemas),
+    ):
+        if required not in supported:
+            detected = ", ".join(str(value) for value in sorted(supported)) or "none"
+            raise EngineeringPlatformCompatibilityError(
+                f"{label} mismatch\nRepository requires: {required}\nRunner supports: {detected}\nBLOCKED\nEngineering Platform upgrade required."
+            )
+    required_cli = _semver(manifest.minimum_codex_cli, "minimum_codex_cli")
+    detected_cli = _semver(detected_codex_cli, "detected Codex CLI version")
+    if detected_cli < required_cli:
+        raise EngineeringPlatformCompatibilityError(
+            f"Codex CLI version mismatch\nRepository requires: {manifest.minimum_codex_cli}\nDetected: {detected_codex_cli}\nBLOCKED\nCodex CLI upgrade required."
+        )
+
+
+def detected_codex_cli_version(output: str) -> str:
+    """Extract a stable semantic version from the local CLI version output."""
+    match = re.search(r"\b(\d+\.\d+\.\d+)\b", output)
+    if not match:
+        raise EngineeringPlatformCompatibilityError(
+            "Detected Codex CLI version is invalid. Run `codex --version` and install a supported release."
+        )
+    return match.group(1)