frontmattering 0.4.2__py3-none-any.whl

frontmattering/common/errors.py

@@ -0,0 +1,1074 @@
+"""Structured error hierarchy for Frontmattering.
+
+Design principles (from GOVERNANCE_RULES):
+- LOUD: Exceptions must be raised, not silently logged
+- INFORMATIVE: Every exception answers WHAT/WHERE/WHY
+- CONTEXTUAL: Include relevant input values (truncated if large)
+
+Hierarchy:
+    FrontmatteringError (base)
+    ├── CliArgError
+    ├── ParsingError
+    │   ├── DocumentTooLargeError
+    │   └── MalformedContentError
+    ├── ValidationError
+    │   ├── SchemaValidationError
+    │   └── ComplianceError
+    ├── StorageError
+    │   ├── NotFoundError
+    │   └── AlreadyExistsError
+    ├── StalenessError
+    │   ├── StaleFactsError
+    │   └── StaleDocumentError
+    ├── EntityError
+    │   ├── EntityNotFoundError
+    │   └── EntityAmbiguousError
+    └── ExternalToolError
+        ├── ToolTimeoutError
+        └── ToolResponseError
+
+Usage:
+    from Frontmattering.common import ValidationError, EntityNotFoundError
+
+    raise ValidationError(
+        what="Schema validation failed",
+        where="schema/extractor.py:extract_plan_manifest",
+        why="Missing required field 'steps'",
+        context={"file": plan_file, "fields_found": list(data.keys())}
+    )
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def capture_exception(
+    fn: Callable[..., T], *args: Any, **kwargs: Any
+) -> tuple[T | None, Exception | None]:
+    """Run a callable and capture any raised exception as a value."""
+    try:
+        return fn(*args, **kwargs), None
+    except Exception as exc:
+        return None, exc
+
+
+class FrontmatteringError(Exception):
+    """Base exception for all Frontmattering errors.
+
+    All Frontmattering exceptions follow WHAT/WHERE/WHY/FIX pattern.
+
+    Args:
+        what: Clear description of what failed
+        where: Context about location (function, file, entity)
+        why: The cause or original exception message
+        fix: User-actionable guidance on how to resolve the error
+        context: Additional values for debugging (auto-truncated)
+
+    Display methods:
+        str(error)      → Single-line format for logs
+        error.display() → Multi-line rich format for terminal
+        error.to_dict() → Structured format for JSON output
+    """
+
+    def __init__(
+        self,
+        what: str,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.what = what
+        self.where = where
+        self.why = why
+        self.fix = fix
+        self.context = context or {}
+
+        # Build message following GOVERNANCE_RULES template
+        parts = [f"WHAT: {what}"]
+        if where:
+            parts.append(f"WHERE: {where}")
+        if why:
+            parts.append(f"WHY: {why}")
+        if fix:
+            parts.append(f"FIX: {fix}")
+        if context:
+            # Truncate large context values
+            truncated = {k: _truncate(v) for k, v in context.items()}
+            parts.append(f"CONTEXT: {truncated}")
+
+        message = " | ".join(parts)
+        super().__init__(message)
+
+    def display(self, use_rich: bool = True) -> str:
+        """Format error for terminal display.
+
+        Args:
+            use_rich: If True, include ANSI color codes
+
+        Returns:
+            Multi-line formatted error message
+        """
+        lines = []
+
+        # Header with error type
+        error_type = self.__class__.__name__
+        if use_rich:
+            lines.append(f"\033[1;31m✗ {error_type}\033[0m")  # Bold red
+        else:
+            lines.append(f"✗ {error_type}")
+
+        # WHAT (always present)
+        if use_rich:
+            lines.append(f"  \033[1mWhat:\033[0m {self.what}")
+        else:
+            lines.append(f"  What: {self.what}")
+
+        # WHERE (if present)
+        if self.where:
+            if use_rich:
+                lines.append(f"  \033[1mWhere:\033[0m {self.where}")
+            else:
+                lines.append(f"  Where: {self.where}")
+
+        # WHY (if present)
+        if self.why:
+            if use_rich:
+                lines.append(f"  \033[1mWhy:\033[0m {self.why}")
+            else:
+                lines.append(f"  Why: {self.why}")
+
+        # FIX (if present - user-actionable guidance)
+        if self.fix:
+            if use_rich:
+                lines.append(f"  \033[1;32mFix:\033[0m {self.fix}")  # Bold green
+            else:
+                lines.append(f"  Fix: {self.fix}")
+
+        # CONTEXT (if present, formatted nicely)
+        if self.context:
+            if use_rich:
+                lines.append("  \033[1mContext:\033[0m")
+            else:
+                lines.append("  Context:")
+            for key, value in self.context.items():
+                truncated = _truncate(value, 80)
+                lines.append(f"    {key}: {truncated}")
+
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert error to dictionary for JSON serialization."""
+        return {
+            "error_type": self.__class__.__name__,
+            "what": self.what,
+            "where": self.where,
+            "why": self.why,
+            "fix": self.fix,
+            "context": self.context,
+        }
+
+
+class CliArgError(FrontmatteringError):
+    """CLI argument parsing/shape errors with actionable fixes."""
+
+
+def _truncate(value: Any, max_len: int = 100) -> str:
+    """Truncate value for error context display."""
+    s = repr(value)
+    if len(s) > max_len:
+        return s[: max_len - 3] + "..."
+    return s
+
+
+# =============================================================================
+# ERROR DISPLAY UTILITIES
+# =============================================================================
+
+
+def format_error(error: Exception, use_rich: bool = True) -> str:
+    """Format any exception for terminal display.
+
+    Args:
+        error: Exception to format
+        use_rich: If True, include ANSI color codes
+
+    Returns:
+        Formatted error string
+
+    Usage:
+        try:
+            risky_operation()
+        except Exception as e:
+            print(format_error(e))
+    """
+    if isinstance(error, FrontmatteringError):
+        return error.display(use_rich=use_rich)
+
+    # Format stdlib exceptions nicely too
+    error_type = error.__class__.__name__
+    message = str(error)
+
+    if use_rich:
+        return f"\033[1;31m✗ {error_type}\033[0m\n  {message}"
+    return f"✗ {error_type}\n  {message}"
+
+
+def print_error(error: Exception, use_rich: bool = True) -> None:
+    """Print formatted error to stderr.
+
+    Args:
+        error: Exception to print
+        use_rich: If True, include ANSI color codes
+    """
+    import sys
+
+    print(format_error(error, use_rich=use_rich), file=sys.stderr)
+
+
+# =============================================================================
+# BATCH ERROR HANDLING (Governance-compliant deferred raising)
+# =============================================================================
+
+
+class BatchProcessingError(FrontmatteringError):
+    """Multiple items failed during batch processing.
+
+    Per GOVERNANCE_RULES: batch operations should accumulate errors
+    and raise a summary at the end (still LOUD, not silent).
+
+    Usage:
+        collector = ErrorCollector("Processing items")
+        for i, item in enumerate(items):
+            try:
+                process(item)
+            except SpecificException as e:
+                collector.add(i, str(e))
+        collector.raise_if_errors()  # Raises BatchProcessingError if any
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        errors: list[tuple[int | str, str]],
+        where: str | None = None,
+    ) -> None:
+        self.operation = operation
+        self.errors = errors
+        self.error_count = len(errors)
+
+        # Show first 3 errors in summary
+        preview = errors[:3]
+        preview_str = "; ".join(f"[{idx}] {msg}" for idx, msg in preview)
+        if len(errors) > 3:
+            preview_str += f"; ... and {len(errors) - 3} more"
+
+        super().__init__(
+            what=f"{operation}: {len(errors)} item(s) failed",
+            where=where,
+            why=preview_str,
+            context={"total_errors": len(errors), "first_errors": preview},
+        )
+
+
+class ErrorCollector:
+    """Collect errors during batch processing for deferred raising.
+
+    Governance-compliant pattern: errors are accumulated but still LOUD
+    at the end of the batch.
+
+    Usage:
+        collector = ErrorCollector("Validating entities")
+        for entity in entities:
+            try:
+                validate(entity)
+            except ValidationError as e:
+                collector.add(entity.name, str(e))
+        collector.raise_if_errors()  # LOUD at the end
+    """
+
+    def __init__(self, operation: str, where: str | None = None) -> None:
+        self.operation = operation
+        self.where = where
+        self.errors: list[tuple[int | str, str]] = []
+
+    def add(self, item_id: int | str, message: str) -> None:
+        """Record an error for an item."""
+        self.errors.append((item_id, message))
+
+    def has_errors(self) -> bool:
+        """Check if any errors were collected."""
+        return len(self.errors) > 0
+
+    def raise_if_errors(self) -> None:
+        """Raise BatchProcessingError if any errors were collected.
+
+        This is the LOUD part - caller knows something failed.
+        """
+        if self.errors:
+            raise BatchProcessingError(
+                operation=self.operation,
+                errors=self.errors,
+                where=self.where,
+            )
+
+    def __len__(self) -> int:
+        return len(self.errors)
+
+
+# =============================================================================
+# PARSING ERRORS (markdown/, mdqt/)
+# =============================================================================
+
+
+class ParsingError(FrontmatteringError):
+    """Base error for parsing failures."""
+
+
+class YAMLReadError(ParsingError):
+    """YAML source file could not be read from disk.
+
+    Used by: yqt/
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        *,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        ctx = {"file_path": file_path}
+        if context:
+            ctx.update(context)
+        super().__init__(
+            what="Failed to read YAML source file",
+            where=where or "yqt.spec.extract_record_from_file",
+            why=why,
+            fix=fix or "Verify file permissions and file system accessibility.",
+            context=ctx,
+        )
+        self.file_path = file_path
+
+
+class FileReadError(ParsingError):
+    """Non-YAML file could not be read from disk.
+
+    Used by: yqt/ for JSON and markdown propagation checks.
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        *,
+        content_kind: str = "file",
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        ctx = {"file_path": file_path, "content_kind": content_kind}
+        if context:
+            ctx.update(context)
+        super().__init__(
+            what=f"Failed to read {content_kind} file",
+            where=where or "yqt.cli._run_propagation_checks",
+            why=why,
+            fix=fix or "Verify file path and read permissions.",
+            context=ctx,
+        )
+        self.file_path = file_path
+        self.content_kind = content_kind
+
+
+class DocumentTooLargeError(ParsingError):
+    """Document exceeds size limits.
+
+    Used by: markdown/, mdqt/
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        size_bytes: int,
+        max_bytes: int,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Document too large: {size_bytes:,} bytes",
+            where=where or "parser",
+            why=f"Exceeds limit of {max_bytes:,} bytes",
+            context={"file": file_path, "size": size_bytes, "max": max_bytes},
+        )
+        self.file_path = file_path
+        self.size_bytes = size_bytes
+        self.max_bytes = max_bytes
+
+
+class MalformedContentError(ParsingError):
+    """Content structure is invalid.
+
+    Used by: markdown/, mdqt/, schema/
+    """
+
+    def __init__(
+        self,
+        what: str,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        line: int | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        ctx = context or {}
+        if line is not None:
+            ctx["line"] = line
+        super().__init__(what=what, where=where, why=why, fix=fix, context=ctx)
+        self.line = line
+
+
+class CollectorTimeoutError(ParsingError, TimeoutError):
+    """Collector exceeded timeout during parsing.
+
+    Used by: markdown/utils/timeout.py
+
+    Inherits from TimeoutError for backward compatibility with existing
+    except TimeoutError handlers.
+    """
+
+    def __init__(
+        self,
+        collector_name: str | None = None,
+        timeout_seconds: float = 0.0,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Collector timeout after {timeout_seconds}s",
+            where=where or "markdown.collectors",
+            why=f"Collector '{collector_name or 'unknown'}' exceeded time limit",
+            fix="Simplify document structure or increase timeout limit",
+            context={"timeout": timeout_seconds, "collector": collector_name},
+        )
+        self.collector_name = collector_name
+        self.timeout_seconds = timeout_seconds
+
+
+class ReentrancyError(ParsingError):
+    """Reentrancy violation detected (nested call corrupts state).
+
+    Used by: markdown/utils/token_warehouse.py
+
+    This is a programming error - calling a non-reentrant method while
+    it's already executing will corrupt internal state.
+    """
+
+    def __init__(
+        self,
+        method: str,
+        where: str | None = None,
+        fix: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Reentrancy violation in {method}()",
+            where=where,
+            why=f"{method}() called while already executing - state corruption risk",
+            fix=fix or f"Check collectors for reentrant calls to {method}()",
+            context={"method": method},
+        )
+        self.method = method
+
+
+# =============================================================================
+# VALIDATION ERRORS (schema/, fdp/)
+# =============================================================================
+
+
+class ValidationError(FrontmatteringError, ValueError):
+    """Base error for validation failures."""
+
+
+class QueryNoMatchError(FrontmatteringError):
+    """A targeted query expected at least one row but matched none.
+
+    Used by: yqt/
+    """
+
+    def __init__(
+        self,
+        *,
+        query_label: str,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"{query_label} query matched zero rows for a targeted extraction",
+            where=where,
+            why=why or "The supplied selector combination resolved to no indexed rows.",
+            fix=fix
+            or "Verify the selector values and rerun the query against indexed files.",
+            context=context,
+        )
+
+
+class DependencyMissingError(ValidationError):
+    """Required (optional) dependency is not installed or cannot be imported.
+
+    Used by: qt_base/, rag/
+    """
+
+    def __init__(
+        self,
+        dependency: str,
+        *,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        ctx = {"dependency": dependency}
+        if context:
+            ctx.update(context)
+        super().__init__(
+            what=f"Dependency not available: {dependency}",
+            where=where,
+            why=why,
+            fix=fix or f"Install with: uv add {dependency}",
+            context=ctx,
+        )
+        self.dependency = dependency
+
+
+class SchemaValidationError(ValidationError):
+    """Schema validation failed.
+
+    Used by: schema/
+    """
+
+    def __init__(
+        self,
+        what: str,
+        field: str | None = None,
+        expected: str | None = None,
+        got: Any = None,
+        where: str | None = None,
+        fix: str | None = None,
+    ) -> None:
+        why_parts = []
+        if expected:
+            why_parts.append(f"expected {expected}")
+        if got is not None:
+            why_parts.append(f"got {_truncate(got, 50)}")
+        why = ", ".join(why_parts) if why_parts else None
+
+        ctx: dict[str, Any] = {}
+        if field:
+            ctx["field"] = field
+
+        super().__init__(what=what, where=where, why=why, fix=fix, context=ctx)
+        self.field = field
+        self.expected = expected
+        self.got = got
+
+
+class ComplianceError(ValidationError):
+    """FDP compliance check failed.
+
+    Used by: fdp/
+    """
+
+    def __init__(
+        self,
+        rule: str,
+        violation: str,
+        where: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Compliance violation: {rule}",
+            where=where,
+            why=violation,
+            context=context,
+        )
+        self.rule = rule
+        self.violation = violation
+
+
+class Q6CompileError(FrontmatteringError):
+    """Base error for q6 compiler failures with explicit blocker routing."""
+
+    def __init__(
+        self,
+        *,
+        blocker_code: str,
+        what: str,
+        where: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        merged_context = {"blocker_code": blocker_code}
+        if context:
+            merged_context.update(context)
+        super().__init__(
+            what=what,
+            where=where,
+            why=why,
+            fix=fix,
+            context=merged_context,
+        )
+        self.blocker_code = blocker_code
+
+
+class Q6IntakeContractError(Q6CompileError):
+    """Authored intake violates the q6 SSOT contract."""
+
+
+class Q6MdparseAcquisitionError(Q6CompileError):
+    """Compiler could not acquire structured intake data from mdparse."""
+
+
+class Q6MdparseContractError(Q6CompileError):
+    """mdparse returned a payload that violates compiler expectations."""
+
+
+class Q6TopologyError(Q6CompileError):
+    """Authoritative q6 topology cannot be resolved exactly."""
+
+
+class Q6CompilerAuthorityError(Q6CompileError):
+    """Compiler authority/provenance binding is missing or inconsistent."""
+
+
+class Q6EmissionError(Q6CompileError):
+    """Compiler could not safely emit the required q6 artifact."""
+
+
+class Q6InternalCompilerError(Q6CompileError):
+    """Unexpected internal compiler failure escaped typed q6 checks."""
+
+
+class ColumnNotFoundError(ValidationError):
+    """Requested column(s) not found in parquet schema.
+
+    Used by shared query layers.
+    """
+
+    def __init__(
+        self,
+        unknown_columns: list[str],
+        available_columns: list[str],
+        suggestions: dict[str, list[str]] | None = None,
+        where: str | None = None,
+        parquet_name: str = "parquet",
+    ) -> None:
+        # Build suggestion text
+        suggestion_lines = []
+        if suggestions:
+            for col, hints in suggestions.items():
+                if hints:
+                    suggestion_lines.append(f"'{col}' → did you mean: {', '.join(hints)}?")
+
+        super().__init__(
+            what=f"Unknown column(s): {', '.join(sorted(unknown_columns))}",
+            where=where,
+            why="\n".join(suggestion_lines) if suggestion_lines else None,
+            fix=f"Available columns in {parquet_name}: {', '.join(sorted(available_columns))}",
+            context={"unknown": unknown_columns, "available": available_columns},
+        )
+        self.unknown_columns = unknown_columns
+        self.available_columns = available_columns
+        self.suggestions = suggestions
+
+
+# =============================================================================
+# STORAGE ERRORS (state/, rag/, fact_archive/)
+# =============================================================================
+
+
+class StorageError(FrontmatteringError):
+    """Base error for storage operations."""
+
+
+class NotFoundError(StorageError):
+    """Requested item not found in storage.
+
+    Used by: state/, rag/, crossref/
+    """
+
+    def __init__(
+        self,
+        item_type: str,
+        item_id: str,
+        where: str | None = None,
+        fix: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"{item_type} not found",
+            where=where,
+            why=f"No {item_type} with id '{item_id}'",
+            fix=fix,
+            context={"type": item_type, "id": item_id},
+        )
+        self.item_type = item_type
+        self.item_id = item_id
+
+
+class AlreadyExistsError(StorageError):
+    """Item already exists in storage.
+
+    Used by: state/, rag/
+    """
+
+    def __init__(
+        self,
+        item_type: str,
+        item_id: str,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"{item_type} already exists",
+            where=where,
+            why=f"{item_type} with id '{item_id}' already present",
+            context={"type": item_type, "id": item_id},
+        )
+        self.item_type = item_type
+        self.item_id = item_id
+
+
+class LockTimeoutError(StorageError):
+    """Failed to acquire a parquet lock within the timeout window."""
+
+
+# =============================================================================
+# STALENESS ERRORS (crossref/, fdp/, mdqt/)
+# =============================================================================
+
+
+class StalenessError(FrontmatteringError):
+    """Base error for stale data detection."""
+
+
+class StaleFactsError(StalenessError):
+    """FACTS.parquet is stale relative to source code.
+
+    Used by: crossref/, fdp/, intelligence/
+
+    TODO(human): Implement staleness detection logic
+    """
+
+    def __init__(
+        self,
+        facts_file: str,
+        facts_mtime: str,
+        source_mtime: str,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what="FACTS.parquet is stale",
+            where=where,
+            why=f"Facts from {facts_mtime}, source modified {source_mtime}",
+            context={"facts_file": facts_file},
+        )
+        self.facts_file = facts_file
+        self.facts_mtime = facts_mtime
+        self.source_mtime = source_mtime
+
+
+class StaleDocumentError(StalenessError):
+    """MD.parquet is stale relative to markdown files.
+
+    Used by: mdqt/, crossref/
+    """
+
+    def __init__(
+        self,
+        md_file: str,
+        parquet_mtime: str,
+        source_mtime: str,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what="MD.parquet is stale",
+            where=where,
+            why=f"Parquet from {parquet_mtime}, source modified {source_mtime}",
+            context={"md_file": md_file},
+        )
+        self.md_file = md_file
+        self.parquet_mtime = parquet_mtime
+        self.source_mtime = source_mtime
+
+
+class StaleIndexError(StalenessError):
+    """RAG index is stale relative to source parquet.
+
+    Used by domain RAG implementations.
+
+    Raised when a FAISS index was built from a different parquet snapshot
+    than the current one. Fail-closed behavior to prevent stale RAG answers.
+    """
+
+    def __init__(
+        self,
+        index_path: str,
+        index_fingerprint: str,
+        current_fingerprint: str,
+        source_path: str | None = None,
+        where: str | None = None,
+    ) -> None:
+        fix_cmd = "Rebuild the RAG index from the current parquet source."
+        super().__init__(
+            what="RAG index is stale",
+            where=where,
+            why=f"Index fingerprint {index_fingerprint[:12]}... != current {current_fingerprint[:12]}...",
+            fix=fix_cmd,
+            context={
+                "index_path": index_path,
+                "index_fingerprint": index_fingerprint,
+                "current_fingerprint": current_fingerprint,
+                "source_path": source_path,
+            },
+        )
+        self.index_path = index_path
+        self.index_fingerprint = index_fingerprint
+        self.current_fingerprint = current_fingerprint
+        self.source_path = source_path
+
+
+# =============================================================================
+# PARQUET SAFETY ERRORS (qt_base/)
+# =============================================================================
+
+
+class UnsafeParquetAccessError(FrontmatteringError):
+    """Unsafe parquet read blocked (bypassed freshness/lock enforcement)."""
+
+    def __init__(
+        self,
+        api: str,
+        *,
+        caller_module: str | None = None,
+        caller_function: str | None = None,
+        where: str | None = None,
+    ) -> None:
+        ctx: dict[str, Any] = {"api": api}
+        if caller_module:
+            ctx["caller_module"] = caller_module
+        if caller_function:
+            ctx["caller_function"] = caller_function
+
+        super().__init__(
+            what="Unsafe direct parquet read blocked",
+            where=where,
+            why=f"{api} was called without passing through qt_base.index_guard",
+            fix="Use Frontmattering.qt_base.index_guard.ensure_index_fresh (or a guard-protected Query class) before reading parquet.",
+            context=ctx,
+        )
+        self.api = api
+        self.caller_module = caller_module
+        self.caller_function = caller_function
+
+
+# =============================================================================
+# ENTITY ERRORS (schema/, intelligence/)
+# =============================================================================
+
+
+class EntityError(FrontmatteringError):
+    """Base error for entity-related issues."""
+
+
+class EntityNotFoundError(EntityError):
+    """Referenced entity does not exist in codebase.
+
+    Used by: schema/, intelligence/, crossref/
+    """
+
+    def __init__(
+        self,
+        entity_type: str,
+        entity_name: str,
+        searched_in: str | None = None,
+        where: str | None = None,
+    ) -> None:
+        ctx: dict[str, Any] = {"type": entity_type, "name": entity_name}
+        if searched_in:
+            ctx["searched_in"] = searched_in
+
+        super().__init__(
+            what=f"{entity_type} '{entity_name}' not found",
+            where=where,
+            why=f"No matching {entity_type} in codebase",
+            context=ctx,
+        )
+        self.entity_type = entity_type
+        self.entity_name = entity_name
+        self.searched_in = searched_in
+
+
+class EntityAmbiguousError(EntityError):
+    """Entity reference matches multiple definitions.
+
+    Used by: schema/, crossref/
+    """
+
+    def __init__(
+        self,
+        entity_name: str,
+        matches: list[str],
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Ambiguous entity reference '{entity_name}'",
+            where=where,
+            why=f"Matches {len(matches)} definitions",
+            context={"matches": matches[:5]},  # Limit to 5
+        )
+        self.entity_name = entity_name
+        self.matches = matches
+
+
+# =============================================================================
+# EXTERNAL TOOL ERRORS (subprocess, FFQT, git)
+# =============================================================================
+
+
+class ExternalToolError(FrontmatteringError):
+    """Base error for external tool/subprocess failures.
+
+    Used by: intelligence/, schema/verifier, mdqt/staleness
+
+    Covers failures from:
+    - FFQT queries (subprocess calls to fact-file-query-tool)
+    - Git operations (subprocess calls to git)
+    - Other external CLI tools
+
+    Usage:
+        raise ExternalToolError(
+            tool="ffqt",
+            command="query --file validator.py --entity function.validate",
+            why="Process timed out after 30s",
+            fix="Increase FFQT_TIMEOUT or check if FACTS.parquet exists"
+        )
+    """
+
+    def __init__(
+        self,
+        tool: str,
+        command: str | None = None,
+        why: str | None = None,
+        fix: str | None = None,
+        where: str | None = None,
+        stdout: str | None = None,
+        stderr: str | None = None,
+        exit_code: int | None = None,
+    ) -> None:
+        self.tool = tool
+        self.command = command
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+        ctx: dict[str, Any] = {"tool": tool}
+        if command:
+            ctx["command"] = command[:200] + "..." if len(command) > 200 else command
+        if exit_code is not None:
+            ctx["exit_code"] = exit_code
+        if stderr:
+            ctx["stderr"] = stderr[:200] + "..." if len(stderr) > 200 else stderr
+
+        super().__init__(
+            what=f"External tool '{tool}' failed",
+            where=where,
+            why=why,
+            fix=fix or f"Verify '{tool}' is installed and accessible",
+            context=ctx,
+        )
+
+
+class ToolTimeoutError(ExternalToolError):
+    """External tool exceeded timeout.
+
+    Used by: schema/verifier
+    """
+
+    def __init__(
+        self,
+        tool: str,
+        timeout_seconds: float,
+        command: str | None = None,
+        where: str | None = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        super().__init__(
+            tool=tool,
+            command=command,
+            why=f"Process timed out after {timeout_seconds}s",
+            fix="Increase timeout or simplify the query",
+            where=where,
+        )
+
+
+class ToolResponseError(ExternalToolError):
+    """External tool returned invalid/unparseable response.
+
+    Used by: intelligence/, schema/verifier (JSON decode failures)
+    """
+
+    def __init__(
+        self,
+        tool: str,
+        expected_format: str = "JSON",
+        parse_error: str | None = None,
+        command: str | None = None,
+        where: str | None = None,
+        stdout: str | None = None,
+    ) -> None:
+        self.expected_format = expected_format
+        self.parse_error = parse_error
+        super().__init__(
+            tool=tool,
+            command=command,
+            why=f"Expected {expected_format}, got unparseable response: {parse_error}",
+            fix=f"Check '{tool}' output format or regenerate FACTS.parquet",
+            where=where,
+            stdout=stdout,
+        )
+
+
+# =============================================================================
+# MODULE ERRORS (Python protocol compliance)
+# =============================================================================
+
+
+class ModuleAttributeError(FrontmatteringError, AttributeError):
+    """Module attribute not found.
+
+    Used by: __init__.py __getattr__ for lazy loading
+
+    Inherits from AttributeError for Python protocol compliance
+    (hasattr, getattr expect AttributeError for missing attributes).
+    """
+
+    def __init__(
+        self,
+        module: str,
+        attribute: str,
+        where: str | None = None,
+    ) -> None:
+        super().__init__(
+            what=f"Module '{module}' has no attribute '{attribute}'",
+            where=where or f"{module}.__getattr__",
+            why="Attribute not found in module exports",
+            fix=f"Check available exports with: dir({module})",
+            context={"module": module, "attribute": attribute},
+        )
+        self.module = module
+        self.attribute = attribute