core-runtime 0.1.1__py3-none-any.whl

mind/logic/engines/workflow_gate/checks/ruff_format.py

@@ -0,0 +1,99 @@
+# src/mind/logic/engines/workflow_gate/checks/ruff_format.py
+
+"""
+Ruff format workflow check.
+
+Verifies that source files conform to ruff's formatting standard.
+Enforces: code.style.ruff_format
+
+Runs `ruff format --check` asynchronously and reports files that
+would be reformatted as violations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from typing import Any
+
+from mind.logic.engines.workflow_gate.base_check import WorkflowCheck
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().workflow_gate
+
+
+# ID: 58a4df52-9edf-475e-b196-781cabfcfbe5
+class RuffFormatCheck(WorkflowCheck):
+    """
+    Verifies source files conform to ruff formatting.
+
+    Runs `ruff format --check` asynchronously and reports files that
+    would be reformatted. Files matching the exclude pattern (e.g.
+    scripts/ or dev-scripts/) are skipped.
+    """
+
+    check_type = "ruff_format_check"
+
+    # ID: a3ceba34-e217-48ec-9a03-6d488ebaba77
+    async def verify(self, file_path: Path | None, params: dict[str, Any]) -> list[str]:
+        """
+        Run ruff format --check asynchronously.
+
+        Args:
+            file_path: Optional specific file to check (None = checks src/)
+            params: Check parameters; supports 'exclude_pattern' regex
+
+        Returns:
+            List of violation messages (empty = all files formatted correctly)
+        """
+        target = str(file_path) if file_path else "src"
+        exclude_pattern = params.get("exclude_pattern", r"^(scripts|dev-scripts)/")
+        violations: list[str] = []
+
+        if file_path and re.search(exclude_pattern, str(file_path)):
+            return violations
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                "ruff",
+                "format",
+                "--check",
+                target,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=_CFG.ruff_format_timeout_sec
+            )
+
+            if process.returncode != 0:
+                output = stdout.decode().strip()
+                if output:
+                    for line in output.splitlines():
+                        line = line.strip()
+                        if not line:
+                            continue
+                        # ruff format --check prefixes with "Would reformat: "
+                        if line.startswith("Would reformat: "):
+                            cleaned = line.removeprefix("Would reformat: ").strip()
+                            if not re.search(exclude_pattern, cleaned):
+                                violations.append(cleaned)
+                else:
+                    err = stderr.decode().strip()
+                    violations.append(f"Ruff format check failed: {err}")
+
+        except TimeoutError:
+            violations.append(
+                f"Ruff format check timed out (>{_CFG.ruff_format_timeout_sec:g}s)"
+            )
+        except FileNotFoundError:
+            violations.append("ruff not found in PATH — cannot check formatting")
+        except Exception as e:
+            violations.append(f"Ruff format check error: {e}")
+
+        return violations

mind/logic/engines/workflow_gate/checks/tests.py

@@ -0,0 +1,81 @@
+# src/mind/logic/engines/workflow_gate/checks/tests.py
+
+"""
+Test verification workflow check.
+
+Verifies that the most recent test suite execution passed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import text
+
+from mind.logic.engines.workflow_gate.base_check import WorkflowCheck
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 33057f65-4f93-452d-a3cd-2a073147dae8
+class TestVerificationCheck(WorkflowCheck):
+    """
+    Checks if the most recent test workflow passed by querying the Action Ledger.
+    """
+
+    check_type = "test_verification"
+
+    # ID: b17085a1-d0f0-4a10-9e2a-801372462e81
+    async def verify(self, file_path: Path | None, params: dict[str, Any]) -> list[str]:
+        """
+        Verify tests passed using the database session provided in params.
+
+        Args:
+            file_path: Unused (context-level check)
+            params: Must contain '_context' with an active 'db_session'
+        """
+        context = params.get("_context")
+        session = getattr(context, "db_session", None)
+
+        if not session:
+            logger.warning(
+                "TestVerificationCheck: Database session unavailable in context."
+            )
+            # We report a sensory gap if the execution environment didn't provide a session.
+            return ["System Sensation Error: Action Ledger (DB) is unreachable."]
+
+        try:
+            # 1. Query the Mind's memory (Postgres SSOT) for the last test result
+            result = await session.execute(
+                text(
+                    """
+                    SELECT ok, error_message
+                    FROM core.action_results
+                    WHERE action_type = 'test_execution'
+                    ORDER BY created_at DESC
+                    LIMIT 1
+                    """
+                )
+            )
+            row = result.fetchone()
+
+            # 2. Logic Evaluation
+            if not row:
+                return [
+                    "No test execution history found. The test suite MUST be "
+                    "executed before this workflow can proceed."
+                ]
+
+            if not row[0]:  # row['ok'] == False
+                error = row[1] or "Unknown test failure"
+                return [f"Required test suite failed: {error}"]
+
+            # SUCCESS: No violations found
+            return []
+
+        except Exception as e:
+            logger.error("Failed to query test results: %s", e)
+            return [f"Database Query Error: {e}"]

