loopx 0.4.8__py3-none-any.whl

loopx/control_plane/goals/active_state_event_projection.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from loopx.event_sourced_state import (
+    AppendOnlyStateEventStore,
+    StateEventError,
+    build_state_projection,
+    render_active_state_sections,
+)
+
+
+DEFAULT_STATE_EVENT_LOG_BASENAME = "events.jsonl"
+STATE_EVENT_PROJECTION_SCHEMA_VERSION = "event_sourced_state_status_projection_v0"
+STATE_EVENT_READ_WARNING_SCHEMA_VERSION = "event_sourced_state_read_warning_v0"
+
+ResolveGoalLocalPath = Callable[..., Optional[Path]]
+ParseActiveStateTodos = Callable[..., dict[str, Any]]
+
+
+def state_event_log_candidates(
+    goal: dict[str, Any],
+    *,
+    state_path: Path,
+    resolve_goal_local_path: ResolveGoalLocalPath,
+    event_log_basename: str = DEFAULT_STATE_EVENT_LOG_BASENAME,
+) -> list[Path]:
+    candidates: list[Path] = []
+    for key in ("state_event_log", "state_events_file", "event_log"):
+        resolved = resolve_goal_local_path(goal.get(key), goal, fallback_base=state_path.parent)
+        if resolved is not None:
+            candidates.append(resolved)
+    candidates.append(state_path.with_name(event_log_basename))
+
+    unique: list[Path] = []
+    seen: set[str] = set()
+    for path in candidates:
+        key = str(path.expanduser())
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(path)
+    return unique
+
+
+def active_state_event_projection_fields(
+    goal: dict[str, Any],
+    *,
+    state_path: Path,
+    resolve_goal_local_path: ResolveGoalLocalPath,
+    parse_active_state_todos: ParseActiveStateTodos,
+    preferred_todo_ids: set[str] | None = None,
+    rollout_events: list[dict[str, Any]] | None = None,
+    item_limit: int | None = None,
+    event_log_basename: str = DEFAULT_STATE_EVENT_LOG_BASENAME,
+) -> dict[str, Any]:
+    goal_id = str(goal.get("id") or "").strip()
+    for event_log_path in state_event_log_candidates(
+        goal,
+        state_path=state_path,
+        resolve_goal_local_path=resolve_goal_local_path,
+        event_log_basename=event_log_basename,
+    ):
+        if not event_log_path.exists():
+            continue
+        try:
+            events = AppendOnlyStateEventStore(event_log_path).load()
+            if not events:
+                continue
+            projection = build_state_projection(events, goal_id=goal_id or None)
+            projection_markdown = render_active_state_sections(projection)
+            fields = parse_active_state_todos(
+                projection_markdown,
+                goal=goal,
+                state_path=state_path,
+                preferred_todo_ids=preferred_todo_ids,
+                rollout_events=rollout_events,
+                item_limit=item_limit,
+            )
+        except (OSError, StateEventError) as exc:
+            return {
+                "state_event_projection_warning": {
+                    "schema_version": STATE_EVENT_READ_WARNING_SCHEMA_VERSION,
+                    "source": "event_log",
+                    "event_log": event_log_path.name,
+                    "fallback": "markdown_active_state",
+                    "reason": type(exc).__name__,
+                }
+            }
+        if fields:
+            fields["state_event_projection"] = {
+                "schema_version": STATE_EVENT_PROJECTION_SCHEMA_VERSION,
+                "source": "event_log",
+                "event_log": event_log_path.name,
+                "source_event_count": projection.get("source_event_count"),
+                "source_checksum": projection.get("source_checksum"),
+                "last_event_id": projection.get("last_event_id"),
+                "last_append_sequence": projection.get("last_append_sequence"),
+                "projection_version": projection.get("projection_version"),
+            }
+            return fields
+    return {}

