loopx 0.4.8__py3-none-any.whl

loopx/benchmark_core/attempts.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Mapping
+
+from .lifecycle import (
+    BenchmarkLifecyclePhase,
+    canonical_lifecycle,
+)
+
+
+BENCHMARK_ATTEMPT_ACCOUNTING_SCHEMA_VERSION = "benchmark_attempt_accounting_v0"
+
+
+class BenchmarkAttemptPhase(str, Enum):
+    LAUNCHER = "launcher"
+    CASE = "case"
+    SOLVER = "solver"
+    VERIFIER = "verifier"
+    OFFICIAL_SCORE = "official_score"
+
+
+class BenchmarkFailureClass(str, Enum):
+    NONE = "none"
+    RUNNER_STARTUP_FAILED = "runner_startup_failed"
+    JOB_MATERIALIZATION_FAILED = "job_materialization_failed"
+    SOLVER_FAILED = "solver_failed"
+    VERIFIER_FAILED = "verifier_failed"
+    OFFICIAL_SCORE_FAILED = "official_score_failed"
+    UNKNOWN_FAILED = "unknown_failed"
+
+
+FAILURE_CLASS_LABELS = {
+    BenchmarkFailureClass.RUNNER_STARTUP_FAILED.value: (
+        "runner_startup_failed",
+        "process_start_failed",
+        "runner_argument_rejected",
+        "runner_accept_args_failed",
+    ),
+    BenchmarkFailureClass.JOB_MATERIALIZATION_FAILED.value: (
+        "job_materialization_failed",
+        "job_root_missing",
+        "job_root_not_materialized",
+        "job_materialization_timeout",
+        "detached_worker_ended_without_job_root",
+    ),
+    BenchmarkFailureClass.SOLVER_FAILED.value: (
+        "solver_failed",
+        "agent_failed",
+        "worker_failed",
+        "worker_ended_without_result",
+        "result_missing",
+        "result_finalization_failed",
+    ),
+    BenchmarkFailureClass.VERIFIER_FAILED.value: (
+        "verifier_failed",
+        "verifier_timeout",
+        "verifier_error",
+        "oracle_failed",
+        "official_verifier_failed",
+    ),
+    BenchmarkFailureClass.OFFICIAL_SCORE_FAILED.value: (
+        "official_score_failed",
+        "official_score_missing",
+        "official_score_error",
+        "scorer_failed",
+        "score_ingest_failed",
+    ),
+}
+
+
+def _normalize(value: Any) -> str:
+    return str(value or "").strip().lower().replace("-", "_").replace(" ", "_")
+
+
+def _coerce_lifecycle(lifecycle: Mapping[str, Any] | None) -> dict[str, Any]:
+    if not isinstance(lifecycle, Mapping):
+        return canonical_lifecycle()
+    if lifecycle.get("schema_version"):
+        return dict(lifecycle)
+    return canonical_lifecycle(**lifecycle)
+
+
+def classify_benchmark_failure(
+    failure_label: str | None,
+    *,
+    lifecycle: Mapping[str, Any] | None = None,
+    default: BenchmarkFailureClass = BenchmarkFailureClass.UNKNOWN_FAILED,
+) -> BenchmarkFailureClass:
+    """Return an adapter-neutral failure class for compact benchmark ledgers."""
+
+    label = _normalize(failure_label)
+    if not label:
+        return BenchmarkFailureClass.NONE
+    for failure_class, aliases in FAILURE_CLASS_LABELS.items():
+        if label == failure_class or label in aliases:
+            return BenchmarkFailureClass(failure_class)
+
+    lifecycle_projection = _coerce_lifecycle(lifecycle)
+    phase = lifecycle_projection.get("current_phase", BenchmarkLifecyclePhase.NOT_STARTED.value)
+    phase_ready = lifecycle_projection.get("phase_ready") or {}
+    if not phase_ready.get(BenchmarkLifecyclePhase.PROCESS_STARTED.value):
+        return BenchmarkFailureClass.RUNNER_STARTUP_FAILED
+    if phase in {
+        BenchmarkLifecyclePhase.PROCESS_STARTED.value,
+        BenchmarkLifecyclePhase.RUNNER_ACCEPTED_ARGS.value,
+    }:
+        return BenchmarkFailureClass.JOB_MATERIALIZATION_FAILED
+    return default
+
+
+def build_benchmark_attempt_accounting(
+    *,
+    lifecycle: Mapping[str, Any] | None = None,
+    failure_label: str | None = None,
+    failure_class: BenchmarkFailureClass | str | None = None,
+    solver_attempted: bool | None = None,
+    verifier_attempted: bool | None = None,
+    official_score_attempted: bool = False,
+) -> dict[str, Any]:
+    """Build compact, adapter-neutral attempt accounting.
+
+    Launcher/materialization failures are recorded as launcher attempts, but
+    they do not consume case/solver/verifier/official-score attempt budgets.
+    """
+
+    lifecycle_projection = _coerce_lifecycle(lifecycle)
+    phase_ready = lifecycle_projection.get("phase_ready") or {}
+    launcher_attempted = any(
+        bool(phase_ready.get(phase.value))
+        for phase in (
+            BenchmarkLifecyclePhase.PROCESS_STARTED,
+            BenchmarkLifecyclePhase.RUNNER_ACCEPTED_ARGS,
+        )
+    )
+    case_attempted = bool(lifecycle_projection.get("entered_benchmark_case"))
+    solver_seen = any(
+        bool(phase_ready.get(phase.value))
+        for phase in (
+            BenchmarkLifecyclePhase.WORKER_STARTED,
+            BenchmarkLifecyclePhase.RESULT_WRITTEN,
+            BenchmarkLifecyclePhase.VERIFIER_SCORED,
+        )
+    )
+    verifier_seen = bool(phase_ready.get(BenchmarkLifecyclePhase.VERIFIER_SCORED.value))
+    solver_attempted_value = solver_seen if solver_attempted is None else bool(solver_attempted)
+    verifier_attempted_value = verifier_seen if verifier_attempted is None else bool(verifier_attempted)
+
+    if failure_class is None:
+        normalized_failure_class = classify_benchmark_failure(
+            failure_label, lifecycle=lifecycle_projection
+        )
+    elif isinstance(failure_class, BenchmarkFailureClass):
+        normalized_failure_class = failure_class
+    else:
+        normalized_failure_class = BenchmarkFailureClass(_normalize(failure_class))
+
+    attempts = {
+        BenchmarkAttemptPhase.LAUNCHER.value: {
+            "attempted": launcher_attempted,
+            "countable": launcher_attempted,
+        },
+        BenchmarkAttemptPhase.CASE.value: {
+            "attempted": case_attempted,
+            "countable": case_attempted,
+        },
+        BenchmarkAttemptPhase.SOLVER.value: {
+            "attempted": solver_attempted_value,
+            "countable": solver_attempted_value,
+        },
+        BenchmarkAttemptPhase.VERIFIER.value: {
+            "attempted": verifier_attempted_value,
+            "countable": verifier_attempted_value,
+        },
+        BenchmarkAttemptPhase.OFFICIAL_SCORE.value: {
+            "attempted": bool(official_score_attempted),
+            "countable": bool(official_score_attempted),
+        },
+    }
+    return {
+        "schema_version": BENCHMARK_ATTEMPT_ACCOUNTING_SCHEMA_VERSION,
+        "lifecycle_phase": lifecycle_projection.get("current_phase"),
+        "failure_label": str(failure_label or ""),
+        "failure_class": normalized_failure_class.value,
+        "attempts": attempts,
+        "launcher_attempt_countable": attempts[BenchmarkAttemptPhase.LAUNCHER.value][
+            "countable"
+        ],
+        "case_attempt_countable": attempts[BenchmarkAttemptPhase.CASE.value]["countable"],
+        "solver_attempt_countable": attempts[BenchmarkAttemptPhase.SOLVER.value][
+            "countable"
+        ],
+        "verifier_attempt_countable": attempts[BenchmarkAttemptPhase.VERIFIER.value][
+            "countable"
+        ],
+        "official_score_attempt_countable": attempts[
+            BenchmarkAttemptPhase.OFFICIAL_SCORE.value
+        ]["countable"],
+    }