mind/logic/engines/workflow_gate/engine.py

@@ -0,0 +1,207 @@
+# src/mind/logic/engines/workflow_gate/engine.py
+
+"""
+Workflow Gate Engine - Context-Aware Process Auditor.
+
+CONSTITUTIONAL ALIGNMENT:
+- Aligned with 'async.no_manual_loop_run'.
+- Promoted to natively async to eliminate thread-based loop hijacking.
+- Provides non-blocking verification for system-wide processes (Tests, Coverage).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from mind.logic.engines.base import BaseEngine, EngineResult
+from mind.logic.engines.workflow_gate.base_check import WorkflowCheck
+from mind.logic.engines.workflow_gate.checks import (
+    AlignmentVerificationCheck,
+    AuditHistoryCheck,
+    CanaryDeploymentCheck,
+    CoverageMinimumCheck,
+    DeadCodeCheck,
+    ImportResolutionCheck,
+    LinterComplianceCheck,
+    RuffFormatCheck,
+    TestVerificationCheck,
+)
+from mind.logic.engines.workflow_gate.checks.quality import QualityGateCheck
+from shared.logger import getLogger
+from shared.models import AuditFinding, AuditSeverity
+from shared.path_resolver import PathResolver
+
+
+if TYPE_CHECKING:
+    from mind.governance.audit_context import AuditorContext
+
+logger = getLogger(__name__)
+
+
+# ID: 170810a6-c446-41de-acf4-29defa345522
+class WorkflowGateEngine(BaseEngine):
+    """
+    Process-Aware Governance Auditor.
+
+    Orchestrates specialized workflow checks (bits) to verify that
+    operational requirements (like test passing or coverage) are met.
+    """
+
+    engine_id = "workflow_gate"
+
+    @classmethod
+    # ID: 2b8e4f3d-1a9c-4b65-9d7e-3f8a1c5e2b04
+    def is_context_level_for(cls, check_type: str | None) -> bool:
+        """
+        ADR-076 D1/D2: every workflow_gate check_type is context-level.
+
+        All twelve checks (tests, coverage, canary, alignment, dead code,
+        audit history, linter, imports, ruff format, mypy, security,
+        pytest collection) walk system state rather than a single file_path.
+        """
+        return True
+
+    def __init__(self, path_resolver: PathResolver) -> None:
+        """Initialize the engine and register its specialized check logic."""
+        check_instances: list[WorkflowCheck] = [
+            TestVerificationCheck(),
+            CoverageMinimumCheck(path_resolver),
+            CanaryDeploymentCheck(),
+            AlignmentVerificationCheck(path_resolver),
+            DeadCodeCheck(path_resolver),
+            AuditHistoryCheck(),
+            LinterComplianceCheck(),
+            ImportResolutionCheck(),
+            RuffFormatCheck(),
+            QualityGateCheck(
+                path_resolver,
+                "mypy_check",
+                ["mypy", "src/", "--ignore-missing-imports"],
+            ),
+            QualityGateCheck(path_resolver, "security_check", ["pip-audit"]),
+            QualityGateCheck(
+                path_resolver,
+                "pytest_check",
+                ["pytest", "tests/", "-q", "--co"],
+            ),  # Collection only for speed
+        ]
+
+        self._checks: dict[str, WorkflowCheck] = {
+            check.check_type: check for check in check_instances
+        }
+
+        logger.debug(
+            "WorkflowGateEngine initialized with %d check types: %s",
+            len(self._checks),
+            ", ".join(sorted(self._checks.keys())),
+        )
+
+    # ID: 9b12e3f4-c5d6-7e8f-9a0b-1c2d3e4f5a6b
+    async def verify_context(
+        self, context: AuditorContext, params: dict[str, Any]
+    ) -> list[AuditFinding]:
+        """
+        Executes a context-level check against system state.
+        """
+        check_type = params.get("check_type")
+        if not check_type:
+            return [
+                AuditFinding(
+                    check_id="workflow_gate.error",
+                    severity=AuditSeverity.BLOCK,
+                    message="Missing 'check_type' parameter in constitutional rule.",
+                    file_path="none",
+                )
+            ]
+
+        check_logic = self._checks.get(check_type)
+        if not check_logic:
+            return [
+                AuditFinding(
+                    check_id="workflow_gate.error",
+                    severity=AuditSeverity.BLOCK,
+                    message=f"Logic Error: Engine does not support check_type '{check_type}'",
+                    file_path="none",
+                )
+            ]
+
+        try:
+            # Native await - no loop hijacking required
+            violations = await check_logic.verify(None, params)
+
+            findings = []
+            for v in violations:
+                if v.endswith(".py"):
+                    findings.append(
+                        AuditFinding(
+                            check_id=f"workflow.{check_type}",
+                            severity=AuditSeverity.BLOCK,
+                            message=f"File would be reformatted: {v}",
+                            file_path=v,
+                        )
+                    )
+                else:
+                    findings.append(
+                        AuditFinding(
+                            check_id=f"workflow.{check_type}",
+                            severity=AuditSeverity.BLOCK,
+                            message=v,
+                            file_path="System",
+                        )
+                    )
+            return findings
+        except Exception as e:
+            logger.error("Workflow logic '%s' failed: %s", check_type, e, exc_info=True)
+            return [
+                AuditFinding(
+                    check_id=f"workflow.{check_type}.error",
+                    severity=AuditSeverity.BLOCK,
+                    message=f"Internal Engine Error during {check_type} verification: {e}",
+                    file_path="none",
+                )
+            ]
+
+    # ID: 449a88ef-71ff-4f63-b692-4cffdc6483ce
+    async def verify(self, file_path: Path, params: dict[str, Any]) -> EngineResult:
+        """
+        Natively async verification.
+
+        REFACTORED: Removed legacy thread-spawning and run_until_complete logic.
+        This now properly participates in the system's async runtime.
+        """
+        return await self._verify_async(file_path, params)
+
+    async def _verify_async(
+        self, file_path: Path | None, params: dict[str, Any]
+    ) -> EngineResult:
+        """Internal async logic shared by verify and verify_context."""
+        check_type = params.get("check_type")
+        if not check_type:
+            return EngineResult(
+                False, "Missing check_type", ["No check_type provided"], self.engine_id
+            )
+
+        check = self._checks.get(check_type)
+        if not check:
+            return EngineResult(
+                False,
+                "Invalid check_type",
+                [f"Unsupported: {check_type}"],
+                self.engine_id,
+            )
+
+        try:
+            violations = await check.verify(file_path, params)
+            return EngineResult(
+                ok=(not violations),
+                message=(
+                    "Workflow compliant"
+                    if not violations
+                    else "Workflow violations found"
+                ),
+                violations=violations,
+                engine_id=self.engine_id,
+            )
+        except Exception as e:
+            return EngineResult(False, f"Engine Error: {e}", [str(e)], self.engine_id)

shared/__init__.py

@@ -0,0 +1,32 @@
+# src/shared/__init__.py
+
+"""
+`shared` — Cross-cutting, foundational building blocks for CORE.
+
+This namespace provides *stable, low-level primitives* used across the
+entire system. Nothing in here depends on features/, agents/, or domain-
+specific logic.
+
+Sub-packages include:
+
+- shared.universal
+    Canonical micro-helpers for reuse-first development.
+
+- shared.utils
+    Implementation modules providing reusable tools, utilities, and
+    low-level helpers. `shared.universal` re-exports a curated,
+    stable surface from here.
+
+- shared.models
+    Simple, shared model definitions used by multiple subsystems.
+
+Dependency rule:
+    shared/ MAY depend only on the Python standard library and other
+    modules inside shared/. Nothing outside shared/ may depend on
+    feature-specific logic.
+
+This guarantees a stable, well-defined reuse surface for CoderAgent and
+ContextPackage reuse analysis.
+"""
+
+from __future__ import annotations

shared/action_logger.py

@@ -0,0 +1,61 @@
+# src/shared/action_logger.py
+
+"""
+Provides a dedicated service for writing structured, auditable events to the system's action log.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from shared.config import settings
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 72f18eea-652f-4098-8ddd-211a346c95fd
+class ActionLogger:
+    """Handles writing structured JSON events to the CORE_ACTION_LOG_PATH."""
+
+    def __init__(self):
+        """Initializes the logger, ensuring the log file's parent directory exists."""
+        try:
+            log_path_str = settings.CORE_ACTION_LOG_PATH
+            if not log_path_str:
+                raise ValueError("CORE_ACTION_LOG_PATH is not set in the environment.")
+            self.log_path = settings.REPO_PATH / log_path_str
+            self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        except (ValueError, AttributeError) as e:
+            logger.error(
+                "ActionLogger failed to initialize: %s. Logging will be disabled.", e
+            )
+            self.log_path = None
+
+    # ID: 45f05bd1-dc47-4dfc-9117-709dff10741e
+    def log_event(self, event_type: str, details: dict[str, Any]):
+        """
+        Writes a single, timestamped event to the action log file.
+
+        Args:
+            event_type: A dot-notation string identifying the event (e.g., 'crate.processing.started').
+            details: A dictionary of context-specific information about the event.
+        """
+        if not self.log_path:
+            return
+        log_entry = {
+            "timestamp_utc": datetime.now(UTC).isoformat(),
+            "event_type": event_type,
+            "details": details,
+        }
+        try:
+            with self.log_path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(log_entry) + "\n")
+        except Exception as e:
+            logger.error("Failed to write to action log at {self.log_path}: %s", e)
+
+
+action_logger = ActionLogger()

