From 9e4da5eb94a189087f6d1abc8fdafe92195b8c95 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:49:39 +0800 Subject: [PATCH] refactor(types): eliminate Any annotations and slim authority and upgrade Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- loopx/authority.py | 568 +++++++---------- loopx/canary/module_metric_baseline.json | 10 + loopx/upgrade.py | 768 ++++++++++------------- 3 files changed, 563 insertions(+), 783 deletions(-) diff --git a/loopx/authority.py b/loopx/authority.py index c64692d779..bacadf244d 100644 --- a/loopx/authority.py +++ b/loopx/authority.py @@ -1,11 +1,11 @@ from __future__ import annotations -from typing import Any, cast - +from collections.abc import Mapping, Sequence import copy import hashlib -import re from pathlib import Path +import re +from typing import cast from urllib.parse import urlparse from .control_plane.projects.registry_codec import ( @@ -20,6 +20,8 @@ classify_private_text, ) +Payload = dict[str, object] +PayloadView = Mapping[str, object] AUTHORITY_SOURCE_REGISTRATION_VERSION = "authority_source_registration_v0" DOC_REGISTRY_AUTHORITY_IMPORT_VERSION = "doc_registry_authority_import_v0" @@ -29,12 +31,7 @@ # contract; re-exported here because callers already import this name. PRIVATE_TEXT_PATTERNS = SHARED_PRIVATE_TEXT_PATTERNS -AUTHORITY_REGISTRY_SUMMARY_FIELDS = ( - "declared", - "required", - "path", - "path_exists", - "read_status", +_INT_SUMMARY_FIELDS = ( "default_entry_count", "default_entries_checked", "default_entries_present", @@ -44,16 +41,40 @@ "project_material_owner_review_required_count", "project_material_stale_count", "project_material_current_authority_count", +) +AUTHORITY_REGISTRY_SUMMARY_FIELDS = ( + "declared", + "required", + "path", + "path_exists", + "read_status", + *_INT_SUMMARY_FIELDS, "deprecated_source_count", "conflict_risk", ) - AUTHORITY_REGISTRY_CANONICAL_FIELDS = ( "default_entry_docs", "topic_authority", "project_materials", "deprecated_sources", ) +_COMPACT_SOURCE_FIELDS = ( + "schema_version", "id", "role", "source_kind", "freshness", "boundary", + "source_ref_kind", "source_ref_sha256", "source_ref_redacted", "owner_status", + "gate_status", "revision", "conflict_rule", "registered_at", + "default_entry_count", "topic_authority_count", "imported_topic_count", +) +_COMMON_MARKDOWN_ENTRY_FIELDS = ("source_ref_redacted", "source_ref_kind", "boundary", "freshness") + + +def _dict_view(value: object) -> PayloadView: + return cast(PayloadView, value) if isinstance(value, dict) else {} + + +def _int_value(value: object) -> int: + if not value: + return 0 + return int(value) if isinstance(value, (int, float, str, bytes, bytearray)) else int(str(value)) def now_local() -> str: @@ -106,7 +127,7 @@ def validate_public_safe_text(label: str, value: str | None) -> None: raise ValueError(f"{label} contains a private-looking value; keep raw evidence in private payloads") -def find_goal_index(registry: dict[str, Any], goal_id: str) -> int: +def find_goal_index(registry: PayloadView, goal_id: str) -> int: goals = registry.get("goals") if not isinstance(goals, list): raise ValueError("registry goals must be a list") @@ -116,36 +137,31 @@ def find_goal_index(registry: dict[str, Any], goal_id: str) -> int: raise ValueError(f"goal id not found in registry: {goal_id}") -def normalize_project_materials(value: Any) -> dict[str, Any]: +def normalize_project_materials(value: object) -> dict[str, Payload]: if isinstance(value, dict): - return {str(key): item for key, item in value.items() if isinstance(item, dict)} + return {str(key): cast(Payload, item) for key, item in value.items() if isinstance(item, dict)} if isinstance(value, list): - result: dict[str, Any] = {} + result: dict[str, Payload] = {} for index, item in enumerate(value): if not isinstance(item, dict): continue item_id = str(item.get("id") or item.get("source_id") or f"source_{index + 1}") - result[item_id] = dict(item) + result[item_id] = cast(Payload, dict(item)) return result return {} -def normalize_topic_authority(value: Any) -> dict[str, Any]: - if isinstance(value, dict): - return dict(value) - return {} +def normalize_topic_authority(value: object) -> Payload: + return {str(key): item for key, item in value.items()} if isinstance(value, dict) else {} -def authority_registry_has_canonical_fields(raw: dict[str, Any]) -> bool: +def authority_registry_has_canonical_fields(raw: PayloadView) -> bool: """Return whether a registry carries source data richer than a summary.""" return any(key in raw for key in AUTHORITY_REGISTRY_CANONICAL_FIELDS) -def apply_authority_registry_summary( - authority_registry: dict[str, Any], - summary: dict[str, Any], -) -> None: +def apply_authority_registry_summary(authority_registry: Payload, summary: PayloadView) -> None: """Refresh co-located summary fields without replacing canonical source data.""" for key in AUTHORITY_REGISTRY_SUMMARY_FIELDS: @@ -166,73 +182,67 @@ def compact_registered_authority_source( revision: str | None, conflict_rule: str | None, registered_at: str, -) -> dict[str, Any]: +) -> Payload: if boundary not in AUTHORITY_SOURCE_BOUNDARIES: raise ValueError(f"boundary must be one of: {', '.join(sorted(AUTHORITY_SOURCE_BOUNDARIES))}") source_id = validate_authority_source_id(source_id) - source_kind = public_safe_optional("source_kind", source_kind) or "" - role = public_safe_optional("role", role) or "" - freshness = public_safe_optional("freshness", freshness) or "" - if not source_kind: - raise ValueError("source_kind is required") - if not role: - raise ValueError("role is required") - if not freshness: - raise ValueError("freshness is required") - - entry: dict[str, Any] = { + required_fields: dict[str, str] = {} + for field_name, raw_value in (("source_kind", source_kind), ("role", role), ("freshness", freshness)): + cleaned = public_safe_optional(field_name, raw_value) or "" + if not cleaned: + raise ValueError(f"{field_name} is required") + required_fields[field_name] = cleaned + + entry: Payload = { "schema_version": AUTHORITY_SOURCE_REGISTRATION_VERSION, "id": source_id, - "role": role, - "source_kind": source_kind, - "freshness": freshness, + "role": required_fields["role"], + "source_kind": required_fields["source_kind"], + "freshness": required_fields["freshness"], "boundary": boundary, "source_ref_redacted": bool(source_ref), "registered_at": registered_at, } - ref_kind = source_ref_kind(source_ref) - ref_digest = source_ref_digest(source_ref) - if ref_kind: - entry["source_ref_kind"] = ref_kind - if ref_digest: - entry["source_ref_sha256"] = ref_digest - for key, value in ( + optional_fields = ( + ("source_ref_kind", source_ref_kind(source_ref)), + ("source_ref_sha256", source_ref_digest(source_ref)), ("owner_status", public_safe_optional("owner_status", owner_status)), ("gate_status", public_safe_optional("gate_status", gate_status)), ("revision", public_safe_optional("revision", revision)), ("conflict_rule", public_safe_optional("conflict_rule", conflict_rule)), - ): + ) + for key, value in optional_fields: if value: entry[key] = value return entry -def render_authority_source_markdown(payload: dict[str, Any]) -> str: +def _render_authority_markdown( + title: str, + payload: PayloadView, + *, + entry_fields: tuple[str, ...], + include_registry: bool = False, +) -> str: lines = [ - "# LoopX Authority Source Registration", + f"# {title}", "", - f"- ok: `{payload.get('ok')}`", - f"- dry_run: `{payload.get('dry_run')}`", - f"- written: `{payload.get('written')}`", - f"- goal_id: `{payload.get('goal_id')}`", - f"- source_id: `{payload.get('source_id')}`", + *(f"- {field}: `{payload.get(field)}`" for field in ("ok", "dry_run", "written", "goal_id", "source_id")), ] if payload.get("error"): lines.append(f"- error: {payload.get('error')}") return "\n".join(lines) - entry = cast(dict[str, Any], payload.get("entry")) if isinstance(payload.get("entry"), dict) else {} + entry = _dict_view(payload.get("entry")) + summary = _dict_view(payload.get("authority_registry_summary")) + global_sync = _dict_view(payload.get("global_sync")) + if include_registry: + lines.append(f"- registry: `{payload.get('registry')}`") + lines.extend(f"- {field}: `{entry.get(field)}`" for field in entry_fields) lines.extend( [ - f"- registry: `{payload.get('registry')}`", - f"- source_ref_redacted: `{entry.get('source_ref_redacted')}`", - f"- source_ref_kind: `{entry.get('source_ref_kind')}`", - f"- boundary: `{entry.get('boundary')}`", - f"- freshness: `{entry.get('freshness')}`", - f"- owner_status: `{entry.get('owner_status')}`", - f"- gate_status: `{entry.get('gate_status')}`", f"- authority_registry_path: `{payload.get('authority_registry_path')}`", - f"- project_material_count: `{payload.get('authority_registry_summary', {}).get('project_material_count') if isinstance(payload.get('authority_registry_summary'), dict) else None}`", - f"- global_sync_wrote: `{payload.get('global_sync', {}).get('wrote') if isinstance(payload.get('global_sync'), dict) else None}`", + f"- project_material_count: `{summary.get('project_material_count') if summary else None}`", + f"- global_sync_wrote: `{global_sync.get('wrote') if global_sync else None}`", "", "## Write Effect", str(payload.get("write_effect") or ""), @@ -241,27 +251,36 @@ def render_authority_source_markdown(payload: dict[str, Any]) -> str: return "\n".join(lines) +def render_authority_source_markdown(payload: PayloadView) -> str: + return _render_authority_markdown( + "LoopX Authority Source Registration", + payload, + entry_fields=(*_COMMON_MARKDOWN_ENTRY_FIELDS, "owner_status", "gate_status"), + include_registry=True, + ) + + def _strip_yaml_scalar(value: str) -> str: text = value.strip() - if not text: - return "" - if text in {">", ">-", "|", "|-"}: + if not text or text in {">", ">-", "|", "|-"}: return "" if (text.startswith('"') and text.endswith('"')) or (text.startswith("'") and text.endswith("'")): return text[1:-1] return text -def read_doc_registry_contract(doc_registry_path: Path) -> dict[str, Any]: +def read_doc_registry_contract(doc_registry_path: Path) -> Payload: """Read the public-safe contract surface from a DOC_REGISTRY-like YAML file.""" path = doc_registry_path.expanduser() text = path.read_text(encoding="utf-8") - result: dict[str, Any] = { + default_entry_docs: list[str] = [] + topic_authority: dict[str, str] = {} + result: Payload = { "version": None, "updated_at": None, - "default_entry_docs": [], - "topic_authority": {}, + "default_entry_docs": default_entry_docs, + "topic_authority": topic_authority, "status_definition_count": 0, } current_section: str | None = None @@ -284,14 +303,14 @@ def read_doc_registry_contract(doc_registry_path: Path) -> dict[str, Any]: if current_section == "default_entry_docs" and stripped.startswith("- "): entry = _strip_yaml_scalar(stripped[2:]) if entry: - result["default_entry_docs"].append(entry) + default_entry_docs.append(entry) continue if current_section == "topic_authority" and ":" in stripped: key, raw_value = stripped.split(":", 1) topic = _strip_yaml_scalar(key) authority = _strip_yaml_scalar(raw_value) if topic and authority: - result["topic_authority"][topic] = authority + topic_authority[topic] = authority continue if in_status_definitions and indent > 0 and ":" in stripped: key, _raw_value = stripped.split(":", 1) @@ -301,106 +320,54 @@ def read_doc_registry_contract(doc_registry_path: Path) -> dict[str, Any]: return result -def render_doc_registry_authority_import_markdown(payload: dict[str, Any]) -> str: - lines = [ - "# LoopX Doc Registry Authority Import", - "", - f"- ok: `{payload.get('ok')}`", - f"- dry_run: `{payload.get('dry_run')}`", - f"- written: `{payload.get('written')}`", - f"- goal_id: `{payload.get('goal_id')}`", - f"- source_id: `{payload.get('source_id')}`", - ] - if payload.get("error"): - lines.append(f"- error: {payload.get('error')}") - return "\n".join(lines) - entry = cast(dict[str, Any], payload.get("entry")) if isinstance(payload.get("entry"), dict) else {} - lines.extend( - [ - f"- source_ref_redacted: `{entry.get('source_ref_redacted')}`", - f"- source_ref_kind: `{entry.get('source_ref_kind')}`", - f"- boundary: `{entry.get('boundary')}`", - f"- freshness: `{entry.get('freshness')}`", - f"- default_entry_count: `{entry.get('default_entry_count')}`", - f"- topic_authority_count: `{entry.get('topic_authority_count')}`", - f"- imported_topic_count: `{entry.get('imported_topic_count')}`", - f"- authority_registry_path: `{payload.get('authority_registry_path')}`", - f"- project_material_count: `{payload.get('authority_registry_summary', {}).get('project_material_count') if isinstance(payload.get('authority_registry_summary'), dict) else None}`", - f"- global_sync_wrote: `{payload.get('global_sync', {}).get('wrote') if isinstance(payload.get('global_sync'), dict) else None}`", - "", - "## Write Effect", - str(payload.get("write_effect") or ""), - ] +def render_doc_registry_authority_import_markdown(payload: PayloadView) -> str: + return _render_authority_markdown( + "LoopX Doc Registry Authority Import", + payload, + entry_fields=(*_COMMON_MARKDOWN_ENTRY_FIELDS, "default_entry_count", "topic_authority_count", "imported_topic_count"), ) - return "\n".join(lines) def _apply_authority_entry( - registry: dict[str, Any], + registry: Payload, *, goal_id: str, - entry: dict[str, Any], + entry: Payload, registered_at: str, imported_topics: dict[str, str] | None = None, -) -> tuple[dict[str, Any], dict[str, Any] | None]: +) -> tuple[Payload, Payload | None]: goal_index = find_goal_index(registry, goal_id) goals = registry.get("goals") if not isinstance(goals, list) or not isinstance(goals[goal_index], dict): raise ValueError("registry goal entry must be an object") - goal = goals[goal_index] + goal = cast(Payload, goals[goal_index]) - authority_registry = ( - dict(goal["authority_registry"]) - if isinstance(goal.get("authority_registry"), dict) + raw_authority_registry = goal.get("authority_registry") + authority_registry: Payload = ( + {str(key): value for key, value in raw_authority_registry.items()} + if isinstance(raw_authority_registry, dict) else {} ) - materials = normalize_project_materials( - authority_registry.get("project_materials") - ) - previous_entry = materials.get(entry["id"]) - materials[str(entry["id"])] = dict(entry) + source_key = str(entry["id"]) + materials = normalize_project_materials(authority_registry.get("project_materials")) + previous_entry = materials.get(source_key) + materials[source_key] = dict(entry) authority_registry["project_materials"] = materials authority_registry.setdefault("read_status", "registered") if imported_topics: - topic_map = normalize_topic_authority( - authority_registry.get("topic_authority") - ) + topic_map = normalize_topic_authority(authority_registry.get("topic_authority")) topic_map.update(imported_topics) authority_registry["topic_authority"] = topic_map goal["authority_registry"] = authority_registry - compact_source_fields = ( - "schema_version", - "id", - "role", - "source_kind", - "freshness", - "boundary", - "source_ref_kind", - "source_ref_sha256", - "source_ref_redacted", - "owner_status", - "gate_status", - "revision", - "conflict_rule", - "registered_at", - "default_entry_count", - "topic_authority_count", - "imported_topic_count", - ) - compact_source = { - key: entry[key] for key in compact_source_fields if key in entry - } + compact_source = {key: entry[key] for key in _COMPACT_SOURCE_FIELDS if key in entry} authority_sources = goal.get("authority_sources") if not isinstance(authority_sources, list): authority_sources = [] goal["authority_sources"] = [ item for item in authority_sources - if not ( - isinstance(item, dict) - and str(item.get("id") or item.get("source_id") or "") == entry["id"] - ) + if not (isinstance(item, dict) and str(item.get("id") or item.get("source_id") or "") == source_key) ] + [compact_source] registry["updated_at"] = registered_at @@ -411,6 +378,53 @@ def _apply_authority_entry( return summary, previous_entry +def _commit_authority_entry( + *, + registry_path: Path, + goal_id: str, + entry: Payload, + registered_at: str, + imported_topics: dict[str, str], + dry_run: bool, + dry_run_operation: str, + mutate_operation: str, + write_effect: str, + raw_ref_field: str, + extra: Payload | None = None, +) -> Payload: + def reduce(registry: Payload) -> tuple[Payload, Payload | None]: + return _apply_authority_entry( + registry, goal_id=goal_id, entry=entry, + registered_at=registered_at, imported_topics=imported_topics, + ) + + if dry_run: + registry = load_project_registry(registry_path) + require_runtime_compatible_project_registry(registry, operation=dry_run_operation) + summary, previous_entry = reduce(copy.deepcopy(registry)) + else: + summary, previous_entry = mutate_project_registry(registry_path, operation=mutate_operation, reducer=reduce) + + if previous_entry: + write_effect += "; previous entry with the same source_id is replaced" + payload: Payload = { + "ok": True, + "dry_run": dry_run, + "written": not dry_run, + "registry": str(registry_path), + "goal_id": goal_id, + "source_id": entry["id"], + "entry": entry, + "authority_registry_path": "authority_registry.project_materials", + "authority_registry_summary": summary, + "write_effect": write_effect, + raw_ref_field: False, + } + if extra is not None: + payload.update(extra) + return payload + + def register_authority_source( *, registry_path: Path, @@ -427,21 +441,13 @@ def register_authority_source( conflict_rule: str | None, topic: str | None, dry_run: bool, -) -> dict[str, Any]: +) -> Payload: registry_path = registry_path.expanduser() registered_at = now_local() entry = compact_registered_authority_source( - source_id=source_id, - source_ref=source_ref, - source_kind=source_kind, - role=role, - freshness=freshness, - owner_status=owner_status, - gate_status=gate_status, - boundary=boundary, - revision=revision, - conflict_rule=conflict_rule, - registered_at=registered_at, + source_id=source_id, source_ref=source_ref, source_kind=source_kind, role=role, + freshness=freshness, owner_status=owner_status, gate_status=gate_status, + boundary=boundary, revision=revision, conflict_rule=conflict_rule, registered_at=registered_at, ) imported_topics: dict[str, str] = {} @@ -450,51 +456,17 @@ def register_authority_source( if topic_text: imported_topics[topic_text] = str(entry["id"]) - def reduce( - registry: dict[str, Any], - ) -> tuple[dict[str, Any], dict[str, Any] | None]: - return _apply_authority_entry( - registry, - goal_id=goal_id, - entry=entry, - registered_at=registered_at, - imported_topics=imported_topics, - ) - - if dry_run: - registry = load_project_registry(registry_path) - require_runtime_compatible_project_registry( - registry, - operation="authority source registration", - ) - summary, previous_entry = reduce(copy.deepcopy(registry)) - else: - summary, previous_entry = mutate_project_registry( - registry_path, - operation="register_authority_source", - reducer=reduce, - ) - action = "would update" if dry_run else "updated" write_effect = ( f"{action} goal `{goal_id}` authority_registry.project_materials[{entry['id']}] " "with a redacted source reference digest; raw source_ref is not stored" ) - if previous_entry: - write_effect += "; previous entry with the same source_id is replaced" - return { - "ok": True, - "dry_run": dry_run, - "written": not dry_run, - "registry": str(registry_path), - "goal_id": goal_id, - "source_id": entry["id"], - "entry": entry, - "authority_registry_path": "authority_registry.project_materials", - "authority_registry_summary": summary, - "write_effect": write_effect, - "raw_source_ref_stored": False, - } + return _commit_authority_entry( + registry_path=registry_path, goal_id=goal_id, entry=entry, + registered_at=registered_at, imported_topics=imported_topics, dry_run=dry_run, + dry_run_operation="authority source registration", mutate_operation="register_authority_source", + write_effect=write_effect, raw_ref_field="raw_source_ref_stored", + ) def import_doc_registry_authority( @@ -511,11 +483,11 @@ def import_doc_registry_authority( boundary: str, revision: str | None, conflict_rule: str | None, - topics: list[str], + topics: Sequence[str], import_topic_prefix: str | None, max_imported_topics: int, dry_run: bool, -) -> dict[str, Any]: +) -> Payload: if max_imported_topics < 0: raise ValueError("max_imported_topics must be non-negative") registry_path = registry_path.expanduser() @@ -523,39 +495,34 @@ def import_doc_registry_authority( contract = read_doc_registry_contract(doc_registry_path) registered_at = now_local() entry = compact_registered_authority_source( - source_id=source_id, - source_ref=str(doc_registry_path), - source_kind=source_kind, - role=role, - freshness=freshness, - owner_status=owner_status, - gate_status=gate_status, - boundary=boundary, - revision=revision or str(contract.get("updated_at") or ""), - conflict_rule=conflict_rule, + source_id=source_id, source_ref=str(doc_registry_path), source_kind=source_kind, role=role, + freshness=freshness, owner_status=owner_status, gate_status=gate_status, boundary=boundary, + revision=revision or str(contract.get("updated_at") or ""), conflict_rule=conflict_rule, registered_at=registered_at, ) entry["schema_version"] = DOC_REGISTRY_AUTHORITY_IMPORT_VERSION - default_entries = [str(item) for item in contract.get("default_entry_docs") or []] - topic_authority = cast(dict[str, Any], contract.get("topic_authority")) if isinstance(contract.get("topic_authority"), dict) else {} + raw_default_entries = contract.get("default_entry_docs") + default_entries = [str(item) for item in raw_default_entries] if isinstance(raw_default_entries, list) else [] + topic_authority = _dict_view(contract.get("topic_authority")) + source_key = str(entry["id"]) imported_topics: dict[str, str] = {} if import_topic_prefix: prefix = public_safe_optional("import_topic_prefix", import_topic_prefix) or "" for topic in list(topic_authority.keys())[:max_imported_topics]: local_topic = f"{prefix}{topic}" public_safe_optional("imported_topic", local_topic) - imported_topics[local_topic] = entry["id"] + imported_topics[local_topic] = source_key for topic in topics: topic_text = public_safe_optional("topic", topic) if topic_text: - imported_topics[topic_text] = entry["id"] + imported_topics[topic_text] = source_key entry.update( { "registry_version": contract.get("version"), "registry_updated_at": contract.get("updated_at"), "default_entry_count": len(default_entries), "topic_authority_count": len(topic_authority), - "status_definition_count": int(contract.get("status_definition_count") or 0), + "status_definition_count": _int_value(contract.get("status_definition_count")), "default_entry_sample": default_entries[:8], "topic_sample": list(topic_authority.keys())[:12], "imported_topic_count": len(imported_topics), @@ -564,31 +531,6 @@ def import_doc_registry_authority( } ) - def reduce( - registry: dict[str, Any], - ) -> tuple[dict[str, Any], dict[str, Any] | None]: - return _apply_authority_entry( - registry, - goal_id=goal_id, - entry=entry, - registered_at=registered_at, - imported_topics=imported_topics, - ) - - if dry_run: - registry = load_project_registry(registry_path) - require_runtime_compatible_project_registry( - registry, - operation="authority registry import", - ) - summary, previous_entry = reduce(copy.deepcopy(registry)) - else: - summary, previous_entry = mutate_project_registry( - registry_path, - operation="import_doc_registry_authority", - reducer=reduce, - ) - action = "would import" if dry_run else "imported" write_effect = ( f"{action} DOC_REGISTRY summary into goal `{goal_id}` " @@ -596,25 +538,16 @@ def reduce( f"{len(default_entries)} default entries and {len(topic_authority)} topic mappings; " "raw doc_registry_path is hashed and not stored" ) - if previous_entry: - write_effect += "; previous entry with the same source_id is replaced" - return { - "ok": True, - "dry_run": dry_run, - "written": not dry_run, - "registry": str(registry_path), - "goal_id": goal_id, - "source_id": entry["id"], - "entry": entry, - "authority_registry_path": "authority_registry.project_materials", - "authority_registry_summary": summary, - "write_effect": write_effect, - "raw_doc_registry_path_stored": False, - "imported_topics": imported_topics, - } + return _commit_authority_entry( + registry_path=registry_path, goal_id=goal_id, entry=entry, + registered_at=registered_at, imported_topics=imported_topics, dry_run=dry_run, + dry_run_operation="authority registry import", mutate_operation="import_doc_registry_authority", + write_effect=write_effect, raw_ref_field="raw_doc_registry_path_stored", + extra={"imported_topics": imported_topics}, + ) -def _path_text(value: Any) -> str | None: +def _path_text(value: object) -> str | None: if not value: return None text = str(value) @@ -628,7 +561,7 @@ def _resolve_project_path(project: Path | None, path_text: str | None) -> Path | return path if path.is_absolute() else project / path -def _entry_path(value: Any) -> str | None: +def _entry_path(value: object) -> str | None: if isinstance(value, str): return _path_text(value) if isinstance(value, dict): @@ -636,42 +569,30 @@ def _entry_path(value: Any) -> str | None: return None -def authority_registry_required(goal: dict[str, Any] | None) -> bool: +def authority_registry_required(goal: PayloadView | None) -> bool: if not goal: return False return bool(goal.get("requires_authority_registry") or goal.get("authority_registry_required")) -def authority_registry_default_entries(raw_entries: Any) -> list[str]: - entries: list[str] = [] - if isinstance(raw_entries, list): - for item in raw_entries: - path = _entry_path(item) - if path: - entries.append(path) - elif isinstance(raw_entries, dict): - for item in raw_entries.values(): - path = _entry_path(item) - if path: - entries.append(path) - return entries - - -def authority_registry_topic_count(raw_topics: Any) -> int: - if isinstance(raw_topics, dict): - return len(raw_topics) - if isinstance(raw_topics, list): - return len(raw_topics) - return 0 - - -def authority_registry_project_material_stats(raw_materials: Any) -> dict[str, int]: - if isinstance(raw_materials, dict): - items = [item for item in raw_materials.values() if isinstance(item, dict)] - elif isinstance(raw_materials, list): - items = [item for item in raw_materials if isinstance(item, dict)] - else: - items = [] +def authority_registry_default_entries(raw_entries: object) -> list[str]: + values = raw_entries if isinstance(raw_entries, list) else raw_entries.values() if isinstance(raw_entries, dict) else () + return [path for item in values if (path := _entry_path(item))] + + +def authority_registry_topic_count(raw_topics: object) -> int: + return len(raw_topics) if isinstance(raw_topics, (dict, list)) else 0 + + +def authority_registry_project_material_stats(raw_materials: object) -> dict[str, int]: + raw_items = ( + raw_materials.values() + if isinstance(raw_materials, dict) + else raw_materials + if isinstance(raw_materials, list) + else () + ) + items = [cast(PayloadView, item) for item in raw_items if isinstance(item, dict)] repository_kinds = {"repository", "repo", "git_repo", "source_repo", "target_repo"} owner_review_freshness = { @@ -703,66 +624,31 @@ def authority_registry_project_material_stats(raw_materials: Any) -> dict[str, i return stats -def authority_registry_deprecated_count(raw_sources: Any) -> int: - if isinstance(raw_sources, (dict, list)): - return len(raw_sources) - return 0 +def authority_registry_deprecated_count(raw_sources: object) -> int: + return len(raw_sources) if isinstance(raw_sources, (dict, list)) else 0 -def compact_authority_registry(goal: dict[str, Any] | None, *, project: Path | None = None) -> dict[str, Any]: - raw = goal.get("authority_registry") if goal and isinstance(goal.get("authority_registry"), dict) else {} - if not raw: - return { - "declared": False, - "required": authority_registry_required(goal), - "path": None, - "path_exists": None, - "read_status": None, - "default_entry_count": 0, - "default_entries_checked": 0, - "default_entries_present": 0, - "topic_authority_count": 0, - "project_material_count": 0, - "project_material_repository_count": 0, - "project_material_owner_review_required_count": 0, - "project_material_stale_count": 0, - "project_material_current_authority_count": 0, - "deprecated_source_count": 0, - "conflict_risk": "unknown", - "default_entries": [], - } - - path_text = _path_text(raw.get("path")) +def compact_authority_registry(goal: PayloadView | None, *, project: Path | None = None) -> Payload: + raw = _dict_view(goal.get("authority_registry")) if goal else {} + path_text = _path_text(raw.get("path")) if raw else None resolved_path = _resolve_project_path(project, path_text) - summary: dict[str, Any] = { - "declared": True if authority_registry_has_canonical_fields(raw) else bool(raw.get("declared")), - "required": bool(raw.get("required") or authority_registry_required(goal)), + summary: Payload = { + "declared": (True if authority_registry_has_canonical_fields(raw) else bool(raw.get("declared"))) if raw else False, + "required": bool(raw.get("required") or authority_registry_required(goal)) if raw else authority_registry_required(goal), "path": path_text, - "path_exists": resolved_path.exists() if resolved_path else raw.get("path_exists"), - "read_status": raw.get("read_status"), - "default_entry_count": int(raw.get("default_entry_count") or 0), - "default_entries_checked": int(raw.get("default_entries_checked") or 0), - "default_entries_present": int(raw.get("default_entries_present") or 0), - "topic_authority_count": int(raw.get("topic_authority_count") or 0), - "project_material_count": int(raw.get("project_material_count") or 0), - "project_material_repository_count": int(raw.get("project_material_repository_count") or 0), - "project_material_owner_review_required_count": int( - raw.get("project_material_owner_review_required_count") or 0 - ), - "project_material_stale_count": int(raw.get("project_material_stale_count") or 0), - "project_material_current_authority_count": int( - raw.get("project_material_current_authority_count") or 0 - ), - "deprecated_source_count": int( - raw.get("deprecated_source_count") or raw.get("deprecated_sources_seen") or 0 - ), - "conflict_risk": str(raw.get("conflict_risk") or "unknown"), + "path_exists": (resolved_path.exists() if resolved_path else raw.get("path_exists")) if raw else None, + "read_status": raw.get("read_status") if raw else None, + **{field: (_int_value(raw.get(field)) if raw else 0) for field in _INT_SUMMARY_FIELDS}, + "deprecated_source_count": _int_value(raw.get("deprecated_source_count") or raw.get("deprecated_sources_seen")) if raw else 0, + "conflict_risk": str(raw.get("conflict_risk") or "unknown") if raw else "unknown", "default_entries": [], } + if not raw: + return summary if "default_entry_docs" in raw: default_entries = authority_registry_default_entries(raw.get("default_entry_docs")) - checked_entries: list[dict[str, Any]] = [] + checked_entries: list[Payload] = [] present = 0 checked = 0 for entry_path in default_entries: @@ -790,11 +676,11 @@ def compact_authority_registry(goal: dict[str, Any] | None, *, project: Path | N return summary -def authority_registry_summary(goal: dict[str, Any] | None) -> dict[str, Any]: +def authority_registry_summary(goal: PayloadView | None) -> Payload: compact = compact_authority_registry(goal, project=None) compact.pop("default_entries", None) return compact -def goal_authority_registry_summary(goal: dict[str, Any] | None) -> dict[str, Any]: +def goal_authority_registry_summary(goal: PayloadView | None) -> Payload: return authority_registry_summary(goal) diff --git a/loopx/canary/module_metric_baseline.json b/loopx/canary/module_metric_baseline.json index e6a6fe67b9..50be6c5c34 100644 --- a/loopx/canary/module_metric_baseline.json +++ b/loopx/canary/module_metric_baseline.json @@ -5,6 +5,11 @@ "lines": 2000 }, "module_metric_ceilings": { + "loopx/authority.py": { + "any_count": 0, + "dict_any_count": 0, + "lines": 686 + }, "loopx/bootstrap_command_pack.py": { "any_count": 32, "dict_any_count": 0, @@ -121,6 +126,11 @@ "any_count": 48, "dict_any_count": 0 }, + "loopx/upgrade.py": { + "any_count": 0, + "dict_any_count": 0, + "lines": 1062 + }, "loopx/worker_bridge.py": { "any_count": 28, "dict_any_count": 0 diff --git a/loopx/upgrade.py b/loopx/upgrade.py index 3a2d2cc99c..f11d04aeb4 100644 --- a/loopx/upgrade.py +++ b/loopx/upgrade.py @@ -1,30 +1,33 @@ from __future__ import annotations +from collections.abc import Mapping, Sequence import hashlib import json import os +from pathlib import Path import re import tomllib -from pathlib import Path -from typing import Any +from typing import cast from .agent_registry import ( agent_profile_for_goal, registered_agent_ids_for_goal, ) -from .execution_profile import execution_profile_turn_granularity -from .heartbeat_prompt import build_heartbeat_prompt -from .history import load_registry -from .paths import global_registry_path, resolve_runtime_root, select_default_runtime_root -from .registry import registry_goals, resolve_state_file from .control_plane.agents.legacy_migration import ( completed_peer_agent_runtime_migration, legacy_agent_hierarchy_present, peer_agent_runtime_migration_completed, peer_agent_runtime_migration_id, ) +from .control_plane.heartbeat.builder import build_heartbeat_prompt from .control_plane.todos.contract import normalize_required_capabilities +from .execution_profile import execution_profile_turn_granularity +from .history import load_registry +from .paths import global_registry_path, resolve_runtime_root, select_default_runtime_root +from .registry import registry_goals, resolve_state_file +Payload = dict[str, object] +PayloadView = Mapping[str, object] DEFAULT_UPGRADE_MODES = ("thin",) SHOULD_RUN_FALSE_RE = re.compile( @@ -56,7 +59,65 @@ STAGE_DEFERRED_ADAPTER_STATUSES = { "planned", } +HOST_LOOP_UPDATE_STATUSES = {"missing", "partial", "stale", "unknown", "error", "unavailable"} _AUTOMATION_PARSE_ERROR_LIMIT = 20 +_SUMMARY_MARKDOWN_FIELDS = ( + "ready_for_default_promotion", "managed_goal_count", "current_prompt_count", + "stale_prompt_count", "unknown_prompt_count", "not_installed_prompt_count", + "stage_deferred_goal_count", "installed_manifest_source", "installed_manifest_entry_count", + "installed_manifest_parse_error_count", "installed_manifest_has_task_body", + "installed_prompt_policy_warning_count", "installed_prompt_policy_warning_prompt_count", + "host_loop_activated_goal_count", "host_loop_missing_goal_count", + "peer_runtime_automation_migration_count", +) +_MANIFEST_MARKDOWN_FIELDS = ("available", "path", "reason", "parse_error_count", "parse_errors_complete") +_PROPAGATION_MARKDOWN_FIELDS = ( + "schema_version", "ready_for_default_promotion", "managed_target_count", + "deferred_target_count", "update_count", "deferred_install_count", "recommended_action", +) +_MIGRATION_MARKDOWN_FIELDS = ( + "migration_id", "delivery_semantics", "host_update_required_once", "completion_command", +) + + +def _dict_view(value: object) -> PayloadView: + return cast(PayloadView, value) if isinstance(value, dict) else {} + + +def _dict_list(value: object) -> list[Payload]: + return [cast(Payload, item) for item in value if isinstance(item, dict)] if isinstance(value, list) else [] + + +def _str_list(value: object) -> list[str]: + return [str(item) for item in value] if isinstance(value, (list, tuple)) else [] + + +def _int_value(value: object) -> int: + if not value: + return 0 + return int(value) if isinstance(value, (int, float, str, bytes, bytearray)) else int(str(value)) + + +def _unavailable_policy_audit(reason: str, *, status: str = "unavailable") -> Payload: + return { + "available": False, + "status": status, + "warning_count": 0, + "warnings": [], + "reason": reason, + } + + +def _first_match(patterns: tuple[str, ...], text: str) -> str | None: + for pattern in patterns: + match = re.search(pattern, text) + if match: + return match.group(1) + return None + + +def _bullet_fields(mapping: PayloadView, keys: tuple[str, ...]) -> list[str]: + return [f"- {key}: `{mapping.get(key)}`" for key in keys] def prompt_digest(text: str) -> str: @@ -64,13 +125,13 @@ def prompt_digest(text: str) -> str: def goal_heartbeat_prompt( - goal: dict[str, Any], + goal: Payload, *, cli_bin: str, mode: str, agent_id: str | None, - available_capabilities: Any = None, -) -> dict[str, Any]: + available_capabilities: Sequence[str] | None = None, +) -> Payload: """Build the prompt one Goal's ``mode`` heartbeat target installs. The prompt inputs come from the Goal's own registration (state file, agent @@ -82,7 +143,8 @@ def goal_heartbeat_prompt( """ goal_id = str(goal.get("id") or "") repo = Path(str(goal.get("repo") or ".")).expanduser() - state_file = resolve_state_file(repo, goal.get("state_file")) + raw_state_file = goal.get("state_file") + state_file = resolve_state_file(repo, str(raw_state_file) if raw_state_file else None) registered_agents = registered_agent_ids_for_goal(goal) reward_memory_enabled = False if agent_id is not None: @@ -93,42 +155,48 @@ def goal_heartbeat_prompt( reward_memory_enabled = reward_memory_automatic_ingest_for_agent( goal, agent_id ) - return build_heartbeat_prompt( - goal_id=goal_id, - active_state=None, - active_state_source="registry", - resolved_active_state=state_file, - compact=mode == "compact", - brief=mode == "brief", - thin=mode == "thin", - cli_bin=cli_bin, - agent_id=agent_id, - agent_profile=agent_profile_for_goal(goal, agent_id), - registered_agents=registered_agents or None, - available_capabilities=available_capabilities, - runtime_profile="codex_app_heartbeat", - turn_granularity=execution_profile_turn_granularity( - goal.get("execution_profile") - if isinstance(goal.get("execution_profile"), dict) - else None + normalized_capabilities = ( + available_capabilities + if isinstance(available_capabilities, (list, tuple)) + else None + if available_capabilities is None + else list(available_capabilities) + ) + raw_profile = goal.get("execution_profile") + return cast( + Payload, + build_heartbeat_prompt( + goal_id=goal_id, + active_state=None, + active_state_source="registry", + resolved_active_state=state_file, + compact=mode == "compact", + brief=mode == "brief", + thin=mode == "thin", + cli_bin=cli_bin, + agent_id=agent_id, + agent_profile=agent_profile_for_goal(goal, agent_id), + registered_agents=registered_agents or None, + available_capabilities=normalized_capabilities, + runtime_profile="codex_app_heartbeat", + turn_granularity=execution_profile_turn_granularity( + cast(Payload, raw_profile) if isinstance(raw_profile, dict) else None + ), + reward_memory_enabled=reward_memory_enabled, ), - reward_memory_enabled=reward_memory_enabled, ) -def prompt_summary(prompt: dict[str, Any], mode: str) -> dict[str, Any]: +def prompt_summary(prompt: PayloadView, mode: str) -> Payload: task_body = str(prompt.get("task_body") or "") - if mode == "full": - command = prompt.get("expanded_prompt_command") - else: - command = prompt.get(f"{mode}_prompt_command") - interface_budget = prompt.get("interface_budget") if isinstance(prompt.get("interface_budget"), dict) else {} + command = prompt.get("expanded_prompt_command") if mode == "full" else prompt.get(f"{mode}_prompt_command") + interface_budget = _dict_view(prompt.get("interface_budget")) return { "mode": mode, "sha256": prompt_digest(task_body), "char_count": len(task_body), "line_count": len(task_body.splitlines()), - "interface_budget": interface_budget, + "interface_budget": dict(interface_budget) if interface_budget else {}, "within_interface_budget": interface_budget.get("within_budget"), "interface_budget_char_count": interface_budget.get("budget_char_count"), "interface_budget_max_chars": interface_budget.get("max_chars"), @@ -136,15 +204,9 @@ def prompt_summary(prompt: dict[str, Any], mode: str) -> dict[str, Any]: } -def prompt_policy_audit(prompt: str | None) -> dict[str, Any]: +def prompt_policy_audit(prompt: str | None) -> Payload: if not isinstance(prompt, str) or not prompt.strip(): - return { - "available": False, - "status": "unavailable", - "warning_count": 0, - "warnings": [], - "reason": "installed prompt body is unavailable", - } + return _unavailable_policy_audit("installed prompt body is unavailable") warnings: list[dict[str, str]] = [] should_run_match = SHOULD_RUN_FALSE_RE.search(prompt) @@ -187,23 +249,17 @@ def prompt_policy_audit(prompt: str | None) -> dict[str, Any]: } -def installed_prompt_policy_audit(entry: dict[str, Any] | None) -> dict[str, Any]: +def installed_prompt_policy_audit(entry: PayloadView | None) -> Payload: if not entry: - return { - "available": False, - "status": "unavailable", - "warning_count": 0, - "warnings": [], - "reason": "installed prompt entry is unavailable", - } + return _unavailable_policy_audit("installed prompt entry is unavailable") audit = entry.get("prompt_policy_audit") if isinstance(audit, dict): - return audit + return cast(Payload, audit) task_body = entry.get("task_body") return prompt_policy_audit(task_body if isinstance(task_body, str) else None) -def load_installed_manifest(path: Path | None) -> dict[str, Any]: +def load_installed_manifest(path: Path | None) -> Payload: if path is None: return load_codex_app_automation_manifest() if not path.exists(): @@ -213,17 +269,17 @@ def load_installed_manifest(path: Path | None) -> dict[str, Any]: "entries": [], "reason": "installed automation manifest does not exist", } - raw = json.loads(path.read_text(encoding="utf-8")) + raw: object = json.loads(path.read_text(encoding="utf-8")) if isinstance(raw, list): - entries = raw + raw_entries: object = raw elif isinstance(raw, dict): - entries = raw.get("automations") or raw.get("entries") or [] + raw_entries = raw.get("automations") or raw.get("entries") or [] else: - entries = [] + raw_entries = [] return { "available": True, "path": str(path), - "entries": [entry for entry in entries if isinstance(entry, dict)], + "entries": _dict_list(raw_entries), } @@ -231,34 +287,30 @@ def codex_home() -> Path: return Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex").expanduser() -def parse_automation_toml(path: Path) -> dict[str, Any]: - return tomllib.loads(path.read_text(encoding="utf-8")) +def parse_automation_toml(path: Path) -> Payload: + return cast(Payload, tomllib.loads(path.read_text(encoding="utf-8"))) def infer_goal_id_from_prompt(prompt: str) -> str | None: - patterns = ( - r"Advance\s+`([^`]+)`\s+from\b", - r"Advance\s+`([^`]+)`\s+using\b", - r"--goal-id\s+([A-Za-z0-9_.:-]+)", - r"goal_id:\s*`([^`]+)`", + return _first_match( + ( + r"Advance\s+`([^`]+)`\s+from\b", + r"Advance\s+`([^`]+)`\s+using\b", + r"--goal-id\s+([A-Za-z0-9_.:-]+)", + r"goal_id:\s*`([^`]+)`", + ), + prompt, ) - for pattern in patterns: - match = re.search(pattern, prompt) - if match: - return match.group(1) - return None def infer_agent_id_from_prompt(prompt: str) -> str | None: - patterns = ( - r"Agent:\s*`([^`]+)`", - r"--agent-id\s+([A-Za-z0-9_.:-]+)", + return _first_match( + ( + r"Agent:\s*`([^`]+)`", + r"--agent-id\s+([A-Za-z0-9_.:-]+)", + ), + prompt, ) - for pattern in patterns: - match = re.search(pattern, prompt) - if match: - return match.group(1) - return None def infer_prompt_mode(prompt: str) -> str: @@ -272,13 +324,12 @@ def infer_prompt_mode(prompt: str) -> str: def infer_available_capabilities_from_prompt(prompt: str) -> list[str]: - return normalize_required_capabilities( - AVAILABLE_CAPABILITY_PATTERN.findall(prompt) - ) + return normalize_required_capabilities(AVAILABLE_CAPABILITY_PATTERN.findall(prompt)) -def load_codex_app_automation_manifest(root: Path | None = None) -> dict[str, Any]: +def load_codex_app_automation_manifest(root: Path | None = None) -> Payload: from .control_plane.heartbeat.automation_upgrade import bootstrap_binding + home = root or codex_home() automations_root = home / "automations" if not automations_root.exists(): @@ -293,10 +344,11 @@ def load_codex_app_automation_manifest(root: Path | None = None) -> dict[str, An "parse_errors_complete": True, } - entries: list[dict[str, Any]] = [] + entries: list[Payload] = [] parse_errors: list[dict[str, str]] = [] parse_error_count = 0 for path in sorted(automations_root.glob("*/automation.toml")): + parse_error_reason: str | None = None try: automation = parse_automation_toml(path) except OSError: @@ -305,17 +357,10 @@ def load_codex_app_automation_manifest(root: Path | None = None) -> dict[str, An parse_error_reason = "invalid_utf8" except tomllib.TOMLDecodeError: parse_error_reason = "invalid_toml" - else: - parse_error_reason = None if parse_error_reason is not None: parse_error_count += 1 if len(parse_errors) < _AUTOMATION_PARSE_ERROR_LIMIT: - parse_errors.append( - { - "automation_id": path.parent.name, - "reason": parse_error_reason, - } - ) + parse_errors.append({"automation_id": path.parent.name, "reason": parse_error_reason}) continue if automation.get("kind") != "heartbeat": continue @@ -328,6 +373,11 @@ def load_codex_app_automation_manifest(root: Path | None = None) -> dict[str, An agent_id = infer_agent_id_from_prompt(prompt) status = str(automation.get("status") or "ACTIVE") binding = bootstrap_binding(prompt) + runtime_thin_bootstrap: Payload | None = ( + {**{str(key): value for key, value in binding.items()}, "registry": str(binding["registry"])} + if binding + else None + ) entries.append( { "automation_id": str(automation.get("id") or path.parent.name), @@ -338,19 +388,13 @@ def load_codex_app_automation_manifest(root: Path | None = None) -> dict[str, An "char_count": len(prompt), "line_count": len(prompt.splitlines()), "prompt_policy_audit": prompt_policy_audit(prompt), - "available_capabilities": infer_available_capabilities_from_prompt( - prompt - ), + "available_capabilities": infer_available_capabilities_from_prompt(prompt), "rrule": str(automation.get("rrule") or "").strip(), - "target_thread_id": str( - automation.get("target_thread_id") or "" - ).strip(), + "target_thread_id": str(automation.get("target_thread_id") or "").strip(), "status": status, "installed": status.upper() != "DELETED", "source": "codex_app_automation_toml", - "runtime_thin_bootstrap": { - **binding, "registry": str(binding["registry"]), - } if binding else None, + "runtime_thin_bootstrap": runtime_thin_bootstrap, "path": str(path), } ) @@ -381,7 +425,7 @@ def resolve_codex_app_automation_rrule( agent_id: str | None = None, thread_id: str | None = None, root: Path | None = None, -) -> dict[str, Any]: +) -> Payload: """Resolve one active Codex App heartbeat RRULE without exposing its body.""" manifest = load_codex_app_automation_manifest(root) @@ -392,19 +436,15 @@ def resolve_codex_app_automation_rrule( safe_thread_id = str(thread_id or os.environ.get("CODEX_THREAD_ID") or "").strip() candidates = [ entry - for entry in manifest.get("entries", []) - if isinstance(entry, dict) - and entry.get("installed") is True + for entry in _dict_list(manifest.get("entries")) + if entry.get("installed") is True and str(entry.get("goal_id") or "") == safe_goal_id and (not safe_agent_id or str(entry.get("agent_id") or "") == safe_agent_id) - and ( - not safe_thread_id - or str(entry.get("target_thread_id") or "") == safe_thread_id - ) + and (not safe_thread_id or str(entry.get("target_thread_id") or "") == safe_thread_id) and str(entry.get("rrule") or "").strip() ] if len(candidates) != 1: - result = { + result: Payload = { "available": False, "reason": ( "Codex App heartbeat RRULE is ambiguous" @@ -413,13 +453,11 @@ def resolve_codex_app_automation_rrule( ), "candidate_count": len(candidates), } - parse_error_count = int(manifest.get("parse_error_count") or 0) + parse_error_count = _int_value(manifest.get("parse_error_count")) if parse_error_count: result["manifest_parse_error_count"] = parse_error_count result["manifest_parse_errors"] = manifest.get("parse_errors") or [] - result["manifest_parse_errors_complete"] = ( - manifest.get("parse_errors_complete") is True - ) + result["manifest_parse_errors_complete"] = manifest.get("parse_errors_complete") is True return result entry = candidates[0] return { @@ -430,42 +468,35 @@ def resolve_codex_app_automation_rrule( } -def installed_entry_digest(entry: dict[str, Any]) -> str | None: +def installed_entry_digest(entry: PayloadView) -> str | None: for key in ("prompt_sha256", "task_body_sha256", "sha256"): value = entry.get(key) if value: return str(value) task_body = entry.get("task_body") - if isinstance(task_body, str): - return prompt_digest(task_body) - return None + return prompt_digest(task_body) if isinstance(task_body, str) else None -def installed_entry_available_capabilities( - entry: dict[str, Any] | None, -) -> list[str]: +def installed_entry_available_capabilities(entry: PayloadView | None) -> list[str]: if not entry: return [] explicit = normalize_required_capabilities(entry.get("available_capabilities")) if explicit: return explicit task_body = entry.get("task_body") - if isinstance(task_body, str): - return infer_available_capabilities_from_prompt(task_body) - return [] + return infer_available_capabilities_from_prompt(task_body) if isinstance(task_body, str) else [] -def entry_declares_not_installed(entry: dict[str, Any] | None) -> bool: +def entry_declares_not_installed(entry: PayloadView | None) -> bool: if not entry: return False status = str(entry.get("status") or "").replace("-", "_").lower() if status in {"not_installed", "no_automation", "uninstalled"}: return True - installed = entry.get("installed") - return installed is False + return entry.get("installed") is False -def entry_key(entry: dict[str, Any]) -> tuple[str, str, str]: +def entry_key(entry: PayloadView) -> tuple[str, str, str]: return ( str(entry.get("goal_id") or ""), str(entry.get("mode") or DEFAULT_UPGRADE_MODES[0]), @@ -473,8 +504,8 @@ def entry_key(entry: dict[str, Any]) -> tuple[str, str, str]: ) -def index_installed_entries(entries: list[dict[str, Any]]) -> dict[tuple[str, str, str], dict[str, Any]]: - indexed: dict[tuple[str, str, str], dict[str, Any]] = {} +def index_installed_entries(entries: Sequence[PayloadView]) -> dict[tuple[str, str, str], PayloadView]: + indexed: dict[tuple[str, str, str], PayloadView] = {} for entry in entries: goal_id, mode, agent_id = entry_key(entry) if goal_id: @@ -487,12 +518,12 @@ def prompt_target_key(mode: str, agent_id: str | None) -> str: def peer_runtime_upgrade_migration( - goal: dict[str, Any], + goal: PayloadView, *, goal_id: str, - installed: dict[str, dict[str, Any]], - generated_prompts: dict[str, dict[str, Any]], -) -> dict[str, Any]: + installed: Mapping[str, PayloadView], + generated_prompts: Mapping[str, PayloadView], +) -> Payload: if peer_agent_runtime_migration_completed(goal): completed = completed_peer_agent_runtime_migration(goal) or {} return { @@ -508,12 +539,9 @@ def peer_runtime_upgrade_migration( "status": "not_required", } migration_id = peer_agent_runtime_migration_id(goal_id, goal) - host_updates = [] + host_updates: list[Payload] = [] for target, prompt_status in installed.items(): - if not ( - prompt_status.get("installed") is True - and prompt_status.get("requires_update") is True - ): + if not (prompt_status.get("installed") is True and prompt_status.get("requires_update") is True): continue generated = generated_prompts.get(target) or {} host_updates.append( @@ -549,14 +577,21 @@ def peer_runtime_upgrade_migration( } -def build_loop_activation_summary( - *, - installed: dict[str, dict[str, Any]], -) -> dict[str, Any]: - current_targets = [key for key, value in installed.items() if value.get("status") == "current"] - stale_targets = [key for key, value in installed.items() if value.get("status") == "stale"] - missing_targets = [key for key, value in installed.items() if value.get("status") == "unknown"] - not_installed_targets = [key for key, value in installed.items() if value.get("status") == "not_installed"] +def build_loop_activation_summary(*, installed: Mapping[str, PayloadView]) -> Payload: + targets_by_status: dict[str, list[str]] = { + "current": [], + "stale": [], + "unknown": [], + "not_installed": [], + } + for key, value in installed.items(): + bucket = targets_by_status.get(str(value.get("status") or "")) + if bucket is not None: + bucket.append(key) + current_targets = targets_by_status["current"] + stale_targets = targets_by_status["stale"] + missing_targets = targets_by_status["unknown"] + not_installed_targets = targets_by_status["not_installed"] target_count = len(installed) if target_count and len(current_targets) == target_count: status = "current" @@ -597,24 +632,20 @@ def build_loop_activation_summary( } -HOST_LOOP_UPDATE_STATUSES = {"missing", "partial", "stale", "unknown", "error", "unavailable"} - - -def goal_adapter(goal: dict[str, Any]) -> dict[str, Any]: - adapter = goal.get("adapter") - return adapter if isinstance(adapter, dict) else {} +def goal_adapter(goal: PayloadView) -> PayloadView: + return _dict_view(goal.get("adapter")) -def goal_adapter_status(goal: dict[str, Any]) -> str: +def goal_adapter_status(goal: PayloadView) -> str: return str(goal_adapter(goal).get("status") or "") -def goal_adapter_kind(goal: dict[str, Any]) -> str | None: +def goal_adapter_kind(goal: PayloadView) -> str | None: kind = goal_adapter(goal).get("kind") return str(kind) if kind else None -def goal_is_stage_deferred(goal: dict[str, Any]) -> bool: +def goal_is_stage_deferred(goal: PayloadView) -> bool: attention_status = str(goal.get("attention_status") or "").replace("-", "_").lower() if attention_status in STAGE_DEFERRED_ATTENTION_STATUSES: return True @@ -622,7 +653,7 @@ def goal_is_stage_deferred(goal: dict[str, Any]) -> bool: return adapter_status in STAGE_DEFERRED_ADAPTER_STATUSES -def stage_deferred_goal_summary(goal: dict[str, Any], state_file: Path | None) -> dict[str, Any]: +def stage_deferred_goal_summary(goal: PayloadView, state_file: Path | None) -> Payload: return { "goal_id": str(goal.get("id") or ""), "adapter_kind": goal_adapter_kind(goal), @@ -639,29 +670,26 @@ def stage_deferred_goal_summary(goal: dict[str, Any], state_file: Path | None) - } -def managed_default_upgrade_target(goal: dict[str, Any]) -> dict[str, Any]: - installed = goal.get("installed_prompts") if isinstance(goal.get("installed_prompts"), dict) else {} - mode_summaries: list[dict[str, Any]] = [] +def managed_default_upgrade_target(goal: PayloadView) -> Payload: + installed = _dict_view(goal.get("installed_prompts")) + mode_summaries: list[Payload] = [] statuses: set[str] = set() policy_warning_count = 0 for mode, prompt_status in installed.items(): if not isinstance(prompt_status, dict): continue - status = str(prompt_status.get("status") or "unknown") + prompt_view = cast(PayloadView, prompt_status) + status = str(prompt_view.get("status") or "unknown") statuses.add(status) - audit = ( - prompt_status.get("prompt_policy_audit") - if isinstance(prompt_status.get("prompt_policy_audit"), dict) - else {} - ) - warning_count = int(audit.get("warning_count") or 0) + audit = _dict_view(prompt_view.get("prompt_policy_audit")) + warning_count = _int_value(audit.get("warning_count")) policy_warning_count += warning_count mode_summaries.append( { "mode": mode, "status": status, - "requires_update": bool(prompt_status.get("requires_update")), - "automation_id": prompt_status.get("automation_id"), + "requires_update": bool(prompt_view.get("requires_update")), + "automation_id": prompt_view.get("automation_id"), "policy_warning_count": warning_count, } ) @@ -698,11 +726,11 @@ def managed_default_upgrade_target(goal: dict[str, Any]) -> dict[str, Any]: def build_default_upgrade_propagation( *, - summary: dict[str, Any], - managed: list[dict[str, Any]], - deferred: list[dict[str, Any]], + summary: PayloadView, + managed: Sequence[PayloadView], + deferred: Sequence[PayloadView], recommended_action: str, -) -> dict[str, Any]: +) -> Payload: managed_targets = [managed_default_upgrade_target(goal) for goal in managed] stage_deferred_targets = [ { @@ -732,6 +760,33 @@ def build_default_upgrade_propagation( } +def _summarize_managed_heartbeats(managed: Sequence[PayloadView]) -> dict[str, int]: + counts = { + "unknown": 0, "stale": 0, "current": 0, "not_installed": 0, + "policy_warning_count": 0, "policy_warning_prompt_count": 0, + "host_loop_activated": 0, "host_loop_missing": 0, "peer_runtime_migration_count": 0, + } + for goal in managed: + for installed in _dict_view(goal.get("installed_prompts")).values(): + if not isinstance(installed, dict): + continue + status_value = installed.get("status") + if status_value in {"unknown", "stale", "current", "not_installed"}: + counts[str(status_value)] += 1 + warning_count = _int_value(_dict_view(installed.get("prompt_policy_audit")).get("warning_count")) + counts["policy_warning_count"] += warning_count + if warning_count > 0: + counts["policy_warning_prompt_count"] += 1 + activation = _dict_view(goal.get("host_loop_activation")) + if activation.get("activated") is True: + counts["host_loop_activated"] += 1 + if activation.get("status") in HOST_LOOP_UPDATE_STATUSES: + counts["host_loop_missing"] += 1 + if _dict_view(goal.get("peer_runtime_automation_migration")).get("required") is True: + counts["peer_runtime_migration_count"] += 1 + return counts + + def build_upgrade_plan( *, registry_path: Path, @@ -740,7 +795,7 @@ def build_upgrade_plan( cli_bin: str = "loopx", modes: list[str] | tuple[str, ...] | None = None, goal_ids: list[str] | tuple[str, ...] | None = None, -) -> dict[str, Any]: +) -> Payload: registry = load_registry(registry_path) runtime_root = resolve_runtime_root(registry, runtime_root_override) if not registry_path.exists(): @@ -753,29 +808,28 @@ def build_upgrade_plan( selected_modes = tuple(modes or DEFAULT_UPGRADE_MODES) selected_goal_ids = set(goal_ids or []) manifest = load_installed_manifest(installed_manifest) - manifest_entries = manifest["entries"] - manifest_task_body_count = sum(1 for entry in manifest_entries if isinstance(entry, dict) and "task_body" in entry) - installed_by_key = index_installed_entries(manifest["entries"]) - managed: list[dict[str, Any]] = [] - deferred: list[dict[str, Any]] = [] - - for goal in registry_goals(registry): + manifest_entries = _dict_list(manifest.get("entries")) + manifest_task_body_count = sum(1 for entry in manifest_entries if "task_body" in entry) + installed_by_key = index_installed_entries(manifest_entries) + managed: list[Payload] = [] + deferred: list[Payload] = [] + + for raw_goal in registry_goals(registry): + goal = cast(Payload, raw_goal) goal_id = str(goal.get("id") or "") if selected_goal_ids and goal_id not in selected_goal_ids: continue repo = Path(str(goal.get("repo") or ".")).expanduser() - state_file = resolve_state_file(repo, goal.get("state_file")) + raw_state_file = goal.get("state_file") + state_file = resolve_state_file(repo, str(raw_state_file) if raw_state_file else None) if goal_is_stage_deferred(goal): deferred.append(stage_deferred_goal_summary(goal, state_file)) continue registered_agents = registered_agent_ids_for_goal(goal) - prompt_summaries: dict[str, dict[str, Any]] = {} - installed: dict[str, dict[str, Any]] = {} - prompt_targets = [ - (mode, agent_id) - for mode in selected_modes - for agent_id in (registered_agents or [None]) - ] + prompt_summaries: dict[str, Payload] = {} + installed: dict[str, Payload] = {} + target_agents: Sequence[str | None] = registered_agents or (None,) + prompt_targets = [(mode, agent_id) for mode in selected_modes for agent_id in target_agents] for mode, agent_id in prompt_targets: key = prompt_target_key(mode, agent_id) entry = installed_by_key.get((goal_id, mode, agent_id or "")) @@ -785,22 +839,19 @@ def build_upgrade_plan( legacy_unscoped = entry is not None available_capabilities = installed_entry_available_capabilities(entry) prompt = goal_heartbeat_prompt( - goal, - cli_bin=cli_bin, - mode=mode, - agent_id=agent_id, + goal, cli_bin=cli_bin, mode=mode, agent_id=agent_id, available_capabilities=available_capabilities, ) - summary = prompt_summary(prompt, mode) - summary["agent_id"] = agent_id - summary["prompt_target"] = key - prompt_summaries[key] = summary - expected_digest = str(summary.get("sha256") or "") + prompt_meta = prompt_summary(prompt, mode) + prompt_meta["agent_id"] = agent_id + prompt_meta["prompt_target"] = key + prompt_summaries[key] = prompt_meta + expected_digest = str(prompt_meta.get("sha256") or "") not_installed = entry_declares_not_installed(entry) actual_digest = None if not_installed else installed_entry_digest(entry) if entry else None - bootstrap = entry.get("runtime_thin_bootstrap") if entry else None + bootstrap = _dict_view(entry.get("runtime_thin_bootstrap")) if entry else {} live_thin = bool( - isinstance(bootstrap, dict) + bootstrap and mode == "thin" and bootstrap.get("goal_id") == goal_id and bootstrap.get("agent_id") == agent_id @@ -808,49 +859,27 @@ def build_upgrade_plan( and bootstrap.get("runtime_root") == (str(Path(runtime_root_override).expanduser().resolve()) if runtime_root_override else None) and Path(str(bootstrap.get("registry"))).resolve() == Path(registry_path).resolve() ) - status = "unknown" - if not_installed: - status = "not_installed" - elif entry: - status = "current" if live_thin or actual_digest == expected_digest else "stale" + prompt_status = "not_installed" if not_installed else ("current" if live_thin or actual_digest == expected_digest else "stale") if entry else "unknown" policy_audit = ( - { - "available": False, - "status": "not_applicable", - "warning_count": 0, - "warnings": [], - "reason": "heartbeat is explicitly not installed", - } + _unavailable_policy_audit("heartbeat is explicitly not installed", status="not_applicable") if not_installed else installed_prompt_policy_audit(entry) ) - warnings = ( - policy_audit.get("warnings") - if isinstance(policy_audit.get("warnings"), list) - else [] - ) + warnings = _dict_list(policy_audit.get("warnings")) if legacy_unscoped: warnings = [ *warnings, { "kind": "legacy_unscoped_prompt_for_registered_agent", "severity": "warning", - "recommended_action": ( - "replace this heartbeat with a scoped prompt generated with " - f"--agent-id {agent_id}" - ), + "recommended_action": f"replace this heartbeat with a scoped prompt generated with --agent-id {agent_id}", }, ] - policy_audit = { - **policy_audit, - "status": "warning", - "warning_count": len(warnings), - "warnings": warnings, - } - policy_warning_count = int(policy_audit.get("warning_count") or 0) + policy_audit = {**policy_audit, "status": "warning", "warning_count": len(warnings), "warnings": warnings} + policy_warning_count = _int_value(policy_audit.get("warning_count")) installed[key] = { - "status": status, - "requires_update": status in {"unknown", "stale"} or policy_warning_count > 0, + "status": prompt_status, + "requires_update": prompt_status in {"unknown", "stale"} or policy_warning_count > 0, "automation_id": entry.get("automation_id") if entry else None, "installed": False if not_installed else bool(entry), "agent_id": agent_id, @@ -863,10 +892,7 @@ def build_upgrade_plan( } loop_activation = build_loop_activation_summary(installed=installed) runtime_migration = peer_runtime_upgrade_migration( - goal, - goal_id=goal_id, - installed=installed, - generated_prompts=prompt_summaries, + goal, goal_id=goal_id, installed=installed, generated_prompts=prompt_summaries, ) managed.append( @@ -883,85 +909,32 @@ def build_upgrade_plan( "installed_prompts": installed, "host_loop_activation": loop_activation, "peer_runtime_automation_migration": runtime_migration, - "requires_update": any(item["requires_update"] for item in installed.values()) + "requires_update": any(bool(item["requires_update"]) for item in installed.values()) or loop_activation.get("status") in HOST_LOOP_UPDATE_STATUSES or runtime_migration.get("required") is True, } ) - unknown = sum( - 1 - for goal in managed - for installed in goal["installed_prompts"].values() - if installed["status"] == "unknown" - ) - stale = sum( - 1 - for goal in managed - for installed in goal["installed_prompts"].values() - if installed["status"] == "stale" - ) - current = sum( - 1 - for goal in managed - for installed in goal["installed_prompts"].values() - if installed["status"] == "current" - ) - not_installed = sum( - 1 - for goal in managed - for installed in goal["installed_prompts"].values() - if installed["status"] == "not_installed" - ) - policy_warning_count = sum( - int(installed.get("prompt_policy_audit", {}).get("warning_count") or 0) - for goal in managed - for installed in goal["installed_prompts"].values() - if isinstance(installed, dict) - ) - policy_warning_prompt_count = sum( - 1 - for goal in managed - for installed in goal["installed_prompts"].values() - if int(installed.get("prompt_policy_audit", {}).get("warning_count") or 0) > 0 - ) - host_loop_activated = sum( - 1 - for goal in managed - if isinstance(goal.get("host_loop_activation"), dict) - and goal["host_loop_activation"].get("activated") is True - ) - host_loop_missing = sum( - 1 - for goal in managed - if isinstance(goal.get("host_loop_activation"), dict) - and goal["host_loop_activation"].get("status") in HOST_LOOP_UPDATE_STATUSES - ) - peer_runtime_migration_count = sum( - 1 - for goal in managed - if isinstance(goal.get("peer_runtime_automation_migration"), dict) - and goal["peer_runtime_automation_migration"].get("required") is True - ) + counts = _summarize_managed_heartbeats(managed) ready = ( bool(managed) - and unknown == 0 - and stale == 0 - and policy_warning_count == 0 - and host_loop_missing == 0 - and peer_runtime_migration_count == 0 + and counts["unknown"] == 0 + and counts["stale"] == 0 + and counts["policy_warning_count"] == 0 + and counts["host_loop_missing"] == 0 + and counts["peer_runtime_migration_count"] == 0 ) if ready: recommended_action = "promotion propagation is complete" - elif peer_runtime_migration_count > 0: + elif counts["peer_runtime_migration_count"] > 0: recommended_action = ( "complete each peer runtime automation migration in the projected order; " "stable migration ids make host updates idempotent and each completion ack " "removes the prompt exactly once" ) - elif host_loop_missing > 0: + elif counts["host_loop_missing"] > 0: recommended_action = "activate missing host loops from generated scoped heartbeat prompts before claiming autonomous setup" - elif policy_warning_count > 0: + elif counts["policy_warning_count"] > 0: recommended_action = "regenerate installed heartbeat automations with prompt policy warnings before default promotion" elif managed: recommended_action = "refresh installed heartbeat automations/controller clients before default promotion" @@ -969,33 +942,28 @@ def build_upgrade_plan( recommended_action = "selected heartbeats are stage-deferred; do not install until the operator authorizes that stage" else: recommended_action = "no registry-managed heartbeats matched the upgrade plan selection" - summary = { + summary: Payload = { "managed_goal_count": len(managed), - "current_prompt_count": current, - "stale_prompt_count": stale, - "unknown_prompt_count": unknown, - "not_installed_prompt_count": not_installed, + "current_prompt_count": counts["current"], + "stale_prompt_count": counts["stale"], + "unknown_prompt_count": counts["unknown"], + "not_installed_prompt_count": counts["not_installed"], "stage_deferred_goal_count": len(deferred), "ready_for_default_promotion": ready, "installed_manifest_available": manifest.get("available"), "installed_manifest_source": manifest.get("source"), "installed_manifest_entry_count": len(manifest_entries), - "installed_manifest_parse_error_count": int( - manifest.get("parse_error_count") or 0 - ), + "installed_manifest_parse_error_count": _int_value(manifest.get("parse_error_count")), "installed_manifest_task_body_count": manifest_task_body_count, "installed_manifest_has_task_body": manifest_task_body_count > 0, - "installed_prompt_policy_warning_count": policy_warning_count, - "installed_prompt_policy_warning_prompt_count": policy_warning_prompt_count, - "host_loop_activated_goal_count": host_loop_activated, - "host_loop_missing_goal_count": host_loop_missing, - "peer_runtime_automation_migration_count": peer_runtime_migration_count, + "installed_prompt_policy_warning_count": counts["policy_warning_count"], + "installed_prompt_policy_warning_prompt_count": counts["policy_warning_prompt_count"], + "host_loop_activated_goal_count": counts["host_loop_activated"], + "host_loop_missing_goal_count": counts["host_loop_missing"], + "peer_runtime_automation_migration_count": counts["peer_runtime_migration_count"], } default_upgrade_propagation = build_default_upgrade_propagation( - summary=summary, - managed=managed, - deferred=deferred, - recommended_action=recommended_action, + summary=summary, managed=managed, deferred=deferred, recommended_action=recommended_action, ) return { "ok": True, @@ -1013,134 +981,64 @@ def build_upgrade_plan( } -def render_upgrade_plan_markdown(payload: dict[str, Any]) -> str: - summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {} +def render_upgrade_plan_markdown(payload: PayloadView) -> str: + summary = _dict_view(payload.get("summary")) lines = [ "# LoopX Upgrade Plan", "", - f"- ok: `{payload.get('ok')}`", - f"- registry: `{payload.get('registry')}`", - f"- runtime_root: `{payload.get('runtime_root')}`", - f"- cli_bin: `{payload.get('cli_bin')}`", - f"- prompt_modes: `{', '.join(payload.get('prompt_modes') or [])}`", - f"- ready_for_default_promotion: `{summary.get('ready_for_default_promotion')}`", - f"- managed_goal_count: `{summary.get('managed_goal_count')}`", - f"- current_prompt_count: `{summary.get('current_prompt_count')}`", - f"- stale_prompt_count: `{summary.get('stale_prompt_count')}`", - f"- unknown_prompt_count: `{summary.get('unknown_prompt_count')}`", - f"- not_installed_prompt_count: `{summary.get('not_installed_prompt_count')}`", - f"- stage_deferred_goal_count: `{summary.get('stage_deferred_goal_count')}`", - f"- installed_manifest_source: `{summary.get('installed_manifest_source')}`", - f"- installed_manifest_entry_count: `{summary.get('installed_manifest_entry_count')}`", - f"- installed_manifest_parse_error_count: `{summary.get('installed_manifest_parse_error_count')}`", - f"- installed_manifest_has_task_body: `{summary.get('installed_manifest_has_task_body')}`", - f"- installed_prompt_policy_warning_count: `{summary.get('installed_prompt_policy_warning_count')}`", - f"- installed_prompt_policy_warning_prompt_count: `{summary.get('installed_prompt_policy_warning_prompt_count')}`", - f"- host_loop_activated_goal_count: `{summary.get('host_loop_activated_goal_count')}`", - f"- host_loop_missing_goal_count: `{summary.get('host_loop_missing_goal_count')}`", - f"- peer_runtime_automation_migration_count: `{summary.get('peer_runtime_automation_migration_count')}`", + *_bullet_fields(payload, ("ok", "registry", "runtime_root", "cli_bin")), + f"- prompt_modes: `{', '.join(_str_list(payload.get('prompt_modes')))}`", + *_bullet_fields(summary, _SUMMARY_MARKDOWN_FIELDS), f"- recommended_action: `{payload.get('recommended_action')}`", ] - manifest = payload.get("installed_manifest") if isinstance(payload.get("installed_manifest"), dict) else {} - lines.extend( - [ - "", - "## Installed Manifest", - "", - f"- available: `{manifest.get('available')}`", - f"- path: `{manifest.get('path')}`", - f"- reason: `{manifest.get('reason')}`", - f"- parse_error_count: `{manifest.get('parse_error_count')}`", - f"- parse_errors_complete: `{manifest.get('parse_errors_complete')}`", - ] - ) - for error in manifest.get("parse_errors") or []: - if not isinstance(error, dict): - continue + manifest = _dict_view(payload.get("installed_manifest")) + lines.extend(["", "## Installed Manifest", "", *_bullet_fields(manifest, _MANIFEST_MARKDOWN_FIELDS)]) + for error in _dict_list(manifest.get("parse_errors")): lines.append( f"- parse_error automation_id=`{error.get('automation_id')}` " f"reason=`{error.get('reason')}`" ) - propagation = ( - payload.get("default_upgrade_propagation") - if isinstance(payload.get("default_upgrade_propagation"), dict) - else {} - ) - lines.extend( - [ - "", - "## Default Upgrade Propagation", - "", - f"- schema_version: `{propagation.get('schema_version')}`", - f"- ready_for_default_promotion: `{propagation.get('ready_for_default_promotion')}`", - f"- managed_target_count: `{propagation.get('managed_target_count')}`", - f"- deferred_target_count: `{propagation.get('deferred_target_count')}`", - f"- update_count: `{propagation.get('update_count')}`", - f"- deferred_install_count: `{propagation.get('deferred_install_count')}`", - f"- recommended_action: `{propagation.get('recommended_action')}`", - ] - ) - managed_targets = ( - propagation.get("managed_targets") if isinstance(propagation.get("managed_targets"), list) else [] - ) - for target in managed_targets: - if not isinstance(target, dict): - continue + propagation = _dict_view(payload.get("default_upgrade_propagation")) + lines.extend(["", "## Default Upgrade Propagation", "", *_bullet_fields(propagation, _PROPAGATION_MARKDOWN_FIELDS)]) + for target in _dict_list(propagation.get("managed_targets")): lines.append( f"- managed `{target.get('goal_id')}` action=`{target.get('action')}` " f"requires_update=`{target.get('requires_update')}` reason=`{target.get('reason')}`" ) - for goal in payload.get("managed_heartbeats") or []: - if not isinstance(goal, dict): - continue - migration = goal.get("peer_runtime_automation_migration") - if not isinstance(migration, dict) or migration.get("required") is not True: - continue - lines.extend( - [ - "", - f"## Peer Runtime Migration: {goal.get('goal_id')}", - "", - f"- migration_id: `{migration.get('migration_id')}`", - f"- delivery_semantics: `{migration.get('delivery_semantics')}`", - f"- host_update_required_once: `{migration.get('host_update_required_once')}`", - f"- completion_command: `{migration.get('completion_command')}`", - ] - ) - deferred_targets = ( - propagation.get("stage_deferred_targets") - if isinstance(propagation.get("stage_deferred_targets"), list) - else [] - ) - for target in deferred_targets: - if not isinstance(target, dict): + managed_heartbeats = _dict_list(payload.get("managed_heartbeats")) + for goal in managed_heartbeats: + migration = _dict_view(goal.get("peer_runtime_automation_migration")) + if migration.get("required") is not True: continue + lines.extend(["", f"## Peer Runtime Migration: {goal.get('goal_id')}", "", *_bullet_fields(migration, _MIGRATION_MARKDOWN_FIELDS)]) + for target in _dict_list(propagation.get("stage_deferred_targets")): lines.append( f"- deferred `{target.get('goal_id')}` action=`{target.get('action')}` " f"requires_update=`{target.get('requires_update')}`" ) lines.extend(["", "## Managed Heartbeats", ""]) - for goal in payload.get("managed_heartbeats") or []: - installed = goal.get("installed_prompts") if isinstance(goal.get("installed_prompts"), dict) else {} - generated = goal.get("generated_prompts") if isinstance(goal.get("generated_prompts"), dict) else {} - activation = ( - goal.get("host_loop_activation") - if isinstance(goal.get("host_loop_activation"), dict) - else {} - ) - status_parts = [] - for mode, status in installed.items(): - if isinstance(status, dict): - audit = status.get("prompt_policy_audit") if isinstance(status.get("prompt_policy_audit"), dict) else {} - audit_warning_count = int(audit.get("warning_count") or 0) - audit_suffix = f",audit_warnings={audit_warning_count}" if audit_warning_count else "" - status_parts.append(f"{mode}={status.get('status')}{audit_suffix}") - prompt_parts = [] - for mode, prompt in generated.items(): - if isinstance(prompt, dict): - prompt_parts.append( - f"{mode}:sha={str(prompt.get('sha256') or '')[:12]} chars={prompt.get('char_count')}" - ) + for goal in managed_heartbeats: + installed = _dict_view(goal.get("installed_prompts")) + generated = _dict_view(goal.get("generated_prompts")) + activation = _dict_view(goal.get("host_loop_activation")) + status_parts: list[str] = [] + warning_lines: list[str] = [] + for mode, status_entry in installed.items(): + if not isinstance(status_entry, dict): + continue + audit = _dict_view(status_entry.get("prompt_policy_audit")) + audit_warning_count = _int_value(audit.get("warning_count")) + audit_suffix = f",audit_warnings={audit_warning_count}" if audit_warning_count else "" + status_parts.append(f"{mode}={status_entry.get('status')}{audit_suffix}") + warnings = _dict_list(audit.get("warnings")) + if warnings: + kinds = ", ".join(str(warning.get("kind")) for warning in warnings if warning.get("kind")) + warning_lines.append(f" prompt_policy_warnings[{mode}]: `{kinds}`") + prompt_parts = [ + f"{mode}:sha={str(prompt.get('sha256') or '')[:12]} chars={prompt.get('char_count')}" + for mode, prompt in generated.items() + if isinstance(prompt, dict) + ] lines.extend( [ f"- `{goal.get('goal_id')}` state_file_exists=`{goal.get('state_file_exists')}` " @@ -1150,27 +1048,13 @@ def render_upgrade_plan_markdown(payload: dict[str, Any]) -> str: f"activated=`{activation.get('activated')}` current=`{activation.get('current_count')}` " f"missing=`{activation.get('missing_count')}` stale=`{activation.get('stale_count')}`", f" prompts: `{'; '.join(prompt_parts)}`", + *warning_lines, ] ) - for mode, status in installed.items(): - if not isinstance(status, dict): - continue - audit = status.get("prompt_policy_audit") if isinstance(status.get("prompt_policy_audit"), dict) else {} - warnings = audit.get("warnings") if isinstance(audit.get("warnings"), list) else [] - if not warnings: - continue - kinds = ", ".join( - str(warning.get("kind")) - for warning in warnings - if isinstance(warning, dict) and warning.get("kind") - ) - lines.append(f" prompt_policy_warnings[{mode}]: `{kinds}`") - deferred = payload.get("stage_deferred_heartbeats") or [] - if deferred: + deferred_goals = _dict_list(payload.get("stage_deferred_heartbeats")) + if deferred_goals: lines.extend(["", "## Stage Deferred Heartbeats", ""]) - for goal in deferred: - if not isinstance(goal, dict): - continue + for goal in deferred_goals: lines.append( f"- `{goal.get('goal_id')}` adapter=`{goal.get('adapter_kind')}:{goal.get('adapter_status')}` " f"attention_status=`{goal.get('attention_status')}` requires_update=`{goal.get('requires_update')}`"