core-runtime 0.1.1__py3-none-any.whl

shared/infrastructure/context/serializers.py

@@ -0,0 +1,144 @@
+# src/shared/infrastructure/context/serializers.py
+
+"""
+ContextSerializer - YAML I/O and token estimation.
+
+Policy:
+- No direct filesystem mutations outside governed surfaces.
+- Writes must go through FileHandler so IntentGuard is enforced.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from shared.config import settings
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().context
+
+
+# ID: 99a31e5a-ce83-437b-a03c-e21343ceeb3c
+class ContextSerializer:
+    """Serializes and deserializes ContextPacket."""
+
+    @staticmethod
+    # ID: 2ff86f07-0d18-4a4a-8778-ce742223f322
+    def to_yaml(packet: dict[str, Any], output_path: str) -> None:
+        yaml_text = yaml.safe_dump(packet, default_flow_style=False, sort_keys=False)
+
+        fh = FileHandler(str(settings.REPO_PATH))
+        rel = _to_repo_relative_path(output_path)
+
+        result = fh.write_runtime_text(rel, yaml_text)
+        try:
+            status = getattr(result, "status", "unknown")
+            logger.debug("Wrote context packet to %s (status=%s)", rel, status)
+        except Exception:
+            logger.debug("Wrote context packet to %s", rel)
+
+    @staticmethod
+    # ID: 9db70cab-e665-4635-858a-70fb80310b51
+    def from_yaml(input_path: str) -> dict[str, Any]:
+        packet = yaml.safe_load(Path(input_path).read_text(encoding="utf-8"))
+        logger.debug("Loaded context packet from %s", input_path)
+        return packet or {}
+
+    @staticmethod
+    # ID: f2d10834-5a64-4252-bd12-ec87c8e3f2c0
+    def estimate_tokens(text: str) -> int:
+        return len(text) // 4
+
+    @staticmethod
+    # ID: 4c1edebf-e182-4a7e-a0f7-a7469e431e9b
+    def compute_packet_hash(packet: dict[str, Any]) -> str:
+        canonical = {
+            "header": packet.get("header", {}),
+            "phase": packet.get("phase"),
+            "constitution": packet.get("constitution", {}),
+            "policy": packet.get("policy", {}),
+            "constraints": packet.get("constraints", {}),
+            "evidence": packet.get("evidence", []),
+            "runtime": packet.get("runtime", {}),
+        }
+        canonical_json = json.dumps(canonical, sort_keys=True, default=str)
+        digest = hashlib.sha256(canonical_json.encode()).hexdigest()
+        logger.debug("Computed context packet hash: %s...", digest[:8])
+        return digest
+
+    @staticmethod
+    # ID: fa12d7ab-310e-4b92-8e7a-95d6084e3536
+    def compute_cache_key(request_payload: dict[str, Any]) -> str:
+        cache_fields = {
+            "goal": request_payload.get("goal"),
+            "trigger": request_payload.get("trigger"),
+            "phase": request_payload.get("phase"),
+            "workflow_id": request_payload.get("workflow_id"),
+            "stage_id": request_payload.get("stage_id"),
+            "target_files": request_payload.get("target_files"),
+            "target_symbols": request_payload.get("target_symbols"),
+            "target_paths": request_payload.get("target_paths"),
+            "include_constitution": request_payload.get("include_constitution"),
+            "include_policy": request_payload.get("include_policy"),
+            "include_symbols": request_payload.get("include_symbols"),
+            "include_vectors": request_payload.get("include_vectors"),
+            "include_runtime": request_payload.get("include_runtime"),
+        }
+
+        cache_json = json.dumps(cache_fields, sort_keys=True, default=str)
+        cache_key = hashlib.sha256(cache_json.encode()).hexdigest()
+        logger.debug("Computed cache key: %s...", cache_key[:8])
+        return cache_key
+
+    @staticmethod
+    # ID: 11dac58e-a863-4210-96f9-cbbb4bc0745b
+    def estimate_packet_tokens(packet: dict[str, Any]) -> int:
+        total = 0
+
+        for item in packet.get("evidence", []):
+            try:
+                total += int(item.get("tokens_est", 0))
+            except Exception:
+                total += 0
+
+        for section_name in ("constitution", "policy", "constraints", "runtime"):
+            section = packet.get(section_name, {})
+            if section:
+                try:
+                    total += ContextSerializer.estimate_tokens(
+                        json.dumps(section, sort_keys=True, default=str)
+                    )
+                except Exception:
+                    total += 0
+
+        phase = packet.get("phase")
+        if phase:
+            total += ContextSerializer.estimate_tokens(str(phase))
+
+        total += _CFG.token_estimate_overhead
+        return total
+
+
+def _to_repo_relative_path(path_str: str) -> str:
+    p = Path(path_str)
+
+    if not p.is_absolute():
+        return p.as_posix().lstrip("./")
+
+    repo_root = Path(settings.REPO_PATH).resolve()
+    resolved = p.resolve()
+
+    if resolved.is_relative_to(repo_root):
+        return resolved.relative_to(repo_root).as_posix()
+
+    raise ValueError(f"Path is outside repository boundary: {path_str}")

shared/infrastructure/context/service.py

@@ -0,0 +1,271 @@
+# src/shared/infrastructure/context/service.py
+
+"""
+ContextService - main orchestrator for ContextPacket lifecycle.
+
+Pipeline:
+    ContextBuildRequest
+        -> ContextBuilder
+        -> ContextValidator
+        -> ContextRedactor
+        -> ContextSerializer
+
+This service does not preserve legacy task_spec or query payload compatibility.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from shared.infrastructure.intent.task_type_phases import resolve_phase
+from shared.logger import getLogger
+from shared.protocols.brain_services import BrainServicesProvider
+
+from .builder import ContextBuilder
+from .cache import ContextCache
+from .database import ContextDatabase
+from .models import ContextBuildRequest, ContextPacket
+from .providers.ast import ASTProvider
+from .providers.db import DBProvider
+from .providers.vectors import VectorProvider
+from .redactor import ContextRedactor
+from .serializers import ContextSerializer
+from .validator import ContextValidator
+
+
+if TYPE_CHECKING:
+    from shared.infrastructure.context.limb_workspace import LimbWorkspace
+
+logger = getLogger(__name__)
+
+
+# ID: abac420e-2c78-4e00-bdae-56ce751388d7
+class ContextService:
+    """
+    Main service for ContextPacket lifecycle management.
+    """
+
+    def __init__(
+        self,
+        qdrant_client: Any | None = None,
+        cognitive_service: Any | None = None,
+        config: dict[str, Any] | None = None,
+        project_root: str = ".",
+        session_factory: Any | None = None,
+        workspace: LimbWorkspace | None = None,
+        brain_services_provider: BrainServicesProvider | None = None,
+    ) -> None:
+        self.config = config or {}
+        self.project_root = Path(project_root)
+        self._session_factory = session_factory
+        self.workspace = workspace
+
+        self._qdrant_client = qdrant_client
+        self._cognitive_service = cognitive_service
+        self._brain_services_provider = brain_services_provider
+
+        self.validator = ContextValidator()
+        self.redactor = ContextRedactor()
+        self.cache = ContextCache(self.config.get("cache_dir", "work/context_cache"))
+        self.database = ContextDatabase()
+        self.ast_provider = ASTProvider(project_root)
+
+        if self.workspace:
+            logger.info("ContextService initialized in SHADOW mode")
+
+    async def _ensure_brain_services(self) -> None:
+        """
+        Resolve vector/cognitive services JIT via the injected provider.
+
+        The provider is asked only for services not already injected at
+        construction. If anything is missing and no provider was supplied,
+        we raise — silently constructing services from a layer-bound
+        global would violate shared/'s isolation.
+        """
+        if self._cognitive_service is not None and self._qdrant_client is not None:
+            return
+
+        if self._brain_services_provider is None:
+            raise RuntimeError(
+                "ContextService requires cognitive_service and qdrant_client; "
+                "neither was injected and no brain_services_provider was "
+                "supplied to resolve them."
+            )
+
+        if self._cognitive_service is None:
+            self._cognitive_service = (
+                await self._brain_services_provider.get_cognitive_service()
+            )
+
+        if self._qdrant_client is None:
+            self._qdrant_client = (
+                await self._brain_services_provider.get_qdrant_service()
+            )
+
+    def _build_context_builder(self) -> ContextBuilder:
+        db_provider = DBProvider(session_factory=self._session_factory)
+        vector_provider = VectorProvider(self._qdrant_client, self._cognitive_service)
+
+        return ContextBuilder(
+            db_provider=db_provider,
+            vector_provider=vector_provider,
+            ast_provider=self.ast_provider,
+            config=self.config,
+            workspace=self.workspace,
+        )
+
+    # ID: b2fddb8f-af40-41d9-a45d-9af40ca1dc10
+    async def build(
+        self,
+        request: ContextBuildRequest,
+        use_cache: bool = True,
+    ) -> ContextPacket:
+        """
+        Canonical entry point for context packet assembly.
+        """
+        await self._ensure_brain_services()
+
+        effective_use_cache = use_cache if self.workspace is None else False
+        cache_key = self._compute_request_cache_key(request)
+
+        if effective_use_cache:
+            cached = self.cache.get(cache_key)
+            if cached:
+                return self._payload_to_packet(cached, request)
+
+        builder = self._build_context_builder()
+        packet = await builder.build(request)
+
+        validation_result = self.validator.validate(packet)
+        if not validation_result.ok:
+            logger.error("Context packet rejected: %s", validation_result.errors)
+            raise ValueError(f"Context validation failed: {validation_result.errors}")
+
+        redacted_packet = self.redactor.redact(validation_result.validated_data)
+        redacted_packet.setdefault("provenance", {})
+        redacted_packet["provenance"]["packet_hash"] = (
+            ContextSerializer.compute_packet_hash(redacted_packet)
+        )
+
+        if effective_use_cache:
+            self.cache.set(cache_key, redacted_packet)
+
+        return self._payload_to_packet(redacted_packet, request)
+
+    # ID: 4f9a1c3e-7b82-4d56-a8e1-2c0f5e9d3a71
+    async def build_for_task(
+        self,
+        task_spec: dict[str, Any],
+        use_cache: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Bridge: task_spec dict -> ContextBuildRequest -> ContextPacket -> legacy dict.
+
+        Callers (code_generator, test_gen, conversational_agent) pass a task_spec
+        dict and expect a plain dict back with a "context" key containing evidence
+        items.  This method converts the dict to a typed ContextBuildRequest, calls
+        the canonical build() pipeline, then re-shapes the ContextPacket back into
+        the dict format those callers consume.
+
+        task_spec shape (authoritative):
+            {
+                "task_id":       str,           # used as goal fallback
+                "task_type":     str,           # maps to PhaseType
+                "target_file":   str,           # primary target file
+                "target_symbol": str,           # primary target symbol
+                "summary":       str,           # becomes goal (preferred)
+                "scope": {
+                    "include":         list[str],   # additional target files
+                    "traversal_depth": int,         # advisory, builder decides
+                },
+                "constraints": {
+                    "max_tokens": int,              # advisory, builder decides
+                    "max_items":  int,              # advisory, builder decides
+                },
+            }
+
+        Returns a dict compatible with all existing callers:
+            {
+                "context":    list[dict],   # evidence items from ContextPacket
+                "provenance": dict,
+                "header":     dict,
+            }
+        """
+        task_type = task_spec.get("task_type", "code_generation")
+        target_file = task_spec.get("target_file", "")
+        target_symbol = task_spec.get("target_symbol", "")
+        # Prefer summary; fall back to task_id, then task_type
+        goal = task_spec.get("summary") or task_spec.get("task_id") or task_type
+        scope_include: list[str] = task_spec.get("scope", {}).get("include", [])
+        phase = resolve_phase(task_type)
+
+        # Merge target_file with scope.include; deduplicate, preserve order, drop empties
+        raw_files = ([target_file] if target_file else []) + list(scope_include)
+        target_files = list(dict.fromkeys(f for f in raw_files if f))
+
+        request = ContextBuildRequest(
+            goal=goal,
+            trigger="agent",  # type: ignore[arg-type]
+            phase=phase,
+            target_files=target_files,
+            target_symbols=[target_symbol] if target_symbol else [],
+            include_constitution=True,
+            include_policy=True,
+            include_symbols=True,
+            include_vectors=True,
+            include_runtime=True,
+        )
+
+        packet = await self.build(request, use_cache=use_cache)
+
+        # Re-shape ContextPacket -> the dict shape consumed by callers.
+        # Callers index on "context"; ContextPacket stores evidence under .evidence.
+        # The builder produces a list; the dataclass annotation says dict — guard both.
+        evidence = packet.evidence
+        if isinstance(evidence, dict):
+            evidence = list(evidence.values()) if evidence else []
+
+        context_count = len(evidence) if isinstance(evidence, list) else 0
+        logger.info("Found %d context items for task_type=%s", context_count, task_type)
+
+        return {
+            "context": evidence,
+            "provenance": packet.provenance,
+            "header": packet.header,
+        }
+
+    def _compute_request_cache_key(self, request: ContextBuildRequest) -> str:
+        payload = {
+            "goal": request.goal,
+            "trigger": request.trigger,
+            "phase": request.phase,
+            "workflow_id": request.workflow_id,
+            "stage_id": request.stage_id,
+            "target_files": list(request.target_files),
+            "target_symbols": list(request.target_symbols),
+            "target_paths": list(request.target_paths),
+            "include_constitution": request.include_constitution,
+            "include_policy": request.include_policy,
+            "include_symbols": request.include_symbols,
+            "include_vectors": request.include_vectors,
+            "include_runtime": request.include_runtime,
+        }
+        return ContextSerializer.compute_cache_key(payload)
+
+    def _payload_to_packet(
+        self,
+        payload: dict[str, Any],
+        request: ContextBuildRequest,
+    ) -> ContextPacket:
+        return ContextPacket(
+            request=request,
+            header=payload.get("header", {}),
+            layer_constraints=payload.get("layer_constraints", {}),
+            constitution=payload.get("constitution", {}),
+            policy=payload.get("policy", {}),
+            constraints=payload.get("constraints", {}),
+            evidence=payload.get("evidence", {}),
+            runtime=payload.get("runtime", {}),
+            provenance=payload.get("provenance", {}),
+        )

shared/infrastructure/context/validator.py

@@ -0,0 +1,247 @@
+# src/shared/infrastructure/context/validator.py
+
+"""
+ContextValidator - enforces ContextPacket schema compliance.
+
+Validates doctrine-aligned packets with sections:
+    header
+    phase
+    constitution
+    policy
+    constraints
+    evidence
+    runtime
+    provenance
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, ClassVar
+
+import yaml
+
+from shared.config import settings
+from shared.logger import getLogger
+from shared.models.validation_result import ValidationResult
+
+
+logger = getLogger(__name__)
+
+
+# ID: 9aba6527-289c-4511-8283-36074d5de950
+class ContextValidator:
+    """Validates ContextPacket packets against the runtime schema."""
+
+    _REQUIRED_HEADER_FIELDS: ClassVar[set[str]] = {
+        "packet_id",
+        "created_at",
+        "builder_version",
+        "privacy",
+        "mode",
+        "goal",
+        "trigger",
+    }
+
+    _ALLOWED_PRIVACY_VALUES: ClassVar[set[str]] = {"local_only", "remote_allowed"}
+    _ALLOWED_PHASE_VALUES: ClassVar[set[str]] = {
+        "parse",
+        "load",
+        "audit",
+        "runtime",
+        "execution",
+    }
+    _ALLOWED_ITEM_TYPES: ClassVar[set[str]] = {
+        "symbol",
+        "snippet",
+        "summary",
+        "dependency",
+        "test",
+        "signature",
+        "code",
+        "semantic_match",
+    }
+    _OPTIONAL_OBJECT_SECTIONS: ClassVar[set[str]] = {
+        "constitution",
+        "policy",
+        "constraints",
+        "runtime",
+        "provenance",
+    }
+
+    def __init__(self, schema_path: Path | None = None) -> None:
+        self.schema_path: Path = schema_path or self._default_schema_path()
+        self.schema: dict[str, Any] = self._load_schema()
+
+    def _default_schema_path(self) -> Path:
+        if hasattr(settings.paths, "context_schema_path"):
+            return settings.paths.context_schema_path()
+        return settings.REPO_PATH / "var" / "context" / "schema.yaml"
+
+    def _load_schema(self) -> dict[str, Any]:
+        if not self.schema_path.exists():
+            raise FileNotFoundError(f"Schema not found: {self.schema_path}")
+
+        try:
+            content = self.schema_path.read_text(encoding="utf-8")
+            data = yaml.safe_load(content) or {}
+        except Exception as exc:
+            raise RuntimeError(
+                f"Failed to load schema: {self.schema_path} ({exc})"
+            ) from exc
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Invalid schema format (expected mapping): {self.schema_path}"
+            )
+
+        return data
+
+    # ID: decfe9e4-f915-4bcc-9ba0-46ea5bc713d7
+    def validate(self, packet: dict[str, Any]) -> ValidationResult:
+        errors: list[str] = []
+
+        required_fields = self.schema.get("required_fields", [])
+        if isinstance(required_fields, list):
+            for field in required_fields:
+                if field not in packet:
+                    errors.append(f"Missing required field: {field}")
+
+        errors.extend(self._validate_header(packet.get("header", {})))
+        errors.extend(self._validate_phase(packet.get("phase")))
+        errors.extend(self._validate_evidence(packet.get("evidence", [])))
+        errors.extend(self._validate_optional_sections(packet))
+        errors.extend(self._validate_constraints(packet.get("constraints", {})))
+        errors.extend(self._validate_policy(packet))
+        errors.extend(self._validate_provenance(packet.get("provenance", {})))
+
+        header = packet.get("header")
+        packet_id = (
+            header.get("packet_id", "unknown")
+            if isinstance(header, dict)
+            else "unknown"
+        )
+
+        is_valid = not errors
+        if is_valid:
+            logger.info("Context packet validated: %s", packet_id)
+        else:
+            logger.warning(
+                "Context validation failed (%s errors) for %s",
+                len(errors),
+                packet_id,
+            )
+
+        return ValidationResult(
+            ok=is_valid,
+            errors=errors,
+            validated_data=packet if is_valid else {},
+            metadata={"packet_id": packet_id},
+        )
+
+    def _validate_header(self, header: Any) -> list[str]:
+        if not isinstance(header, dict):
+            return ["Header must be an object"]
+
+        errors: list[str] = []
+
+        missing_fields = sorted(self._REQUIRED_HEADER_FIELDS - set(header.keys()))
+        for field in missing_fields:
+            errors.append(f"Header missing required field: {field}")
+
+        privacy = header.get("privacy")
+        if privacy is not None and privacy not in self._ALLOWED_PRIVACY_VALUES:
+            errors.append(f"Invalid privacy value: {privacy}")
+
+        return errors
+
+    def _validate_phase(self, phase: Any) -> list[str]:
+        if not isinstance(phase, str):
+            return ["Phase must be a string"]
+        if phase not in self._ALLOWED_PHASE_VALUES:
+            return [f"Invalid phase value: {phase}"]
+        return []
+
+    def _validate_constraints(self, constraints: Any) -> list[str]:
+        if not isinstance(constraints, dict):
+            return ["Constraints must be an object"]
+
+        errors: list[str] = []
+
+        applicable_rules = constraints.get("applicable_rules")
+        if applicable_rules is not None and not isinstance(applicable_rules, list):
+            errors.append("Constraints.applicable_rules must be an array")
+
+        return errors
+
+    def _validate_evidence(self, evidence: Any) -> list[str]:
+        if not isinstance(evidence, list):
+            return ["Evidence must be an array"]
+
+        errors: list[str] = []
+
+        for idx, item in enumerate(evidence):
+            if not isinstance(item, dict):
+                errors.append(f"Evidence[{idx}] must be an object")
+                continue
+
+            missing_fields = sorted({"name", "item_type", "source"} - set(item.keys()))
+            for field in missing_fields:
+                errors.append(f"Evidence[{idx}] missing required field: {field}")
+
+            item_type = item.get("item_type")
+            if item_type is not None and item_type not in self._ALLOWED_ITEM_TYPES:
+                errors.append(f"Evidence[{idx}] invalid item_type: {item_type}")
+
+        return errors
+
+    def _validate_optional_sections(self, packet: dict[str, Any]) -> list[str]:
+        errors: list[str] = []
+
+        for section in self._OPTIONAL_OBJECT_SECTIONS:
+            if section in packet and not isinstance(packet[section], dict):
+                errors.append(f"{section.capitalize()} must be an object")
+
+        constitution = packet.get("constitution")
+        if constitution is not None and not isinstance(constitution, dict):
+            errors.append("Constitution must be an object")
+
+        return errors
+
+    def _validate_policy(self, packet: dict[str, Any]) -> list[str]:
+        policy = packet.get("policy", {})
+        header = packet.get("header", {})
+
+        if not isinstance(policy, dict):
+            return ["Policy must be an object"]
+        if not isinstance(header, dict):
+            return ["Header must be an object"]
+
+        errors: list[str] = []
+
+        privacy = header.get("privacy")
+        remote_allowed = bool(policy.get("remote_allowed"))
+
+        if privacy == "local_only" and remote_allowed:
+            errors.append("Privacy is local_only but policy.remote_allowed is true")
+
+        return errors
+
+    def _validate_provenance(self, provenance: Any) -> list[str]:
+        if not isinstance(provenance, dict):
+            return ["Provenance must be an object"]
+
+        errors: list[str] = []
+
+        if "cache_key" in provenance and not isinstance(provenance["cache_key"], str):
+            errors.append("Provenance.cache_key must be a string")
+
+        if "providers" in provenance and not isinstance(provenance["providers"], list):
+            errors.append("Provenance.providers must be an array")
+
+        if "build_stats" in provenance and not isinstance(
+            provenance["build_stats"], dict
+        ):
+            errors.append("Provenance.build_stats must be an object")
+
+        return errors