loopx 0.4.8__py3-none-any.whl

loopx/control_plane/runtime/shared_runtime_material_projection.py

@@ -0,0 +1,332 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from ...global_registry import sync_project_registry_to_global
+from .run_compaction import (
+    compact_operator_gate,
+    compact_operator_gate_resume_contract,
+)
+from .runtime_projection_route import (
+    compact_runtime_projection_route,
+    resolve_runtime_projection_route,
+)
+from .runtime_projection_writer import write_compact_runtime_projection
+
+
+SHARED_RUNTIME_MATERIAL_PROJECTION_SCHEMA_VERSION = (
+    "shared_runtime_material_projection_v0"
+)
+SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER = "shared_runtime_material_projection"
+MATERIAL_PROJECTION_KINDS = {
+    "dreaming_decision",
+    "operator_gate_decision",
+    "read_only_project_map",
+}
+
+
+def prepare_material_projection_route(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    source_runtime_root: Path,
+    sync_global: bool,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Resolve and compact the route before the source event is appended."""
+
+    route = resolve_runtime_projection_route(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        source_runtime_root=source_runtime_root,
+    )
+    compact = compact_runtime_projection_route(route)
+    compact["projection_enabled"] = bool(sync_global)
+    compact["projection_marker_field"] = SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER
+    return route, compact
+
+
+def _compact_dreaming_decision(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    compact = {
+        field: value[field]
+        for field in (
+            "schema_version",
+            "proposal_id",
+            "decision",
+            "reason_summary",
+            "promoted_to_delivery",
+            "promoted_todo_id",
+            "created_todo_id",
+            "todo_added",
+            "delivery_spend_allowed",
+            "quota_spent",
+        )
+        if field in value
+    }
+    return compact or None
+
+
+def _compact_source_dreaming_proposal(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    compact = {
+        field: value[field]
+        for field in (
+            "generated_at",
+            "classification",
+            "proposal_id",
+            "proposal_type",
+            "evidence_window",
+            "summary",
+        )
+        if field in value
+    }
+    return compact or None
+
+
+def build_shared_runtime_material_projection(
+    *,
+    source_row: dict[str, Any],
+    projection_kind: str,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build one compact, allowlisted shared-runtime event projection."""
+
+    if projection_kind not in MATERIAL_PROJECTION_KINDS:
+        raise ValueError(
+            "projection_kind must be one of: "
+            + ", ".join(sorted(MATERIAL_PROJECTION_KINDS))
+        )
+
+    route = (
+        source_row.get("runtime_projection_route")
+        if isinstance(source_row.get("runtime_projection_route"), dict)
+        else {}
+    )
+    marker: dict[str, Any] = {
+        "schema_version": SHARED_RUNTIME_MATERIAL_PROJECTION_SCHEMA_VERSION,
+        "projection_kind": projection_kind,
+        "source_generated_at": source_row.get("generated_at"),
+        "raw_artifacts_copied": False,
+        "recommended_action_copied": False,
+    }
+    if route.get("route_id"):
+        marker["runtime_projection_route_id"] = route["route_id"]
+
+    projection: dict[str, Any] = {
+        field: source_row[field]
+        for field in (
+            "generated_at",
+            "goal_id",
+            "classification",
+            "health_check",
+            "delivery_batch_scale",
+            "delivery_outcome",
+        )
+        if field in source_row
+    }
+    if projection_kind == "operator_gate_decision":
+        operator_gate = compact_operator_gate(source_row.get("operator_gate"))
+        if operator_gate:
+            projection["operator_gate"] = operator_gate
+        resume_contract = compact_operator_gate_resume_contract(
+            source_row.get("operator_gate_resume_contract")
+        )
+        if resume_contract:
+            resume_contract.pop("resulting_action", None)
+            projection["operator_gate_resume_contract"] = resume_contract
+    elif projection_kind == "read_only_project_map":
+        project_map = source_row.get("project_map")
+        if isinstance(project_map, dict):
+            projection["project_map"] = dict(project_map)
+    else:
+        dreaming_decision = _compact_dreaming_decision(
+            source_row.get("dreaming_decision")
+        )
+        if dreaming_decision:
+            projection["dreaming_decision"] = dreaming_decision
+        source_proposal = _compact_source_dreaming_proposal(
+            source_row.get("source_dreaming_proposal")
+        )
+        if source_proposal:
+            projection["source_dreaming_proposal"] = source_proposal
+
+    projection[SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER] = marker
+    marker["source_projection_sha256_16"] = hashlib.sha256(
+        json.dumps(projection, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+    index_record = dict(projection)
+    return projection, index_record
+
+
+def _render_projection_markdown(record: dict[str, Any]) -> str:
+    marker = record.get(SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER) or {}
+    return "\n".join(
+        [
+            "# LoopX Shared Runtime Material Projection",
+            "",
+            f"- goal_id: `{record.get('goal_id')}`",
+            f"- classification: `{record.get('classification')}`",
+            f"- generated_at: `{record.get('generated_at')}`",
+            f"- projection_kind: `{marker.get('projection_kind')}`",
+            f"- raw_artifacts_copied: `{marker.get('raw_artifacts_copied')}`",
+            f"- recommended_action_copied: `{marker.get('recommended_action_copied')}`",
+            f"- runtime_projection_route_id: `{marker.get('runtime_projection_route_id')}`",
+        ]
+    )
+
+
+def write_shared_runtime_material_projection(
+    *,
+    shared_runtime_root: Path,
+    goal_id: str,
+    record: dict[str, Any],
+    index_record: dict[str, Any],
+    dry_run: bool,
+) -> dict[str, Any]:
+    result = write_compact_runtime_projection(
+        target_runtime_root=shared_runtime_root,
+        goal_id=goal_id,
+        record=record,
+        index_record=index_record,
+        marker_field=SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER,
+        identity_fields=(
+            "source_generated_at",
+            "source_projection_sha256_16",
+        ),
+        markdown_renderer=_render_projection_markdown,
+        dry_run=dry_run,
+    )
+    marker = record[SHARED_RUNTIME_MATERIAL_PROJECTION_MARKER]
+    result.update(
+        {
+            "shared_runtime_root": str(shared_runtime_root),
+            "projection_kind": marker.get("projection_kind"),
+            "raw_artifacts_copied": False,
+            "recommended_action_copied": False,
+            "source_generated_at": marker.get("source_generated_at"),
+        }
+    )
+    return result
+
+
+def finalize_material_projection(
+    *,
+    registry_path: Path,
+    source_runtime_root: Path,
+    goal_id: str,
+    source_row: dict[str, Any],
+    projection_kind: str,
+    route: dict[str, Any],
+    sync_global: bool,
+    dry_run: bool,
+) -> dict[str, Any]:
+    """Sync the registry and project a source-first material event."""
+
+    disabled_sync = {
+        "enabled": False,
+        "global_registry": str(source_runtime_root / "registry.global.json"),
+        "synced_goal_ids": [],
+        "wrote": False,
+    }
+    projection_base = {
+        "dry_run": dry_run,
+        "projection_kind": projection_kind,
+        "raw_artifacts_copied": False,
+        "recommended_action_copied": False,
+    }
+    if not sync_global:
+        return {
+            "ok": True,
+            "partial_write": False,
+            "global_sync": disabled_sync,
+            "shared_runtime_material_projection": {
+                **projection_base,
+                "ok": True,
+                "status": "disabled",
+            },
+        }
+
+    route_status = str(route.get("status") or "missing")
+    if route_status in {"missing", "ambiguous"}:
+        return {
+            "ok": False,
+            "partial_write": not dry_run,
+            "global_sync": {
+                "ok": False,
+                "enabled": False,
+                "wrote": False,
+                "reason": f"runtime projection route is {route_status}",
+                "route_status": route_status,
+            },
+            "shared_runtime_material_projection": {
+                **projection_base,
+                "ok": False,
+                "status": f"route_{route_status}",
+            },
+        }
+
+    target_text = str(route.get("target_runtime_root") or "").strip()
+    target_runtime = Path(target_text) if target_text else source_runtime_root
+    global_sync = sync_project_registry_to_global(
+        registry_path=registry_path,
+        runtime_root_override=str(target_runtime),
+        goal_id=goal_id,
+        dry_run=dry_run,
+    )
+    if route_status == "single_runtime":
+        return {
+            "ok": bool(global_sync.get("ok")),
+            "partial_write": bool(not dry_run and not global_sync.get("ok")),
+            "global_sync": global_sync,
+            "shared_runtime_material_projection": {
+                **projection_base,
+                "ok": bool(global_sync.get("ok")),
+                "status": (
+                    "not_required" if global_sync.get("ok") else "blocked_by_global_sync"
+                ),
+            },
+        }
+
+    if not global_sync.get("ok"):
+        return {
+            "ok": False,
+            "partial_write": not dry_run,
+            "global_sync": global_sync,
+            "shared_runtime_material_projection": {
+                **projection_base,
+                "ok": False,
+                "status": "blocked_by_global_sync",
+                "shared_runtime_root": str(target_runtime),
+            },
+        }
+
+    record, index_record = build_shared_runtime_material_projection(
+        source_row=source_row,
+        projection_kind=projection_kind,
+    )
+    try:
+        projection = write_shared_runtime_material_projection(
+            shared_runtime_root=target_runtime,
+            goal_id=goal_id,
+            record=record,
+            index_record=index_record,
+            dry_run=dry_run,
+        )
+    except OSError as exc:
+        projection = {
+            **projection_base,
+            "ok": False,
+            "status": "write_failed",
+            "shared_runtime_root": str(target_runtime),
+            "error": str(exc),
+        }
+    return {
+        "ok": bool(projection.get("ok")),
+        "partial_write": bool(not dry_run and not projection.get("ok")),
+        "global_sync": global_sync,
+        "shared_runtime_material_projection": projection,
+    }

loopx/control_plane/runtime/shared_runtime_refresh_projection.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from ..goals.goal_vision import compact_goal_vision_packet
+from .runtime_projection_route import (
+    resolve_runtime_projection_route,
+)
+from .runtime_projection_writer import write_compact_runtime_projection
+
+
+SHARED_RUNTIME_PROJECTION_SCHEMA_VERSION = "shared_runtime_refresh_projection_v0"
+ISO_LIKE_TIMESTAMP_RE = re.compile(r"[0-9TZ:+.\-]{10,64}")
+
+
+def registered_shared_runtime_root(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    source_runtime_root: Path,
+) -> Path | None:
+    """Compatibility wrapper over the first-class runtime projection route."""
+
+    route = resolve_runtime_projection_route(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        source_runtime_root=source_runtime_root,
+    )
+    if route.get("status") != "resolved":
+        return None
+    target = str(route.get("target_runtime_root") or "").strip()
+    return Path(target) if target else None
+
+
+def build_shared_runtime_projection(
+    *,
+    record: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build the compact allowlisted record consumed by shared status/quota."""
+
+    state = record.get("state") if isinstance(record.get("state"), dict) else {}
+    frontmatter = (
+        state.get("frontmatter") if isinstance(state.get("frontmatter"), dict) else {}
+    )
+    updated_at = str(frontmatter.get("updated_at") or "").strip()
+    if not ISO_LIKE_TIMESTAMP_RE.fullmatch(updated_at):
+        updated_at = ""
+    marker = {
+        "schema_version": SHARED_RUNTIME_PROJECTION_SCHEMA_VERSION,
+        "source": "refresh_state",
+        "source_generated_at": record.get("generated_at"),
+        "raw_artifacts_copied": False,
+        "recommended_action_copied": False,
+    }
+    route_marker = (
+        record.get("runtime_projection_route")
+        if isinstance(record.get("runtime_projection_route"), dict)
+        else {}
+    )
+    if route_marker.get("route_id"):
+        marker["runtime_projection_route_id"] = route_marker["route_id"]
+    projection: dict[str, Any] = {
+        "generated_at": record.get("generated_at"),
+        "goal_id": record.get("goal_id"),
+        "classification": record.get("classification"),
+        "health_check": "project-local refresh projected to registered shared runtime",
+        "state": {
+            "sha256_16": state.get("sha256_16"),
+            "frontmatter": {"updated_at": updated_at or None},
+        },
+        "shared_runtime_projection": marker,
+    }
+    compact_vision = compact_goal_vision_packet(record.get("agent_vision"))
+    if compact_vision:
+        projection["agent_vision"] = compact_vision
+    for field in (
+        "delivery_batch_scale",
+        "delivery_outcome",
+        "progress_scope",
+        "agent_id",
+        "agent_lane",
+        "vision_checkpoint",
+    ):
+        if field in record:
+            projection[field] = record[field]
+
+    ack = (
+        record.get("autonomous_replan_ack")
+        if isinstance(record.get("autonomous_replan_ack"), dict)
+        else {}
+    )
+    if ack:
+        compact_ack = {
+            field: ack[field]
+            for field in ("schema_version", "recorded", "source", "requested")
+            if field in ack
+        }
+        delta = ack.get("delta_contract") if isinstance(ack.get("delta_contract"), dict) else {}
+        if delta:
+            compact_ack["delta_contract"] = {
+                field: delta[field]
+                for field in (
+                    "schema_version",
+                    "required",
+                    "delta_present",
+                    "delta_kinds",
+                    "accepted_without_delta",
+                )
+                if field in delta
+            }
+        projection["autonomous_replan_ack"] = compact_ack
+
+    marker["source_projection_sha256_16"] = hashlib.sha256(
+        json.dumps(projection, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+    projected_index = {
+        key: projection[key]
+        for key in (
+            "generated_at",
+            "goal_id",
+            "classification",
+            "health_check",
+            "state",
+            "delivery_batch_scale",
+            "delivery_outcome",
+            "progress_scope",
+            "agent_id",
+            "agent_lane",
+            "autonomous_replan_ack",
+            "agent_vision",
+            "vision_checkpoint",
+            "shared_runtime_projection",
+        )
+        if key in projection
+    }
+    return projection, projected_index
+
+
+def _render_projection_markdown(record: dict[str, Any]) -> str:
+    marker = record.get("shared_runtime_projection") or {}
+    return "\n".join(
+        [
+            "# LoopX Shared Runtime Refresh Projection",
+            "",
+            f"- goal_id: `{record.get('goal_id')}`",
+            f"- classification: `{record.get('classification')}`",
+            f"- generated_at: `{record.get('generated_at')}`",
+            f"- agent_id: `{record.get('agent_id')}`",
+            f"- raw_artifacts_copied: `{marker.get('raw_artifacts_copied')}`",
+            f"- recommended_action_copied: `{marker.get('recommended_action_copied')}`",
+            f"- runtime_projection_route_id: `{marker.get('runtime_projection_route_id')}`",
+        ]
+    )
+
+
+def write_shared_runtime_projection(
+    *,
+    shared_runtime_root: Path,
+    goal_id: str,
+    record: dict[str, Any],
+    index_record: dict[str, Any],
+    dry_run: bool,
+) -> dict[str, Any]:
+    marker = record["shared_runtime_projection"]
+    result = write_compact_runtime_projection(
+        target_runtime_root=shared_runtime_root,
+        goal_id=goal_id,
+        record=record,
+        index_record=index_record,
+        marker_field="shared_runtime_projection",
+        identity_fields=("source_generated_at", "source_projection_sha256_16"),
+        markdown_renderer=_render_projection_markdown,
+        dry_run=dry_run,
+    )
+    result["shared_runtime_root"] = str(shared_runtime_root)
+    result["raw_artifacts_copied"] = False
+    result["recommended_action_copied"] = False
+    result["source_generated_at"] = marker.get("source_generated_at")
+    return result

loopx/control_plane/runtime/stale_latest_run.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+PathResolver = Callable[[Any, dict[str, Any]], Optional[Path]]
+FrontmatterParser = Callable[[str], dict[str, str]]
+TimestampParser = Callable[[Any], Any]
+
+
+def stale_latest_run_projection_warning(
+    goal: dict[str, Any],
+    current_run: dict[str, Any] | None,
+    *,
+    agent_lane_progress_scope: str,
+    resolve_goal_local_path: PathResolver,
+    parse_state_frontmatter: FrontmatterParser,
+    parse_timestamp: TimestampParser,
+) -> dict[str, Any] | None:
+    if not isinstance(goal, dict) or not goal.get("registry_member") or not isinstance(current_run, dict):
+        return None
+    state_path = resolve_goal_local_path(goal.get("state_file"), goal)
+    if state_path is None or not state_path.exists():
+        return None
+    try:
+        state_text = state_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    frontmatter = parse_state_frontmatter(state_text)
+    active_updated_at = frontmatter.get("updated_at")
+    active_digest = hashlib.sha256(state_text.encode("utf-8")).hexdigest()[:16]
+    run_state = current_run.get("state") if isinstance(current_run.get("state"), dict) else {}
+    run_frontmatter = run_state.get("frontmatter") if isinstance(run_state.get("frontmatter"), dict) else {}
+    run_state_updated_at = run_frontmatter.get("updated_at")
+    run_state_digest = str(run_state.get("sha256_16") or "")
+    latest_run_generated_at = str(current_run.get("generated_at") or "")
+
+    active_dt = parse_timestamp(active_updated_at)
+    run_state_dt = parse_timestamp(run_state_updated_at)
+    run_generated_dt = parse_timestamp(latest_run_generated_at)
+    active_newer_than_run_state = bool(active_dt and run_state_dt and active_dt > run_state_dt)
+    active_newer_than_run = bool(active_dt and run_generated_dt and active_dt > run_generated_dt)
+    digest_mismatch = bool(run_state_digest and active_digest != run_state_digest)
+    if not (active_newer_than_run_state or active_newer_than_run or digest_mismatch):
+        return None
+    for run in goal.get("latest_runs") if isinstance(goal.get("latest_runs"), list) else []:
+        if not isinstance(run, dict):
+            continue
+        if str(run.get("progress_scope") or "") != agent_lane_progress_scope:
+            continue
+        agent_run_state = run.get("state") if isinstance(run.get("state"), dict) else {}
+        agent_run_frontmatter = (
+            agent_run_state.get("frontmatter")
+            if isinstance(agent_run_state.get("frontmatter"), dict)
+            else {}
+        )
+        agent_run_digest = str(agent_run_state.get("sha256_16") or "")
+        agent_run_updated_at = agent_run_frontmatter.get("updated_at")
+        agent_run_state_dt = parse_timestamp(agent_run_updated_at)
+        agent_run_generated_dt = parse_timestamp(str(run.get("generated_at") or ""))
+        if agent_run_digest and agent_run_digest == active_digest:
+            return None
+        if active_dt and agent_run_state_dt and active_dt <= agent_run_state_dt:
+            return None
+        if active_dt and not agent_run_state_dt and agent_run_generated_dt and active_dt <= agent_run_generated_dt:
+            return None
+
+    reasons: list[str] = []
+    if active_newer_than_run:
+        reasons.append("active_state_updated_after_latest_run")
+    if active_newer_than_run_state:
+        reasons.append("active_state_updated_after_latest_run_snapshot")
+    if digest_mismatch:
+        reasons.append("active_state_digest_differs_from_latest_run_snapshot")
+
+    return {
+        "kind": "stale_latest_run_projection",
+        "source": "active_state_vs_latest_run",
+        "severity": "warning",
+        "requires_refresh_state": True,
+        "reason": ",".join(reasons),
+        "active_state_updated_at": active_updated_at,
+        "latest_run_generated_at": latest_run_generated_at,
+        "latest_run_state_updated_at": run_state_updated_at,
+        "latest_run_classification": current_run.get("classification"),
+        "recommended_action": "run refresh-state before trusting latest_run-derived routing",
+    }

loopx/control_plane/runtime/status_classifications.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+"""Pure status classification sets owned by the runtime read model.
+
+`loopx.status` re-exports these names for compatibility. No module in this
+file may import from ``loopx.status`` or other presentation surfaces.
+"""
+
+
+CODEX_READY_CLASSIFICATIONS = {
+    "controller_opted_in_waiting_for_run",
+    "design_next_experiment",
+    "inspect_eval_result",
+    "inspect_result",
+    "needs_more_read_only_evidence",
+    "needs_validation",
+    "public_harness_healthy",
+    "read_only_project_map",
+    "run_validation",
+    "state_refreshed",
+    "operator_gate_approved",
+    "monitor_todo_repeat_dedupe_deployed",
+}
+
+HANDOFF_READY_CLASSIFICATIONS = {
+    "operator_gate_approved",
+    "controller_opted_in_waiting_for_run",
+}
+
+DREAMING_ADVISORY_CLASSIFICATIONS = {
+    "dreaming_exploration_proposal",
+    "dreaming_memory_consolidation",
+    "dreaming_refactor_warning",
+    "dreaming_archive_suggestion",
+}
+
+USER_OR_CONTROLLER_CLASSIFICATIONS = {
+    "needs_human_reward",
+    "needs_controller_opt_in",
+    "needs_user_relay",
+    "ready_for_controller_opt_in",
+    "ready_for_user_relay",
+    "operator_gate_deferred",
+    "operator_gate_rejected",
+} | DREAMING_ADVISORY_CLASSIFICATIONS
+
+BLOCKING_CLASSIFICATIONS = {
+    "blocked_by_safety",
+}