core-runtime 0.1.1__py3-none-any.whl

body/introspection/discovery/loader.py

@@ -0,0 +1,62 @@
+# src/body/introspection/discovery/loader.py
+
+"""Refactored logic for src/features/introspection/discovery/loader.py."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def _iter_capability_files(base: Path) -> Iterable[Path]:
+    if not base.exists():
+        return []
+    for p in sorted(base.glob("**/*")):
+        if p.is_dir():
+            continue
+        if p.suffix.lower() in {".yaml", ".yml"}:
+            yield p
+
+
+def _extract_canonical_from_doc(doc: dict) -> set[str]:
+    canonical: set[str] = set()
+    tags = doc.get("tags", [])
+    if isinstance(tags, list):
+        for item in tags:
+            if isinstance(item, dict) and isinstance(item.get("key"), str):
+                canonical.add(item["key"])
+    return canonical
+
+
+def _extract_aliases_from_doc(doc: dict) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    raw = doc.get("aliases")
+    if isinstance(raw, dict):
+        for k, v in raw.items():
+            if isinstance(k, str) and isinstance(v, str) and k and v:
+                aliases[k] = v
+    return aliases
+
+
+def _detect_alias_cycles(aliases: dict[str, str]) -> list[list[str]]:
+    visited: set[str] = set()
+    stack: set[str] = set()
+    cycles: list[list[str]] = []
+
+    # ID: d0cbfb51-a865-4552-ad69-a1b3953ff36d
+    def dfs(node: str, path: list[str]):
+        visited.add(node)
+        stack.add(node)
+        nxt = aliases.get(node)
+        if nxt:
+            if nxt not in visited:
+                dfs(nxt, [*path, nxt])
+            elif nxt in stack and nxt in path:
+                idx = path.index(nxt)
+                cycles.append([*path[idx:], nxt])
+        stack.remove(node)
+
+    for a in aliases:
+        if a not in visited:
+            dfs(a, [a])
+    return cycles

body/introspection/discovery/registry.py

@@ -0,0 +1,22 @@
+# src/body/introspection/discovery/registry.py
+
+"""Provides functionality for the registry module."""
+
+from __future__ import annotations
+
+
+# ID: a3e2c0e1-ab3a-4384-ad7d-e65025a70789
+class CapabilityRegistry:
+    """
+    Holds canonical capability keys and alias mapping.
+    """
+
+    def __init__(self, canonical: set[str], aliases: dict[str, str]):
+        self.canonical = set(canonical)
+        self.aliases = dict(aliases)
+
+    # ID: 8910cd7d-01b5-4bf4-87ff-b37733a82532
+    def resolve(self, tag: str) -> str | None:
+        if tag in self.canonical:
+            return tag
+        return self.aliases.get(tag)

body/introspection/discovery/semantics.py

@@ -0,0 +1,21 @@
+# src/body/introspection/discovery/semantics.py
+
+"""Provides functionality for the semantics module."""
+
+from __future__ import annotations
+
+
+# ID: ad12da2d-dac6-4192-9729-9095c28db8c2
+def _split_capability_key(key: str) -> tuple[str, str | None]:
+    """
+    Split a capability key into (domain, namespace).
+
+    RULES (constitutional):
+    - domain is the ONLY authority boundary
+    - namespace is informational only
+    - namespace MUST NOT be used for access control, ownership, or governance
+    """
+    if "." not in key:
+        return key, None
+    domain, namespace = key.split(".", 1)
+    return domain, namespace or None

body/introspection/discovery/sync.py

@@ -0,0 +1,47 @@
+# src/body/introspection/discovery/sync.py
+
+"""Refactored logic for src/features/introspection/discovery/sync.py."""
+
+from __future__ import annotations
+
+import json
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .semantics import _split_capability_key
+
+
+# ID: 1124a2cb-cfaf-4a2f-82a7-3f4cfd171fd3
+async def run_capability_upsert(db: AsyncSession, keys: set[str]) -> int:
+    """Sync constitutional capabilities into DB with authority boundaries."""
+    upserted = 0
+    for key in keys:
+        domain, namespace = _split_capability_key(key)
+        title = key.replace(".", " ").replace("_", " ").title()
+
+        stmt = text(
+            """
+            INSERT INTO core.capabilities
+                (name, domain, subdomain, title, owner, status, tags, updated_at)
+            VALUES
+                (:name, :domain, :subdomain, :title, 'constitution', 'Active', :tags, NOW())
+            ON CONFLICT (domain, name) DO UPDATE SET
+                subdomain = EXCLUDED.subdomain,
+                status = 'Active',
+                updated_at = NOW()
+        """
+        )
+
+        await db.execute(
+            stmt,
+            {
+                "name": key,
+                "domain": domain,
+                "subdomain": namespace,
+                "title": title,
+                "tags": json.dumps(["constitutional"]),
+            },
+        )
+        upserted += 1
+    return upserted

body/introspection/drift_detector.py

@@ -0,0 +1,81 @@
+# src/body/introspection/drift_detector.py
+"""
+Detects drift between declared capabilities in manifests and implemented
+capabilities in the source code.
+
+CONSTITUTIONAL FIX:
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Enforces IntentGuard and audit logging for drift reports.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from pathlib import Path
+
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+from shared.models import CapabilityMeta, DriftReport
+
+
+logger = getLogger(__name__)
+
+
+# ID: 6cc5efdf-037e-4862-b13e-0a569d889a97
+def detect_capability_drift(
+    manifest_caps: dict[str, CapabilityMeta], code_caps: dict[str, CapabilityMeta]
+) -> DriftReport:
+    """
+    Compares two dictionaries of capabilities and returns a drift report.
+    """
+    manifest_keys: set[str] = set(manifest_caps.keys())
+    code_keys: set[str] = set(code_caps.keys())
+
+    missing_in_code = sorted(list(manifest_keys - code_keys))
+    undeclared_in_manifest = sorted(list(code_keys - manifest_keys))
+
+    mismatched = []
+    for key in manifest_keys.intersection(code_keys):
+        manifest_cap = manifest_caps[key]
+        code_cap = code_caps[key]
+        if manifest_cap != code_cap:
+            mismatched.append(
+                {
+                    "capability": key,
+                    "manifest": asdict(manifest_cap),
+                    "code": asdict(code_cap),
+                }
+            )
+
+    return DriftReport(
+        missing_in_code=missing_in_code,
+        undeclared_in_manifest=undeclared_in_manifest,
+        mismatched_mappings=mismatched,
+    )
+
+
+# ID: db10bc9b-b4b3-41f2-8d81-b32731540d95
+def write_report(path: Path, report: DriftReport, repo_root: Path) -> None:
+    """
+    Writes the drift report to a JSON file via the governed FileHandler.
+    """
+    fh = FileHandler(str(repo_root))
+
+    try:
+        # Resolve to a repo-relative string as required by the FileHandler API
+        rel_path = str(path.resolve().relative_to(repo_root.resolve())).replace(
+            "\\", "/"
+        )
+
+        # This logs the mutation to core.action_results and enforces safety policies
+        fh.write_runtime_json(rel_path, report.to_dict())
+
+        logger.info("Drift report successfully persisted to %s", rel_path)
+    except ValueError:
+        # If the path is outside the repo, we log a warning but the Law forbids the write
+        logger.error(
+            "Security Violation: Attempted to write report to an ungoverned path: %s",
+            path,
+        )
+        raise

