core-runtime 0.1.1__py3-none-any.whl

shared/processors/yaml_processor.py

@@ -0,0 +1,72 @@
+# src/shared/processors/yaml_processor.py
+
+"""
+YAML processor implementing BaseProcessor interface.
+
+Eliminates AST duplication detected by purity.no_ast_duplication rule.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import yaml
+
+from shared.processors.base_processor import BaseProcessor
+
+
+# ID: f9d8e7c6-b5a4-9382-7160-5e4d3c2b1a09
+class YAMLProcessor(BaseProcessor):
+    """
+    Centralized YAML processor for constitutional file operations.
+
+    Implements BaseProcessor template methods using yaml module.
+    """
+
+    # ID: ccde777c-d73f-4530-8b20-68b35a955416
+    def _deserialize(self, file_handle: Any) -> dict[str, Any] | None:
+        """Deserialize using yaml.safe_load()."""
+        return yaml.safe_load(file_handle)
+
+    # ID: 8355f747-02fe-42c2-b9bb-d1a1c326baa6
+    def _validate_data(self, data: Any) -> bool:
+        """
+        Validate YAML-serializable data.
+
+        Checks that data can be safely serialized to YAML.
+        """
+        try:
+            yaml.safe_dump(data)
+            return True
+        except (yaml.YAMLError, TypeError):
+            return False
+
+    # ID: f2a3b4c5-d6e7-8f9a-0b1c-2d3e4f5a6b7c
+    def _format_name(self) -> str:
+        """Return format name for logging."""
+        return "YAML"
+
+    # ID: a3b4c5d6-e7f8-9a0b-1c2d-3e4f5a6b7c8d
+    def dump_yaml(self, data: Any) -> str:
+        """
+        Dump data to a JSON string.
+
+        Used for vectorization and creating text representations of
+        structured data.
+
+        Args:
+            data: Data to dump
+
+        Returns:
+            JSON string
+
+        NOTE: Method name kept as dump_yaml for backward compatibility,
+        but returns JSON for consistent vectorization format.
+        """
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+# Module-level instances for backward compatibility
+yaml_processor = YAMLProcessor(allow_duplicates=True)
+strict_yaml_processor = YAMLProcessor(allow_duplicates=False)

shared/protocols/__init__.py

@@ -0,0 +1,21 @@
+# src/shared/protocols/__init__.py
+"""
+Constitutional Protocols Hub.
+"""
+
+from __future__ import annotations
+
+from .cognitive import CognitiveProtocol
+from .executor import ActionExecutorProtocol
+from .interpreter import TaskStructureProtocol
+from .knowledge import SessionProviderProtocol
+from .llm import LLMClientProtocol
+
+
+all = [
+    "CognitiveProtocol",
+    "ActionExecutorProtocol",
+    "SessionProviderProtocol",
+    "LLMClientProtocol",
+    "TaskStructureProtocol",
+]

shared/protocols/brain_services.py

@@ -0,0 +1,35 @@
+# src/shared/protocols/brain_services.py
+
+"""
+Brain Services Provider Protocol.
+
+Defines the interface for resolving cognitive_service and qdrant_service
+at runtime. Allows shared-layer infrastructure (notably ContextService)
+to delegate service resolution without importing directly from body or
+will. The body's ServiceRegistry structurally satisfies this protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+# ID: 50fefd28-6dcb-4105-8c9c-973a9bdb2100
+class BrainServicesProvider(Protocol):
+    """
+    Structural interface for the runtime service resolver.
+
+    Implementations expose lazy async getters for the cognitive and vector
+    services so callers can defer resolution past sync construction boundaries.
+    """
+
+    # ID: 97faba28-2ce5-4d35-8c70-a00f3f0d17b6
+    async def get_cognitive_service(self) -> Any:
+        """Return the initialized cognitive service instance."""
+        ...
+
+    # ID: 075d81b3-40b2-4431-ac99-381e3fb1ecc8
+    async def get_qdrant_service(self) -> Any:
+        """Return the initialized vector (Qdrant) service instance."""
+        ...

shared/protocols/cognitive.py

