xp-libs-analytics 0.4.0__py3-none-any.whl

xp_libs_analytics/parser/__init__.py

@@ -0,0 +1,142 @@
+"""Restricted YAML boundary; no global PyYAML resolver mutation."""
+
+import math
+import re
+from typing import Any
+
+import yaml
+from yaml import events, nodes
+
+from xp_libs_analytics.errors import AnalyticsError
+from xp_libs_analytics.policy import Limits
+
+
+def fault(code: str, mark: Any) -> AnalyticsError:
+    return AnalyticsError(code, line=mark.line + 1, column=mark.column + 1)
+
+
+class RestrictedLoader(yaml.SafeLoader):
+    yaml_implicit_resolvers: dict[str, list[tuple[str, re.Pattern[str]]]] = {}
+
+
+for tag, pattern, initial in [
+    ("bool", r"^(?:true|false)$", "tf"),
+    ("null", r"^null$", "n"),
+    ("int", r"^-?(?:0|[1-9][0-9]*)$", "-0123456789"),
+    (
+        "float",
+        r"^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+(?:[eE][+-]?[0-9]+)?|[eE][+-]?[0-9]+)$",
+        "-0123456789",
+    ),
+]:
+    RestrictedLoader.add_implicit_resolver("tag:yaml.org,2002:" + tag, re.compile(pattern), initial)
+
+
+DEFAULT_LIMITS = Limits()
+
+
+def parse_yaml(
+    text: str,
+    limits: Limits = DEFAULT_LIMITS,
+    *,
+    source_marks: dict[str, tuple[int, int]] | None = None,
+) -> dict[str, Any]:
+    if not isinstance(text, str):
+        raise AnalyticsError("QUERY_MALFORMED")
+    try:
+        encoded = text.encode("utf-8", "strict")
+    except UnicodeError:
+        raise AnalyticsError("QUERY_YAML_SCALAR_INVALID") from None
+    if len(encoded) > limits.max_query_bytes:
+        raise AnalyticsError("QUERY_YAML_COMPLEXITY_LIMIT")
+    depth = docs = count = 0
+    widths: list[int] = []
+    try:
+        for event in yaml.parse(text, Loader=RestrictedLoader):
+            count += 1
+            if count > limits.max_yaml_nodes:
+                raise fault("QUERY_YAML_COMPLEXITY_LIMIT", event.start_mark)
+            if isinstance(event, events.DocumentStartEvent):
+                docs += 1
+                if docs > 1:
+                    raise fault("QUERY_YAML_MULTI_DOCUMENT", event.start_mark)
+                if event.tags or event.version:
+                    raise fault("QUERY_YAML_TAG_FORBIDDEN", event.start_mark)
+            if isinstance(event, events.AliasEvent):
+                raise fault("QUERY_YAML_ALIAS_FORBIDDEN", event.start_mark)
+            if getattr(event, "anchor", None):
+                raise fault("QUERY_YAML_ANCHOR_FORBIDDEN", event.start_mark)
+            if getattr(event, "tag", None):
+                raise fault("QUERY_YAML_TAG_FORBIDDEN", event.start_mark)
+            if isinstance(event, (events.ScalarEvent, events.CollectionStartEvent)) and widths:
+                widths[-1] += 1
+                if widths[-1] > limits.max_collection_items:
+                    raise fault("QUERY_YAML_COMPLEXITY_LIMIT", event.start_mark)
+            if isinstance(event, events.CollectionStartEvent):
+                depth += 1
+                widths.append(0)
+                if depth > limits.max_yaml_depth:
+                    raise fault("QUERY_YAML_COMPLEXITY_LIMIT", event.start_mark)
+            elif isinstance(event, events.CollectionEndEvent):
+                depth -= 1
+                widths.pop()
+            elif isinstance(event, events.ScalarEvent):
+                if len(event.value) > limits.max_scalar_chars:
+                    raise fault("QUERY_YAML_COMPLEXITY_LIMIT", event.start_mark)
+                if any(
+                    ord(c) < 32 and c not in "\n\r\t" or 0xD800 <= ord(c) <= 0xDFFF
+                    for c in event.value
+                ):
+                    raise fault("QUERY_YAML_SCALAR_INVALID", event.start_mark)
+        loader = RestrictedLoader(text)
+        marks: dict[str, tuple[int, int]] = {}
+        try:
+            root = loader.get_single_node()
+
+            def convert(node: Any, path: str) -> Any:
+                if node is not None:
+                    marks[path] = (node.start_mark.line + 1, node.start_mark.column + 1)
+                if isinstance(node, nodes.MappingNode):
+                    result = {}
+                    for key, value in node.value:
+                        k = convert(key, path)
+                        if not isinstance(k, str):
+                            raise fault("QUERY_YAML_ROOT_INVALID", key.start_mark)
+                        if k == "<<":
+                            raise fault("QUERY_YAML_ALIAS_FORBIDDEN", key.start_mark)
+                        if k in result:
+                            raise fault("QUERY_YAML_DUPLICATE_KEY", key.start_mark)
+                        result[k] = convert(value, path + "." + k)
+                    return result
+                if isinstance(node, nodes.SequenceNode):
+                    return [convert(v, path + f"[{i}]") for i, v in enumerate(node.value)]
+                if isinstance(node, nodes.ScalarNode):
+                    value = loader.construct_object(node)
+                    if isinstance(value, float) and not math.isfinite(value):
+                        raise fault("QUERY_YAML_SCALAR_INVALID", node.start_mark)
+                    if (
+                        isinstance(value, int)
+                        and not isinstance(value, bool)
+                        and not -(2**63) <= value < 2**63
+                    ):
+                        raise fault("QUERY_YAML_SCALAR_INVALID", node.start_mark)
+                    if node.style is None and re.match(
+                        r"^(?:[+-]?\.(?:nan|inf)|[+-]?0[xob][0-9a-f]+|0[0-9]+)$", node.value, re.I
+                    ):
+                        raise fault("QUERY_YAML_SCALAR_INVALID", node.start_mark)
+                    return value
+                raise AnalyticsError("QUERY_YAML_ROOT_INVALID")
+
+            result = convert(root, "$")
+        finally:
+            loader.dispose()
+        if not isinstance(result, dict) or not result:
+            raise AnalyticsError("QUERY_YAML_ROOT_INVALID")
+        if source_marks is not None:
+            source_marks.update(marks)
+        return result
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        if mark:
+            raise fault("QUERY_YAML_INVALID", mark) from None
+        raise AnalyticsError("QUERY_YAML_INVALID") from None

