omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/shared/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Shared Module.
+
+Provides shared utilities and components used across infrastructure services.
+"""
+
+__all__: list[str] = []

omnibase_infra/testing/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Testing utilities for omnibase_infra.
+
+This module provides shared testing utilities for the infrastructure layer,
+including CI environment detection and other common test helpers.
+"""
+
+from omnibase_infra.testing.utils import is_ci_environment
+
+__all__ = ["is_ci_environment"]

omnibase_infra/testing/utils.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared testing utilities for omnibase_infra.
+
+This module provides utility functions commonly needed across test files,
+such as environment detection and test configuration helpers.
+"""
+
+import os
+
+
+def is_ci_environment() -> bool:
+    """Detect if running in CI environment.
+
+    Checks common CI environment variables:
+    - CI: Generic CI flag used by most CI systems
+    - GITHUB_ACTIONS: GitHub Actions specific
+
+    Returns:
+        True if running in a CI environment, False otherwise.
+    """
+    ci_value = os.getenv("CI", "").lower()
+    github_actions = os.getenv("GITHUB_ACTIONS", "").lower()
+    return ci_value in ("true", "1", "yes") or github_actions in ("true", "1", "yes")

omnibase_infra/types/__init__.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Types module for omnibase_infra.
+
+This module re-exports commonly used types for external consumption.
+Types are organized into categories:
+
+Top-level exports (this module):
+    - ModelParsedDSN: Pydantic model for parsed DSN components
+    - TypeCacheInfo: NamedTuple for cache hit/miss statistics
+    - TypedDictCapabilities: TypedDict for node capability introspection
+
+Type aliases (from type_infra_aliases):
+    - ASTFunctionDef: ast.AsyncFunctionDef | ast.FunctionDef
+    - MessageOutputCategory: EnumMessageCategory | EnumNodeOutputType
+    - PathInput: Path | str (named to avoid collision with stdlib os.PathLike)
+    - PolicyTypeInput: EnumPolicyType | str
+
+Note on cache-related TypedDicts:
+    TypedDictIntrospectionCache and TypedDictPerformanceMetricsCache are NOT
+    re-exported here because they are internal implementation details of the
+    MixinNodeIntrospection mixin. These types are tightly coupled to the mixin's
+    caching implementation and should not be used directly by external consumers.
+    If needed for testing or advanced use cases, import from the typed_dict submodule:
+        from omnibase_infra.types.typed_dict import TypedDictIntrospectionCache
+"""
+
+from omnibase_infra.types.type_cache_info import TypeCacheInfo
+from omnibase_infra.types.type_dsn import ModelParsedDSN
+from omnibase_infra.types.type_infra_aliases import (
+    ASTFunctionDef,
+    MessageOutputCategory,
+    PathInput,
+    PolicyTypeInput,
+)
+from omnibase_infra.types.typed_dict_capabilities import TypedDictCapabilities
+
+__all__: list[str] = [
+    # Type aliases
+    "ASTFunctionDef",
+    "MessageOutputCategory",
+    "PathInput",
+    "PolicyTypeInput",
+    # Models and TypedDicts
+    "ModelParsedDSN",
+    "TypeCacheInfo",
+    "TypedDictCapabilities",
+]

omnibase_infra/types/type_cache_info.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2025 OmniNode Team
+
+"""Cache information type for topic parser caching statistics.
+
+This module provides a type-safe NamedTuple for representing cache statistics,
+mirroring the structure of functools._CacheInfo for compatibility with LRU
+cache implementations.
+
+Example:
+    >>> from omnibase_infra.types import TypeCacheInfo
+    >>> info = TypeCacheInfo(hits=100, misses=10, maxsize=128, currsize=50)
+    >>> print(f"Hit rate: {info.hits / (info.hits + info.misses):.2%}")
+    Hit rate: 90.91%
+"""
+
+from typing import NamedTuple
+
+__all__ = ["TypeCacheInfo"]
+
+
+class TypeCacheInfo(NamedTuple):
+    """Cache statistics for topic parsing operations.
+
+    This mirrors functools._CacheInfo structure for type safety when
+    exposing cache statistics from LRU-cached parsing functions.
+
+    Attributes:
+        hits: Number of cache hits (requests served from cache).
+        misses: Number of cache misses (requests requiring computation).
+        maxsize: Maximum cache size, or None for unlimited cache.
+        currsize: Current number of entries in the cache.
+
+    Example:
+        >>> info = TypeCacheInfo(hits=50, misses=5, maxsize=128, currsize=30)
+        >>> info.hits
+        50
+        >>> info.maxsize
+        128
+
+    Note:
+        This type is intentionally compatible with functools._CacheInfo
+        to allow seamless interoperability with standard library caching.
+    """
+
+    hits: int
+    misses: int
+    maxsize: int | None
+    currsize: int