@@ -0,0 +1,35 @@
+# src/shared/protocols/cognitive.py
+
+"""
+Cognitive Service Protocol - The Reasoning Contract.
+
+Defines the interface for Large Language Model (LLM) interactions.
+Allows agents to request reasoning and embeddings without being
+coupled to specific provider implementations or database logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+# ID: f9cf5915-0c9d-4f7b-8915-6a1ceedf6c6f
+class CognitiveProtocol(Protocol):
+    """
+    Structural interface for the central cognitive facade.
+    """
+
+    # ID: 216dfad8-24c9-4861-9349-d7092d1ee76a
+    async def aget_client_for_role(self, role_name: str, **kwargs: Any) -> Any:
+        """
+        Return an LLM client configured for a specific cognitive role.
+        """
+        ...
+
+    # ID: 9bd4942a-b642-4262-89f8-936a16bcf103
+    async def get_embedding_for_code(self, source_code: str) -> list[float] | None:
+        """
+        Generate a semantic embedding vector for a piece of text.
+        """
+        ...

shared/protocols/executor.py

@@ -0,0 +1,47 @@
+# src/shared/protocols/executor.py
+
+"""
+Action Executor Protocol - The Universal Mutation Contract.
+
+This protocol defines the "shape" of the component responsible for
+executing atomic actions. It allows the Will layer (Agents) to
+request system changes without depending on the Body layer's
+implementation details.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from shared.action_types import ActionResult
+
+
+@runtime_checkable
+# ID: 9b980986-296c-4156-8818-0ccd98a38254
+class ActionExecutorProtocol(Protocol):
+    """
+    Structural interface for the universal action execution gateway.
+
+    Any class that implements this 'execute' method can be used by
+    CORE agents to perform governed mutations.
+    """
+
+    # ID: a0e7d2d1-1961-4024-ab89-55508e815ec2
+    async def execute(
+        self,
+        action_id: str,
+        write: bool = False,
+        **params: Any,
+    ) -> ActionResult:
+        """
+        Execute an action with full constitutional governance.
+
+        Args:
+            action_id: Registered action ID (e.g., "fix.format")
+            write: Whether to apply changes (False = dry-run)
+            **params: Action-specific parameters
+
+        Returns:
+            ActionResult with execution details and status
+        """
+        ...

shared/protocols/interpreter.py

@@ -0,0 +1,24 @@
+# src/shared/protocols/interpreter.py
+
+"""
+Protocol defining the shape of Task Structures.
+
+Allows Mind layer to reason about intent without importing Will.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+# ID: 4dd18afc-de7e-4703-abf8-d815ce21c874
+class TaskStructureProtocol(Protocol):
+    """The formal blueprint for a parsed user task."""
+
+    task_type: Any
+    intent: str
+    targets: list[str]
+    constraints: dict[str, Any]
+    context: dict[str, Any]
+    confidence: float

shared/protocols/knowledge.py

@@ -0,0 +1,21 @@
+# src/shared/protocols/knowledge.py
+
+"""
+Protocol defining the shape of a Session provider.
+
+Allows Mind layer to access DB infrastructure via injection.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+# ID: 2331a8d3-36e3-4bf3-aa76-b4fbbb110194
+class SessionProviderProtocol(Protocol):
+    """The formal blueprint for getting a DB session."""
+
+    # ID: 32604693-5d46-4f66-b006-9704313f6681
+    def session(self) -> AbstractAsyncContextManager[Any]: ...

shared/protocols/llm.py

