core-runtime 0.1.1__py3-none-any.whl

cli/logic/governance/engine.py

@@ -0,0 +1,216 @@
+# src/cli/logic/governance/engine.py
+
+"""
+Governance Coverage Engine.
+Determines system-wide compliance by cross-referencing the Constitution (Law)
+with Enforcement Mappings (Implementation).
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from mind.governance.audit_context import AuditorContext
+from mind.governance.enforcement_loader import EnforcementMappingLoader
+from mind.logic.engines.ast_gate import ASTGateEngine
+from shared.path_resolver import PathResolver
+
+
+def _extract_rules_from_policy(content: dict[str, Any]) -> list[dict[str, Any]]:
+    rules = content.get("rules", [])
+    return [r for r in rules if isinstance(r, dict)] if isinstance(rules, list) else []
+
+
+def _detect_policy_format(content: dict[str, Any]) -> str:
+    return (
+        "flat"
+        if "rules" in content and isinstance(content["rules"], list)
+        else "unknown"
+    )
+
+
+def _canonical_policy_key(key: str, content: dict[str, Any]) -> str:
+    source = (
+        content.get("_source_path")
+        or content.get("source_path")
+        or content.get("__source_path")
+    )
+    if isinstance(source, str) and source.strip():
+        return source
+    declared_id = content.get("id") or content.get("policy_id")
+    return declared_id if isinstance(declared_id, str) and declared_id.strip() else key
+
+
+def _dedupe_loaded_resources(
+    resources: dict[str, Any],
+) -> list[tuple[str, dict[str, Any]]]:
+    seen, unique = set(), []
+    for key, value in resources.items():
+        if not isinstance(key, str) or not isinstance(value, dict):
+            continue
+        if id(value) in seen:
+            continue
+        seen.add(id(value))
+        unique.append((key, value))
+    return sorted(unique, key=lambda kv: _canonical_policy_key(kv[0], kv[1]))
+
+
+def _supported_ast_gate_check_types() -> set[str]:
+    candidate = getattr(ASTGateEngine, "supported_check_types", None)
+    if callable(candidate):
+        try:
+            res = candidate()
+            return {str(x) for x in res if isinstance(x, str) and x.strip()}
+        except Exception:
+            return set()
+    return set()
+
+
+def _is_rule_implementable(engine: str | None, params: dict[str, Any]) -> bool:
+    """
+    V2.3 FIX: Logic moved to check the Engine and Parameters derived
+    from the YAML Mappings, not the JSON Law.
+    """
+    if not engine:
+        return False
+
+    if engine == "ast_gate":
+        check_type = params.get("check_type")
+        if check_type is None:
+            return True
+        supported = _supported_ast_gate_check_types()
+        # Ensure new types like 'required_calls' are recognized
+        supported.add("id_anchor")
+        supported.add("required_calls")
+        return check_type in supported
+
+    return engine in (
+        "glob_gate",
+        "workflow_gate",
+        "knowledge_gate",
+        "llm_gate",
+        "regex_gate",
+    )
+
+
+def _load_executed_ids(evidence: dict[str, Any]) -> set[str]:
+    for key in ["executed_rules", "executed_checks"]:
+        ids = evidence.get(key)
+        if isinstance(ids, list):
+            return {x for x in ids if isinstance(x, str) and x.strip()}
+    return set()
+
+
+# ID: 48f98a6f-2010-43ae-96fb-1b54eb7ec657
+def generate_coverage_map(repo_root: Path) -> dict[str, Any]:
+    """
+    Generates the coverage map by joining JSON Rules with YAML Mappings.
+    """
+    evidence_file = (
+        PathResolver.from_repo(repo_root).reports_dir / "audit" / "latest_audit.json"
+    )
+    if not evidence_file.exists():
+        executed_ids = set()
+    else:
+        with evidence_file.open(encoding="utf-8") as f:
+            evidence = json.load(f)
+        executed_ids = _load_executed_ids(evidence)
+
+    # Initialize Context and the all-important Enforcement Loader
+    auditor_context = AuditorContext(repo_root)
+    mapping_loader = EnforcementMappingLoader(repo_root / ".intent")
+
+    unique_docs = _dedupe_loaded_resources(auditor_context.policies or {})
+
+    policy_metadata, all_rules = {}, []
+
+    for key, content in unique_docs:
+        policy_key = _canonical_policy_key(key, content)
+        policy_metadata[policy_key] = {
+            "title": str(content.get("title", "")),
+            "id": str(content.get("id", "")),
+            "format": _detect_policy_format(content),
+        }
+
+        for rule_dict in _extract_rules_from_policy(content):
+            rid = rule_dict.get("id")
+            if not rid or rid.startswith(("standard_", "schema_", "global_")):
+                continue
+
+            # NEW: Look up the implementation strategy from the YAML mappings
+            strategy = mapping_loader.get_enforcement_strategy(rid)
+
+            engine = strategy.get("engine") if strategy else None
+            params = strategy.get("params", {}) if strategy else {}
+
+            all_rules.append(
+                {
+                    "rule_id": rid,
+                    "statement": rule_dict.get("statement")
+                    or rule_dict.get("title")
+                    or "",
+                    "severity": str(rule_dict.get("enforcement") or "warning").lower(),
+                    "policy": policy_key,
+                    "check_engine": engine,
+                    "implementable": _is_rule_implementable(engine, params),
+                }
+            )
+
+    entries = []
+    for rule in all_rules:
+        in_exec = rule["rule_id"] in executed_ids
+
+        status = "declared_only"
+        if in_exec:
+            status = "enforced"
+        elif rule.get("implementable"):
+            status = "implementable"
+
+        entries.append(
+            {"rule": rule, "coverage_status": status, "in_executed_ids": in_exec}
+        )
+
+    total = len(entries)
+    enforced_count = sum(1 for e in entries if e["coverage_status"] == "enforced")
+    implementable_count = sum(
+        1 for e in entries if e["coverage_status"] == "implementable"
+    )
+
+    return {
+        "metadata": {
+            "generated_at_utc": datetime.now(UTC).isoformat(),
+            "total_policy_rules": total,
+            "total_executed_ids": len(executed_ids),
+            "total_policy_files": len(policy_metadata),
+        },
+        "summary": {
+            "rules_total": total,
+            "rules_enforced": enforced_count,
+            "rules_implementable": implementable_count,
+            "rules_declared_only": total - enforced_count - implementable_count,
+            "execution_rate": (
+                round(100 * enforced_count / total, 1) if total > 0 else 0
+            ),
+        },
+        "entries": entries,
+        "executed_ids_list": sorted(executed_ids),
+        "policy_metadata": policy_metadata,
+    }
+
+
+# ID: de089263-22f0-4548-996f-27bb2f4a2dd2
+def ensure_coverage_map(repo_root: Path, file_handler: Any) -> Path:
+    map_path = (
+        PathResolver.from_repo(repo_root).reports_dir
+        / "governance"
+        / "enforcement_coverage_map.json"
+    )
+
+    # Force regeneration to reflect recent V2.3 mapping updates
+    data = generate_coverage_map(repo_root)
+    file_handler.write_runtime_json(str(map_path.relative_to(repo_root)), data)
+
+    return map_path

cli/logic/governance/forensics_service.py

@@ -0,0 +1,67 @@
+# src/cli/logic/governance/forensics_service.py
+
+"""
+Forensics Service - Phase 3 Hardening.
+Reconstructs the Chain of Legality by linking Agent decisions to Body actions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import text
+
+from body.services.service_registry import service_registry
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: e7b07817-9cc6-4082-a9ef-1c003ad71001
+class GovernanceForensicsService:
+    """
+    Assembles evidence packets for autonomous operations.
+    """
+
+    def __init__(self):
+        self.session_factory = service_registry.session
+
+    # ID: 5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b
+    async def get_audit_trail(self, session_id: str) -> dict[str, Any]:
+        """
+        Retrieves the complete history of thoughts and actions for a session.
+        """
+        async with self.session_factory() as session:
+            # 1. Get the Agent's reasoning (The Intent)
+            trace_query = text(
+                """
+                SELECT agent_name, goal, decisions, pattern_stats
+                FROM core.decision_traces
+                WHERE session_id = :sid
+            """
+            )
+            trace_res = await session.execute(trace_query, {"sid": session_id})
+            trace = trace_res.mappings().first()
+
+            # 2. Get the Body's execution (The Action)
+            # We match by looking for the session_id in the action metadata
+            action_query = text(
+                """
+                SELECT action_type, ok, error_message, action_metadata, created_at
+                FROM core.action_results
+                WHERE action_metadata::text LIKE :sid_pattern
+                ORDER BY created_at ASC
+            """
+            )
+            action_res = await session.execute(
+                action_query, {"sid_pattern": f"%{session_id}%"}
+            )
+            actions = action_res.mappings().all()
+
+        return {
+            "session_id": session_id,
+            "intent": dict(trace) if trace else None,
+            "actions": [dict(a) for a in actions],
+            "legality_verified": trace is not None and len(actions) > 0,
+        }