body/introspection/drift_service.py

@@ -0,0 +1,48 @@
+# src/body/introspection/drift_service.py
+
+"""
+Drift Service - Detects divergence between the Mind (Intent) and Body (Code).
+
+CONSTITUTIONAL FIX (V2.3):
+- Uses IntentRepository as the SSOT for declared capabilities.
+- Removed dependency on legacy 'from_manifest.py' crawler.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from body.introspection.drift_detector import detect_capability_drift
+from shared.infrastructure.intent.intent_repository import get_intent_repository
+from shared.infrastructure.knowledge.knowledge_service import KnowledgeService
+from shared.models import CapabilityMeta, DriftReport
+
+
+# DORMANT pending #503 — symbols-drift contract redesign (ADR-057 D5 first-scope semantics).
+# ID: 51f59218-c7f5-41ae-b2c9-87d4459e14d2
+async def run_drift_analysis_async(root: Path) -> DriftReport:
+    """
+    Performs drift analysis by comparing manifest rules (Mind)
+    against implemented symbols (Body).
+    """
+    # 1. Get Declared Capabilities from the Mind (IntentRepository)
+    repo = get_intent_repository()
+    # PathResolver handles mapping 'project_manifest' to the actual file
+    manifest_data = repo.load_policy("project_manifest")
+    declared_keys = manifest_data.get("capabilities", [])
+
+    manifest_caps = {
+        k: CapabilityMeta(key=k) for k in declared_keys if isinstance(k, str)
+    }
+
+    # 2. Get Implemented Capabilities from the Body (KnowledgeService)
+    knowledge_service = KnowledgeService(root)
+    graph = await knowledge_service.get_graph()
+
+    code_caps: dict[str, CapabilityMeta] = {}
+    for data in graph.get("symbols", {}).values():
+        key = data.get("key")
+        if key and key != "unassigned":
+            code_caps[key] = CapabilityMeta(key=key, domain=data.get("domain"))
+
+    return detect_capability_drift(manifest_caps, code_caps)

body/introspection/export_vectors.py

@@ -0,0 +1,133 @@
+# src/body/introspection/export_vectors.py
+
+"""
+A utility to export all vectors and their payloads from the Qdrant database
+to a local JSONL file for analysis, clustering, or backup.
+
+Refactored to use the canonical FileHandler for governed report persistence.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from qdrant_client.http import models as qm
+
+# REFACTORED: Removed direct settings import
+from shared.exceptions import CoreError
+from shared.logger import getLogger
+from shared.path_resolver import PathResolver
+
+
+if TYPE_CHECKING:
+    from shared.context import CoreContext
+    from shared.infrastructure.clients.qdrant_client import QdrantService
+    from shared.infrastructure.storage.file_handler import FileHandler
+
+logger = getLogger(__name__)
+
+
+# ID: 3196d095-9e61-4dbe-952c-dc4b7ea7c8e2
+class VectorExportError(CoreError):
+    """Raised when vector export cannot complete."""
+
+
+def _normalize_output_path(output_path: Path, repo_root: Path) -> str:
+    """
+    Convert the provided path to a repository-relative POSIX string.
+
+    Raises VectorExportError if the path escapes the repository boundary.
+    """
+    try:
+        if output_path.is_absolute():
+            rel_path = output_path.relative_to(repo_root)
+        else:
+            rel_path = output_path
+        return str(rel_path).replace("\\", "/")
+    except ValueError as exc:
+        logger.error("Output path %s must be within the repository root.", output_path)
+        raise VectorExportError(
+            "Output path must be within the repository root.", exit_code=1
+        ) from exc
+
+
+async def _async_export(
+    qdrant_service: QdrantService,
+    file_handler: FileHandler,
+    output_path: Path,
+    repo_root: Path,
+):
+    """
+    The core async logic for exporting vectors.
+    Mutations are routed through the governed FileHandler.
+    """
+
+    # 1. Path Normalization
+    # Convert absolute or relative path to a repo-relative string for the FileHandler
+    rel_path_str = _normalize_output_path(output_path, repo_root)
+
+    logger.info("Exporting all vectors to %s...", rel_path_str)
+
+    try:
+        # 2. Data Retrieval
+        all_vectors: list[qm.Record] = await qdrant_service.get_all_vectors()
+        if not all_vectors:
+            logger.info("No vectors found in the database to export.")
+            return
+
+        # 3. Content Preparation (JSONL format)
+        lines = []
+        for record in all_vectors:
+            vector_data = record.vector
+            if hasattr(vector_data, "tolist"):
+                vector_data = vector_data.tolist()
+
+            line_data = {
+                "id": str(record.id),
+                "payload": record.payload,
+                "vector": vector_data,
+            }
+            lines.append(json.dumps(line_data, ensure_ascii=False))
+
+        content = "\n".join(lines) + "\n"
+
+        # 4. Governed Write
+        # ensure_dir and write_runtime_text enforce IntentGuard and log the action
+        file_handler.ensure_dir(str(Path(rel_path_str).parent))
+        file_handler.write_runtime_text(rel_path_str, content)
+
+        logger.info(
+            "Successfully exported %s vectors via FileHandler.", len(all_vectors)
+        )
+
+    except Exception as e:
+        logger.error("Failed to export vectors: %s", e, exc_info=True)
+        raise VectorExportError("Failed to export vectors.", exit_code=1) from e
+
+
+# ID: 9d8d50b8-b533-4169-b21f-839a06db1f46
+async def export_vectors(
+    context: CoreContext, output: Path | str | None = None
+) -> None:
+    """Exports all vectors from Qdrant to a JSONL file via governed services."""
+    if output is None:
+        output = (
+            PathResolver.from_repo(context.git_service.repo_path).reports_dir
+            / "vectors_export.jsonl"
+        )
+    output_path = Path(output)
+    if not getattr(context, "qdrant_service", None) or not getattr(
+        context, "file_handler", None
+    ):
+        raise VectorExportError(
+            "CoreContext must provide qdrant_service and file_handler.", exit_code=1
+        )
+
+    await _async_export(
+        context.qdrant_service,
+        context.file_handler,
+        output_path,
+        context.git_service.repo_path,
+    )