@@ -0,0 +1,25 @@
+# src/shared/protocols/llm.py
+
+"""
+Protocol defining the shape of an LLM Client.
+
+Allows Mind/Will layers to use AI without importing Body implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+# ID: eda72309-ce4a-43a7-b25b-edce15912fad
+class LLMClientProtocol(Protocol):
+    """The formal blueprint for an LLM requester."""
+
+    # ID: e5c09d35-665a-4b15-922d-5486579a4d09
+    async def invoke_semantic_check(
+        self,
+        prompt: str,
+        system_prompt: str = "You are a helpful assistant.",
+        max_tokens: int | None = None,
+    ) -> str: ...

shared/protocols/typer_protocols.py

@@ -0,0 +1,37 @@
+# src/shared/protocols/typer_protocols.py
+"""Structural protocols for Typer CLI introspection.
+
+Single source of truth for TyperCommandLike, TyperGroupLike, TyperAppLike.
+Consumed by:
+  - body.maintenance.command_sync_service
+  - cli.logic.diagnostics
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+# ID: 10bc5565-2f20-4497-8865-c36de47dcb48
+class TyperCommandLike(Protocol):
+    """Structural protocol for a Typer registered command."""
+
+    name: str | None
+    callback: Any
+    help: str | None
+
+
+# ID: d01d9def-d26d-4c50-84f6-4ecc6921c9a1
+class TyperGroupLike(Protocol):
+    """Structural protocol for a Typer registered group."""
+
+    name: str | None
+    typer_instance: Any
+
+
+# ID: f9bd5ff6-605c-4575-b5c6-dc61f23bf964
+class TyperAppLike(Protocol):
+    """Structural protocol for a Typer application."""
+
+    registered_commands: list[TyperCommandLike]
+    registered_groups: list[TyperGroupLike]

shared/time.py

@@ -0,0 +1,18 @@
+# src/shared/time.py
+"""
+Lightweight time utilities shared across services.
+Implements the canonical capability for a UTC ISO timestamp function.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+# ID: 4f686bb3-7252-4f74-8e7c-d38a6ec85dc6
+def now_iso() -> str:
+    """Return current UTC timestamp in ISO 8601 format."""
+    return datetime.now(UTC).isoformat()
+
+
+# A trivial change for testing.

shared/universal.py

@@ -0,0 +1,43 @@
+# src/shared/universal.py
+"""
+Canonical hub for ultra-reusable micro-helpers.
+
+This module defines the **public, curated surface** of helpers that are truly
+universal across the CORE codebase — tiny, pure, side-effect-free utilities
+that stabilize patterns and reduce duplication.
+
+Rules for anything placed here:
+- MUST be pure (no I/O, no logging, no exceptions for control-flow).
+- MUST be simple, composable, and stable.
+- MUST NOT depend on ANYTHING outside the `shared/` namespace.
+- SHOULD be broadly applicable across features, agents, and governance.
+- SHOULD be preferred over re-creating ad-hoc helpers in features/.
+
+This module re-exports helpers defined under `shared.utils.common_knowledge`.
+Agents and developers MUST import through `shared.universal` instead of the
+implementation module.
+
+Example:
+    from shared.universal import normalize_whitespace
+"""
+
+from __future__ import annotations
+
+from shared.utils.common_knowledge import (
+    collapse_blank_lines,
+    ensure_trailing_newline,
+    get_deterministic_id,
+    normalize_text,
+    normalize_whitespace,
+    safe_truncate,
+)
+
+
+__all__ = [
+    "collapse_blank_lines",
+    "ensure_trailing_newline",
+    "get_deterministic_id",
+    "normalize_text",
+    "normalize_whitespace",
+    "safe_truncate",
+]

shared/utils/__init__.py

@@ -0,0 +1,81 @@
+# src/shared/utils/__init__.py
+
+"""
+Shared utility functions and helpers.
+
+Pure, stateless functions with no side effects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import cast
+
+
+# ID: fca84726-8bb7-4472-80cf-9d847144a1b2
+def create_greeting(name: str, *, time_of_day: str | None = None) -> str:
+    """
+    Create a personalized greeting message.
+    """
+    if not name or not isinstance(name, str):
+        raise ValueError("Name must be a non-empty string")
+
+    if time_of_day is None:
+        current_hour = datetime.now().hour
+        if current_hour < 12:
+            time_of_day = "morning"
+        elif current_hour < 17:
+            time_of_day = "afternoon"
+        else:
+            time_of_day = "evening"
+
+    time_greetings = {
+        "morning": "Good morning",
+        "afternoon": "Good afternoon",
+        "evening": "Good evening",
+        "night": "Good night",
+    }
+
+    base_greeting = time_greetings.get(time_of_day.lower(), "Hello")
+    return f"{base_greeting}, {name}!"
+
+
+# ID: ca71dd28-0aff-45c8-bba2-f4d12e7bcb7c
+def create_greeting_action(names: list[str], *, write: bool = False) -> list[str]:
+    """
+    Action pattern for creating multiple greetings.
+    """
+    if not isinstance(names, list):
+        raise TypeError("names must be a list")
+
+    greetings = []
+    try:
+        for name in names:
+            if not isinstance(name, str):
+                raise TypeError(f"All names must be strings. Found: {type(name)}")
+            greetings.append(create_greeting(name))
+
+        if write:
+            pass
+        return greetings
+
+    except Exception as e:
+        raise
+
+
+# ID: d8b9f0cb-037b-47ed-b0c2-b280b1d15ad2
+def format_greeting_for_output(greeting: str, style: str = "standard") -> str:
+    """
+    Format a greeting for different output styles.
+    """
+    styles: dict[str, Callable[[str], str]] = {
+        "standard": lambda g: g,
+        "uppercase": lambda g: g.upper(),
+        "lowercase": lambda g: g.lower(),
+        "excited": lambda g: g.replace("!", "!!!") if "!" in g else g + "!!!",
+    }
+
+    formatter = styles.get(style, styles["standard"])
+    # FIXED: Added cast to str for MyPy
+    return cast(str, formatter(greeting))