cli/logic/governance/limb_status_service.py

@@ -0,0 +1,83 @@
+# src/cli/logic/governance/limb_status_service.py
+
+"""
+Limb Status Service - Phase 3 Hardening.
+Summarizes recent limb operations to highlight system-wide issues.
+
+CONSTITUTIONAL COMPLIANCE:
+- logic.di.no_global_session: Session factory is injected via __init__.
+- logic.logging.standard_only: Uses getLogger, no Rich/Console usage.
+- architecture.boundary.settings_access: No direct settings import.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy import text
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().misc
+
+
+# ID: 56a20121-fe6c-4747-bd59-4021fd455df6
+class LimbStatusService:
+    """
+    Analyzes the Body's action ledger to provide a forensic health summary.
+    """
+
+    def __init__(self, session_factory: Callable):
+        """
+        Constitutional DI: Receives factory, does not import globals.
+        """
+        self.session_factory = session_factory
+
+    # ID: 30c15118-63c5-4356-9586-e254a8cb8ff1
+    async def get_recent_limb_health(
+        self, limit: int = _CFG.limb_status_recent_limit
+    ) -> dict[str, Any]:
+        """
+        Queries the action_results table and groups failing patterns.
+        """
+        async with self.session_factory() as session:
+            # Sensation: Pull the most recent operational evidence
+            query = text(
+                """
+                SELECT action_type, ok, error_message, created_at
+                FROM core.action_results
+                ORDER BY created_at DESC
+                LIMIT :limit
+            """
+            )
+            res = await session.execute(query, {"limit": limit})
+            actions = res.mappings().all()
+
+        if not actions:
+            return {"status": "unknown", "issues": []}
+
+        # Logic: Detect failing neurons
+        issues = []
+        failures = 0
+        for a in actions:
+            if not a["ok"]:
+                failures += 1
+                issues.append(
+                    {
+                        "action": a["action_type"],
+                        "error": a["error_message"] or "Policy Warning",
+                        "time": a["created_at"],
+                    }
+                )
+
+        return {
+            "total_checked": len(actions),
+            "failure_count": failures,
+            "status": "OPTIMAL" if failures == 0 else "DEGRADED",
+            "issues": issues,
+        }

cli/logic/governance/renderer.py

@@ -0,0 +1,115 @@
+# src/cli/logic/governance/renderer.py
+
+"""Refactored logic for src/body/cli/logic/governance/renderer.py."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+
+# ID: a466a91e-d15a-475f-99fb-d7d8f20ffdf4
+def render_summary(coverage_data: dict[str, Any]) -> str:
+    entries, summary, metadata = (
+        coverage_data.get("entries", []),
+        coverage_data.get("summary", {}),
+        coverage_data.get("metadata", {}),
+    )
+    enforced = sorted(
+        [e for e in entries if e.get("coverage_status") == "enforced"],
+        key=lambda x: x.get("rule", {}).get("rule_id", ""),
+    )
+    declared = [e for e in entries if e.get("coverage_status") == "declared_only"]
+
+    lines = ["# Enforcement Coverage Summary", "", "## Totals", ""]
+    lines.append(f"- Total rules: {summary.get('rules_total', 0)}")
+    lines.append(f"- Enforced (executed): {summary.get('rules_enforced', 0)}")
+    lines.append(
+        f"- Implementable (not executed): {summary.get('rules_implementable', 0)}"
+    )
+    lines.append(
+        f"- Declared only (not implementable): {summary.get('rules_declared_only', 0)}"
+    )
+    lines.append(f"- Execution rate: {summary.get('execution_rate', 0)}%")
+    lines.append(
+        f"\n**Evidence key used**: `{metadata.get('evidence_key_used', 'unknown')}`\n"
+    )
+
+    lines.append("## Enforced rules\n")
+    if not enforced:
+        lines.append("_None yet._")
+    else:
+        for e in enforced:
+            lines.append(f"- `{e['rule']['rule_id']}` — {e['rule']['policy']}")
+
+    lines.append("\n## Top gaps (highest severity first)\n")
+    sev_rank = {"error": 0, "warn": 1, "warning": 1, "info": 2, "": 3}
+    gaps = sorted(
+        [
+            (
+                str(e["rule"].get("severity", "")).lower(),
+                e["rule"]["rule_id"],
+                e["rule"]["policy"],
+            )
+            for e in declared
+        ],
+        key=lambda x: (sev_rank.get(x[0], 9), x[1]),
+    )
+
+    for sev, rid, pol in gaps[:25]:
+        lines.append(f"- **{sev or 'unknown'}** `{rid}` — {pol}")
+    return "\n".join(lines) + "\n"
+
+
+# ID: eec5766e-a5a2-4bc9-9d7e-cd9af1cc4b35
+def render_hierarchical(coverage_data: dict[str, Any]) -> str:
+    entries, metadata = (
+        coverage_data.get("entries", []),
+        coverage_data.get("metadata", {}),
+    )
+    by_policy = defaultdict(list)
+    for entry in entries:
+        by_policy[str(entry["rule"]["policy"])].append(entry)
+
+    lines = [
+        "# Enforcement Coverage by Policy",
+        "",
+        f"**Generated**: {metadata.get('generated_at_utc', 'unknown')}",
+        "",
+        "## Summary",
+    ]
+    lines.append(f"- **Total policies**: {len(by_policy)}\n")
+
+    stats = []
+    for pol, rules in by_policy.items():
+        total = len(rules)
+        exec_c = sum(1 for r in rules if r["coverage_status"] == "enforced")
+        stats.append((pol, rules, total, exec_c, exec_c / total if total > 0 else 0))
+
+    for pol, rules, total, exec_c, rate in sorted(stats, key=lambda x: (x[4], x[0])):
+        icon = "✅" if total > 0 and exec_c == total else ("⚠️" if exec_c > 0 else "❌")
+        lines.append(
+            f"### {icon} {pol}\n**Executed**: {exec_c}/{total} rules ({int(100 * rate)}%)\n"
+        )
+        for re in sorted(rules, key=lambda r: r["rule"]["rule_id"]):
+            status = re["coverage_status"]
+            s_icon = (
+                "✅"
+                if status == "enforced"
+                else ("🟦" if status == "implementable" else "❌")
+            )
+            lines.append(
+                f"- {s_icon} **`{re['rule']['rule_id']}`**: {re['rule']['statement'][:100]}..."
+            )
+        lines.append("")
+
+    lines.extend(
+        [
+            "---",
+            "## Legend",
+            "- ✅ **EXECUTED**: Rule was executed in latest audit evidence",
+            "- 🟦 **IMPLEMENTABLE**: Engine exists but audit did not execute it",
+            "- ❌ **DECLARED**: Rule exists but is not implementable",
+        ]
+    )
+    return "\n".join(lines) + "\n"

