loopx 0.4.8__py3-none-any.whl

loopx/control_plane/runtime/event_ledger.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Callable, Iterable, Optional
+
+from .time import now_utc
+
+EVENT_LEDGER_CLASSES = (
+    "accounting",
+    "decision",
+    "evidence",
+    "state",
+    "work",
+)
+EVENT_LEDGER_PROXY_NOTE = "append-only run-history projection; compact event-class counts only"
+
+ParseTimestamp = Callable[[Any], Any]
+RunCompactor = Callable[[dict[str, Any]], Optional[dict[str, Any]]]
+RunPredicate = Callable[[dict[str, Any]], bool]
+
+
+def blank_event_class_counts(
+    event_classes: Iterable[str] = EVENT_LEDGER_CLASSES,
+) -> dict[str, int]:
+    return {event_class: 0 for event_class in event_classes}
+
+
+def blank_event_ledger_goal(
+    goal_id: str,
+    *,
+    event_classes: Iterable[str] = EVENT_LEDGER_CLASSES,
+) -> dict[str, Any]:
+    return {
+        "goal_id": goal_id,
+        "events_24h": 0,
+        "events_7d": 0,
+        "benchmark_runs_24h": 0,
+        "benchmark_runs_7d": 0,
+        "by_class_24h": blank_event_class_counts(event_classes),
+        "by_class_7d": blank_event_class_counts(event_classes),
+        "latest_event_class": None,
+        "latest_event_at": None,
+        "latest_benchmark_run": None,
+    }
+
+
+def event_ledger_event_class(
+    run: dict[str, Any],
+    *,
+    compact_benchmark_run: RunCompactor,
+    compact_benchmark_result: RunCompactor,
+    compact_benchmark_comparison: RunCompactor,
+    compact_benchmark_learning_ledger: RunCompactor,
+    compact_benchmark_experiment_report: RunCompactor,
+    compact_active_user_assisted_pilot: RunCompactor,
+    run_has_external_evidence_watch_signal: RunPredicate,
+    decision_classifications: set[str],
+    evidence_classifications: set[str],
+    evidence_hints: tuple[str, ...],
+    state_classifications: set[str],
+) -> str:
+    classification = str(run.get("classification") or "").lower()
+    if classification == "quota_slot_spent" or isinstance(run.get("quota_event"), dict):
+        return "accounting"
+    if (
+        compact_benchmark_run(run)
+        or compact_benchmark_result(run)
+        or compact_benchmark_comparison(run)
+        or compact_benchmark_learning_ledger(run)
+        or compact_benchmark_experiment_report(run)
+        or compact_active_user_assisted_pilot(run)
+    ):
+        return "evidence"
+    if (
+        classification in decision_classifications
+        or "operator_gate" in classification
+        or "human_reward" in classification
+        or "reward" in classification
+        or isinstance(run.get("human_reward"), dict)
+        or isinstance(run.get("operator_gate"), dict)
+        or isinstance(run.get("operator_gate_resume_contract"), dict)
+    ):
+        return "decision"
+    if classification in evidence_classifications:
+        return "evidence"
+    if run_has_external_evidence_watch_signal(run):
+        return "evidence"
+    if any(hint in classification for hint in evidence_hints):
+        return "evidence"
+    if any(
+        key in run
+        for key in (
+            "active_priorities",
+            "active_task_count",
+            "artifact",
+            "artifacts",
+            "cache_check",
+            "controller_readiness",
+            "project_map",
+        )
+    ):
+        return "evidence"
+    if classification in state_classifications or classification.endswith("_refreshed"):
+        return "state"
+    return "work"
+
+
+def build_event_ledger_summary(
+    history: dict[str, Any],
+    *,
+    parse_timestamp: ParseTimestamp,
+    event_class_for_run: Callable[[dict[str, Any]], str],
+    compact_benchmark_run: RunCompactor,
+    event_classes: tuple[str, ...] = EVENT_LEDGER_CLASSES,
+    proxy_note: str = EVENT_LEDGER_PROXY_NOTE,
+) -> dict[str, Any]:
+    now = now_utc()
+    cutoff_24h = now - timedelta(hours=24)
+    cutoff_7d = now - timedelta(days=7)
+    totals = {
+        "events_24h": 0,
+        "events_7d": 0,
+        "benchmark_runs_24h": 0,
+        "benchmark_runs_7d": 0,
+        "by_class_24h": blank_event_class_counts(event_classes),
+        "by_class_7d": blank_event_class_counts(event_classes),
+    }
+    goals: dict[str, dict[str, Any]] = {}
+    sample_count = 0
+
+    for run in history.get("runs") or []:
+        if not isinstance(run, dict):
+            continue
+        sample_count += 1
+        generated_at = parse_timestamp(run.get("generated_at"))
+        if generated_at is None:
+            continue
+        event_class = event_class_for_run(run)
+        goal_id = str(run.get("goal_id") or "unknown-goal")
+        goal = goals.setdefault(
+            goal_id,
+            blank_event_ledger_goal(goal_id, event_classes=event_classes),
+        )
+        latest_event_at = parse_timestamp(goal.get("latest_event_at"))
+        if latest_event_at is None or generated_at > latest_event_at:
+            goal["latest_event_class"] = event_class
+            goal["latest_event_at"] = generated_at.isoformat()
+        benchmark_run = compact_benchmark_run(run)
+        if benchmark_run:
+            latest_benchmark_at = parse_timestamp(
+                (goal.get("latest_benchmark_run") or {}).get("generated_at")
+                if isinstance(goal.get("latest_benchmark_run"), dict)
+                else None
+            )
+            if latest_benchmark_at is None or generated_at > latest_benchmark_at:
+                goal["latest_benchmark_run"] = {
+                    "generated_at": generated_at.isoformat(),
+                    "classification": run.get("classification"),
+                    **benchmark_run,
+                }
+
+        if generated_at >= cutoff_7d:
+            totals["events_7d"] += 1
+            totals["by_class_7d"][event_class] += 1
+            goal["events_7d"] += 1
+            goal["by_class_7d"][event_class] += 1
+            if benchmark_run:
+                totals["benchmark_runs_7d"] += 1
+                goal["benchmark_runs_7d"] += 1
+        if generated_at >= cutoff_24h:
+            totals["events_24h"] += 1
+            totals["by_class_24h"][event_class] += 1
+            goal["events_24h"] += 1
+            goal["by_class_24h"][event_class] += 1
+            if benchmark_run:
+                totals["benchmark_runs_24h"] += 1
+                goal["benchmark_runs_24h"] += 1
+
+    goal_rows = sorted(
+        goals.values(),
+        key=lambda item: (
+            item["events_24h"],
+            item["events_7d"],
+            item["goal_id"],
+        ),
+        reverse=True,
+    )
+    return {
+        "available": True,
+        "source": "run_history",
+        "generated_at": now.isoformat(),
+        "sample_run_count": sample_count,
+        "proxy_note": proxy_note,
+        "event_classes": list(event_classes),
+        "totals": totals,
+        "goals": goal_rows,
+    }