shared/utils/audit_grouping.py

@@ -0,0 +1,50 @@
+# src/shared/utils/audit_grouping.py
+## src/shared/utils/audit_grouping.py
+"""Utilities for grouping and analyzing audit findings."""
+
+from collections import defaultdict
+
+from shared.models import AuditFinding, AuditSeverity
+from shared.models.audit_rendering import SeverityGroup
+
+
+SEVERITY_ORDER: dict[AuditSeverity, int] = {
+    AuditSeverity.BLOCK: 5,
+    AuditSeverity.HIGH: 4,
+    AuditSeverity.MEDIUM: 3,
+    AuditSeverity.LOW: 2,
+    AuditSeverity.INFO: 1,
+}
+
+
+# ID: 9b328c94-6552-41e2-9a2e-46419693f6da
+def group_findings(findings: list[AuditFinding]) -> list[SeverityGroup]:
+    """Group findings by severity and return sorted list of groups (descending severity).
+
+    Returns new lists/tuples; no in-place mutation.
+    """
+    groups_dict: dict[AuditSeverity, list[AuditFinding]] = defaultdict(list)
+    for finding in findings:
+        groups_dict[finding.severity].append(finding)
+
+    sorted_severities = sorted(
+        groups_dict,
+        key=lambda s: SEVERITY_ORDER.get(s, -1),
+        reverse=True,
+    )
+
+    groups: list[SeverityGroup] = []
+    for sev in sorted_severities:
+        findings_list = groups_dict[sev]
+        groups.append(SeverityGroup(sev, tuple(findings_list)))
+    return groups
+
+
+# ID: f845871b-2720-4de3-a92d-29c7d14f9682
+def get_max_severity(groups: list[SeverityGroup]) -> AuditSeverity | None:
+    """Get highest severity from non-empty groups."""
+    non_empty_groups = [g for g in groups if g.count > 0]
+    if not non_empty_groups:
+        return None
+    max_group = max(non_empty_groups, key=lambda g: SEVERITY_ORDER.get(g.severity, -1))
+    return max_group.severity

shared/utils/common_knowledge.py