body/introspection/generate_capability_docs.py

@@ -0,0 +1,130 @@
+# src/body/introspection/generate_capability_docs.py
+"""
+Generates the canonical capability reference documentation from the database.
+
+ARCHITECTURE: Pure feature - no standalone execution.
+Use via: core-admin build capability-docs
+
+CONSTITUTIONAL FIX:
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Enforces IntentGuard and audit logging for documentation exports.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+# --- Configuration ---
+# Internal logic uses repo-relative path for FileHandler compatibility
+REL_OUTPUT_PATH = "docs/10_CAPABILITY_REFERENCE.md"
+GITHUB_URL_BASE = "https://github.com/DariuszNewecki/CORE/blob/main/"
+
+HEADER = """
+# 10. Capability Reference
+
+This document is the canonical, auto-generated reference for all capabilities recognized by the CORE constitution.
+It is generated from the `core.knowledge_graph` database view and should not be edited manually.
+"""
+
+
+async def _fetch_capabilities(session: AsyncSession) -> list[dict]:
+    """
+    Fetches all public capabilities from the database knowledge graph view.
+
+    Args:
+        session: Injected database session
+    """
+    logger.info("Fetching capabilities from the database...")
+    stmt = text(
+        """
+            SELECT
+                capability,
+                intent,
+                file_path as file
+            FROM core.knowledge_graph
+            WHERE is_public = TRUE AND capability IS NOT NULL
+            ORDER BY capability;
+            """
+    )
+    result = await session.execute(stmt)
+    return [dict(row._mapping) for row in result]
+
+
+def _group_by_domain(capabilities: list[dict]) -> dict[str, list[dict]]:
+    """Groups capabilities by their domain prefix."""
+    domains = {}
+    for cap in capabilities:
+        key = cap["capability"]
+        # Infer domain from the key
+        domain_key = ".".join(key.split(".")[:-1]) if "." in key else "general"
+        if domain_key not in domains:
+            domains[domain_key] = []
+        domains[domain_key].append(cap)
+    return domains
+
+
+# ID: 2ea63de3-081d-40b3-9386-0d372487aabd
+async def main(session: AsyncSession, repo_root: Path):
+    """
+    The main entry point for the documentation generation script.
+    """
+    try:
+        capabilities = await _fetch_capabilities(session)
+    except Exception as e:
+        logger.error("Error fetching capabilities: %s", e)
+        return
+
+    if not capabilities:
+        logger.warning(
+            "No capabilities found in the database. Documentation will be empty."
+        )
+        return
+
+    domains = _group_by_domain(capabilities)
+
+    logger.info(
+        "Generating documentation for %d capabilities across %d domains...",
+        len(capabilities),
+        len(domains),
+    )
+
+    md_content = [HEADER.strip(), ""]
+
+    for domain_name in sorted(domains.keys()):
+        md_content.append(f"## Domain: `{domain_name}`")
+        md_content.append("")
+
+        for cap in sorted(domains[domain_name], key=lambda x: x["capability"]):
+            md_content.append(f"- **`{cap['capability']}`**")
+
+            description = cap.get("intent") or "No description provided."
+            md_content.append(f"  - **Description:** {description.strip()}")
+
+            file_path = cap.get("file")
+            line_number = 1
+            github_link = f"{GITHUB_URL_BASE}{file_path}#L{line_number}"
+            md_content.append(f"  - **Source:** [{file_path}]({github_link})")
+        md_content.append("")
+
+    final_text = "\n".join(md_content)
+
+    file_handler = FileHandler(str(repo_root))
+
+    try:
+        file_handler.write_runtime_text(REL_OUTPUT_PATH, final_text)
+        logger.info(
+            "Capability reference documentation successfully written to %s via FileHandler",
+            REL_OUTPUT_PATH,
+        )
+    except Exception as e:
+        logger.error("Failed to write documentation: %s", e)

body/introspection/generate_correction_map.py

@@ -0,0 +1,98 @@
+# src/body/introspection/generate_correction_map.py
+
+"""
+A utility to generate alias maps from semantic clustering results.
+It takes the proposed domain mappings and creates a YAML file that can be used
+by the AliasResolver to standardize capability keys.
+
+CONSTITUTIONAL FIX:
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Enforces IntentGuard and audit logging for alias map generation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from shared.exceptions import CoreError
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+from shared.path_resolver import PathResolver
+
+
+logger = getLogger(__name__)
+
+
+# ID: 2ae2b8e5-8e07-45d9-849e-d9fc2392bc16
+class GenerateCorrectionMapError(CoreError):
+    """Raised when correction map generation fails."""
+
+
+# ID: 58cc1c15-5bd9-401e-9bf2-8b64d1550631
+def generate_maps(
+    input_path: Path | str | None = None,
+    output: Path | str | None = None,
+    repo_root: Path | None = None,
+) -> None:
+    """
+    Generates an alias map from clustering results to a YAML file via FileHandler.
+    """
+    if repo_root is None:
+        raise ValueError("repo_root is required")
+    path_resolver = PathResolver.from_repo(repo_root)
+    if input_path is None:
+        input_path = path_resolver.reports_dir / "proposed_domains.json"
+    if output is None:
+        output = path_resolver.reports_dir / "aliases.yaml"
+    input_path = Path(input_path)
+    output_path = Path(output)
+
+    logger.info("Generating alias map from %s...", input_path)
+    try:
+        # We assume input is readable (read operations are governed differently)
+        proposed_domains = json.loads(input_path.read_text("utf-8"))
+    except (json.JSONDecodeError, FileNotFoundError) as e:
+        logger.error("Failed to load or parse input file: %s", e)
+        raise GenerateCorrectionMapError(
+            "Failed to load or parse input file.", exit_code=1
+        ) from e
+
+    alias_map = {"aliases": proposed_domains}
+    content_str = yaml.dump(alias_map, indent=2, sort_keys=True)
+
+    file_handler = FileHandler(str(repo_root))
+
+    try:
+        # Resolve to a repo-relative string for FileHandler
+        rel_output = str(
+            output_path.resolve().relative_to(repo_root.resolve())
+        ).replace("\\", "/")
+
+        # Governed write: checks IntentGuard and logs the event
+        file_handler.write_runtime_text(rel_output, content_str)
+
+        logger.info(
+            "Successfully generated alias map with %s entries.", len(proposed_domains)
+        )
+        logger.info("   -> Saved to: %s via FileHandler", rel_output)
+
+    except ValueError:
+        logger.error(
+            "Security Violation: Attempted to write alias map to ungoverned path: %s",
+            output_path,
+        )
+        raise GenerateCorrectionMapError("Path boundary violation.", exit_code=1)
+    except Exception as e:
+        logger.error("Failed to persist alias map: %s", e)
+        raise GenerateCorrectionMapError(f"Persistence failure: {e}", exit_code=1)
+
+
+if __name__ == "__main__":
+    try:
+        generate_maps()
+    except GenerateCorrectionMapError as exc:
+        raise SystemExit(exc.exit_code) from exc