omnibase_infra/types/type_dsn.py

@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2025 OmniNode Team
+
+"""Strongly-typed DSN parse result model.
+
+This module provides a Pydantic model for representing parsed PostgreSQL
+Data Source Name (DSN) connection strings with full type safety and
+validation.
+
+The model replaces loose dict[str, object] return types with a structured,
+immutable, and validated representation of DSN components.
+
+Example:
+    >>> from omnibase_infra.types import ModelParsedDSN
+    >>> dsn = ModelParsedDSN(
+    ...     scheme="postgresql",
+    ...     username="admin",
+    ...     password="secret",
+    ...     hostname="localhost",
+    ...     port=5432,
+    ...     database="mydb",
+    ... )
+    >>> dsn.hostname
+    'localhost'
+    >>> dsn.port
+    5432
+
+Note:
+    The model is frozen (immutable) to ensure DSN components cannot be
+    accidentally modified after parsing. This provides safety when passing
+    DSN information through multiple layers of the application.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["ModelParsedDSN"]
+
+
+class ModelParsedDSN(BaseModel):
+    """Strongly-typed DSN parse result for PostgreSQL connection strings.
+
+    This model provides a structured representation of parsed DSN components
+    with validation for port ranges and scheme restrictions. The model is
+    immutable (frozen) to prevent accidental modification of connection
+    parameters.
+
+    Attributes:
+        scheme: The database scheme/protocol. Must be 'postgresql' or 'postgres'.
+        username: The database username for authentication. None if not specified.
+        password: The database password for authentication. None if not specified.
+            Note: Handle with care as this contains sensitive credentials.
+        hostname: The database server hostname or IP address. None if not specified.
+        port: The database server port number (1-65535). None if not specified.
+        database: The name of the database to connect to.
+        query: Additional connection parameters as key-value pairs. Values may be
+            strings or lists of strings for multi-value parameters.
+
+    Example:
+        >>> dsn = ModelParsedDSN(
+        ...     scheme="postgresql",
+        ...     username="app_user",
+        ...     hostname="db.example.com",
+        ...     port=5432,
+        ...     database="production",
+        ...     query={"sslmode": "require"},
+        ... )
+        >>> dsn.scheme
+        'postgresql'
+        >>> dsn.query
+        {'sslmode': 'require'}
+
+    Note:
+        The password field should be handled carefully in logging and
+        error messages to avoid credential exposure. Use the sanitization
+        utilities from util_dsn_validation for safe string representations.
+    """
+
+    scheme: Literal["postgresql", "postgres"] = Field(
+        description="Database scheme/protocol. Must be 'postgresql' or 'postgres'."
+    )
+    username: str | None = Field(
+        default=None,
+        description="Database username for authentication.",
+    )
+    password: str | None = Field(
+        default=None,
+        description="Database password for authentication. Handle with care.",
+    )
+    hostname: str | None = Field(
+        default=None,
+        description="Database server hostname or IP address.",
+    )
+    port: int | None = Field(
+        default=None,
+        ge=1,
+        le=65535,
+        description="Database server port number (valid range: 1-65535).",
+    )
+    database: str = Field(
+        description="Name of the database to connect to.",
+    )
+    query: dict[str, str | list[str]] = Field(
+        default_factory=dict,
+        description="Additional connection parameters as key-value pairs.",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    def __repr__(self) -> str:
+        """Return string representation with masked password.
+
+        This method overrides the default Pydantic __repr__ to prevent
+        credential exposure in logs, debug output, and error messages.
+        The actual password value remains accessible via the .password
+        attribute for legitimate use cases.
+
+        Returns:
+            String representation with password shown as '[REDACTED]' if set,
+            or None if not set.
+
+        Example:
+            >>> dsn = ModelParsedDSN(
+            ...     scheme="postgresql",
+            ...     username="admin",
+            ...     password="secret123",
+            ...     hostname="localhost",
+            ...     port=5432,
+            ...     database="mydb",
+            ... )
+            >>> repr(dsn)  # Shows '[REDACTED]' instead of 'secret123'
+            "ModelParsedDSN(scheme='postgresql', username='admin', ...)"
+        """
+        password_display = "[REDACTED]" if self.password else None
+        return (
+            f"ModelParsedDSN(scheme={self.scheme!r}, username={self.username!r}, "
+            f"password={password_display!r}, hostname={self.hostname!r}, "
+            f"port={self.port!r}, database={self.database!r}, query={self.query!r})"
+        )
+
+    def __str__(self) -> str:
+        """Return string representation with masked password.
+
+        Delegates to __repr__ to ensure consistent password masking across
+        all string conversion contexts (str(), print(), f-strings, etc.).
+
+        Returns:
+            String representation with password masked.
+        """
+        return self.__repr__()
+
+    def to_sanitized_dict(self) -> dict[str, object]:
+        """Return a dict representation with the password masked.
+
+        Useful for logging and debugging without exposing credentials.
+
+        Returns:
+            dict[str, object]: Model data with password replaced by '[REDACTED]' if set.
+
+        Example:
+            >>> dsn = ModelParsedDSN(
+            ...     scheme="postgresql", username="user", password="secret",
+            ...     hostname="localhost", port=5432, database="mydb"
+            ... )
+            >>> dsn.to_sanitized_dict()
+            {'scheme': 'postgresql', 'username': 'user', 'password': '[REDACTED]',
+             'hostname': 'localhost', 'port': 5432, 'database': 'mydb', 'query': {}}
+        """
+        data = self.model_dump()
+        if data.get("password"):
+            data["password"] = "[REDACTED]"
+        return data

omnibase_infra/types/type_infra_aliases.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Infrastructure-specific type aliases for union complexity reduction.
+
+These type aliases consolidate repeated union patterns found in omnibase_infra,
+following the same pattern as omnibase_core.types.type_json.
+
+When to use each alias:
+    MessageOutputCategory: Use for message routing, dispatcher selection,
+        and node output validation. Accepts both EnumMessageCategory (EVENT,
+        COMMAND, INTENT) and EnumNodeOutputType (includes PROJECTION).
+
+    PathInput: Use for function parameters that accept filesystem paths.
+        Allows callers to pass either Path objects or string paths.
+
+    PolicyTypeInput: Use for policy configuration APIs that need flexibility
+        between enum values and string representations.
+
+    ASTFunctionDef: Use when analyzing Python AST for function definitions,
+        covering both sync and async functions.
+
+See OMN-1358 for the union reduction initiative that drove these definitions.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from omnibase_infra.enums import EnumMessageCategory, EnumNodeOutputType, EnumPolicyType
+
+# Message category or node output type (for routing and validation)
+# Replaces 24 occurrences of: EnumMessageCategory | EnumNodeOutputType
+type MessageOutputCategory = EnumMessageCategory | EnumNodeOutputType
+
+# Filesystem path input flexibility
+# Replaces 11 occurrences of: Path | str
+# Note: Named PathInput (not PathLike) to avoid collision with stdlib os.PathLike Protocol.
+# PathInput represents filesystem path flexibility (Path | str), whereas os.PathLike is
+# a Protocol for objects implementing __fspath__().
+type PathInput = Path | str
+
+# Policy type with string fallback for API flexibility
+# Replaces 8 occurrences of: EnumPolicyType | str
+# NOTE: This is an INPUT type alias for API flexibility. Pydantic validators
+# using validate_policy_type_value() COERCE strings to EnumPolicyType, so
+# the actual stored value is always an enum, ensuring type-safe field access.
+type PolicyTypeInput = EnumPolicyType | str
+
+# AST function definition node types
+# Replaces 7 occurrences of: ast.AsyncFunctionDef | ast.FunctionDef
+type ASTFunctionDef = ast.AsyncFunctionDef | ast.FunctionDef
+
+__all__ = [
+    "ASTFunctionDef",
+    "MessageOutputCategory",
+    "PathInput",
+    "PolicyTypeInput",
+]

omnibase_infra/types/typed_dict/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definitions for omnibase_infra.
+
+This package contains TypedDict definitions that represent JSON-serialized
+forms of Pydantic models, enabling proper type checking for cache operations
+and JSON serialization/deserialization without requiring type: ignore comments.
+
+Available TypedDicts:
+    - TypedDictIntrospectionCache: JSON-serialized ModelNodeIntrospectionEvent
+    - TypedDictPerformanceMetricsCache: JSON-serialized introspection performance metrics
+"""
+
+from omnibase_infra.types.typed_dict.typed_dict_introspection_cache import (
+    TypedDictIntrospectionCache,
+)
+from omnibase_infra.types.typed_dict.typed_dict_performance_metrics_cache import (
+    TypedDictPerformanceMetricsCache,
+)
+
+__all__ = ["TypedDictIntrospectionCache", "TypedDictPerformanceMetricsCache"]