loopx/control_plane/runtime/event_store_migration_bridge.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+EVENT_STORE_MIGRATION_BRIDGE_SCHEMA_VERSION = "event_store_migration_bridge_v0"
+EVENT_STORE_MIGRATION_CANARY_SCHEMA_VERSION = "event_store_migration_canary_v0"
+
+MARKDOWN_ACTIVE_STATE_SOURCE = "markdown_active_state"
+EVENT_PROJECTION_SOURCE = "event_projection"
+
+
+def _compact_text(value: Any) -> str:
+    return " ".join(str(value or "").strip().split())
+
+
+def _bool(value: Any) -> bool:
+    return value is True
+
+
+def build_event_store_migration_bridge(
+    *,
+    goal_id: str,
+    event_read_path_ready: bool,
+    dual_read_parity_clean: bool = False,
+    rollback_plan_recorded: bool = False,
+    bounded_canary_passed: bool = False,
+    idempotency_conflicts_clean: bool = False,
+    public_boundary_clean: bool = False,
+    active_state_projection_ready: bool = False,
+    event_projection_head_matches_store: bool = False,
+    canary_goal_limit: int = 1,
+    canary_duration_minutes: int = 30,
+    evidence_refs: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build a fail-closed migration bridge before event projection promotion."""
+
+    normalized_goal_id = _compact_text(goal_id)
+    if not normalized_goal_id:
+        raise ValueError("goal_id is required")
+    canary_goal_limit = max(1, int(canary_goal_limit or 1))
+    canary_duration_minutes = max(1, int(canary_duration_minutes or 1))
+    evidence = [_compact_text(ref) for ref in (evidence_refs or []) if _compact_text(ref)]
+
+    checks = {
+        "event_read_path_ready": _bool(event_read_path_ready),
+        "active_state_projection_ready": _bool(active_state_projection_ready),
+        "dual_read_parity_clean": _bool(dual_read_parity_clean),
+        "event_projection_head_matches_store": _bool(event_projection_head_matches_store),
+        "rollback_plan_recorded": _bool(rollback_plan_recorded),
+        "bounded_canary_passed": _bool(bounded_canary_passed),
+        "idempotency_conflicts_clean": _bool(idempotency_conflicts_clean),
+        "public_boundary_clean": _bool(public_boundary_clean),
+    }
+    required_for_shadow = [
+        "event_read_path_ready",
+        "active_state_projection_ready",
+    ]
+    required_for_canary = [
+        *required_for_shadow,
+        "dual_read_parity_clean",
+        "event_projection_head_matches_store",
+        "rollback_plan_recorded",
+        "idempotency_conflicts_clean",
+        "public_boundary_clean",
+    ]
+    required_for_promotion = [
+        *required_for_canary,
+        "bounded_canary_passed",
+    ]
+    missing_for_shadow = [key for key in required_for_shadow if not checks[key]]
+    missing_for_canary = [key for key in required_for_canary if not checks[key]]
+    missing_for_promotion = [key for key in required_for_promotion if not checks[key]]
+
+    if missing_for_shadow:
+        stage = "wait_for_event_read_path"
+        next_action = (
+            "finish event read-path prerequisites before dual-read migration work"
+        )
+    elif missing_for_canary:
+        stage = "dual_read_shadow"
+        next_action = (
+            "compare Markdown read model and event projection until parity, rollback, "
+            "idempotency, and public-boundary checks are clean"
+        )
+    elif missing_for_promotion:
+        stage = "bounded_canary"
+        next_action = (
+            "run the bounded canary on a small goal set before promotion"
+        )
+    else:
+        stage = "promotion_candidate"
+        next_action = (
+            "promote event projection only through an explicit reviewed write-path change"
+        )
+
+    return {
+        "schema_version": EVENT_STORE_MIGRATION_BRIDGE_SCHEMA_VERSION,
+        "goal_id": normalized_goal_id,
+        "source_of_truth": MARKDOWN_ACTIVE_STATE_SOURCE,
+        "candidate_source": EVENT_PROJECTION_SOURCE,
+        "stage": stage,
+        "promotion_allowed": False,
+        "promotion_candidate": not missing_for_promotion,
+        "next_action": next_action,
+        "checks": checks,
+        "missing_for_shadow": missing_for_shadow,
+        "missing_for_canary": missing_for_canary,
+        "missing_for_promotion": missing_for_promotion,
+        "dual_read": {
+            "enabled": not missing_for_shadow,
+            "read_order": [
+                MARKDOWN_ACTIVE_STATE_SOURCE,
+                EVENT_PROJECTION_SOURCE,
+            ],
+            "failure_policy": "prefer_markdown_and_record_parity_delta",
+            "required_equality": [
+                "todo ids",
+                "todo status",
+                "priority and planner order",
+                "claimed_by",
+                "user todo binding",
+                "gate refs",
+                "projection head sequence",
+            ],
+        },
+        "rollback": {
+            "required": True,
+            "recorded": checks["rollback_plan_recorded"],
+            "fallback_source": MARKDOWN_ACTIVE_STATE_SOURCE,
+            "trigger": [
+                "parity delta",
+                "projection head mismatch",
+                "event append conflict",
+                "public boundary warning",
+                "canary regression",
+            ],
+            "action": "disable event projection preference and keep Markdown parser as canonical read fallback",
+        },
+        "canary": build_event_store_migration_canary(
+            goal_id=normalized_goal_id,
+            ready=not missing_for_canary,
+            passed=checks["bounded_canary_passed"],
+            goal_limit=canary_goal_limit,
+            duration_minutes=canary_duration_minutes,
+            evidence_refs=evidence,
+        ),
+        "evidence_refs": evidence,
+    }
+
+
+def build_event_store_migration_canary(
+    *,
+    goal_id: str,
+    ready: bool,
+    passed: bool = False,
+    goal_limit: int = 1,
+    duration_minutes: int = 30,
+    evidence_refs: list[str] | None = None,
+) -> dict[str, Any]:
+    """Describe the bounded rollout canary for event-store read promotion."""
+
+    normalized_goal_id = _compact_text(goal_id)
+    if not normalized_goal_id:
+        raise ValueError("goal_id is required")
+    goal_limit = max(1, int(goal_limit or 1))
+    duration_minutes = max(1, int(duration_minutes or 1))
+    evidence = [_compact_text(ref) for ref in (evidence_refs or []) if _compact_text(ref)]
+
+    return {
+        "schema_version": EVENT_STORE_MIGRATION_CANARY_SCHEMA_VERSION,
+        "goal_id": normalized_goal_id,
+        "ready": bool(ready),
+        "passed": bool(passed),
+        "scope": {
+            "max_goals": goal_limit,
+            "duration_minutes": duration_minutes,
+            "write_path": "disabled",
+            "read_preference": MARKDOWN_ACTIVE_STATE_SOURCE,
+        },
+        "observe": [
+            "status todo summaries",
+            "quota selected todo",
+            "review packet todo refs",
+            "dashboard/frontstage projection",
+            "event projection head sequence",
+        ],
+        "success_criteria": [
+            "no parity delta",
+            "no idempotency conflict",
+            "no private-boundary warning",
+            "rollback remains one-command safe",
+        ],
+        "failure_policy": "stop canary and keep Markdown parser canonical",
+        "evidence_refs": evidence,
+    }

loopx/control_plane/runtime/goal_project_route.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ...history import load_registry
+from ...paths import registry_project_root
+from ...registry import registry_goals
+from .runtime_projection_route import resolve_goal_source_runtime_route
+
+
+def resolve_goal_project_route(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    project_override: str | Path | None = None,
+) -> tuple[dict[str, Any], Path, dict[str, Any]]:
+    """Resolve a goal-scoped control-plane command to its canonical project.
+
+    Shared registries are read models.  A command invoked from a linked worktree
+    must therefore follow ``goal.source_registry`` before resolving relative,
+    local-private configuration pointers.  An explicit project remains a
+    consistency assertion; it must not silently replace the registered route.
+    """
+
+    route = resolve_goal_source_runtime_route(
+        registry_path=registry_path,
+        goal_id=goal_id,
+    )
+    source_registry = Path(str(route["source_registry"])).expanduser().resolve()
+
+    def load_goal(path: Path) -> tuple[dict[str, Any], dict[str, Any] | None]:
+        payload = load_registry(path)
+        matched = next(
+            (
+                item
+                for item in registry_goals(payload)
+                if str(item.get("id") or "") == goal_id
+            ),
+            None,
+        )
+        return payload, matched if isinstance(matched, dict) else None
+
+    _, goal = load_goal(source_registry)
+    if goal is None and project_override is not None:
+        requested = Path(project_override).expanduser().resolve()
+        project_registry = requested / ".loopx" / "registry.json"
+        if project_registry.is_file() and project_registry.resolve() != source_registry:
+            route = resolve_goal_source_runtime_route(
+                registry_path=project_registry,
+                goal_id=goal_id,
+            )
+            source_registry = Path(str(route["source_registry"])).expanduser().resolve()
+            _, goal = load_goal(source_registry)
+    if not isinstance(goal, dict):
+        raise ValueError(f"goal_id not found in canonical source registry: {goal_id}")
+    raw_repo = str(goal.get("repo") or "").strip()
+    if not raw_repo:
+        raise ValueError("connected goal repository is required")
+    project = Path(raw_repo).expanduser()
+    if not project.is_absolute():
+        project = registry_project_root(source_registry) / project
+    project = project.resolve()
+    if project_override is not None:
+        requested = Path(project_override).expanduser().resolve()
+        if requested != project:
+            raise ValueError(
+                "--project must match the canonical connected goal repository"
+            )
+    return goal, project, route