core-runtime 0.1.1__py3-none-any.whl

body/crate_processing/canary_executor.py

@@ -0,0 +1,144 @@
+# src/body/crate_processing/canary_executor.py
+
+"""
+Canary Policy Enforcement.
+
+This module enforces the canary deployment rules defined in
+.intent/phases/canary_validation.yaml or .intent/workflows/ configuration.
+
+It acts as a bridge between raw runtime signals (AuditFindings, Test Results)
+and the constitutional thresholds defined in the Mind layer.
+
+CONSTITUTIONAL COMPLIANCE:
+- Stateless validator pattern (no filesystem access)
+- Receives configuration via dependency injection
+- Pure enforcement logic (Mind/Body separation)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from shared.logger import getLogger
+from shared.models import AuditFinding, AuditSeverity
+
+
+logger = getLogger(__name__)
+
+
+@dataclass
+# ID: 180cc1c7-60c1-4c69-bce8-3fc77ce12cc9
+class CanaryResult:
+    """The outcome of a canary check."""
+
+    passed: bool
+    violations: list[str] = field(default_factory=list)
+    metrics: dict[str, float] = field(default_factory=dict)
+
+
+# ID: 227aa1c0-77d7-4171-adac-58b6a47959b1
+class CanaryExecutor:
+    """
+    Enforces Canary Policy thresholds.
+
+    Pattern: Stateless Transformer / Validator
+    Input: Configuration dict (from phase configuration)
+    Output: CanaryResult
+
+    CONSTITUTIONAL COMPLIANCE:
+    - Receives policy via dependency injection (no direct .intent/ access)
+    - Stateless execution (Body layer capability)
+    - No filesystem operations
+    """
+
+    def __init__(self, canary_config: dict[str, Any]):
+        """
+        Initialize with the 'canary' section of phase configuration.
+
+        Args:
+            canary_config: Dict containing 'enabled', 'metrics', 'abort_conditions'.
+        """
+        self.config = canary_config
+        self.enabled = self.config.get("enabled", True)
+
+    # ID: 5281cdc8-9cd5-4f32-ba3d-8bd3b2eed8a0
+    def derive_metrics_from_audit(
+        self, findings: list[AuditFinding]
+    ) -> dict[str, float]:
+        """
+        Convert a list of AuditFindings into quantitative metrics for policy checking.
+
+        Args:
+            findings: List of audit findings to analyze
+
+        Returns:
+            Dictionary of metric names to values
+        """
+        error_count = sum(1 for f in findings if f.severity == AuditSeverity.BLOCK)
+        warning_count = sum(1 for f in findings if f.severity == AuditSeverity.HIGH)
+        return {
+            "audit.errors": float(error_count),
+            "audit.warnings": float(warning_count),
+            "audit.findings": float(len(findings)),
+        }
+
+    # ID: 2a89880e-9157-4a36-8b47-e1e13a54becd
+    def enforce(self, runtime_metrics: dict[str, float]) -> CanaryResult:
+        """
+        Compare runtime metrics against policy thresholds.
+
+        Args:
+            runtime_metrics: Dictionary of metric_name -> value
+                             (e.g., {"audit.errors": 0, "tests.failed": 0})
+
+        Returns:
+            CanaryResult: Pass/Fail status with details.
+        """
+        if not self.enabled:
+            logger.info("Canary checks disabled in policy.")
+            return CanaryResult(True, [], runtime_metrics)
+
+        violations = []
+        policy_metrics = self.config.get("metrics", [])
+
+        for rule in policy_metrics:
+            metric_name = rule["name"]
+            threshold = float(rule["threshold"])
+            direction = rule.get("direction", "less")
+            actual_value = runtime_metrics.get(metric_name)
+
+            if actual_value is None:
+                logger.debug(
+                    "Canary metric '%s' not present in runtime report.", metric_name
+                )
+                continue
+
+            if direction == "less":
+                if actual_value > threshold:
+                    violations.append(
+                        f"Metric '{metric_name}' failed: {actual_value} > {threshold}"
+                    )
+            elif direction == "greater":
+                if actual_value < threshold:
+                    violations.append(
+                        f"Metric '{metric_name}' failed: {actual_value} < {threshold}"
+                    )
+
+        abort_conditions = self.config.get("abort_conditions", [])
+        for condition in abort_conditions:
+            if condition == "audit:level=error":
+                if runtime_metrics.get("audit.errors", 0) > 0:
+                    violations.append("Abort condition triggered: audit:level=error")
+            elif condition == "tests:failed>0":
+                if runtime_metrics.get("tests.failed", 0) > 0:
+                    violations.append("Abort condition triggered: tests:failed>0")
+
+        passed = len(violations) == 0
+
+        if not passed:
+            logger.warning("Canary checks failed: %s", violations)
+        else:
+            logger.info("Canary checks passed.")
+
+        return CanaryResult(passed, violations, runtime_metrics)

body/evaluators/__init__.py

@@ -0,0 +1,27 @@
+# src/body/evaluators/__init__.py
+
+"""
+Body Evaluators - AUDIT Phase Components.
+Organized for High-Fidelity precision.
+"""
+
+from __future__ import annotations
+
+from .atomic_actions_evaluator import AtomicActionsEvaluator
+from .base_evaluator import BaseEvaluator
+from .clarity_evaluator import ClarityEvaluator
+from .constitutional_evaluator import ConstitutionalEvaluator
+from .failure_evaluator import FailureEvaluator
+from .performance_evaluator import PerformanceEvaluator
+from .security_evaluator import SecurityEvaluator
+
+
+__all__ = [
+    "AtomicActionsEvaluator",
+    "BaseEvaluator",
+    "ClarityEvaluator",
+    "ConstitutionalEvaluator",
+    "FailureEvaluator",
+    "PerformanceEvaluator",
+    "SecurityEvaluator",
+]

body/evaluators/atomic_actions_evaluator.py

@@ -0,0 +1,162 @@
+# src/body/evaluators/atomic_actions_evaluator.py
+"""Atomic Actions Evaluator - AUDIT Phase Component.
+
+Validates code compliance with the atomic actions pattern.
+
+Constitutional Alignment:
+- Phase: AUDIT (Quality assessment and pattern detection)
+- Authority: POLICY (Enforces constitutional atomic actions pattern)
+- Purpose: Validate atomic action compliance across codebase
+- Self-contained: No external checker dependencies
+
+PURIFIED (V2.3.0)
+- Removed Will-layer 'DecisionTracer' to satisfy architecture.layers.no_body_to_will.
+- Preserves 100% of original AST analysis and validation logic.
+- Rationale is now returned in metadata for Will-layer consumption.
+
+This module is the audit orchestration shell. The contract definition
+(AtomicActionViolation dataclass, AST predicates, validator functions)
+lives in atomic_actions_rules.py. The CLI-facing formatter lives in
+atomic_actions_format.py.
+"""
+
+from __future__ import annotations
+
+import ast
+import time
+from pathlib import Path
+from typing import Any
+
+from shared.component_primitive import ComponentResult
+from shared.logger import getLogger
+
+from .atomic_actions_rules import (
+    AtomicActionViolation,
+    is_atomic_action_candidate,
+    validate_atomic_action,
+)
+from .base_evaluator import BaseEvaluator
+
+
+logger = getLogger(__name__)
+
+
+# ID: 54c63404-6a42-4ec3-9b88-8a039d52d7ec
+class AtomicActionsEvaluator(BaseEvaluator):
+    """Evaluate codebase for atomic action pattern compliance.
+
+    This is a fully self-contained V2 component with no external dependencies.
+    All AST analysis and validation logic is internal to this component
+    (split across atomic_actions_rules.py for the contract definition).
+    """
+
+    # ID: a9bd8873-8696-4f14-a055-a32ba0ecd956
+    async def execute(self, repo_root: Path, **kwargs: Any) -> ComponentResult:
+        """Execute the atomic actions compliance audit."""
+        start_time = time.time()
+        src_dir = repo_root / "src"
+
+        violations: list[AtomicActionViolation] = []
+        total_actions = 0
+
+        if not src_dir.exists():
+            logger.warning("Source directory not found: %s", src_dir)
+            return await self._create_result(
+                ok=True,
+                data={
+                    "total_actions": 0,
+                    "compliant_actions": 0,
+                    "compliance_rate": 100.0,
+                    "violations": [],
+                },
+                confidence=1.0,
+                duration=0.0,
+                rationale="Source directory missing; no actions audited.",
+            )
+
+        # 1) Sensation: scan all Python files in src/
+        for py_file in src_dir.rglob("*.py"):
+            # Skip private modules (except __init__.py) and test files
+            if py_file.name.startswith("_") and py_file.name != "__init__.py":
+                continue
+            if "test" in str(py_file):
+                continue
+
+            file_violations, file_actions = self._check_file(py_file)
+            violations.extend(file_violations)
+            total_actions += file_actions
+
+        # 2) Analysis: calculate metrics
+        compliant_actions = total_actions - len(
+            [v for v in violations if v.severity == "error"]
+        )
+        compliance_rate = (
+            (compliant_actions / total_actions * 100.0) if total_actions > 0 else 100.0
+        )
+        has_errors = any(v.severity == "error" for v in violations)
+
+        # 3) Decision tracing: preserved logic, moved to metadata
+        rationale = (
+            f"Audited {total_actions} actions. Compliance: {compliance_rate:.1f}%"
+        )
+
+        violation_dicts = [
+            {
+                "file": str(
+                    v.file_path.relative_to(repo_root)
+                    if v.file_path.is_absolute()
+                    else v.file_path
+                ),
+                "function": v.function_name,
+                "rule": v.rule_id,
+                "message": v.message,
+                "severity": v.severity,
+                "line": v.line_number,
+                "suggested_fix": v.suggested_fix,
+            }
+            for v in violations
+        ]
+
+        return await self._create_result(
+            ok=not has_errors,
+            data={
+                "total_actions": total_actions,
+                "compliant_actions": compliant_actions,
+                "compliance_rate": compliance_rate,
+                "violations": violation_dicts,
+            },
+            confidence=1.0,
+            duration=time.time() - start_time,
+            rationale=rationale,
+        )
+
+    def _check_file(self, file_path: Path) -> tuple[list[AtomicActionViolation], int]:
+        """Check a single file for atomic action pattern compliance."""
+        violations: list[AtomicActionViolation] = []
+        action_count = 0
+
+        try:
+            source = file_path.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+
+            for node in ast.walk(tree):
+                if isinstance(
+                    node, ast.AsyncFunctionDef
+                ) and is_atomic_action_candidate(node):
+                    action_count += 1
+                    violations.extend(validate_atomic_action(file_path, node, source))
+
+        except SyntaxError as e:
+            violations.append(
+                AtomicActionViolation(
+                    file_path=file_path,
+                    function_name="<parse_error>",
+                    rule_id="syntax_error",
+                    message=f"Syntax error: {e}",
+                    severity="error",
+                )
+            )
+        except Exception as e:
+            logger.error("Error checking %s: %s", file_path, e, exc_info=True)
+
+        return (violations, action_count)

body/evaluators/atomic_actions_format.py

@@ -0,0 +1,45 @@
+# src/body/evaluators/atomic_actions_format.py
+"""Human-readable formatter for AtomicActionViolation lists.
+
+Pure transformation: consumes a list of violations and returns a string
+for CLI/log display. No scan logic, no rule logic, no AST awareness.
+
+LAYER: body/evaluators — rendering helper. No side effects beyond
+constructing a string.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from body.evaluators.atomic_actions_rules import AtomicActionViolation
+
+
+# ID: 2f8a6d5c-3e3f-4f3a-b881-e454ca73d5a4
+def format_atomic_action_violations(
+    violations: list[AtomicActionViolation],
+    verbose: bool = False,
+) -> str:
+    """Format atomic action violations for display."""
+    if not violations:
+        return "✅ All atomic actions follow constitutional pattern!"
+
+    output: list[str] = ["\n❌ Found Atomic Action Violations:\n"]
+
+    by_file: dict[Path, list[AtomicActionViolation]] = {}
+    for v in violations:
+        by_file.setdefault(v.file_path, []).append(v)
+
+    for file_path, file_violations in sorted(by_file.items(), key=lambda x: str(x[0])):
+        output.append(f"\n📄 {file_path}")
+        for v in file_violations:
+            severity_marker = "🔴" if v.severity == "error" else "🟡"
+            output.append(
+                f"  {severity_marker} {v.function_name} (line {v.line_number or '?'})"
+            )
+            output.append(f"     Rule: {v.rule_id}")
+            output.append(f"     {v.message}")
+            if verbose and v.suggested_fix:
+                output.append(f"     💡 Fix: {v.suggested_fix}")
+
+    return "\n".join(output)