loopx/control_plane/goals/active_state_metadata.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+
+USER_TODO_HEADER_MARKERS = (
+    "user todo",
+    "owner review reading queue",
+    "owner reading queue",
+)
+AGENT_TODO_HEADER_MARKERS = (
+    "agent todo",
+    "codex todo",
+    "project agent todo",
+)
+TODO_ARCHIVE_HEADER_MARKERS = (
+    "todo archive",
+    "work archive",
+    "completed archive",
+    "completed work",
+    "完成归档",
+    "待办归档",
+)
+
+
+def parse_state_frontmatter(state_text: str) -> dict[str, str]:
+    if not state_text.startswith("---"):
+        return {}
+    parts = state_text.split("---", 2)
+    if len(parts) < 3:
+        return {}
+    result: dict[str, str] = {}
+    for line in parts[1].splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        result[key.strip()] = value.strip().strip('"')
+    return result
+
+
+def todo_role_for_heading(heading: str) -> str | None:
+    normalized = heading.strip().lower()
+    if any(marker in normalized for marker in TODO_ARCHIVE_HEADER_MARKERS):
+        return None
+    if any(marker in normalized for marker in USER_TODO_HEADER_MARKERS):
+        return "user"
+    if any(marker in normalized for marker in AGENT_TODO_HEADER_MARKERS):
+        return "agent"
+    return None

loopx/control_plane/goals/active_state_sections.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from typing import Callable
+
+
+NormalizeText = Callable[..., str]
+
+
+def active_state_sections(
+    state_text: str,
+    headings: tuple[str, ...],
+    *,
+    section_heading_pattern: re.Pattern[str],
+) -> dict[str, list[str]]:
+    wanted = {heading.lower(): heading for heading in headings}
+    current: str | None = None
+    sections: dict[str, list[str]] = {heading: [] for heading in headings}
+    for line in state_text.splitlines():
+        match = section_heading_pattern.match(line)
+        if match:
+            normalized = match.group(1).strip().lower()
+            current = wanted.get(normalized)
+            continue
+        if current:
+            sections[current].append(line)
+    return sections
+
+
+def active_state_section_entries(
+    lines: list[str],
+    *,
+    bullet_pattern: re.Pattern[str],
+    normalize_text: NormalizeText,
+) -> list[str]:
+    entries: list[str] = []
+    current: list[str] = []
+    for line in lines:
+        bullet_match = bullet_pattern.match(line)
+        if bullet_match:
+            if current:
+                entries.append(normalize_text(" ".join(current)))
+            current = [bullet_match.group(1)]
+            continue
+        if current and line.startswith((" ", "\t")):
+            continuation = line.strip()
+            if continuation:
+                current.append(continuation)
+            continue
+        if current:
+            entries.append(normalize_text(" ".join(current)))
+            current = []
+        stripped = line.strip()
+        if stripped:
+            entries.append(stripped)
+    if current:
+        entries.append(normalize_text(" ".join(current)))
+    return entries