loopx/benchmark_core/container_exec.py

@@ -0,0 +1,216 @@
+"""Container command completion markers shared by benchmark runners."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import re
+import shlex
+import tempfile
+import time
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+_EXIT_STATUS_PATTERN = re.compile(r"^[0-9]{1,3}$")
+
+
+def wrap_container_command_with_exit_status(command: str, status_path: str) -> str:
+    """Run *command* in a subshell and atomically leave its exit status behind."""
+
+    parent = str(PurePosixPath(status_path).parent)
+    return (
+        f"mkdir -p {shlex.quote(parent)} && {{ "
+        f"( {command} ); loopx_command_rc=$?; "
+        f"printf '%s\\n' \"$loopx_command_rc\" > {shlex.quote(status_path)}; "
+        'exit "$loopx_command_rc"; }'
+    )
+
+
+def parse_container_exit_status(payload: bytes | str | None) -> int | None:
+    """Return a valid POSIX shell exit status from a completion marker."""
+
+    if isinstance(payload, bytes):
+        try:
+            text = payload.decode("ascii")
+        except UnicodeDecodeError:
+            return None
+    elif isinstance(payload, str):
+        text = payload
+    else:
+        return None
+    text = text.strip()
+    if not _EXIT_STATUS_PATTERN.fullmatch(text):
+        return None
+    value = int(text)
+    return value if 0 <= value <= 255 else None
+
+
+async def read_container_file_via_compose_copy(
+    compose_fn: Callable[..., Awaitable[Any]],
+    container_path: str,
+    *,
+    service: str,
+    timeout_sec: float,
+) -> bytes | None:
+    """Copy a container file to the host when exec stdout is unreliable."""
+
+    with tempfile.TemporaryDirectory(prefix="loopx-container-file-") as tmp_dir:
+        destination = Path(tmp_dir) / "payload"
+        try:
+            result = await compose_fn(
+                ["cp", f"{service}:{container_path}", str(destination)],
+                check=False,
+                timeout_sec=max(1, min(10, int(timeout_sec))),
+            )
+        except (OSError, RuntimeError, TimeoutError):
+            return None
+        if getattr(result, "return_code", 1) != 0:
+            return None
+        try:
+            return destination.read_bytes()
+        except OSError:
+            return None
+
+
+async def run_container_command_with_exit_status(
+    exec_fn: Callable[..., Awaitable[Any]],
+    command: str,
+    *,
+    timeout_sec: float,
+    exec_args: tuple[Any, ...] = (),
+    exec_kwargs: Mapping[str, Any] | None = None,
+    poll_interval_sec: float = 0.5,
+    status_reader_fn: Callable[[str, str, float], Awaitable[bytes | str | None]]
+    | None = None,
+) -> Any:
+    """Run a container command and wait for its side-channel completion marker."""
+
+    status_path = f"/tmp/loopx-benchmark-exec-status/{uuid.uuid4().hex}.status"
+    kwargs = dict(exec_kwargs or {})
+    kwargs["timeout_sec"] = timeout_sec
+    service = kwargs.get("service", "main")
+    deadline = time.monotonic() + timeout_sec
+    try:
+        result = await exec_fn(
+            wrap_container_command_with_exit_status(command, status_path),
+            *exec_args,
+            **kwargs,
+        )
+        captured_exit_code = None
+        while captured_exit_code is None:
+            remaining = deadline - time.monotonic()
+            if status_reader_fn is not None:
+                payload = await status_reader_fn(status_path, service, remaining)
+            else:
+                probe = await exec_fn(
+                    f"cat {shlex.quote(status_path)} 2>/dev/null",
+                    timeout_sec=max(1.0, min(10.0, max(remaining, 1.0))),
+                    user="root",
+                    service=service,
+                )
+                payload = getattr(probe, "stdout", None)
+            captured_exit_code = parse_container_exit_status(payload)
+            if captured_exit_code is None:
+                if remaining <= 0:
+                    raise asyncio.TimeoutError("container completion marker timed out")
+                await asyncio.sleep(min(poll_interval_sec, remaining))
+        if hasattr(result, "model_copy"):
+            return result.model_copy(update={"return_code": captured_exit_code})
+        setattr(result, "return_code", captured_exit_code)
+        return result
+    finally:
+        with contextlib.suppress(Exception):
+            await exec_fn(
+                f"rm -f {shlex.quote(status_path)}",
+                timeout_sec=10,
+                user="root",
+                service=service,
+            )
+
+
+async def run_container_command_with_output_capture(
+    exec_fn: Callable[..., Awaitable[Any]],
+    command: str,
+    *,
+    timeout_sec: float,
+    exec_args: tuple[Any, ...] = (),
+    exec_kwargs: Mapping[str, Any] | None = None,
+    poll_interval_sec: float = 0.5,
+    file_reader_fn: Callable[[str, str, float], Awaitable[bytes | str | None]],
+) -> Any:
+    """Run a command when attached container exec output is untrustworthy.
+
+    Some Docker client/daemon combinations execute ``compose exec`` but return
+    empty output and status 0 immediately. Capture all three result channels in
+    container files, then read them through the compose copy path.
+    """
+
+    capture_dir = f"/tmp/loopx-benchmark-exec-capture/{uuid.uuid4().hex}"
+    stdout_path = f"{capture_dir}/stdout"
+    stderr_path = f"{capture_dir}/stderr"
+    status_path = f"{capture_dir}/status"
+    kwargs = dict(exec_kwargs or {})
+    kwargs["timeout_sec"] = timeout_sec
+    service = kwargs.get("service", "main")
+    deadline = time.monotonic() + timeout_sec
+    bounded_command = (
+        f"timeout {shlex.quote(str(max(1.0, timeout_sec)))} "
+        f"sh -c {shlex.quote(command)}"
+    )
+    captured_command = (
+        f"{bounded_command} > {shlex.quote(stdout_path)} "
+        f"2> {shlex.quote(stderr_path)}"
+    )
+    try:
+        result = await exec_fn(
+            wrap_container_command_with_exit_status(
+                captured_command,
+                status_path,
+            ),
+            *exec_args,
+            **kwargs,
+        )
+        captured_exit_code = None
+        while captured_exit_code is None:
+            remaining = deadline - time.monotonic()
+            payload = await file_reader_fn(status_path, service, remaining)
+            captured_exit_code = parse_container_exit_status(payload)
+            if captured_exit_code is None:
+                if remaining <= 0:
+                    raise asyncio.TimeoutError(
+                        "container output capture completion marker timed out"
+                    )
+                await asyncio.sleep(min(poll_interval_sec, remaining))
+
+        remaining = max(1.0, deadline - time.monotonic())
+        stdout = await file_reader_fn(stdout_path, service, remaining)
+        stderr = await file_reader_fn(stderr_path, service, remaining)
+        if stdout is None or stderr is None:
+            raise RuntimeError("container output capture unavailable")
+
+        def decoded(value: bytes | str) -> str:
+            if isinstance(value, bytes):
+                return value.decode("utf-8", errors="replace")
+            return value
+
+        update = {
+            "return_code": captured_exit_code,
+            "stdout": decoded(stdout),
+            "stderr": decoded(stderr),
+        }
+        if hasattr(result, "model_copy"):
+            return result.model_copy(update=update)
+        for field, value in update.items():
+            setattr(result, field, value)
+        return result
+    finally:
+        with contextlib.suppress(Exception):
+            await exec_fn(
+                f"rm -rf {shlex.quote(capture_dir)}",
+                timeout_sec=10,
+                user="root",
+                service=service,
+            )

loopx/benchmark_core/io.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_json_object(path: Path) -> dict[str, Any]:
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def load_jsonl_objects(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    try:
+        raw_lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return rows
+    for raw_line in raw_lines:
+        raw_line = raw_line.strip()
+        if not raw_line:
+            continue
+        try:
+            parsed = json.loads(raw_line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            rows.append(parsed)
+    return rows
+
+
+def optional_float(value: Any) -> float | None:
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return None
+    return None
+
+
+def optional_positive_int(value: Any) -> int | None:
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, float) and value.is_integer():
+        parsed = int(value)
+        return parsed if parsed > 0 else None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            parsed_float = float(text)
+        except ValueError:
+            return None
+        if not parsed_float.is_integer():
+            return None
+        parsed = int(parsed_float)
+        return parsed if parsed > 0 else None
+    return None

loopx/benchmark_core/lifecycle.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+BENCHMARK_LIFECYCLE_STATE_SCHEMA_VERSION = "benchmark_lifecycle_state_v0"
+BENCHMARK_CANONICAL_LIFECYCLE_SCHEMA_VERSION = "benchmark_canonical_lifecycle_v0"
+BENCHMARK_LIVE_WORKER_PHASE_SCHEMA_VERSION = "benchmark_live_worker_phase_v0"
+
+
+class BenchmarkLifecyclePhase(str, Enum):
+    NOT_STARTED = "not_started"
+    PROCESS_STARTED = "process_started"
+    RUNNER_ACCEPTED_ARGS = "runner_accepted_args"
+    JOB_ROOT_MATERIALIZED = "job_root_materialized"
+    TRIAL_STARTED = "trial_started"
+    WORKER_STARTED = "worker_started"
+    RESULT_WRITTEN = "result_written"
+    VERIFIER_SCORED = "verifier_scored"
+
+
+class BenchmarkLiveWorkerPhase(str, Enum):
+    NOT_OBSERVED = "not_observed"
+    RUNTIME_PREPARING = "runtime_preparing"
+    WORKER_PREPARED = "worker_prepared"
+    WORKER_RUNNING = "worker_running"
+    AGENT_ACTIVE = "agent_active"
+
+
+CANONICAL_LIFECYCLE_PHASES = tuple(phase.value for phase in BenchmarkLifecyclePhase)
+LIVE_WORKER_PHASES = tuple(phase.value for phase in BenchmarkLiveWorkerPhase)
+LIVE_WORKER_TERMINAL_DISPOSITIONS = (
+    "open",
+    "completed",
+    "failed",
+    "ended_unresolved",
+)
+CASE_ENTRY_PHASES = {
+    BenchmarkLifecyclePhase.JOB_ROOT_MATERIALIZED.value,
+    BenchmarkLifecyclePhase.TRIAL_STARTED.value,
+    BenchmarkLifecyclePhase.WORKER_STARTED.value,
+    BenchmarkLifecyclePhase.RESULT_WRITTEN.value,
+    BenchmarkLifecyclePhase.VERIFIER_SCORED.value,
+}
+
+
+def build_benchmark_live_worker_phase(
+    *,
+    runtime_preparing: bool = False,
+    worker_prepared: bool = False,
+    worker_running: bool = False,
+    agent_active: bool = False,
+    terminal_disposition: str = "open",
+) -> dict[str, Any]:
+    """Project a benchmark-neutral live worker phase from public evidence."""
+
+    if terminal_disposition not in LIVE_WORKER_TERMINAL_DISPOSITIONS:
+        raise ValueError(
+            "terminal_disposition must be one of: "
+            + ", ".join(LIVE_WORKER_TERMINAL_DISPOSITIONS)
+        )
+
+    ready = {
+        BenchmarkLiveWorkerPhase.RUNTIME_PREPARING.value: bool(
+            runtime_preparing or worker_prepared or worker_running or agent_active
+        ),
+        BenchmarkLiveWorkerPhase.WORKER_PREPARED.value: bool(
+            worker_prepared or worker_running or agent_active
+        ),
+        BenchmarkLiveWorkerPhase.WORKER_RUNNING.value: bool(
+            worker_running or agent_active
+        ),
+        BenchmarkLiveWorkerPhase.AGENT_ACTIVE.value: bool(agent_active),
+    }
+    current_phase = BenchmarkLiveWorkerPhase.NOT_OBSERVED.value
+    for candidate in LIVE_WORKER_PHASES[1:]:
+        if ready[candidate]:
+            current_phase = candidate
+        else:
+            break
+
+    terminal = terminal_disposition != "open"
+    next_required_phase = ""
+    if not terminal:
+        for candidate in LIVE_WORKER_PHASES[1:]:
+            if not ready[candidate]:
+                next_required_phase = candidate
+                break
+
+    return {
+        "schema_version": BENCHMARK_LIVE_WORKER_PHASE_SCHEMA_VERSION,
+        "current_phase": current_phase,
+        "next_required_phase": next_required_phase,
+        "phase_ready": ready,
+        "worker_live": bool(ready["worker_running"] and not terminal),
+        "agent_active_observed": ready["agent_active"],
+        "terminal": terminal,
+        "terminal_disposition": terminal_disposition,
+        "public_evidence_only": True,
+    }
+
+
+def compact_benchmark_live_worker_phase(value: Any) -> dict[str, Any]:
+    """Return a normalized public-safe live worker phase projection."""
+
+    if not isinstance(value, dict):
+        return {}
+    if value.get("schema_version") != BENCHMARK_LIVE_WORKER_PHASE_SCHEMA_VERSION:
+        return {}
+
+    phase_ready = value.get("phase_ready")
+    if not isinstance(phase_ready, dict):
+        return {}
+    terminal_disposition = value.get("terminal_disposition")
+    if terminal_disposition not in LIVE_WORKER_TERMINAL_DISPOSITIONS:
+        return {}
+    return build_benchmark_live_worker_phase(
+        runtime_preparing=phase_ready.get("runtime_preparing") is True,
+        worker_prepared=phase_ready.get("worker_prepared") is True,
+        worker_running=phase_ready.get("worker_running") is True,
+        agent_active=phase_ready.get("agent_active") is True,
+        terminal_disposition=terminal_disposition,
+    )
+
+
+def compact_benchmark_live_worker_phase_from_run(value: Any) -> dict[str, Any]:
+    """Read the shared live worker phase from a run or runner prerequisites."""
+
+    if not isinstance(value, dict):
+        return {}
+    phase = compact_benchmark_live_worker_phase(
+        value.get("benchmark_live_worker_phase")
+    )
+    if phase:
+        return phase
+    runner_prerequisites = value.get("runner_prerequisites")
+    if not isinstance(runner_prerequisites, dict):
+        return {}
+    return compact_benchmark_live_worker_phase(
+        runner_prerequisites.get("benchmark_live_worker_phase")
+    )
+
+
+def _coerce_flags(flags: dict[str, Any]) -> dict[str, bool]:
+    coerced: dict[str, bool] = {}
+    previous = True
+    for phase in CANONICAL_LIFECYCLE_PHASES:
+        if phase == BenchmarkLifecyclePhase.NOT_STARTED.value:
+            continue
+        ready = bool(flags.get(phase))
+        coerced[phase] = bool(previous and ready)
+        previous = coerced[phase]
+    return coerced
+
+
+def canonical_lifecycle(**flags: Any) -> dict[str, Any]:
+    """Return an adapter-neutral lifecycle projection.
+
+    `process_started` is intentionally not enough to enter a benchmark case.
+    Control-plane accounting should only treat the case as entered once the
+    job root materializes or a later phase is observed.
+    """
+
+    ready = _coerce_flags(flags)
+    phase = BenchmarkLifecyclePhase.NOT_STARTED.value
+    for candidate in CANONICAL_LIFECYCLE_PHASES[1:]:
+        if ready.get(candidate):
+            phase = candidate
+        else:
+            break
+    entered_case = phase in CASE_ENTRY_PHASES
+    next_required_phase = ""
+    for candidate in CANONICAL_LIFECYCLE_PHASES[1:]:
+        if not ready.get(candidate):
+            next_required_phase = candidate
+            break
+    return {
+        "schema_version": BENCHMARK_CANONICAL_LIFECYCLE_SCHEMA_VERSION,
+        "current_phase": phase,
+        "entered_benchmark_case": entered_case,
+        "case_attempt_countable": entered_case,
+        "next_required_phase": next_required_phase,
+        "phase_ready": ready,
+    }
+
+
+def compact_benchmark_canonical_lifecycle(value: Any) -> dict[str, Any]:
+    """Return the public-safe subset of a canonical lifecycle projection."""
+
+    if not isinstance(value, dict):
+        return {}
+    compact: dict[str, Any] = {}
+    if value.get("schema_version") == BENCHMARK_CANONICAL_LIFECYCLE_SCHEMA_VERSION:
+        compact["schema_version"] = BENCHMARK_CANONICAL_LIFECYCLE_SCHEMA_VERSION
+    for field in ("current_phase", "next_required_phase"):
+        raw = value.get(field)
+        if isinstance(raw, str) and raw in CANONICAL_LIFECYCLE_PHASES:
+            compact[field] = raw
+    for field in ("entered_benchmark_case", "case_attempt_countable"):
+        if isinstance(value.get(field), bool):
+            compact[field] = value[field]
+    phase_ready = value.get("phase_ready")
+    if isinstance(phase_ready, dict):
+        compact_phase_ready: dict[str, bool] = {}
+        for key, ready in phase_ready.items():
+            if key in CANONICAL_LIFECYCLE_PHASES and isinstance(ready, bool):
+                compact_phase_ready[key] = ready
+        if compact_phase_ready:
+            compact["phase_ready"] = compact_phase_ready
+    return compact