body/evaluators/atomic_actions_rules.py

@@ -0,0 +1,278 @@
+# src/body/evaluators/atomic_actions_rules.py
+"""Atomic action contract — data shape, AST predicates, and validation rules.
+
+This module answers: "what does it mean to be a well-formed atomic action?"
+
+It owns:
+- AtomicActionViolation — the violation record produced by rule functions
+  and consumed by both the orchestrator (AtomicActionsEvaluator) and the
+  formatter (atomic_actions_format.format_atomic_action_violations).
+- AST predicates — pure inspection functions that identify whether an
+  AsyncFunctionDef looks like an atomic action.
+- Rule functions — produce violations when the @atomic_action decorator
+  or the returned ActionResult is malformed.
+
+LAYER: body/evaluators — read-only AST inspection only. No filesystem
+writes, no DB access, no Will-layer imports. Functions are module-level
+and take all inputs explicitly; no instance state.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+# ID: 6f296fc1-4fc3-4da3-b38d-b712ab452667
+class AtomicActionViolation:
+    """Violation of atomic action pattern contract."""
+
+    file_path: Path
+    function_name: str
+    rule_id: str
+    message: str
+    line_number: int | None = None
+    severity: str = "error"
+    suggested_fix: str | None = None
+
+
+# ID: c61f81e9-5e68-47f7-af7f-8899ab5c6045
+def is_atomic_action_candidate(node: ast.AsyncFunctionDef) -> bool:
+    """Return True if the function looks like it intends to be an atomic action.
+
+    A candidate is any async function whose name ends with '_internal',
+    or that carries an @atomic_action decorator (bare or called), or
+    whose return type annotation is ActionResult.
+    """
+    if node.name.endswith("_internal"):
+        return True
+    if _has_atomic_action_decorator(node):
+        return True
+    if _returns_action_result(node):
+        return True
+    return False
+
+
+def _has_atomic_action_decorator(node: ast.AsyncFunctionDef) -> bool:
+    for decorator in node.decorator_list:
+        if isinstance(decorator, ast.Name) and decorator.id == "atomic_action":
+            return True
+        if isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Name):
+            if decorator.func.id == "atomic_action":
+                return True
+    return False
+
+
+def _returns_action_result(node: ast.AsyncFunctionDef) -> bool:
+    if not node.returns:
+        return False
+    if isinstance(node.returns, ast.Name):
+        return node.returns.id == "ActionResult"
+    if isinstance(node.returns, ast.Subscript) and isinstance(
+        node.returns.value, ast.Name
+    ):
+        return node.returns.value.id == "ActionResult"
+    return False
+
+
+# ID: 0266bc9f-720b-402d-baac-637bc425543a
+def validate_atomic_action(
+    file_path: Path,
+    node: ast.AsyncFunctionDef,
+    source: str,
+) -> list[AtomicActionViolation]:
+    """Run all contract checks on a single atomic-action candidate.
+
+    Returns the combined list of violations across three sub-checks:
+      1. @atomic_action decorator presence + required metadata fields.
+      2. ActionResult return-type annotation presence.
+      3. Each `return ActionResult(...)` statement carries required fields
+         and uses a dict literal for `data`.
+    """
+    violations: list[AtomicActionViolation] = []
+
+    if not _has_atomic_action_decorator(node):
+        violations.append(
+            AtomicActionViolation(
+                file_path=file_path,
+                function_name=node.name,
+                rule_id="action_must_have_decorator",
+                message=f"Atomic action '{node.name}' missing @atomic_action decorator",
+                line_number=node.lineno,
+                severity="error",
+                suggested_fix=(
+                    "Add @atomic_action decorator with action_id, intent, impact, and policies"
+                ),
+            )
+        )
+
+    if not _returns_action_result(node):
+        violations.append(
+            AtomicActionViolation(
+                file_path=file_path,
+                function_name=node.name,
+                rule_id="action_must_return_result",
+                message=f"Atomic action '{node.name}' must return ActionResult",
+                line_number=node.lineno,
+                severity="error",
+                suggested_fix="Add '-> ActionResult' return type annotation",
+            )
+        )
+
+    if _has_atomic_action_decorator(node):
+        violations.extend(_validate_decorator_metadata(file_path, node, source))
+
+    violations.extend(_validate_return_statements(file_path, node))
+    return violations
+
+
+def _validate_decorator_metadata(
+    file_path: Path,
+    node: ast.AsyncFunctionDef,
+    source: str,
+) -> list[AtomicActionViolation]:
+    violations: list[AtomicActionViolation] = []
+    decorator: ast.Call | None = None
+
+    for dec in node.decorator_list:
+        if (
+            isinstance(dec, ast.Call)
+            and isinstance(dec.func, ast.Name)
+            and dec.func.id == "atomic_action"
+        ):
+            decorator = dec
+            break
+
+    if not decorator:
+        return violations
+
+    decorator_args: dict[str, Any] = {}
+
+    for keyword in decorator.keywords:
+        if isinstance(keyword.value, ast.Constant):
+            decorator_args[keyword.arg] = keyword.value.value
+        elif isinstance(keyword.value, ast.Attribute):
+            # Example: ActionImpact.LOW
+            base = keyword.value.value
+            if isinstance(base, ast.Name):
+                decorator_args[keyword.arg] = f"{base.id}.{keyword.value.attr}"
+        elif isinstance(keyword.value, ast.List):
+            decorator_args[keyword.arg] = [
+                elt.value for elt in keyword.value.elts if isinstance(elt, ast.Constant)
+            ]
+
+    required_fields = {
+        "action_id": "Unique identifier for this action",
+        "intent": "Clear statement of purpose",
+        "impact": "ActionImpact classification",
+        "policies": "List of constitutional policies validated",
+    }
+
+    for field, description in required_fields.items():
+        if field not in decorator_args:
+            violations.append(
+                AtomicActionViolation(
+                    file_path=file_path,
+                    function_name=node.name,
+                    rule_id="decorator_missing_required_field",
+                    message=(
+                        f"@atomic_action missing required field '{field}': {description}"
+                    ),
+                    line_number=node.lineno,
+                    severity="error",
+                    suggested_fix=f"Add {field}=... to @atomic_action decorator",
+                )
+            )
+
+    if "action_id" in decorator_args:
+        action_id = decorator_args["action_id"]
+        if not isinstance(action_id, str) or "." not in action_id:
+            violations.append(
+                AtomicActionViolation(
+                    file_path=file_path,
+                    function_name=node.name,
+                    rule_id="invalid_action_id_format",
+                    message=f"action_id '{action_id}' must use dot notation",
+                    line_number=node.lineno,
+                    severity="warning",
+                    suggested_fix="Use category.name format for action_id",
+                )
+            )
+
+    return violations
+
+
+def _validate_return_statements(
+    file_path: Path,
+    node: ast.AsyncFunctionDef,
+) -> list[AtomicActionViolation]:
+    violations: list[AtomicActionViolation] = []
+
+    for child in ast.walk(node):
+        if (
+            isinstance(child, ast.Return)
+            and child.value
+            and isinstance(child.value, ast.Call)
+        ):
+            call = child.value
+            if isinstance(call.func, ast.Name) and call.func.id == "ActionResult":
+                violations.extend(
+                    _validate_action_result_call(
+                        file_path,
+                        node.name,
+                        child,
+                        child.lineno,
+                    )
+                )
+
+    return violations
+
+
+def _validate_action_result_call(
+    file_path: Path,
+    function_name: str,
+    return_node: ast.Return,
+    line_number: int,
+) -> list[AtomicActionViolation]:
+    violations: list[AtomicActionViolation] = []
+
+    call = return_node.value
+    if not isinstance(call, ast.Call):
+        return violations
+
+    result_args: dict[str, ast.AST] = {k.arg: k.value for k in call.keywords if k.arg}
+
+    required_fields = ["action_id", "ok", "data"]
+    for field in required_fields:
+        if field not in result_args:
+            violations.append(
+                AtomicActionViolation(
+                    file_path=file_path,
+                    function_name=function_name,
+                    rule_id="result_missing_required_field",
+                    message=f"ActionResult missing required field '{field}'",
+                    line_number=line_number,
+                    severity="error",
+                    suggested_fix=f"Add {field}=... to ActionResult constructor",
+                )
+            )
+
+    if "data" in result_args:
+        data_value = result_args["data"]
+        if not isinstance(data_value, ast.Dict):
+            violations.append(
+                AtomicActionViolation(
+                    file_path=file_path,
+                    function_name=function_name,
+                    rule_id="result_must_be_structured",
+                    message="ActionResult.data must be a dictionary literal",
+                    line_number=line_number,
+                    severity="warning",
+                    suggested_fix="Use data={...} with explicit key-value pairs",
+                )
+            )
+
+    return violations