xp_libs_analytics/policy/__init__.py

@@ -0,0 +1,69 @@
+"""Host-owned policy. Request documents cannot override these limits."""
+
+import threading
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Limits:
+    max_bytes: int = 8 * 1024 * 1024
+    max_rows: int = 100_000
+    max_columns: int = 256
+    max_depth: int = 12
+    max_record_bytes: int = 128 * 1024
+    max_datasets: int = 8
+    max_total_bytes: int = 64 * 1024 * 1024
+    ttl_seconds: int = 900
+    max_result_bytes: int = 1024 * 1024
+    max_groups: int = 10_000
+    max_windows: int = 10_000
+    max_expanded_rows: int = 1_200_000
+    max_distinct: int = 10_000
+    max_query_bytes: int = 65_536
+    max_yaml_depth: int = 16
+    max_yaml_nodes: int = 4096
+    max_scalar_chars: int = 1024
+    max_collection_items: int = 1024
+    max_concurrency: int = 2
+    max_queries_per_minute: int = 120
+    timeout_seconds: float = 15.0
+    memory_bytes: int = 1024 * 1024 * 1024
+    min_samples: int = 1
+    allow_null_cast: bool = True
+    max_match_fields: int = 10
+    max_match_patterns: int = 10
+    max_match_work: int = 40
+    max_match_literal_chars: int = 1024
+    max_regex_bytes: int = 512
+    max_match_value_chars: int = 1024
+    max_fuzzy_candidates: int = 10_000
+    max_match_normalized_bytes: int = 8 * 1024 * 1024
+    max_fuzzy_comparisons: int = 100_000
+    min_fuzzy_query_chars: int = 3
+    min_fuzzy_score: float = 70.0
+    max_match_diagnostic_values: int = 20
+    max_match_diagnostic_candidates: int = 10_000
+    allow_match_raw_values: bool = False
+    allow_match_catch_all: bool = False
+    match_pushdown: bool = True
+    force_matching_isolation: bool = True
+
+
+@dataclass(frozen=True)
+class Principal:
+    id: str = "local"
+    fields: frozenset[str] | None = None
+    scopes: frozenset[str] = frozenset({"read", "upload", "release"})
+
+    match_raw_fields: frozenset[str] = frozenset()
+
+    def permits(self, field: str) -> bool:
+        return self.fields is None or field in self.fields
+
+
+class RequestBudget:
+    def __init__(self, limits: Limits) -> None:
+        self.slots = threading.BoundedSemaphore(limits.max_concurrency)
+        self.calls: deque[float] = deque()
+        self.lock = threading.Lock()