cli/logic/governance/traceability_service.py

@@ -0,0 +1,78 @@
+# src/cli/logic/governance/traceability_service.py
+
+"""
+Governance Traceability Service - Phase 3 Hardening.
+Produces a detailed mapping of Constitutional Law to physical Enforcement Engines.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+from shared.path_resolver import PathResolver
+
+from .engine import generate_coverage_map
+
+
+logger = getLogger(__name__)
+
+
+# ID: 722fc9bd-1796-40e2-960e-5fadf75104cb
+class GovernanceTraceabilityService:
+    """
+    Analyzes the gap between declared law and physical enforcement.
+    """
+
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root
+        self.report_dir = PathResolver.from_repo(repo_root).reports_dir / "governance"
+        self._fh = FileHandler(str(repo_root))
+        self._fh.ensure_dir(str(self.report_dir.relative_to(repo_root)))
+
+    # ID: d5e39414-301c-4f9a-8381-52caea6bd50e
+    def generate_traceability_report(self) -> dict[str, Any]:
+        """
+        Calculates the binding state of all constitutional rules.
+        """
+        # Reuse your existing high-fidelity mapping engine
+        coverage_data = generate_coverage_map(self.repo_root)
+
+        unbound_rules = []
+        enforced_rules = []
+
+        for entry in coverage_data.get("entries", []):
+            rule = entry["rule"]
+            status = entry["coverage_status"]
+
+            rule_info = {
+                "id": rule["rule_id"],
+                "policy": rule["policy"],
+                "engine": rule.get("check_engine") or "NONE",
+                "severity": rule["severity"],
+            }
+
+            if status == "declared_only":
+                unbound_rules.append(rule_info)
+            else:
+                enforced_rules.append(rule_info)
+
+        report = {
+            "summary": {
+                "total_rules": len(coverage_data["entries"]),
+                "enforced_count": len(enforced_rules),
+                "unbound_count": len(unbound_rules),
+                "coverage_percent": coverage_data["summary"]["execution_rate"],
+            },
+            "critical_gaps": [r for r in unbound_rules if r["severity"] == "error"],
+            "unbound_rules": unbound_rules,
+        }
+
+        # Persist as a formal evidence artifact
+        output_path = self.report_dir / "traceability_matrix.json"
+        rel_path = str(output_path.relative_to(self.repo_root))
+        self._fh.write_runtime_json(rel_path, report)
+
+        return report

cli/logic/governance_logic.py

@@ -0,0 +1,33 @@
+# src/cli/logic/governance_logic.py
+
+"""
+Engine logic for constitutional governance reporting.
+Headless redirector for V2.3 Octopus Synthesis.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .governance import ensure_coverage_map, renderer
+
+
+# ID: 64b1509a-d090-4e54-9afb-545edec329db
+def get_coverage_data(repo_root: Path, file_handler: Any) -> dict[str, Any]:
+    """Authoritative entry point to get coverage data."""
+    map_path = ensure_coverage_map(repo_root, file_handler)
+    import json
+
+    with map_path.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ID: 3f4a9774-4080-4be0-9ab3-8473187b62f7
+def render_summary(coverage_data: dict[str, Any]) -> str:
+    return renderer.render_summary(coverage_data)
+
+
+# ID: 223508d6-92b3-451e-8aed-a9930471db3b
+def render_hierarchical(coverage_data: dict[str, Any]) -> str:
+    return renderer.render_hierarchical(coverage_data)

cli/logic/hub/__init__.py

@@ -0,0 +1,14 @@
+# src/cli/logic/hub/__init__.py
+"""
+Central Hub Package.
+Traffic controller for CORE tool discovery.
+"""
+
+from __future__ import annotations
+
+# We export the app for the main CLI registry
+# and the search logic for the 'search' command group
+from .app import hub_app, hub_search_cmd
+
+
+__all__ = ["hub_app", "hub_search_cmd"]