loopx/control_plane/goals/configure_goal_service.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from ...configure_goal import configure_goal
+from ...global_registry import (
+    sanitize_goal_for_global,
+    sync_project_registry_to_global,
+)
+from ...history import load_registry
+from ...paths import global_registry_path, resolve_runtime_root
+from ...registry import registry_goals
+from ...registry_writability import probe_registry_write_path
+from ..runtime.runtime_projection_route import (
+    compact_runtime_projection_route,
+    resolve_runtime_projection_route,
+)
+
+
+CONFIGURE_GOAL_GLOBAL_SYNC_SCHEMA_VERSION = "configure_goal_global_sync_v0"
+CONFIGURE_GOAL_GLOBAL_SYNC_READBACK_SCHEMA_VERSION = (
+    "configure_goal_global_sync_readback_v0"
+)
+
+
+def _same_path(left: Path, right: Path) -> bool:
+    try:
+        return left.expanduser().resolve() == right.expanduser().resolve()
+    except OSError:
+        return str(left.expanduser()) == str(right.expanduser())
+
+
+def _goal(payload: dict[str, Any], goal_id: str) -> dict[str, Any] | None:
+    return next(
+        (
+            item
+            for item in registry_goals(payload)
+            if str(item.get("id") or "") == goal_id
+        ),
+        None,
+    )
+
+
+def _digest(value: Any) -> str:
+    return hashlib.sha256(
+        json.dumps(value, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def resolve_configure_goal_sync_target(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    runtime_root_override: str | None,
+) -> dict[str, Any]:
+    source_registry = registry_path.expanduser().resolve()
+    source_payload = load_registry(source_registry)
+    if _goal(source_payload, goal_id) is None:
+        raise ValueError(f"goal id not found in source registry: {goal_id}")
+    source_runtime = (
+        resolve_runtime_root(
+            source_payload,
+            None,
+            registry_path=source_registry,
+        )
+        .expanduser()
+        .resolve()
+    )
+
+    if runtime_root_override:
+        target_runtime = Path(runtime_root_override).expanduser().resolve()
+        route = {
+            "schema_version": "runtime_projection_route_v0",
+            "status": "explicit_override",
+            "projection_required": not _same_path(source_runtime, target_runtime),
+            "declaration_source": "cli.runtime_root_override",
+            "source_registry": str(source_registry),
+            "source_runtime_root": str(source_runtime),
+            "target_runtime_root": str(target_runtime),
+            "target_registry": str(global_registry_path(target_runtime)),
+            "match_count": 1,
+            "source_mirror_match_count": 0,
+            "conflict_count": 0,
+            "unreadable_target_count": 0,
+        }
+    else:
+        route = resolve_runtime_projection_route(
+            registry_path=source_registry,
+            goal_id=goal_id,
+            source_runtime_root=source_runtime,
+        )
+        status = str(route.get("status") or "missing")
+        if status not in {"resolved", "single_runtime"}:
+            raise ValueError(
+                f"configure-goal global sync route is {status}; refusing to write "
+                "the source registry without one authoritative shared runtime"
+            )
+        target_text = str(route.get("target_runtime_root") or "").strip()
+        if not target_text:
+            raise ValueError(
+                "configure-goal global sync route has no target runtime; refusing partial write"
+            )
+        target_runtime = Path(target_text).expanduser().resolve()
+
+    target_registry = global_registry_path(target_runtime).expanduser().resolve()
+    return {
+        "ok": True,
+        "schema_version": CONFIGURE_GOAL_GLOBAL_SYNC_SCHEMA_VERSION,
+        "goal_id": goal_id,
+        "status": route.get("status"),
+        "declaration_source": route.get("declaration_source"),
+        "explicit_runtime_override": bool(runtime_root_override),
+        "source_registry": str(source_registry),
+        "source_runtime_root": str(source_runtime),
+        "target_runtime_root": str(target_runtime),
+        "target_global_registry": str(target_registry),
+        "route": compact_runtime_projection_route(route),
+    }
+
+
+def _readback(
+    *,
+    source_registry: Path,
+    target_registry: Path,
+    goal_id: str,
+    sync_payload: dict[str, Any],
+) -> dict[str, Any]:
+    source_payload = load_registry(source_registry)
+    target_payload = load_registry(target_registry)
+    source_goal = _goal(source_payload, goal_id)
+    target_goal = _goal(target_payload, goal_id)
+    synced_at = str(sync_payload.get("updated_at") or "").strip()
+    source_is_target = _same_path(source_registry, target_registry)
+
+    expected_goal = source_goal
+    if source_goal is not None and not source_is_target:
+        expected_goal = sanitize_goal_for_global(
+            source_goal,
+            source_registry=source_registry,
+            synced_at=synced_at,
+        )
+    expected_digest = _digest(expected_goal) if expected_goal is not None else None
+    target_digest = _digest(target_goal) if target_goal is not None else None
+    target_source_registry = str(
+        (target_goal or {}).get("source_registry") or ""
+    ).strip()
+    source_registry_match = bool(
+        target_goal is not None
+        and (
+            source_is_target
+            or (
+                target_source_registry
+                and _same_path(Path(target_source_registry), source_registry)
+            )
+        )
+    )
+    synced_at_match = bool(
+        source_is_target
+        or (
+            target_goal is not None
+            and str(target_goal.get("synced_at") or "") == synced_at
+        )
+    )
+    verified = bool(
+        source_goal is not None
+        and target_goal is not None
+        and expected_digest == target_digest
+        and source_registry_match
+        and synced_at_match
+    )
+    return {
+        "schema_version": CONFIGURE_GOAL_GLOBAL_SYNC_READBACK_SCHEMA_VERSION,
+        "status": "verified" if verified else "mismatch",
+        "verified": verified,
+        "goal_id": goal_id,
+        "target_global_registry": str(target_registry),
+        "goal_present": target_goal is not None,
+        "source_registry_match": source_registry_match,
+        "synced_at_match": synced_at_match,
+        "expected_goal_sha256_16": expected_digest,
+        "target_goal_sha256_16": target_digest,
+    }
+
+
+def _sync_plan(
+    *,
+    changed: bool,
+    target_resolution: dict[str, Any] | None,
+    execute: bool,
+) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "schema_version": CONFIGURE_GOAL_GLOBAL_SYNC_SCHEMA_VERSION,
+        "enabled": bool(changed),
+        "required": bool(changed),
+        "executed": False,
+        "target_resolution": target_resolution,
+        "selected_target": (
+            {
+                "runtime_root": target_resolution.get("target_runtime_root"),
+                "global_registry": target_resolution.get("target_global_registry"),
+                "declaration_source": target_resolution.get("declaration_source"),
+                "explicit_runtime_override": target_resolution.get(
+                    "explicit_runtime_override"
+                ),
+            }
+            if target_resolution
+            else None
+        ),
+        "readback": {
+            "schema_version": CONFIGURE_GOAL_GLOBAL_SYNC_READBACK_SCHEMA_VERSION,
+            "status": "not_required" if not changed else "not_executed",
+            "verified": False,
+        },
+        "reason": (
+            "no configuration change"
+            if not changed
+            else "dry-run preview; source and shared registries are unchanged"
+            if not execute
+            else None
+        ),
+    }
+
+
+def configure_goal_with_global_sync(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    runtime_root_override: str | None,
+    execute: bool,
+    **configure_options: Any,
+) -> dict[str, Any]:
+    """Configure one source goal and keep its authoritative shared read model current."""
+
+    preview = configure_goal(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        execute=False,
+        **configure_options,
+    )
+    changed = bool(preview.get("changed"))
+    target_resolution = (
+        resolve_configure_goal_sync_target(
+            registry_path=registry_path,
+            goal_id=goal_id,
+            runtime_root_override=runtime_root_override,
+        )
+        if changed
+        else None
+    )
+    preview["global_sync"] = _sync_plan(
+        changed=changed,
+        target_resolution=target_resolution,
+        execute=execute,
+    )
+    if not execute:
+        return preview
+
+    if not changed:
+        applied = configure_goal(
+            registry_path=registry_path,
+            goal_id=goal_id,
+            execute=True,
+            **configure_options,
+        )
+        applied["global_sync"] = preview["global_sync"]
+        return applied
+
+    if target_resolution is None:
+        raise RuntimeError("configure-goal sync target was not resolved")
+    target_registry = Path(str(target_resolution["target_global_registry"]))
+    writability = probe_registry_write_path(target_registry, create_parent=True)
+    if not writability.get("ok"):
+        preview.update(
+            {
+                "ok": False,
+                "dry_run": False,
+                "execute": True,
+                "written": False,
+                "error": str(
+                    writability.get("error")
+                    or "authoritative shared registry is not writable"
+                ),
+                "recommended_action": writability.get("recommended_action"),
+            }
+        )
+        preview["global_sync"].update(
+            {
+                "ok": False,
+                "reason": "authoritative shared registry preflight failed",
+                "global_registry_writability": writability,
+            }
+        )
+        return preview
+
+    applied = configure_goal(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        execute=True,
+        **configure_options,
+    )
+    if not applied.get("written"):
+        applied["global_sync"] = _sync_plan(
+            changed=False,
+            target_resolution=target_resolution,
+            execute=True,
+        )
+        return applied
+
+    sync_payload = sync_project_registry_to_global(
+        registry_path=registry_path,
+        runtime_root_override=str(target_resolution["target_runtime_root"]),
+        goal_id=goal_id,
+        dry_run=False,
+    )
+    readback = (
+        _readback(
+            source_registry=registry_path.expanduser().resolve(),
+            target_registry=target_registry,
+            goal_id=goal_id,
+            sync_payload=sync_payload,
+        )
+        if sync_payload.get("ok")
+        else {
+            "schema_version": CONFIGURE_GOAL_GLOBAL_SYNC_READBACK_SCHEMA_VERSION,
+            "status": "not_run",
+            "verified": False,
+        }
+    )
+    sync_ok = bool(sync_payload.get("ok") and readback.get("verified"))
+    applied["global_sync"] = {
+        **_sync_plan(
+            changed=True,
+            target_resolution=target_resolution,
+            execute=True,
+        ),
+        "ok": sync_ok,
+        "executed": True,
+        "sync": sync_payload,
+        "readback": readback,
+        "global_registry_writability": writability,
+    }
+    applied["ok"] = bool(applied.get("ok") and sync_ok)
+    applied["partial_write"] = bool(applied.get("written") and not sync_ok)
+    if not sync_ok:
+        applied["error"] = "configure-goal shared registry readback did not verify"
+        applied["recommended_action"] = (
+            sync_payload.get("recommended_action")
+            or f"rerun loopx sync-global --goal-id {goal_id} after repairing the shared runtime route"
+        )
+    return applied

loopx/control_plane/goals/contract_health.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+CONTRACT_ERROR_DIAGNOSTIC_SCHEMA_VERSION = "loopx_contract_error_diagnostic_v0"
+CONTRACT_ERROR_SCOPE_GLOBAL = "global"
+CONTRACT_ERROR_SCOPE_GOAL = "goal"
+CONTRACT_ERROR_SCOPE_GOALS = "goals"
+
+
+def contract_error_diagnostic(
+    *,
+    code: str,
+    message: str,
+    goal_id: str | None = None,
+    goal_ids: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    safe_goal_id = str(goal_id or "").strip()
+    safe_goal_ids = sorted(
+        {
+            str(item or "").strip()
+            for item in goal_ids or []
+            if str(item or "").strip()
+        }
+    )
+    diagnostic = {
+        "schema_version": CONTRACT_ERROR_DIAGNOSTIC_SCHEMA_VERSION,
+        "severity": "error",
+        "scope": (
+            CONTRACT_ERROR_SCOPE_GOAL
+            if safe_goal_id
+            else CONTRACT_ERROR_SCOPE_GOALS
+            if safe_goal_ids
+            else CONTRACT_ERROR_SCOPE_GLOBAL
+        ),
+        "code": str(code or "contract_error").strip() or "contract_error",
+        "message": str(message or "").strip(),
+    }
+    if safe_goal_id:
+        diagnostic["goal_id"] = safe_goal_id
+    elif safe_goal_ids:
+        diagnostic["goal_ids"] = safe_goal_ids
+    return diagnostic
+
+
+def contract_error_views(
+    diagnostics: Iterable[dict[str, Any]],
+) -> dict[str, Any]:
+    errors: list[str] = []
+    global_errors: list[str] = []
+    goal_errors: dict[str, list[str]] = {}
+    normalized: list[dict[str, Any]] = []
+    for raw in diagnostics:
+        diagnostic = dict(raw)
+        message = str(diagnostic.get("message") or "").strip()
+        if not message:
+            continue
+        normalized.append(diagnostic)
+        errors.append(message)
+        goal_id = str(diagnostic.get("goal_id") or "").strip()
+        if (
+            diagnostic.get("scope") == CONTRACT_ERROR_SCOPE_GOAL
+            and goal_id
+        ):
+            goal_errors.setdefault(goal_id, []).append(message)
+        elif diagnostic.get("scope") == CONTRACT_ERROR_SCOPE_GOALS:
+            goal_ids = [
+                str(item or "").strip()
+                for item in diagnostic.get("goal_ids") or []
+                if str(item or "").strip()
+            ]
+            if goal_ids:
+                for affected_goal_id in goal_ids:
+                    goal_errors.setdefault(affected_goal_id, []).append(message)
+            else:
+                global_errors.append(message)
+        else:
+            global_errors.append(message)
+    return {
+        "error_diagnostics": normalized,
+        "errors": errors,
+        "global_errors": global_errors,
+        "goal_errors": goal_errors,
+    }
+
+
+def project_contract_health_for_goal(
+    contract: dict[str, Any],
+    *,
+    goal_id: str | None,
+) -> dict[str, Any]:
+    safe_goal_id = str(goal_id or "").strip()
+    if not safe_goal_id or "error_diagnostics" not in contract:
+        return dict(contract)
+
+    diagnostics = contract.get("error_diagnostics")
+    if not isinstance(diagnostics, list):
+        return dict(contract)
+    selected_diagnostics = [
+        item
+        for item in diagnostics
+        if isinstance(item, dict)
+        and (
+            item.get("scope") == CONTRACT_ERROR_SCOPE_GLOBAL
+            or (
+                item.get("scope") == CONTRACT_ERROR_SCOPE_GOAL
+                and str(item.get("goal_id") or "").strip() == safe_goal_id
+            )
+            or (
+                item.get("scope") == CONTRACT_ERROR_SCOPE_GOALS
+                and safe_goal_id
+                in {
+                    str(goal_id or "").strip()
+                    for goal_id in item.get("goal_ids") or []
+                }
+            )
+        )
+    ]
+    error_views = contract_error_views(selected_diagnostics)
+    summary = (
+        dict(contract.get("summary"))
+        if isinstance(contract.get("summary"), dict)
+        else {}
+    )
+    summary["errors"] = len(error_views["errors"])
+    return {
+        **contract,
+        **error_views,
+        "ok": not error_views["errors"],
+        "summary": summary,
+    }