@@ -0,0 +1,82 @@
+# src/shared/utils/common_knowledge.py
+"""
+Common Knowledge Helpers
+
+This module defines the implementation of small, pure, general-purpose utilities
+used across CORE. These helpers feed the curated surface exposed through the
+`shared.universal` module.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+
+# ID: 88db4d40-e91a-4d5e-b627-c215ea063f2e
+def normalize_whitespace(text: str) -> str:
+    """
+    Collapse consecutive whitespace characters (including tabs/newlines)
+    into a single space, preserving readable semantics.
+    """
+    return " ".join(text.split())
+
+
+# Backwards-compatible alias.
+# Explicitly aliased to avoid semantic duplication detection.
+normalize_text = normalize_whitespace
+
+
+# ID: 6fca50dc-e2a4-4b44-ae52-cb599eaded0e
+def collapse_blank_lines(text: str) -> str:
+    """
+    Remove redundant blank lines while preserving paragraph separation.
+    """
+    lines = text.splitlines()
+    result: list[str] = []
+    buffer_blank = False
+
+    for line in lines:
+        if not line.strip():
+            if not buffer_blank:
+                result.append("")
+            buffer_blank = True
+        else:
+            result.append(line)
+            buffer_blank = False
+
+    return "\n".join(result)
+
+
+# ID: 23ad1f63-c768-4a4b-8f4c-41bbb6dbbb66
+def ensure_trailing_newline(text: str) -> str:
+    """
+    Ensure that a string ends with exactly one newline. Helps keep diffs minimal.
+    """
+    return text.rstrip("\n") + "\n"
+
+
+# ID: 0b51b893-0212-4037-8e6d-5af16677924c
+def safe_truncate(text: str, max_chars: int) -> str:
+    """
+    Truncate text safely to `max_chars`, preserving whole words where possible,
+    and adding '…' to indicate truncation.
+    """
+    if len(text) <= max_chars:
+        return text
+
+    cut = text[:max_chars].rsplit(" ", 1)[0]
+    return cut + "…"
+
+
+# ID: 7cbb0bb7-3ba8-4b35-9b9d-9422541d25de
+def get_deterministic_id(text: str) -> str:
+    """
+    Generate a stable UUID from text using SHA-256 and UUID5.
+
+    This is CORE's universal identity function - all deterministic IDs
+    must be UUIDs to maintain constitutional consistency.
+
+    Returns:
+        str: UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+    """
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, text))

shared/utils/domain_mapper.py

@@ -0,0 +1,61 @@
+# src/shared/utils/domain_mapper.py
+"""
+Constitutional domain mapper - maps module paths to domains defined in Constitution.
+This is the SINGLE SOURCE OF TRUTH for domain assignment.
+
+UPDATE (Wave 1 Reorganization):
+Supports both legacy 'features.X' and new layered 'body/will/mind.X' paths.
+"""
+
+from __future__ import annotations
+
+
+# src/shared/utils/domain_mapper.py
+
+
+# ID: a8fe04f1-60ec-4418-8727-2eaf690d1543
+def map_module_to_domain(module_path: str) -> str:
+    """
+    Maps a module path to its constitutional domain.
+    REFACTORED: Removed legacy 'features' prefixes.
+    """
+
+    # AUTONOMY: Agent orchestration, decision-making, planning
+    if module_path.startswith("will.autonomy."):
+        return "autonomy"
+    if module_path.startswith("will."):  # Primary catch-all for Agent logic
+        return "autonomy"
+
+    # CRATE_PROCESSING: External crate analysis
+    if module_path.startswith("body.crate_processing."):
+        return "crate_processing"
+
+    # GOVERNANCE: Constitutional enforcement, auditing, policy
+    if module_path.startswith(("mind.governance.", "mind.logic.engines.")):
+        return "governance"
+
+    # INTROSPECTION: Knowledge graph, vectorization, discovery
+    if module_path.startswith("body.introspection."):
+        return "introspection"
+
+    # MAINTENANCE: Database migrations, cleanup, sync
+    if module_path.startswith("body.maintenance."):
+        return "maintenance"
+
+    # OPERATIONS: CLI, API, infrastructure, shared
+    if module_path.startswith(("body.cli.", "body.operations.", "shared.", "api.")):
+        return "operations"
+
+    # PROJECT_LIFECYCLE: Bootstrap, scaffolding
+    if module_path.startswith("body.project_lifecycle."):
+        return "project_lifecycle"
+
+    # QUALITY: Code quality checks
+    if module_path.startswith("body.quality."):
+        return "quality"
+
+    # SELF_HEALING: Test generation, auto-remediation
+    if module_path.startswith(("body.self_healing.", "will.self_healing.")):
+        return "self_healing"
+
+    return "operations"