xp_libs_analytics/registry.py

@@ -0,0 +1,204 @@
+"""Context-local logical sources, atomic publication and pinned immutable snapshots."""
+
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal, Protocol
+
+from xp_libs_analytics.errors import AnalyticsError
+from xp_libs_analytics.ingest import DatasetHandle, DatasetStore, Snapshot
+from xp_libs_analytics.policy import Principal
+
+
+class SnapshotSource(Protocol):
+    """Trusted source binding; execution consumes snapshots, never DataFrames or user code."""
+
+    @property
+    def handle(self) -> DatasetHandle: ...
+
+    @property
+    def expires(self) -> datetime: ...
+
+    @property
+    def mode(self) -> Literal["snapshot"]: ...
+
+
+@dataclass(frozen=True)
+class RecordsSnapshotSource:
+    handle: DatasetHandle
+    expires: datetime
+    mode: Literal["snapshot"] = "snapshot"
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    """Public binding metadata; opaque IDs remain internal."""
+
+    name: str
+    revision: int
+
+
+def validate_name(name: str) -> None:
+    if type(name) is not str or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,63}", name):
+        raise AnalyticsError("DATASET_NAME_INVALID")
+
+
+class _Namespace:
+    def __init__(self, owner: str) -> None:
+        self.bindings: dict[str, SnapshotSource] = {}
+        self.lock = threading.RLock()
+        self.closed = False
+        self.owner = owner
+        self.generation = 0
+
+
+class DatasetRegistry:
+    """A bounded namespace owned by one execution context, never a global name table."""
+
+    def __init__(
+        self,
+        store: DatasetStore,
+        principal: Callable[[], Principal],
+        clock: Callable[[], datetime],
+        *,
+        namespace: _Namespace | None = None,
+    ) -> None:
+        self._store, self._principal, self._clock = store, principal, clock
+        self._namespace = namespace or _Namespace(principal().id)
+        self._bindings = self._namespace.bindings
+        self._lock = self._namespace.lock
+
+    def _check(self, scope: str) -> Principal:
+        principal = self._principal()
+        if (
+            self._namespace.closed
+            or scope not in principal.scopes
+            or principal.id != self._namespace.owner
+        ):
+            raise AnalyticsError("ACCESS_DENIED")
+        return principal
+
+    def _source(self, name: str, revision: int | None = None) -> SnapshotSource:
+        validate_name(name)
+        source = self._bindings.get(name)
+        if source is None:
+            # A foreign context's name is indistinguishable from an unknown name.
+            raise AnalyticsError("DATASET_NAME_UNKNOWN")
+        if revision is not None and (
+            type(revision) is not int or revision != source.handle.revision
+        ):
+            raise AnalyticsError("DATASET_SNAPSHOT_STALE")
+        return source
+
+    def _publish(
+        self,
+        name: str,
+        records: Any,
+        *,
+        replace: bool,
+        ndjson: bool,
+        expected_revision: int | None = None,
+    ) -> DatasetInfo:
+        validate_name(name)
+        with self._lock:
+            principal = self._check("upload")
+            old = self._source(name, expected_revision) if replace else None
+            if not replace and name in self._bindings:
+                raise AnalyticsError("DATASET_NAME_DUPLICATE")
+            if not replace and len(self._bindings) >= self._store.limits.max_datasets:
+                raise AnalyticsError("RESOURCE_DATASETS_LIMIT")
+            now = self._clock()
+            revision = self._namespace.generation + 1
+            handle = self._store.register(
+                records,
+                principal,
+                now,
+                ndjson=ndjson,
+                replaces=old.handle if old else None,
+                revision=revision,
+            )
+            snapshot = self._store.get_snapshot(handle, principal, now)
+            self._namespace.generation = revision
+            self._bindings[name] = RecordsSnapshotSource(handle, snapshot.expires)
+            return DatasetInfo(name, revision)
+
+    def register_records(self, name: str, records: Any, *, ndjson: bool = False) -> DatasetInfo:
+        return self._publish(name, records, replace=False, ndjson=ndjson)
+
+    def replace_records(
+        self,
+        name: str,
+        records: Any,
+        *,
+        ndjson: bool = False,
+        expected_revision: int | None = None,
+    ) -> DatasetInfo:
+        return self._publish(
+            name, records, replace=True, ndjson=ndjson, expected_revision=expected_revision
+        )
+
+    @contextmanager
+    def snapshot(self, name: str, *, revision: int | None = None) -> Iterator[Snapshot]:
+        with self._lock:
+            principal = self._check("read")
+            source = self._source(name, revision)
+            now = self._clock()
+            if source.expires <= now:
+                raise AnalyticsError("DATASET_SNAPSHOT_STALE")
+            snapshot = self._store.acquire(source.handle, principal, now)
+        try:
+            yield snapshot
+        finally:
+            self._store.unpin(source.handle)
+
+    def names(self) -> list[str]:
+        with self._lock:
+            self._check("read")
+            return sorted(self._bindings)
+
+    def describe(self, name: str) -> dict[str, Any]:
+        with self.snapshot(name) as snapshot:
+            principal = self._check("read")
+            return {
+                "name": name,
+                "revision": snapshot.handle.revision,
+                "records": snapshot.row_count,
+                "source_kind": snapshot.source_kind,
+                "mode": "snapshot",
+                "expires": snapshot.expires.isoformat(),
+                "fields": {
+                    p: info for p, info in snapshot.schema().items() if principal.permits(p)
+                },
+            }
+
+    def list_datasets(self) -> list[dict[str, Any]]:
+        datasets = []
+        for name in self.names():
+            try:
+                datasets.append(self.describe(name))
+            except AnalyticsError as exc:
+                if exc.code not in {"DATASET_NAME_UNKNOWN", "DATASET_SNAPSHOT_STALE"}:
+                    raise
+        return datasets
+
+    def unregister_dataset(self, name: str, *, expected_revision: int | None = None) -> None:
+        with self._lock:
+            self._check("release")
+            source = self._source(name, expected_revision)
+            # Expired bindings can still be removed. No query can resolve them again.
+            with self._store._lock:
+                self._store._retire(source.handle.id)
+            del self._bindings[name]
+
+    def close(self) -> None:
+        with self._lock:
+            for source in self._bindings.values():
+                with self._store._lock:
+                    self._store._retire(source.handle.id)
+            self._bindings.clear()
+            self._namespace.closed = True