omnibase_infra/types/typed_dict/typed_dict_introspection_cache.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definition for JSON-serialized introspection cache data.
+
+This module provides a TypedDict that represents the JSON-serialized form of
+ModelNodeIntrospectionEvent, enabling proper type checking for cache operations
+without requiring type: ignore comments.
+
+The TypedDictIntrospectionCache matches the output of
+ModelNodeIntrospectionEvent.model_dump(mode="json"), providing a typed interface
+for working with cached introspection data.
+
+Key Features:
+    - Full type annotations for all introspection event fields
+    - Proper handling of serialized datetime (ISO string format)
+    - Proper handling of serialized UUID (string format)
+    - Integration with TypedDictCapabilities for nested capabilities structure
+    - Integration with TypedDictPerformanceMetricsCache for performance metrics
+
+Usage:
+    This TypedDict is primarily used for:
+    - Typing cache storage for introspection data
+    - Type-safe JSON deserialization of introspection events
+    - Avoiding type: ignore comments in cache operations
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictIntrospectionCache
+
+    # Cache storage with proper typing
+    cache: TypedDictIntrospectionCache | None = None
+
+    def store_introspection(event: ModelNodeIntrospectionEvent) -> None:
+        global cache
+        # model_dump(mode="json") returns data matching TypedDictIntrospectionCache
+        cache = event.model_dump(mode="json")
+
+    def get_cached_node_id() -> str | None:
+        if cache is not None:
+            return cache["node_id"]  # Type-safe access
+        return None
+    ```
+
+See Also:
+    - TypedDictCapabilities: Nested structure for capability information
+    - TypedDictPerformanceMetricsCache: Nested structure for performance metrics
+    - ModelNodeIntrospectionEvent: Source Pydantic model for introspection events
+    - MixinNodeIntrospection: Primary consumer of this TypedDict
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from omnibase_infra.types.typed_dict.typed_dict_performance_metrics_cache import (
+    TypedDictPerformanceMetricsCache,
+)
+from omnibase_infra.types.typed_dict_capabilities import TypedDictCapabilities
+
+__all__ = ["TypedDictIntrospectionCache"]
+
+
+class TypedDictIntrospectionCache(TypedDict):
+    """TypedDict representing the JSON-serialized ModelNodeIntrospectionEvent.
+
+    This type matches the output of ModelNodeIntrospectionEvent.model_dump(mode="json"),
+    enabling proper type checking for cache operations without requiring type: ignore
+    comments.
+
+    The TypedDict provides a typed interface for working with introspection cache data,
+    ensuring type safety when accessing fields from cached introspection events.
+
+    Attributes:
+        node_id: Unique identifier for the node (UUID serialized to string).
+        node_type: The type classification of the node (e.g., "EFFECT", "COMPUTE").
+        capabilities: Nested structure containing node capabilities information.
+            Uses TypedDictCapabilities which includes operations, protocols,
+            has_fsm flag, and method_signatures.
+        endpoints: Dictionary mapping endpoint names to their URLs.
+            Common keys include "health", "api", and "metrics".
+        current_state: Current FSM state if applicable, None otherwise.
+            Represents the node's finite state machine state.
+        version: Semantic version string of the node.
+        reason: The reason for the introspection event (e.g., "startup", "shutdown",
+            "heartbeat", "request").
+        correlation_id: Optional correlation ID for request tracing.
+            UUID serializes to string in JSON mode, may be None.
+        timestamp: ISO 8601 formatted datetime string indicating when the
+            introspection event was created.
+        performance_metrics: Optional performance metrics from the introspection
+            operation. Contains timing information for capability discovery,
+            endpoint gathering, and state retrieval. May be None if metrics
+            were not captured.
+
+    Note:
+        The capabilities field uses TypedDictCapabilities for type safety.
+        When serialized to JSON, the structure is:
+        - operations (list[str]): Discovered operation method names
+        - protocols (list[str]): Implemented protocol names
+        - has_fsm (bool): Whether the node has FSM capabilities
+        - method_signatures (dict[str, str]): Method name to signature mapping
+
+    Example:
+        ```python
+        # Type-safe cache access
+        cache: TypedDictIntrospectionCache = event.model_dump(mode="json")
+
+        # All field access is type-checked
+        node_id: str = cache["node_id"]
+        capabilities: TypedDictCapabilities = cache["capabilities"]
+        operations: list[str] = capabilities["operations"]
+
+        # Nullable fields properly typed
+        state: str | None = cache["current_state"]
+        metrics: TypedDictPerformanceMetricsCache | None = cache["performance_metrics"]
+        ```
+    """
+
+    node_id: str
+    node_type: str
+    capabilities: TypedDictCapabilities
+    endpoints: dict[str, str]
+    current_state: str | None
+    version: str
+    reason: str
+    correlation_id: str | None  # UUID serializes to string in JSON mode
+    timestamp: str  # datetime serializes to ISO string in JSON mode
+    performance_metrics: TypedDictPerformanceMetricsCache | None

omnibase_infra/types/typed_dict/typed_dict_performance_metrics_cache.py

@@ -0,0 +1,140 @@
+# Copyright 2025 OmniNode Team. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""TypedDict for JSON-serialized performance metrics cache.
+
+This module provides a TypedDict that matches the JSON output of
+ModelIntrospectionPerformanceMetrics.model_dump(mode="json"), enabling
+proper type checking for cached performance metrics without runtime
+validation overhead.
+
+The TypedDict is used for:
+- Type-safe cache operations for performance metrics
+- Avoiding type: ignore comments when working with serialized metrics
+- Static type checking of JSON-structured performance data
+- Documentation of the expected cache entry shape
+
+Related Models:
+    - ModelIntrospectionPerformanceMetrics: The Pydantic source model
+    - MixinNodeIntrospection: Uses this for caching introspection metrics
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictPerformanceMetricsCache
+
+    def get_cached_metrics() -> TypedDictPerformanceMetricsCache | None:
+        cache_entry = cache.get("metrics")
+        if cache_entry is not None:
+            # Type checker knows the shape without runtime validation
+            return cache_entry
+        return None
+
+    metrics = get_cached_metrics()
+    if metrics:
+        print(f"Total time: {metrics['total_introspection_ms']}ms")
+        if metrics.get('threshold_exceeded'):
+            print(f"Slow ops: {metrics.get('slow_operations', [])}")
+    ```
+
+Note:
+    This TypedDict uses `total=True` (default) because the source Pydantic
+    model `ModelIntrospectionPerformanceMetrics` has defaults for all fields,
+    ensuring that `model_dump(mode="json")` always produces complete JSON
+    with all fields present. Type checkers will require all fields when
+    constructing dict literals, which matches the actual runtime behavior.
+"""
+
+from typing import TypedDict
+
+
+class TypedDictPerformanceMetricsCache(TypedDict):
+    """TypedDict for JSON-serialized ModelIntrospectionPerformanceMetrics.
+
+    This type matches the output of ModelIntrospectionPerformanceMetrics.model_dump(mode="json"),
+    enabling proper type checking for cached performance metrics.
+
+    All fields are required (total=True, the default) because the source Pydantic
+    model has defaults for all fields, ensuring model_dump() always produces
+    complete JSON output with all fields present.
+
+    Attributes:
+        get_capabilities_ms: Time taken by get_capabilities() in milliseconds.
+            Threshold: <50ms for acceptable performance.
+        discover_capabilities_ms: Time taken by _discover_capabilities() in milliseconds.
+            Threshold: <30ms for acceptable performance.
+        get_endpoints_ms: Time taken by get_endpoints() in milliseconds.
+            This operation is typically fast (<1ms) as it returns static data.
+        get_current_state_ms: Time taken by get_current_state() in milliseconds.
+            This operation is typically fast (<1ms) for simple state retrieval.
+        total_introspection_ms: Total time for get_introspection_data() in milliseconds.
+            Threshold: <50ms for acceptable performance.
+        cache_hit: Whether the result was served from cache.
+            Cache hits should complete in <1ms.
+        method_count: Number of methods discovered during reflection.
+            Higher counts may correlate with longer discover_capabilities_ms times.
+        threshold_exceeded: Whether any operation exceeded performance thresholds.
+            True indicates potential performance degradation.
+        slow_operations: List of operation names that exceeded their thresholds.
+            Possible values: 'get_capabilities', 'discover_capabilities',
+            'total_introspection', 'cache_hit'.
+        captured_at: UTC timestamp when metrics were captured (ISO 8601 string).
+            Datetime serializes to ISO string format in JSON mode.
+
+    Example:
+        ```python
+        from omnibase_infra.types.typed_dict import TypedDictPerformanceMetricsCache
+
+        # Type-safe cache dictionary
+        cache: dict[str, TypedDictPerformanceMetricsCache] = {}
+
+        # Store metrics
+        cache["node-123"] = {
+            "get_capabilities_ms": 12.5,
+            "discover_capabilities_ms": 8.2,
+            "get_endpoints_ms": 0.5,
+            "get_current_state_ms": 0.1,
+            "total_introspection_ms": 21.3,
+            "cache_hit": False,
+            "method_count": 15,
+            "threshold_exceeded": False,
+            "slow_operations": [],
+            "captured_at": "2025-01-15T10:30:00Z",
+        }
+
+        # Retrieve with full type safety
+        if entry := cache.get("node-123"):
+            total_ms = entry.get("total_introspection_ms", 0.0)
+            if entry.get("threshold_exceeded"):
+                slow_ops = entry.get("slow_operations", [])
+                print(f"Performance degradation: {slow_ops}")
+        ```
+
+    Performance Thresholds:
+        The following thresholds are defined as module-level constants in:
+        src/omnibase_infra/mixins/mixin_node_introspection.py
+
+        Constants (SOURCE OF TRUTH - update this docstring if values change):
+        - PERF_THRESHOLD_GET_CAPABILITIES_MS: 50.0ms
+        - PERF_THRESHOLD_DISCOVER_CAPABILITIES_MS: 30.0ms
+        - PERF_THRESHOLD_GET_INTROSPECTION_DATA_MS: 50.0ms
+        - PERF_THRESHOLD_CACHE_HIT_MS: 1.0ms
+
+        Summary:
+        - get_capabilities: <50ms
+        - discover_capabilities: <30ms
+        - total_introspection: <50ms
+        - cache_hit: <1ms
+    """
+
+    get_capabilities_ms: float
+    discover_capabilities_ms: float
+    get_endpoints_ms: float
+    get_current_state_ms: float
+    total_introspection_ms: float
+    cache_hit: bool
+    method_count: int
+    threshold_exceeded: bool
+    slow_operations: list[str]
+    captured_at: str  # datetime serializes to ISO string in JSON mode
+
+
+__all__ = ["TypedDictPerformanceMetricsCache"]