loopx 0.4.8__py3-none-any.whl

loopx/control_plane/runtime/status_projection_cache.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from ...history import load_registry
+from ...paths import resolve_runtime_root
+from ..todos.contract import normalize_required_capabilities
+from .time import now_utc as runtime_now_utc
+from .time import now_utc_iso as runtime_now_utc_iso
+from .time import parse_timestamp
+
+
+STATUS_PROJECTION_CACHE_SCHEMA_VERSION = "status_projection_cache_v0"
+
+
+def _normalized_available_capabilities(value: Any) -> list[str]:
+    return sorted(normalize_required_capabilities(value))
+
+
+def now_utc() -> datetime:
+    return runtime_now_utc()
+
+
+def now_utc_iso() -> str:
+    return runtime_now_utc_iso()
+
+
+def resolve_status_projection_cache_runtime_root(
+    *,
+    registry_path: Path,
+    runtime_root_override: str | None,
+) -> Path:
+    registry = load_registry(registry_path)
+    return resolve_runtime_root(
+        registry,
+        runtime_root_override,
+        registry_path=registry_path,
+    )
+
+
+def status_projection_cache_dir(runtime_root: Path) -> Path:
+    return runtime_root / "status-projection-cache"
+
+
+def status_projection_cache_key(
+    *,
+    registry_path: Path,
+    runtime_root: Path,
+    scan_roots: list[Path],
+    limit: int,
+    include_task_graph: bool,
+    goal_id: str | None,
+    available_capabilities: Any = None,
+) -> str:
+    request = {
+        "schema_version": STATUS_PROJECTION_CACHE_SCHEMA_VERSION,
+        "collector": "collect_status",
+        "registry_path": str(registry_path.expanduser().resolve()),
+        "runtime_root": str(runtime_root.expanduser()),
+        "scan_roots": [str(path.expanduser().resolve()) for path in scan_roots],
+        "limit": max(0, int(limit)),
+        "include_task_graph": bool(include_task_graph),
+        "goal_id": str(goal_id or "").strip() or None,
+        "available_capabilities": _normalized_available_capabilities(
+            available_capabilities
+        ),
+    }
+    encoded = json.dumps(
+        request,
+        ensure_ascii=True,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def status_projection_cache_path(runtime_root: Path, key: str) -> Path:
+    return status_projection_cache_dir(runtime_root) / f"{key}.json"
+
+
+def status_projection_cache_metadata(
+    *,
+    registry_path: Path,
+    runtime_root: Path,
+    scan_roots: list[Path],
+    limit: int,
+    include_task_graph: bool,
+    goal_id: str | None,
+    max_age_seconds: int,
+    available_capabilities: Any = None,
+) -> dict[str, Any]:
+    key = status_projection_cache_key(
+        registry_path=registry_path,
+        runtime_root=runtime_root,
+        scan_roots=scan_roots,
+        limit=limit,
+        include_task_graph=include_task_graph,
+        goal_id=goal_id,
+        available_capabilities=available_capabilities,
+    )
+    normalized_capabilities = _normalized_available_capabilities(
+        available_capabilities
+    )
+    return {
+        "schema_version": STATUS_PROJECTION_CACHE_SCHEMA_VERSION,
+        "key": key,
+        "path": str(status_projection_cache_path(runtime_root, key)),
+        "max_age_seconds": max(0, int(max_age_seconds)),
+        "goal_id": str(goal_id or "").strip() or None,
+        "limit": max(0, int(limit)),
+        "include_task_graph": bool(include_task_graph),
+        "scan_roots": [str(path.expanduser()) for path in scan_roots],
+        "available_capabilities": normalized_capabilities,
+    }
+
+
+def load_status_projection_cache(
+    *,
+    registry_path: Path,
+    runtime_root: Path,
+    scan_roots: list[Path],
+    limit: int,
+    include_task_graph: bool,
+    goal_id: str | None,
+    max_age_seconds: int,
+    available_capabilities: Any = None,
+) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+    metadata = status_projection_cache_metadata(
+        registry_path=registry_path,
+        runtime_root=runtime_root,
+        scan_roots=scan_roots,
+        limit=limit,
+        include_task_graph=include_task_graph,
+        goal_id=goal_id,
+        max_age_seconds=max_age_seconds,
+        available_capabilities=available_capabilities,
+    )
+    path = Path(str(metadata["path"]))
+    metadata["hit"] = False
+    if max_age_seconds < 0:
+        metadata["miss_reason"] = "disabled"
+        return None, metadata
+    if not path.exists():
+        metadata["miss_reason"] = "missing"
+        return None, metadata
+    try:
+        cache_record = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        metadata["miss_reason"] = "unreadable"
+        metadata["error"] = str(exc)
+        return None, metadata
+    if not isinstance(cache_record, dict):
+        metadata["miss_reason"] = "invalid_record"
+        return None, metadata
+    if cache_record.get("schema_version") != STATUS_PROJECTION_CACHE_SCHEMA_VERSION:
+        metadata["miss_reason"] = "schema_mismatch"
+        return None, metadata
+    generated_at = parse_timestamp(cache_record.get("generated_at"))
+    if generated_at is None:
+        metadata["miss_reason"] = "missing_generated_at"
+        return None, metadata
+    age_seconds = max(0.0, (now_utc() - generated_at).total_seconds())
+    metadata["generated_at"] = cache_record.get("generated_at")
+    metadata["age_seconds"] = age_seconds
+    if age_seconds > max(0, int(max_age_seconds)):
+        metadata["miss_reason"] = "expired"
+        return None, metadata
+    payload = cache_record.get("payload")
+    if not isinstance(payload, dict):
+        metadata["miss_reason"] = "missing_payload"
+        return None, metadata
+    metadata["hit"] = True
+    metadata["miss_reason"] = None
+    payload = dict(payload)
+    payload["projection_cache"] = dict(metadata)
+    return payload, metadata
+
+
+def write_status_projection_cache(
+    *,
+    registry_path: Path,
+    runtime_root: Path,
+    scan_roots: list[Path],
+    limit: int,
+    include_task_graph: bool,
+    goal_id: str | None,
+    payload: dict[str, Any],
+    max_age_seconds: int,
+    available_capabilities: Any = None,
+) -> dict[str, Any]:
+    metadata = status_projection_cache_metadata(
+        registry_path=registry_path,
+        runtime_root=runtime_root,
+        scan_roots=scan_roots,
+        limit=limit,
+        include_task_graph=include_task_graph,
+        goal_id=goal_id,
+        max_age_seconds=max_age_seconds,
+        available_capabilities=available_capabilities,
+    )
+    path = Path(str(metadata["path"]))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    stored_payload = dict(payload)
+    stored_payload.pop("projection_cache", None)
+    record = {
+        "schema_version": STATUS_PROJECTION_CACHE_SCHEMA_VERSION,
+        "generated_at": now_utc_iso(),
+        "payload": stored_payload,
+    }
+    temp_path = path.with_name(f".{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+    try:
+        temp_path.write_text(
+            json.dumps(record, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        temp_path.replace(path)
+    finally:
+        try:
+            temp_path.unlink()
+        except FileNotFoundError:
+            pass
+    metadata.update(
+        {
+            "hit": False,
+            "written": True,
+            "generated_at": record["generated_at"],
+        }
+    )
+    return metadata

loopx/control_plane/runtime/stride_observation.py

@@ -0,0 +1,144 @@
+"""Read-only hierarchical stride observation (RFC #3204, M1 shadow slice).
+
+This module derives a provider-neutral ``hierarchical_stride_observation_v0``
+projection from existing public-safe run receipts. It is observation only:
+it never changes Todo selection, scheduler cadence, quota spend,
+notification, gates, or execution behavior (``shadow_only`` is always true).
+Fields that cannot be derived from existing receipts stay ``unknown`` rather
+than being guessed from prose or command names.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+STRIDE_OBSERVATION_SCHEMA_VERSION = "hierarchical_stride_observation_v0"
+STRIDE_EVALUATION_SCHEMA_VERSION = "hierarchical_stride_evaluation_v0"
+EVIDENCE_FRESH_WINDOW_HOURS = 6
+AUTHORITY_CHANGE_MARKERS = ("replan", "vision", "gate")
+
+
+def _compact_text(value: Any, *, limit: int = 180) -> str:
+    return " ".join(str(value or "").strip().split())[:limit]
+
+
+def read_run_index(runtime_root: Path, goal_id: str) -> list[dict[str, Any]]:
+    """Read one goal's durable public run index (best effort, tolerant)."""
+
+    index_path = runtime_root / "goals" / goal_id / "runs" / "index.jsonl"
+    if not index_path.exists():
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in index_path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(row, dict):
+            rows.append(row)
+    return rows
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    text = _compact_text(value, limit=80)
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def build_stride_observation(
+    runtime_root: Path,
+    *,
+    goal_id: str,
+    agent_id: str,
+) -> dict[str, Any]:
+    """Project a shadow-only stride observation from existing run receipts."""
+
+    runs = read_run_index(runtime_root, goal_id)
+    agent_runs = [
+        run
+        for run in runs
+        if _compact_text(run.get("agent_id")) == agent_id
+    ]
+    generated_at = datetime.now(UTC)
+    fresh_cutoff = generated_at - timedelta(hours=EVIDENCE_FRESH_WINDOW_HOURS)
+    latest_run = agent_runs[-1] if agent_runs else None
+    latest_generated_at = _parse_timestamp(
+        (latest_run or {}).get("generated_at")
+    )
+    evidence_fresh = (
+        latest_generated_at is not None
+        and latest_generated_at >= fresh_cutoff
+    )
+
+    authority_change_index: int | None = None
+    for index, run in enumerate(agent_runs):
+        classification = _compact_text(run.get("classification"), limit=240)
+        lowered = classification.lower()
+        if any(marker in lowered for marker in AUTHORITY_CHANGE_MARKERS):
+            authority_change_index = index
+    bounded_slices_since_change = (
+        len(agent_runs) - authority_change_index - 1
+        if authority_change_index is not None
+        else len(agent_runs)
+    )
+
+    material_slices = sum(
+        1
+        for run in agent_runs
+        if _compact_text(run.get("delivery_outcome")) == "outcome_progress"
+    )
+    latest_outcome = (
+        _compact_text((latest_run or {}).get("delivery_outcome"), limit=60)
+        or "none"
+    )
+
+    mismatch_signals: list[str] = []
+    if agent_runs and not evidence_fresh:
+        mismatch_signals.append("settlement_lag")
+
+    return {
+        "schema_version": STRIDE_OBSERVATION_SCHEMA_VERSION,
+        "lineage": {
+            "goal_id": _compact_text(goal_id),
+            "agent_id": _compact_text(agent_id),
+            "source_run_count": len(agent_runs),
+        },
+        "delivery": {
+            "material_slices": material_slices,
+            "latest_outcome": latest_outcome,
+            "evidence_fresh": evidence_fresh,
+        },
+        "authority": {
+            "bounded_slices_since_change": bounded_slices_since_change,
+            "segment_disposition": "unknown",
+        },
+        "effect": {
+            "unknown": True,
+        },
+        "mismatch_signals": mismatch_signals,
+        "shadow_only": True,
+    }
+
+
+def evaluate_stride_observation(observation: dict[str, Any]) -> dict[str, Any]:
+    """Offline evaluator: report derived mismatch signals, recommend nothing."""
+
+    signals = list(observation.get("mismatch_signals") or [])
+    return {
+        "schema_version": STRIDE_EVALUATION_SCHEMA_VERSION,
+        "signals": signals,
+        "recommendations": [],
+        "shadow_only": True,
+    }

loopx/control_plane/runtime/time.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def parse_timestamp(value: Any) -> datetime | None:
+    if not value:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def now_utc_iso() -> str:
+    return utc_isoformat(now_utc())
+
+
+def now_local_iso() -> str:
+    return datetime.now(timezone.utc).astimezone().replace(microsecond=0).isoformat()
+
+
+def utc_isoformat(value: datetime) -> str:
+    return value.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def utc_timestamp() -> str:
+    return now_utc().strftime("%Y%m%dT%H%M%SZ")

loopx/control_plane/runtime/trajectory_hygiene.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+from collections import Counter
+from collections.abc import Mapping
+from typing import Any
+
+
+TRAJECTORY_HYGIENE_SCHEMA_VERSION = "trajectory_hygiene_summary_v0"
+CONTROLLER_CLASSIFICATION_PREFIXES = ("quota_",)
+CONTROLLER_CLASSIFICATIONS = {
+    "state_refreshed",
+}
+MATERIAL_DELIVERY_OUTCOMES = {
+    "outcome_gap",
+    "outcome_progress",
+    "primary_goal_outcome",
+}
+
+
+def _ratio(numerator: int, denominator: int) -> float:
+    if denominator <= 0:
+        return 0.0
+    return round(numerator / denominator, 4)
+
+
+def _truthy(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value or "").strip().lower() in {"1", "true", "yes"}
+
+
+def _compact_chars(run: Mapping[str, Any]) -> int:
+    return len(json.dumps(dict(run), ensure_ascii=False, sort_keys=True, separators=(",", ":")))
+
+
+def compact_history_event_channel(run: Mapping[str, Any]) -> str:
+    """Classify one public-safe compact history row without reading run artifacts."""
+
+    if isinstance(run.get("human_reward"), Mapping) or isinstance(run.get("operator_gate"), Mapping):
+        return "human_decision"
+
+    classification = str(run.get("classification") or "").strip().lower()
+    if classification in CONTROLLER_CLASSIFICATIONS or classification.startswith(
+        CONTROLLER_CLASSIFICATION_PREFIXES
+    ):
+        return "controller"
+
+    if str(run.get("delivery_outcome") or "").strip() in MATERIAL_DELIVERY_OUTCOMES:
+        return "outcome"
+    return "task_event"
+
+
+def _material_transition(run: Mapping[str, Any], channel: str) -> bool:
+    if _truthy(run.get("material_change")):
+        return True
+    if channel == "human_decision":
+        return True
+    return str(run.get("delivery_outcome") or "").strip() in MATERIAL_DELIVERY_OUTCOMES
+
+
+def build_trajectory_hygiene_summary(history: Mapping[str, Any]) -> dict[str, Any]:
+    """Build training-hygiene proxies from compact history metadata only.
+
+    The summary intentionally does not claim that compact run history is a model
+    training trajectory. It measures controller density and attribution gaps so
+    maintainers can decide whether a separate learning projection is warranted.
+    """
+
+    runs = [run for run in history.get("runs") or [] if isinstance(run, Mapping)]
+    channel_counts: Counter[str] = Counter()
+    classification_counts: Counter[str] = Counter()
+    controller_chars = 0
+    total_chars = 0
+    non_material_count = 0
+    learning_candidate_count = 0
+    learning_action_count = 0
+    learning_outcome_count = 0
+    decision_anchor_count = 0
+    learning_actions: list[str] = []
+
+    for run in runs:
+        channel = compact_history_event_channel(run)
+        channel_counts[channel] += 1
+        classification = str(run.get("classification") or "unknown").strip() or "unknown"
+        classification_counts[classification] += 1
+
+        char_count = _compact_chars(run)
+        total_chars += char_count
+        if channel == "controller":
+            controller_chars += char_count
+        if not _material_transition(run, channel):
+            non_material_count += 1
+
+        if channel == "controller":
+            continue
+
+        learning_candidate_count += 1
+        action = " ".join(str(run.get("recommended_action") or "").split())
+        outcome = str(run.get("delivery_outcome") or "").strip()
+        if action:
+            learning_action_count += 1
+            learning_actions.append(action)
+        if outcome:
+            learning_outcome_count += 1
+        if action and outcome:
+            decision_anchor_count += 1
+
+    action_counts = Counter(learning_actions)
+    duplicate_action_count = sum(max(0, count - 1) for count in action_counts.values())
+    total_count = len(runs)
+    controller_count = channel_counts["controller"]
+
+    return {
+        "ok": True,
+        "schema_version": TRAJECTORY_HYGIENE_SCHEMA_VERSION,
+        "goal_filter": history.get("goal_filter"),
+        "sample": {
+            "compact_history_row_count": total_count,
+            "goal_count": history.get("goal_count"),
+            "source": "public_safe_compact_run_index",
+        },
+        "channel_counts": dict(sorted(channel_counts.items())),
+        "classification_counts": dict(classification_counts.most_common()),
+        "metrics": {
+            "controller_event_ratio": _ratio(controller_count, total_count),
+            "compact_controller_char_ratio": _ratio(controller_chars, total_chars),
+            "non_material_event_ratio": _ratio(non_material_count, total_count),
+            "learning_candidate_count": learning_candidate_count,
+            "learning_action_coverage": _ratio(learning_action_count, learning_candidate_count),
+            "learning_outcome_coverage": _ratio(learning_outcome_count, learning_candidate_count),
+            "decision_anchor_coverage": _ratio(decision_anchor_count, learning_candidate_count),
+            "duplicate_learning_action_ratio": _ratio(
+                duplicate_action_count,
+                learning_action_count,
+            ),
+        },
+        "training_boundary": {
+            "raw_session_read": False,
+            "raw_trajectory_read": False,
+            "run_artifact_read": False,
+            "compact_index_only": True,
+            "seed_model_training_eligible": False,
+            "reason": (
+                "compact history is an audit baseline, not a learning trajectory; "
+                "export model-visible task turns separately and link controller events by stable ids"
+            ),
+        },
+    }

loopx/control_plane/runtime/validation_command.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+# Frozen wire id shared with capabilities/issue_fix. Kept verbatim for wire
+# compatibility with existing caller-repo-branch receipts.
+CALLER_VALIDATION_RECEIPT_SCHEMA_VERSION = "issue_fix_validation_command_v0"
+
+
+def run_caller_validation(
+    workspace: Path,
+    *,
+    validation_command: str | None = None,
+    validation_argv: list[str] | None = None,
+    validation_label: str,
+    timeout_seconds: int,
+) -> dict[str, Any]:
+    """Run a caller-approved validation command and return a privacy-safe receipt.
+
+    Exactly one of ``validation_command`` (shell-free ``shlex.split``) or
+    ``validation_argv`` (pre-split JSON argv array, no shell parsing) selects
+    the command form. The command runs with ``cwd=workspace``.
+    Only ``exit_code`` and the boolean ``passed`` are recorded; command stdout,
+    stderr, and local paths are deliberately not captured. A timeout raises
+    ``subprocess.TimeoutExpired``; callers decide whether to convert that into
+    a failure receipt.
+    """
+    if (validation_command is None) == (validation_argv is None):
+        raise ValueError(
+            "exactly one of validation_command or validation_argv is required"
+        )
+    argv = (
+        [str(item) for item in validation_argv]
+        if validation_argv is not None
+        else shlex.split(validation_command or "")
+    )
+    if not argv:
+        raise ValueError("validation command must not be empty")
+    result = subprocess.run(
+        argv,
+        cwd=workspace,
+        env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=timeout_seconds,
+    )
+    return {
+        "schema_version": CALLER_VALIDATION_RECEIPT_SCHEMA_VERSION,
+        "command_label": validation_label or "caller-declared validation",
+        "exit_code": result.returncode,
+        "passed": result.returncode == 0,
+        "stdout_captured": False,
+        "stderr_captured": False,
+        "local_path_captured": False,
+    }
+
+
+def require_validation_passed(step: Mapping[str, Any]) -> None:
+    """Raise ``RuntimeError`` unless the validation step ``passed``."""
+    if step.get("passed") is not True:
+        raise RuntimeError(
+            f"{step.get('command_label')} failed with exit code {step.get('exit_code')}"
+        )

loopx/control_plane/scheduler/__init__.py

@@ -0,0 +1 @@
+"""Scheduler and monitor-display control-plane helpers."""