xp_libs_analytics/sdk/__init__.py

@@ -0,0 +1,259 @@
+"""Headless Python API; identity is supplied by the trusted application."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from time import monotonic
+from typing import Any
+from uuid import uuid4
+
+from xp_libs_analytics.engine.planner import LogicalPlan, plan_query
+from xp_libs_analytics.errors import CATALOG, AnalyticsError
+from xp_libs_analytics.ingest import DatasetStore, Snapshot, utc_now
+from xp_libs_analytics.models import AGG_OPS, FILTER_OPS, AnalyticsQuery, parse_query
+from xp_libs_analytics.policy import Limits, Principal
+from xp_libs_analytics.registry import DatasetInfo, DatasetRegistry
+
+
+class AnalyticsEngine:
+    def __init__(
+        self,
+        *,
+        limits: Limits | None = None,
+        principal: Principal | None = None,
+        store: DatasetStore | None = None,
+        clock: Callable[[], datetime] = utc_now,
+        isolated: bool = False,
+        telemetry: Callable[[dict[str, Any]], None] | None = None,
+    ) -> None:
+        self.limits = limits or Limits()
+        self.principal = principal or Principal()
+        self.store = store or DatasetStore(self.limits)
+        self.registry = DatasetRegistry(self.store, lambda: self.principal, lambda: self.clock())
+        self.clock = clock
+        self.isolated = isolated
+        self.telemetry = telemetry
+        request_budget = self.store.request_budget(self.principal)
+        self._slots = request_budget.slots
+        self._calls = request_budget.calls
+        self._quota_lock = request_budget.lock
+
+    def register_records(self, name: str, records: Any, *, ndjson: bool = False) -> DatasetInfo:
+        return self.registry.register_records(name, records, ndjson=ndjson)
+
+    def replace_records(
+        self,
+        name: str,
+        records: Any,
+        *,
+        ndjson: bool = False,
+        expected_revision: int | None = None,
+    ) -> DatasetInfo:
+        return self.registry.replace_records(
+            name, records, ndjson=ndjson, expected_revision=expected_revision
+        )
+
+    def describe(self, name: str) -> dict[str, Any]:
+        return self.registry.describe(name)
+
+    def list_datasets(self) -> list[dict[str, Any]]:
+        return self.registry.list_datasets()
+
+    def unregister_dataset(self, name: str, *, expected_revision: int | None = None) -> None:
+        self.registry.unregister_dataset(name, expected_revision=expected_revision)
+
+    def register_stream(self, name: str, source: Any) -> None:
+        """Reserved seam; V1 cannot admit or execute continuous sources."""
+        raise AnalyticsError("QUERY_UNSUPPORTED_FEATURE")
+
+    def create_context(self) -> AnalyticsEngine:
+        """Create an independent namespace with shared host resource/owner budgets."""
+        return AnalyticsEngine(
+            limits=self.limits,
+            principal=self.principal,
+            store=self.store,
+            clock=self.clock,
+            isolated=self.isolated,
+            telemetry=self.telemetry,
+        )
+
+    def _authorized_view(self, principal: Principal) -> AnalyticsEngine:
+        if principal.id != self.principal.id:
+            raise AnalyticsError("ACCESS_DENIED")
+        view = AnalyticsEngine(
+            limits=self.limits,
+            principal=principal,
+            store=self.store,
+            clock=self.clock,
+            isolated=self.isolated,
+            telemetry=self.telemetry,
+        )
+        view.registry = DatasetRegistry(
+            self.store,
+            lambda: view.principal,
+            lambda: view.clock(),
+            namespace=self.registry._namespace,
+        )
+        return view
+
+    def close(self) -> None:
+        self.registry.close()
+
+    def __enter__(self) -> AnalyticsEngine:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def capabilities(self) -> dict[str, Any]:
+        from dataclasses import asdict
+
+        return {
+            "version": "analytics.query/v1",
+            "authoring_format": "yaml",
+            "mode": "snapshot",
+            "filters": FILTER_OPS,
+            "matching": {
+                "algorithms": ["ratio", "wratio", "token_sort"],
+                "normalization": {
+                    "case_sensitive": True,
+                    "unicode": ["none", "nfc", "nfkc"],
+                    "trim": False,
+                },
+                "diagnostics": "options.matching_details",
+                "reference": "analytics://string-matching/v1",
+                "entity_inference": False,
+            },
+            "aggregations": AGG_OPS,
+            "limits": asdict(self.limits),
+            "schema": AnalyticsQuery.model_json_schema(),
+            "execution_isolated": self.isolated,
+        }
+
+    @contextmanager
+    def _prepare(self, text: str) -> Iterator[tuple[LogicalPlan, Snapshot, datetime]]:
+        query = parse_query(text, self.limits)
+        with self.registry.snapshot(query.dataset.name) as snapshot:
+            now = self.clock()
+            yield plan_query(query, snapshot, self.principal, self.limits, now), snapshot, now
+
+    def validate_query(self, query_yaml: str) -> dict[str, Any]:
+        return self.explain_query(query_yaml)
+
+    def explain_query(self, query_yaml: str) -> dict[str, Any]:
+        try:
+            self._take_quota()
+            with self._prepare(query_yaml) as (plan, snapshot, _):
+                return {
+                    "status": "OK",
+                    "plan": plan.explain(),
+                    "dataset": {
+                        "name": json.loads(plan.query_json)["dataset"]["name"],
+                        "revision": snapshot.handle.revision,
+                    },
+                }
+        except AnalyticsError as exc:
+            return exc.envelope()
+        except Exception:
+            return AnalyticsError("INTERNAL_ERROR").envelope()
+
+    def _take_quota(self) -> None:
+        with self._quota_lock:
+            now = monotonic()
+            while self._calls and self._calls[0] < now - 60:
+                self._calls.popleft()
+            if len(self._calls) >= self.limits.max_queries_per_minute:
+                raise AnalyticsError("QUERY_TOO_EXPENSIVE")
+            self._calls.append(now)
+
+    def query_yaml(self, query_yaml: str) -> dict[str, Any]:
+        query_id = uuid4().hex
+        started = monotonic()
+        event: dict[str, Any] = {
+            "query_id": query_id,
+            "event": "query",
+            "principal_hash": hashlib.sha256(self.principal.id.encode()).hexdigest(),
+            "outcome": "ERROR",
+        }
+        acquired = False
+        try:
+            self._take_quota()
+            acquired = self._slots.acquire(blocking=False)
+            if not acquired:
+                raise AnalyticsError("RESOURCE_CONCURRENCY_LIMIT")
+            with self._prepare(query_yaml) as (plan, snapshot, now):
+                event["plan_fingerprint"] = plan.fingerprint
+                event["snapshot_id"] = snapshot.handle.id
+                event["snapshot_revision"] = snapshot.handle.revision
+                if (
+                    self.isolated
+                    or self.limits.force_matching_isolation
+                    and json.loads(plan.matching_cost_json).get("requires_isolation")
+                ):
+                    from xp_libs_analytics.engine.worker import execute_isolated
+
+                    result = execute_isolated(plan, self.limits)
+                else:
+                    from xp_libs_analytics.engine.backend import execute_plan
+
+                    result = execute_plan(plan, self.limits)
+                result.update(
+                    version="analytics.result/v1",
+                    query_id=query_id,
+                    dataset={
+                        "name": json.loads(plan.query_json)["dataset"]["name"],
+                        "revision": snapshot.handle.revision,
+                    },
+                )
+                if result["status"] != "ERROR":
+                    result["evidence"].update(
+                        schema_revision=snapshot.handle.revision,
+                        source_kind=snapshot.source_kind,
+                        computed_at=now.isoformat().replace("+00:00", "Z"),
+                    )
+                if (
+                    len(json.dumps(result, allow_nan=False).encode("utf-8"))
+                    > self.limits.max_result_bytes
+                ):
+                    raise AnalyticsError("RESOURCE_RESULT_LIMIT")
+                event["outcome"] = result["status"]
+                if result["status"] == "ERROR":
+                    event["error_code"] = result["error"]["code"]
+                return result
+        except AnalyticsError as exc:
+            event["error_code"] = exc.code.value
+            return exc.envelope(query_id)
+        except Exception:
+            event["error_code"] = "EXECUTION_BACKEND_ERROR"
+            return AnalyticsError("EXECUTION_BACKEND_ERROR").envelope(query_id)
+        finally:
+            if acquired:
+                self._slots.release()
+            if self.telemetry is not None:
+                event["duration_seconds"] = monotonic() - started
+                try:
+                    self.telemetry(event)
+                except Exception:  # noqa: S110 -- do not log sensitive host hook exceptions
+                    # A host observability outage cannot alter analytical results.
+                    pass
+
+    def query_file(self, path: Path) -> dict[str, Any]:
+        if path.suffix.lower() not in (".yaml", ".yml"):
+            return AnalyticsError("QUERY_MALFORMED").envelope()
+        try:
+            with path.open("rb") as stream:
+                text = stream.read(self.limits.max_query_bytes + 1).decode("utf-8")
+            return self.query_yaml(text)
+        except (OSError, UnicodeError):
+            return AnalyticsError("QUERY_YAML_INVALID").envelope()
+
+    @staticmethod
+    def error_info(code: str) -> dict[str, Any]:
+        if code not in CATALOG:
+            return AnalyticsError("MCP_INVALID_TOOL_CALL").envelope()
+        return {"code": code, "message": CATALOG[code]}