shared/action_types.py

@@ -0,0 +1,199 @@
+# src/shared/action_types.py
+"""
+Universal action result types for CORE's atomic action framework.
+
+This module defines the foundational types that unify all operations in CORE,
+replacing the separate CommandResult and AuditCheckResult with a single,
+universal contract that enables constitutional governance across all domains.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+# Note: load_operational_config() is imported lazily inside __post_init__ to
+# break a circular dependency: operational_config → shared.logger →
+# shared.action_types → operational_config. Cost is negligible because the
+# loader path memoises through IntentRepository.
+
+
+# ID: 29ed0df5-f34f-4af8-81f1-49207bd75e6e
+class ActionImpact(Enum):
+    """
+    Classification of an action's impact on system state.
+
+    This helps the constitutional framework understand what kind of changes
+    an action will make, enabling appropriate validation and governance.
+    """
+
+    READ_ONLY = "read-only"
+    """Action only reads data, makes no changes"""
+
+    WRITE_METADATA = "write-metadata"
+    """Action writes metadata (IDs, tags, comments) but not functional code"""
+
+    WRITE_CODE = "write-code"
+    """Action writes or modifies functional code"""
+
+    WRITE_DATA = "write-data"
+    """Action writes to databases, files, or external systems"""
+
+
+@dataclass
+# ID: 9c64e67a-8078-4c5b-b8c3-d9d0735fd883
+class ActionResult:
+    """
+    Universal result contract for all atomic actions in CORE.
+
+    This replaces both CommandResult (for commands) and AuditCheckResult (for checks)
+    with a single abstraction that enables:
+    - Universal governance (same validation for all actions)
+    - Composable workflows (actions return compatible results)
+    - Constitutional compliance (structured data for policy enforcement)
+    - Machine-readable outcomes (enables autonomous decision-making)
+
+    Every operation in CORE—whether checking code, generating documentation,
+    or building systems—returns an ActionResult.
+    """
+
+    action_id: str
+    """
+    Unique identifier for this action (e.g., 'fix.ids', 'check.imports').
+
+    Convention: Use dot notation with category prefix:
+    - fix.*: Code fixing actions
+    - check.*: Validation actions
+    - generate.*: Code generation actions
+    - sync.*: Data synchronization actions
+    """
+
+    ok: bool
+    """
+    Binary success indicator.
+
+    True: Action completed successfully
+    False: Action failed or found violations
+
+    For checks: False means violations found
+    For fixes: False means couldn't complete the fix
+    For generation: False means couldn't generate valid output
+    """
+
+    data: dict[str, Any]
+    """
+    Action-specific structured results.
+
+    This is the flexible payload where each action type can store its
+    specific outcomes. Common patterns:
+
+    For checks:
+        {"violations_count": int, "violations": list[dict], "files_scanned": int}
+
+    For fixes:
+        {"items_fixed": int, "items_failed": int, "dry_run": bool}
+
+    For generation:
+        {"files_created": list[str], "lines_of_code": int}
+
+    Constitutional validation can inspect this data to ensure actions
+    are operating within policy bounds.
+    """
+
+    duration_sec: float = 0.0
+    """
+    Execution time in seconds.
+
+    Used for:
+    - Performance monitoring
+    - Timeout enforcement
+    - Workflow optimization
+    """
+
+    impact: ActionImpact | None = None
+    """
+    What kind of changes this action made.
+
+    Optional but recommended for constitutional governance.
+    Helps the system understand the scope of changes.
+    """
+
+    logs: list[str] = field(default_factory=list)
+    """
+    Debug trace messages (internal use only, not shown to users).
+
+    For troubleshooting and detailed audit trails.
+    Logged at DEBUG level by default.
+    """
+
+    warnings: list[str] = field(default_factory=list)
+    """
+    Non-fatal issues encountered during execution.
+
+    Action succeeded (ok=True) but these issues should be noted.
+    Example: "Using fallback method due to missing dependency"
+    """
+
+    suggestions: list[str] = field(default_factory=list)
+    """
+    Recommended follow-up actions.
+
+    Example: If a check finds violations, suggest the fix command.
+    Enables autonomous agents to chain actions intelligently.
+    """
+
+    def __post_init__(self):
+        """Validate ActionResult structure and size constraints."""
+        if not isinstance(self.action_id, str) or not self.action_id:
+            raise ValueError("action_id must be non-empty string")
+        if not isinstance(self.data, dict):
+            raise ValueError("data must be a dict")
+        if not isinstance(self.ok, bool):
+            raise ValueError("ok must be a boolean")
+
+        # Enforce data size limit to prevent memory bloating in workflows
+        try:
+            # We use JSON serialization as a proxy for data size
+            serialized = json.dumps(self.data, default=str)
+            # Lazy import — see module-level note on the circular dependency.
+            from shared.infrastructure.intent.operational_config import (
+                load_operational_config,
+            )
+
+            max_size = load_operational_config().action.max_data_size_bytes
+            if len(serialized) > max_size:
+                raise ValueError(
+                    f"ActionResult.data exceeds size limit of {max_size} bytes "
+                    f"(got {len(serialized)} bytes). Action: {self.action_id}"
+                )
+        except (TypeError, OverflowError):
+            # If data isn't serializable, we warn but don't crash (logging handled by caller)
+            pass
+
+    # ------------------------------------------------------------------
+    # Alias for CommandResult.name usage
+    # ------------------------------------------------------------------
+    @property
+    # ID: c70bf747-67ee-4913-a8df-91e325b8021a
+    def name(self) -> str:
+        """
+        Backwards-compatible alias for `action_id`.
+
+        Older code (like CLI workflows and reporters) still expects
+        `result.name`. New code should prefer `action_id`, but this
+        keeps existing workflows running while we migrate.
+        """
+        return self.action_id
+
+
+# Backward compatibility aliases (temporary - will be removed in future version)
+CommandResult = ActionResult
+"""
+DEPRECATED: Use ActionResult instead.
+
+This alias exists for backward compatibility during migration.
+Will be removed once all commands are migrated to ActionResult.
+"""