core-runtime 0.1.1__py3-none-any.whl

mind/logic/engines/ast_gate/__init__.py

@@ -0,0 +1,9 @@
+# src/mind/logic/engines/ast_gate/__init__.py
+"""Constitutional AST Gate Engine - Main Orchestrator."""
+
+from __future__ import annotations
+
+from mind.logic.engines.ast_gate.engine import ASTGateEngine
+
+
+__all__ = ["ASTGateEngine"]

mind/logic/engines/ast_gate/base.py

@@ -0,0 +1,263 @@
+# src/mind/logic/engines/ast_gate/base.py
+
+"""
+Shared AST analysis utilities for constitutional enforcement.
+
+Provides common helpers for traversing and analyzing Python AST nodes.
+CONSTITUTIONAL FIX (V2.3.0):
+- Added 'extract_domain_from_path' to centralize architectural layout knowledge.
+- Added 'domain_matches' to support trust-zone based enforcement.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+from pathlib import Path
+
+
+# ID: f75299d7-84aa-4254-8a2d-0e17da174d45
+class ASTHelpers:
+    """
+    Reusable AST traversal and analysis utilities.
+
+    Used by all AST check implementations to avoid duplication.
+    """
+
+    @staticmethod
+    # ID: b338ca12-adb5-482c-8399-a691192ee7ae
+    def lineno(node: ast.AST) -> int:
+        """Extract line number from AST node."""
+        return int(getattr(node, "lineno", 0) or 0)
+
+    @staticmethod
+    # ID: 533311f7-6f83-4660-a3b7-1db18d2a60ce
+    def full_attr_name(node: ast.AST) -> str | None:
+        """
+        Resolve dotted name from ast.Name / ast.Attribute chains.
+
+        Examples:
+            asyncio.run  -> "asyncio.run"
+            loop.create_task -> "loop.create_task"
+            create_async_engine -> "create_async_engine"
+        """
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            left = ASTHelpers.full_attr_name(node.value)
+            if left:
+                return f"{left}.{node.attr}"
+            return node.attr
+        return None
+
+    @staticmethod
+    # ID: b86381d2-3020-4866-b5d0-265950020b84
+    def build_import_alias_map(tree: ast.AST) -> dict[str, str]:
+        """Map local names to their qualified imported names.
+
+        Walks ImportFrom and Import statements anywhere in the tree and
+        records the translation a caller needs to recover the fully
+        qualified form of a Name- or Attribute-rooted call:
+
+            from os import replace            -> {"replace": "os.replace"}
+            from os import replace as r       -> {"r": "os.replace"}
+            import os                         -> {"os": "os"}
+            import os.path as op              -> {"op": "os.path"}
+
+        Function-local imports are included by design: governance-grade
+        detection prefers conservative over-inclusion to silent
+        bypass via `def f(): from os import replace`. False positives
+        from local shadowing are an accepted trade.
+
+        Out of scope (per #488):
+        - Star imports (`from os import *`) — explicit policy is no.
+        - Relative imports (`from . import x`) — `node.level > 0` skipped.
+        - Dynamic / `__import__` / `importlib` patterns.
+        """
+        alias_map: dict[str, str] = {}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                if not node.module or node.level > 0:
+                    continue
+                for alias in node.names:
+                    if alias.name == "*":
+                        continue
+                    local = alias.asname or alias.name
+                    alias_map[local] = f"{node.module}.{alias.name}"
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.asname:
+                        # `import os.path as op` -> {"op": "os.path"}
+                        alias_map[alias.asname] = alias.name
+                    else:
+                        # `import os` -> {"os": "os"}
+                        # `import os.path` binds the leftmost name "os";
+                        # callers still write `os.path.exists(...)`, which
+                        # full_attr_name already resolves correctly.
+                        head = alias.name.split(".", 1)[0]
+                        alias_map[head] = head
+        return alias_map
+
+    @staticmethod
+    # ID: a24dd4d6-a617-4197-a65e-d1257c691d38
+    def resolve_qualified_name(node: ast.AST, alias_map: dict[str, str]) -> str | None:
+        """Resolve a Name/Attribute chain to its qualified form via aliases.
+
+        Computes `full_attr_name(node)` and, if the leftmost segment is in
+        the alias map, replaces it with the imported qualified form:
+
+            r                  + {"r": "os.replace"}    -> "os.replace"
+            path.exists        + {"path": "os.path"}    -> "os.path.exists"
+            os.replace         + {"os": "os"}           -> "os.replace"
+            unrelated.thing    + {}                     -> "unrelated.thing"
+
+        Returns None when the node is neither a Name nor an Attribute
+        chain (e.g., Call().method() — the receiver is a Call, not a
+        resolvable dotted name).
+        """
+        name = ASTHelpers.full_attr_name(node)
+        if not name:
+            return None
+        head, _, tail = name.partition(".")
+        if head in alias_map:
+            resolved = alias_map[head]
+            return f"{resolved}.{tail}" if tail else resolved
+        return name
+
+    @staticmethod
+    # ID: e5fec108-e53c-4611-9ccb-1b17f9d3523b
+    def matches_call(call_name: str, disallowed: list[str]) -> bool:
+        """
+        Match call name against disallowed patterns.
+
+        Strategies:
+        - Exact match on fully qualified name (e.g., "asyncio.run" == "asyncio.run")
+        - Suffix match with dot (e.g., "foo.asyncio.run" matches "asyncio.run")
+
+        DOES NOT match bare leaf names to prevent false positives.
+        Example: "subprocess.run" will NOT match "asyncio.run"
+
+        Args:
+            call_name: Fully qualified call name from AST (e.g., "asyncio.run")
+            disallowed: List of forbidden call patterns (e.g., ["asyncio.run"])
+
+        Returns:
+            True if call_name matches any disallowed pattern
+        """
+        for pattern in disallowed:
+            # Strategy 1: Exact match
+            if call_name == pattern:
+                return True
+
+            # Strategy 2: Suffix match (handles nested imports)
+            if "." in pattern:
+                # Only match if it's a proper suffix with a dot boundary
+                if call_name.endswith(f".{pattern}") or call_name.endswith(pattern):
+                    call_parts = call_name.split(".")
+                    pattern_parts = pattern.split(".")
+
+                    if len(call_parts) >= len(pattern_parts):
+                        # Check if the rightmost N parts match
+                        if call_parts[-len(pattern_parts) :] == pattern_parts:
+                            return True
+
+        return False
+
+    @staticmethod
+    # ID: 9e091307-b265-4f46-8a62-e6b4ac1681eb
+    def iter_module_level_stmts(tree: ast.AST) -> Iterable[ast.stmt]:
+        """Iterate over module-level statements."""
+        if isinstance(tree, ast.Module):
+            return tree.body
+        return []
+
+    @staticmethod
+    # ID: 10e7f915-2059-4010-afe6-6be56b2084fb
+    def walk_module_stmt_without_nested_scopes(stmt: ast.stmt) -> Iterable[ast.AST]:
+        """
+        Walk statement but don't descend into nested scopes.
+
+        Skips: function defs, class defs, lambdas
+        """
+
+        def _walk(node: ast.AST) -> Iterable[ast.AST]:
+            yield node
+            for child in ast.iter_child_nodes(node):
+                if isinstance(
+                    child,
+                    (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda),
+                ):
+                    continue
+                yield from _walk(child)
+
+        return _walk(stmt)
+
+    # -------------------------------------------------------------------------
+    # NEW ARCHITECTURAL HELPERS (Constitutional Mapping Logic)
+    # -------------------------------------------------------------------------
+
+    @staticmethod
+    # ID: e4d3c2b1-a0f9-8e7d-6c5b-4a3f2e1d0c9b
+    def extract_domain_from_path(file_path: Path | str) -> str:
+        """
+        Extract domain from file path following CORE's domain convention.
+
+        Example: 'src/mind/governance/auditor.py' -> 'mind.governance'
+        """
+        path_str = str(file_path).replace("\\", "/")
+
+        if "/src/" in path_str:
+            path_str = path_str.split("/src/", 1)[1]
+        elif path_str.startswith("src/"):
+            path_str = path_str[4:]
+
+        parts = path_str.split("/")
+        domain_parts = [p for p in parts[:-1] if p]
+
+        return ".".join(domain_parts) if domain_parts else ""
+
+    @staticmethod
+    # ID: f3e2d1c0-b9a8-7f6e-5d4c-3b2a1f0e9d8c
+    def domain_matches(file_domain: str, allowed_domains: list[str]) -> bool:
+        """
+        Check if file domain matches any allowed domain (exact or prefix).
+        """
+        if not file_domain or not allowed_domains:
+            return False
+
+        for allowed in allowed_domains:
+            if file_domain == allowed or file_domain.startswith(f"{allowed}."):
+                return True
+
+        return False
+
+    @staticmethod
+    # ID: 337aed3b-dc01-4b17-bbe3-e8498e1dee13
+    def is_type_checking_condition(test_node: ast.expr) -> bool:
+        """
+        Check if an If condition is checking TYPE_CHECKING.
+
+        Matches:
+        - TYPE_CHECKING
+        - typing.TYPE_CHECKING
+
+        Args:
+            test_node: The test expression from an ast.If node
+
+        Returns:
+            True if the condition checks TYPE_CHECKING
+
+        Examples:
+            >>> # Matches: if TYPE_CHECKING:
+            >>> # Matches: if typing.TYPE_CHECKING:
+        """
+        if isinstance(test_node, ast.Name):
+            return test_node.id == "TYPE_CHECKING"
+
+        if isinstance(test_node, ast.Attribute):
+            # Handle typing.TYPE_CHECKING
+            if test_node.attr == "TYPE_CHECKING":
+                if isinstance(test_node.value, ast.Name):
+                    return test_node.value.id == "typing"
+
+        return False

mind/logic/engines/ast_gate/checks/__init__.py

@@ -0,0 +1,35 @@
+# src/mind/logic/engines/ast_gate/checks/__init__.py
+
+"""Provides functionality for the __init__ module."""
+
+from __future__ import annotations
+
+from .async_checks import AsyncChecks
+from .capability_checks import CapabilityChecks
+from .conservation_checks import ConservationChecks
+from .generic_checks import GenericASTChecks
+from .import_checks import ImportChecks
+from .logging_checks import LoggingChecks
+from .metadata_checks import normalize_ast, verify_metadata_only_diff
+from .naming_checks import NamingChecks
+from .prompt_model_checks import PromptModelChecks
+from .protected_namespace_access_check import ProtectedNamespaceAccessCheck
+from .purity_checks import PurityChecks
+from .schema_conformance_checks import SchemaConformanceChecks
+
+
+__all__ = [
+    "AsyncChecks",
+    "CapabilityChecks",
+    "ConservationChecks",
+    "GenericASTChecks",
+    "ImportChecks",
+    "LoggingChecks",
+    "NamingChecks",
+    "PromptModelChecks",
+    "ProtectedNamespaceAccessCheck",
+    "PurityChecks",
+    "SchemaConformanceChecks",
+    "normalize_ast",
+    "verify_metadata_only_diff",
+]

mind/logic/engines/ast_gate/checks/async_checks.py

@@ -0,0 +1,276 @@
+# src/mind/logic/engines/ast_gate/checks/async_checks.py
+"""Async safety checks for constitutional enforcement."""
+
+from __future__ import annotations
+
+import ast
+
+from mind.logic.engines.ast_gate.base import ASTHelpers
+
+
+# ID: a6facc5a-b9b3-45fd-9ae9-414ca0976c6c
+class AsyncChecks:
+    """Async safety and event loop management checks."""
+
+    @staticmethod
+    # ID: 965336f9-45fd-4c4e-b063-1cba88974b3c
+    def check_restricted_event_loop_creation(
+        tree: ast.AST, forbidden_calls: list[str]
+    ) -> list[str]:
+        """
+        Forbid dangerous event loop hijacking.
+
+        ALLOWS (defensive patterns):
+        - asyncio.get_event_loop() for checking state (not followed by .run_until_complete())
+        - asyncio.run() when guarded by loop existence check
+
+        FORBIDS (dangerous patterns):
+        - asyncio.run() without checking for existing loop first
+        - loop.run_until_complete() (manual loop hijacking)
+        - asyncio.new_event_loop() (manual loop creation)
+        """
+        if not forbidden_calls:
+            return []
+
+        findings: list[str] = []
+
+        # Build parent map for context analysis
+        parent_map = {}
+        for parent in ast.walk(tree):
+            for child in ast.iter_child_nodes(parent):
+                parent_map[child] = parent
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            fn = ASTHelpers.full_attr_name(node.func)
+            if not fn:
+                continue
+
+            # 1. CHECK: loop.run_until_complete() - ALWAYS DANGEROUS
+            if fn.endswith(".run_until_complete"):
+                findings.append(
+                    f"Line {ASTHelpers.lineno(node)}: Forbidden manual loop hijacking '{fn}()'"
+                )
+                continue
+
+            # 2. CHECK: asyncio.get_event_loop() - only dangerous if used for run_until_complete
+            if ASTHelpers.matches_call(fn, ["asyncio.get_event_loop"]):
+                # Check what they do with the loop
+                if AsyncChecks._is_loop_hijacking(node, parent_map):
+                    findings.append(
+                        f"Line {ASTHelpers.lineno(node)}: Forbidden event-loop hijacking via get_event_loop().run_until_complete()"
+                    )
+                # Otherwise it's just checking - SAFE (defensive pattern)
+                continue
+
+            # 3. CHECK: asyncio.run() - only dangerous if NOT guarded
+            if ASTHelpers.matches_call(fn, ["asyncio.run"]):
+                # Check if this is in a defensive pattern
+                if not AsyncChecks._is_defensively_guarded(node, tree, parent_map):
+                    findings.append(
+                        f"Line {ASTHelpers.lineno(node)}: Forbidden asyncio.run() without defensive loop check"
+                    )
+                # Otherwise it's guarded - SAFE (defensive pattern)
+                continue
+
+            # 4. CHECK: Other forbidden calls (asyncio.new_event_loop, etc.)
+            if ASTHelpers.matches_call(fn, forbidden_calls):
+                # These are always dangerous
+                if fn not in [
+                    "asyncio.get_event_loop",
+                    "asyncio.run",
+                ]:  # Already handled above
+                    findings.append(
+                        f"Line {ASTHelpers.lineno(node)}: Forbidden event-loop call '{fn}()'"
+                    )
+
+        return findings
+
+    @staticmethod
+    def _is_loop_hijacking(get_event_loop_call: ast.Call, parent_map: dict) -> bool:
+        """
+        Check if asyncio.get_event_loop() is followed by .run_until_complete().
+
+        Pattern we're detecting:
+            loop = asyncio.get_event_loop()
+            loop.run_until_complete(...)  # DANGEROUS
+        """
+        # Get the parent assignment or expression
+        parent = parent_map.get(get_event_loop_call)
+
+        # Check if assigned to a variable
+        if isinstance(parent, ast.Assign):
+            # Get the variable name
+            if parent.targets and isinstance(parent.targets[0], ast.Name):
+                loop_var = parent.targets[0].id
+
+                # Look for usage of this variable with .run_until_complete()
+                # We need to check the function/method body containing this assignment
+                function_node = AsyncChecks._find_containing_function(
+                    parent, parent_map
+                )
+                if function_node:
+                    for node in ast.walk(function_node):
+                        if isinstance(node, ast.Call):
+                            if isinstance(node.func, ast.Attribute):
+                                if (
+                                    node.func.attr
+                                    in ["run_until_complete", "run_forever"]
+                                    and isinstance(node.func.value, ast.Name)
+                                    and node.func.value.id == loop_var
+                                ):
+                                    return True
+
+        # Check for direct chaining: asyncio.get_event_loop().run_until_complete(...)
+        if isinstance(parent, ast.Attribute):
+            if parent.attr in ["run_until_complete", "run_forever"]:
+                return True
+
+        return False
+
+    @staticmethod
+    def _is_defensively_guarded(
+        asyncio_run_call: ast.Call, tree: ast.AST, parent_map: dict
+    ) -> bool:
+        """
+        Check if asyncio.run() is guarded by a check for existing event loop.
+
+        Defensive pattern we're allowing:
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = None
+
+            if loop and loop.is_running():
+                # handle async context
+            else:
+                asyncio.run(...)  # SAFE - guarded
+        """
+        # Find the function containing this asyncio.run() call
+        function_node = AsyncChecks._find_containing_function(
+            asyncio_run_call, parent_map
+        )
+        if not function_node:
+            # Top-level or script - always unguarded
+            return False
+
+        # Look for defensive patterns in the function:
+        # 1. try/except with get_running_loop
+        # 2. if statement checking loop.is_running()
+
+        has_get_running_loop = False
+        has_is_running_check = False
+
+        for node in ast.walk(function_node):
+            # Check for asyncio.get_running_loop() call
+            if isinstance(node, ast.Call):
+                fn = ASTHelpers.full_attr_name(node.func)
+                if fn == "asyncio.get_running_loop":
+                    has_get_running_loop = True
+
+            # Check for .is_running() check
+            if isinstance(node, ast.Attribute):
+                if node.attr == "is_running":
+                    has_is_running_check = True
+
+        # If both defensive checks are present, it's guarded
+        return has_get_running_loop and has_is_running_check
+
+    @staticmethod
+    def _find_containing_function(
+        node: ast.AST, parent_map: dict
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+        """Walk up the parent chain to find the containing function."""
+        current = node
+        while current in parent_map:
+            current = parent_map[current]
+            if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                return current
+        return None
+
+    @staticmethod
+    # ID: b6ae62b2-abe5-404a-a607-40095adb556e
+    def check_no_import_time_async_singletons(
+        tree: ast.AST, disallowed_calls: list[str]
+    ) -> list[str]:
+        """Forbid loop-bound async resource creation at module import time."""
+        if not disallowed_calls:
+            return []
+
+        findings: list[str] = []
+        for stmt in ASTHelpers.iter_module_level_stmts(tree):
+            for node in ASTHelpers.walk_module_stmt_without_nested_scopes(stmt):
+                if isinstance(node, ast.Call):
+                    fn = ASTHelpers.full_attr_name(node.func)
+                    if not fn:
+                        continue
+                    if ASTHelpers.matches_call(fn, disallowed_calls):
+                        findings.append(
+                            f"Line {ASTHelpers.lineno(node)}: Import-time async singleton creation: '{fn}()'"
+                        )
+        return findings
+
+    @staticmethod
+    # ID: ad987b5e-75c6-4e39-a44f-e349acf5fae2
+    def check_no_module_level_async_engine(tree: ast.AST) -> list[str]:
+        """Forbid module-level create_async_engine assignment."""
+        findings: list[str] = []
+        disallowed = [
+            "create_async_engine",
+            "sqlalchemy.ext.asyncio.create_async_engine",
+        ]
+
+        for stmt in ASTHelpers.iter_module_level_stmts(tree):
+            value: ast.AST | None
+            if isinstance(stmt, ast.Assign):
+                value = stmt.value
+            elif isinstance(stmt, ast.AnnAssign):
+                value = stmt.value
+            else:
+                continue
+
+            if value is None or not isinstance(value, ast.Call):
+                continue
+
+            fn = ASTHelpers.full_attr_name(value.func)
+            if not fn:
+                continue
+
+            if ASTHelpers.matches_call(fn, disallowed):
+                line = ASTHelpers.lineno(value)
+                findings.append(
+                    f"Line {line}: Module-level async engine creation is forbidden: '{fn}()'"
+                )
+
+        return findings
+
+    @staticmethod
+    # ID: 55f1eafc-a82d-4f56-90d8-fc40d7a6eb2e
+    def check_no_task_return_from_sync_cli(tree: ast.AST) -> list[str]:
+        """Forbid returning asyncio Tasks/Futures from sync functions."""
+        findings: list[str] = []
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.FunctionDef):
+                continue
+
+            for inner in ast.walk(node):
+                if not isinstance(inner, ast.Return):
+                    continue
+                if inner.value is None:
+                    continue
+
+                if isinstance(inner.value, ast.Call):
+                    fn = ASTHelpers.full_attr_name(inner.value.func) or ""
+                    leaf = fn.split(".")[-1]
+                    if leaf == "create_task":
+                        findings.append(
+                            f"Line {ASTHelpers.lineno(inner)}: Sync function '{node.name}' returns Task"
+                        )
+                    elif leaf == "ensure_future":
+                        findings.append(
+                            f"Line {ASTHelpers.lineno(inner)}: Sync function '{node.name}' returns Future"
+                        )
+
+        return findings