omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/runtime/models/model_runtime_scheduler_metrics.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Runtime Scheduler Metrics Model.
+
+This module provides the Pydantic model for tracking runtime scheduler performance
+and operational metrics. Used for monitoring tick emission reliability, timing
+performance, and scheduler health.
+
+Metrics Categories:
+    - Tick Counts: Total ticks emitted and failed
+    - Timing Metrics: Duration tracking for individual ticks
+    - Sequence Tracking: For restart-safety and exactly-once semantics
+    - Circuit Breaker: Failure tolerance state
+    - Uptime: Scheduler operational duration
+
+Thread Safety:
+    This model is immutable (frozen=True) and safe to share across threads.
+    Create new instances for updated metrics using model_copy(update={...}).
+
+Example:
+    >>> from datetime import datetime, timezone
+    >>> # Use explicit timestamps for deterministic behavior
+    >>> last_tick = datetime(2025, 1, 15, 12, 0, 0, tzinfo=timezone.utc)
+    >>> metrics = ModelRuntimeSchedulerMetrics(
+    ...     scheduler_id="scheduler-001",
+    ...     ticks_emitted=100,
+    ...     last_tick_at=last_tick,
+    ... )
+    >>> print(metrics.tick_success_rate())
+    1.0
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.enums import EnumSchedulerStatus
+
+
+class ModelRuntimeSchedulerMetrics(BaseModel):
+    """Metrics for runtime scheduler operation.
+
+    Tracks tick emission performance, reliability, and operational state
+    of the ONEX runtime scheduler. These metrics are essential for
+    monitoring scheduler health and identifying performance issues.
+
+    Attributes:
+        scheduler_id: Unique identifier for this scheduler instance
+        status: Current operational status of the scheduler
+        ticks_emitted: Total number of ticks successfully emitted
+        ticks_failed: Total number of tick emissions that failed
+        last_tick_at: Timestamp of the most recent tick emission
+        last_tick_duration_ms: Duration of the most recent tick in milliseconds
+        average_tick_duration_ms: Rolling average tick duration in milliseconds
+        max_tick_duration_ms: Maximum tick duration observed in milliseconds
+        current_sequence_number: Current tick sequence number
+        last_persisted_sequence: Last sequence number persisted for restart-safety
+        circuit_breaker_open: Whether the circuit breaker is currently open
+        consecutive_failures: Number of consecutive tick failures
+        started_at: Timestamp when the scheduler started
+        total_uptime_seconds: Total scheduler uptime in seconds
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> metrics = ModelRuntimeSchedulerMetrics(
+        ...     scheduler_id="prod-scheduler-001",
+        ...     ticks_emitted=1000,
+        ...     ticks_failed=5,
+        ...     average_tick_duration_ms=0.5,
+        ... )
+        >>> metrics.tick_success_rate()
+        0.995...
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    # Scheduler identification
+    scheduler_id: str = Field(
+        ...,
+        description="Unique identifier for this scheduler instance",
+        min_length=1,
+    )
+
+    # Current status
+    status: EnumSchedulerStatus = Field(
+        default=EnumSchedulerStatus.STOPPED,
+        description="Current operational status of the scheduler",
+    )
+
+    # Tick counts
+    ticks_emitted: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of ticks successfully emitted",
+    )
+    ticks_failed: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of tick emissions that failed",
+    )
+
+    # Timing metrics (milliseconds)
+    last_tick_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of the most recent tick emission",
+    )
+    last_tick_duration_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Duration of the most recent tick in milliseconds",
+    )
+    average_tick_duration_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Rolling average tick duration in milliseconds",
+    )
+    max_tick_duration_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Maximum tick duration observed in milliseconds",
+    )
+
+    # Sequence tracking (for restart-safety)
+    current_sequence_number: int = Field(
+        default=0,
+        ge=0,
+        description="Current tick sequence number",
+    )
+    last_persisted_sequence: int = Field(
+        default=0,
+        ge=0,
+        description="Last sequence number persisted for restart-safety",
+    )
+
+    # Circuit breaker state
+    circuit_breaker_open: bool = Field(
+        default=False,
+        description="Whether the circuit breaker is currently open",
+    )
+    consecutive_failures: int = Field(
+        default=0,
+        ge=0,
+        description="Number of consecutive tick failures",
+    )
+
+    # Uptime tracking
+    started_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when the scheduler started",
+    )
+    total_uptime_seconds: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Total scheduler uptime in seconds",
+    )
+
+    def tick_success_rate(self) -> float:
+        """
+        Calculate the tick success rate.
+
+        Returns:
+            Success rate as a float between 0.0 and 1.0.
+            Returns 1.0 if no ticks have been attempted.
+
+        Example:
+            >>> metrics = ModelRuntimeSchedulerMetrics(
+            ...     scheduler_id="test",
+            ...     ticks_emitted=95,
+            ...     ticks_failed=5,
+            ... )
+            >>> metrics.tick_success_rate()
+            0.95
+        """
+        total = self.ticks_emitted + self.ticks_failed
+        if total == 0:
+            return 1.0
+        return self.ticks_emitted / total
+
+    def is_healthy(self) -> bool:
+        """
+        Check if the scheduler is in a healthy state.
+
+        A scheduler is considered healthy if:
+        - It is in RUNNING status
+        - The circuit breaker is closed
+        - Consecutive failures are below threshold (5)
+
+        Returns:
+            True if the scheduler is healthy, False otherwise
+
+        Example:
+            >>> metrics = ModelRuntimeSchedulerMetrics(
+            ...     scheduler_id="test",
+            ...     status=EnumSchedulerStatus.RUNNING,
+            ... )
+            >>> metrics.is_healthy()
+            True
+        """
+        return (
+            self.status == EnumSchedulerStatus.RUNNING
+            and not self.circuit_breaker_open
+            and self.consecutive_failures < 5
+        )
+
+    def unpersisted_sequence_count(self) -> int:
+        """
+        Calculate the number of sequences not yet persisted.
+
+        This is important for restart-safety to ensure no ticks are lost.
+
+        Returns:
+            Number of sequences that have been emitted but not persisted
+
+        Example:
+            >>> metrics = ModelRuntimeSchedulerMetrics(
+            ...     scheduler_id="test",
+            ...     current_sequence_number=100,
+            ...     last_persisted_sequence=95,
+            ... )
+            >>> metrics.unpersisted_sequence_count()
+            5
+        """
+        return self.current_sequence_number - self.last_persisted_sequence
+
+
+__all__: list[str] = ["ModelRuntimeSchedulerMetrics"]

omnibase_infra/runtime/models/model_runtime_tick.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Runtime Tick Event Model.
+
+This module defines the ModelRuntimeTick infrastructure event model, which is emitted
+by the runtime scheduler at configured intervals. This is an INFRASTRUCTURE concern,
+not a domain event.
+
+Infrastructure vs Domain Separation:
+    - RuntimeTick is emitted by the runtime scheduler (infrastructure concern)
+    - Orchestrators SUBSCRIBE to RuntimeTick and derive timeout decisions (domain concern)
+    - The `now` field is the single source of truth for current time across the system
+    - This field aligns with ModelOrchestratorContext.now and ModelEffectContext.now
+
+Specification Reference:
+    This model implements ticket B6 (Runtime Scheduler) from the ONEX Runtime Registration
+    Ticket Plan. See docs/design/ONEX_RUNTIME_REGISTRATION_TICKET_PLAN.md for full spec.
+
+Key Design Decisions:
+    - `now`: The authoritative wall-clock time for this tick. Orchestrators use this
+      for timeout calculations. Reducers MUST NOT use this field.
+    - `sequence_number`: Monotonically increasing counter per runtime instance.
+      Enables restart-safety and ordering guarantees within a single runtime.
+    - `tick_id`: Unique identifier for this specific tick emission. Used for
+      idempotency and distributed tracing.
+    - `scheduler_id`: Identifies which runtime scheduler instance emitted this tick.
+      Critical for multi-runtime deployments where each runtime emits its own ticks.
+
+Usage:
+    Runtime schedulers emit this event on a configurable cadence:
+    - Default: 1000ms (1 second)
+    - Min: 100ms (prevents excessive CPU usage)
+    - Max: 60000ms (ensures timely timeout detection)
+
+    Configuration via: ONEX_RUNTIME_TICK_INTERVAL_MS environment variable
+
+Example:
+    >>> from datetime import datetime, timezone
+    >>> from uuid import uuid4
+    >>> # Use explicit timestamps (time injection pattern) - not datetime.now()
+    >>> tick_time = datetime(2025, 1, 15, 12, 0, 0, tzinfo=timezone.utc)
+    >>> tick = ModelRuntimeTick(
+    ...     now=tick_time,
+    ...     tick_id=uuid4(),
+    ...     sequence_number=42,
+    ...     scheduled_at=tick_time,
+    ...     correlation_id=uuid4(),
+    ...     scheduler_id="runtime-instance-001",
+    ...     tick_interval_ms=1000,
+    ... )
+    >>> print(tick.sequence_number)
+    42
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelRuntimeTick(BaseModel):
+    """Infrastructure event emitted by runtime scheduler at configured intervals.
+
+    Orchestrators subscribe to this event and derive timeout decisions from it.
+    The `now` field is the single source of truth for current time across the system,
+    matching the time injection pattern used in ModelOrchestratorContext and
+    ModelEffectContext (see OMN-948).
+
+    This is an INFRASTRUCTURE event, not a domain event. The distinction is:
+    - Infrastructure: RuntimeTick emission (scheduler responsibility)
+    - Domain: Timeout decisions derived from ticks (orchestrator responsibility)
+
+    Attributes:
+        now: The authoritative wall-clock time for this tick. UTC, timezone-aware.
+             Orchestrators use this for deadline/timeout calculations.
+             Effects may use this for retry/metrics timing.
+             Reducers MUST ignore this field and never depend on it.
+        tick_id: Unique identifier for this tick emission. Used for idempotency
+                 guards and distributed tracing.
+        sequence_number: Monotonically increasing counter per runtime instance.
+                        Provides ordering guarantees and restart-safety detection.
+                        Resets to 0 on runtime restart.
+        scheduled_at: When this tick was scheduled to occur. May differ from `now`
+                     if there was processing delay or clock skew.
+        correlation_id: Correlation ID for distributed tracing. All downstream
+                       operations triggered by this tick share this ID.
+        scheduler_id: Identifies the runtime scheduler instance that emitted this tick.
+                     Critical for multi-runtime deployments to avoid tick duplication.
+        tick_interval_ms: The configured tick interval in milliseconds. Informational
+                         field indicating the scheduler's cadence configuration.
+
+    Thread Safety:
+        This model is frozen (immutable) for thread safety. Once created,
+        a RuntimeTick instance cannot be modified.
+
+    Restart Safety:
+        The sequence_number field enables detection of runtime restarts.
+        If sequence_number < expected, a restart has occurred. Orchestrators
+        should handle this gracefully by resetting their timeout calculations.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> from uuid import uuid4
+        >>> # Use explicit timestamps (time injection pattern) - not datetime.now()
+        >>> tick_time = datetime(2025, 1, 15, 12, 0, 0, tzinfo=timezone.utc)
+        >>> tick = ModelRuntimeTick(
+        ...     now=tick_time,
+        ...     tick_id=uuid4(),
+        ...     sequence_number=1,
+        ...     scheduled_at=tick_time,
+        ...     correlation_id=uuid4(),
+        ...     scheduler_id="runtime-001",
+        ...     tick_interval_ms=1000,
+        ... )
+        >>> assert tick.tick_interval_ms == 1000
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for thread safety
+        extra="forbid",  # Strict validation - no extra fields allowed
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    # Core time field - matches handler context injection pattern (OMN-948)
+    now: datetime = Field(
+        ...,
+        description=(
+            "The authoritative wall-clock time for this tick. UTC, timezone-aware. "
+            "Orchestrators use this for timeout calculations. Reducers MUST ignore."
+        ),
+    )
+
+    # Tick identification
+    tick_id: UUID = Field(
+        ...,
+        description=(
+            "Unique identifier for this specific tick emission. "
+            "Used for idempotency and distributed tracing."
+        ),
+    )
+
+    # Ordering and restart-safety
+    sequence_number: int = Field(
+        ...,
+        ge=0,
+        description=(
+            "Monotonically increasing counter per runtime instance. "
+            "Provides ordering guarantees and restart-safety detection. "
+            "Resets to 0 on runtime restart."
+        ),
+    )
+
+    # Scheduling metadata
+    scheduled_at: datetime = Field(
+        ...,
+        description=(
+            "When this tick was scheduled to occur. May differ from `now` "
+            "if there was processing delay or clock skew."
+        ),
+    )
+
+    # Tracing
+    correlation_id: UUID = Field(
+        ...,
+        description=(
+            "Correlation ID for distributed tracing. All downstream "
+            "operations triggered by this tick share this ID."
+        ),
+    )
+
+    # Scheduler identification
+    scheduler_id: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Identifies which runtime scheduler instance emitted this tick. "
+            "Critical for multi-runtime deployments."
+        ),
+    )
+
+    # Configuration metadata
+    tick_interval_ms: int = Field(
+        ...,
+        ge=100,
+        le=60000,
+        description=(
+            "Configured tick interval in milliseconds. "
+            "Valid range: 100ms (min) to 60000ms (max)."
+        ),
+    )
+
+
+__all__: list[str] = ["ModelRuntimeTick"]

omnibase_infra/runtime/models/model_secret_cache_stats.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for secret cache statistics.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-764.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelSecretCacheStats(BaseModel):
+    """Cache statistics for observability.
+
+    Provides metrics for monitoring cache performance and health.
+
+    Attributes:
+        total_entries: Current number of cached entries.
+        hits: Total number of cache hits.
+        misses: Total number of cache misses.
+        refreshes: Total number of cache refreshes (TTL expiration).
+        expired_evictions: Total number of entries evicted due to expiration.
+
+    Example:
+        >>> stats = ModelSecretCacheStats(hits=100, misses=10)
+        >>> stats.hit_rate
+        0.909090909090909
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    total_entries: int = Field(
+        default=0,
+        ge=0,
+        description="Current number of secrets in the cache.",
+    )
+    hits: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of cache hits.",
+    )
+    misses: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of cache misses.",
+    )
+    refreshes: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of cache refreshes due to TTL expiration.",
+    )
+    expired_evictions: int = Field(
+        default=0,
+        ge=0,
+        description="Total number of entries evicted due to expiration.",
+    )
+
+    @property
+    def hit_rate(self) -> float:
+        """Calculate cache hit rate.
+
+        Returns:
+            Hit rate as a float between 0.0 and 1.0.
+            Returns 0.0 if no hits or misses have occurred.
+
+        Example:
+            >>> stats = ModelSecretCacheStats(hits=80, misses=20)
+            >>> stats.hit_rate
+            0.8
+        """
+        total = self.hits + self.misses
+        return self.hits / total if total > 0 else 0.0
+
+
+__all__: list[str] = ["ModelSecretCacheStats"]

omnibase_infra/runtime/models/model_secret_mapping.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for secret mapping configuration.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-764.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_secret_source_spec import ModelSecretSourceSpec
+
+
+class ModelSecretMapping(BaseModel):
+    """Mapping from logical name to source specification.
+
+    Defines an explicit mapping between a logical secret name used in the
+    application and its concrete source location.
+
+    Attributes:
+        logical_name: Application-level secret identifier using dot notation.
+        source: Specification of where to retrieve the secret.
+        ttl_seconds: Optional TTL override for this specific secret.
+
+    Example:
+        >>> mapping = ModelSecretMapping(
+        ...     logical_name="database.postgres.password",
+        ...     source=ModelSecretSourceSpec(
+        ...         source_type="vault",
+        ...         source_path="secret/data/database/postgres#password",
+        ...     ),
+        ...     ttl_seconds=60,  # Refresh every minute
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    logical_name: str = Field(
+        ...,
+        min_length=1,
+        description="Logical name for the secret using dot notation "
+        "(e.g., 'database.postgres.password').",
+    )
+    source: ModelSecretSourceSpec = Field(
+        ...,
+        description="Source specification defining where to retrieve the secret.",
+    )
+    ttl_seconds: int | None = Field(
+        default=None,
+        ge=0,
+        description="Optional TTL override in seconds for this specific secret. "
+        "If None, uses the default TTL for the source type.",
+    )
+
+
+__all__: list[str] = ["ModelSecretMapping"]

omnibase_infra/runtime/models/model_secret_resolver_config.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for SecretResolver.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-764.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_secret_mapping import ModelSecretMapping
+
+
+class ModelSecretResolverConfig(BaseModel):
+    """Configuration for SecretResolver.
+
+    Configures the centralized secret resolution system that supports
+    multiple secret sources with priority-based resolution.
+
+    Source Priority Order:
+        1. Vault (if configured) - for production secrets
+        2. Environment variables - for local development
+        3. File-based secrets - for Kubernetes deployments
+
+    Attributes:
+        mappings: Explicit mappings from logical names to source specs.
+        default_ttl_env_seconds: Default TTL for environment variable secrets.
+        default_ttl_file_seconds: Default TTL for file-based secrets.
+        default_ttl_vault_seconds: Default TTL for Vault secrets.
+        enable_convention_fallback: Enable automatic source discovery by convention.
+        convention_env_prefix: Prefix for environment variable convention lookup.
+        bootstrap_secrets: Secrets resolved directly from env (never through chain).
+        secrets_dir: Directory for file-based secrets (K8s secrets volume).
+
+    Example:
+        >>> config = ModelSecretResolverConfig(
+        ...     default_ttl_vault_seconds=60,
+        ...     enable_convention_fallback=True,
+        ...     convention_env_prefix="ONEX_",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=False,  # Allow mutation for runtime configuration
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Explicit mappings: logical_name -> source_spec
+    mappings: list[ModelSecretMapping] = Field(
+        default_factory=list,
+        description="Explicit mappings from logical secret names to source specifications. "
+        "Takes precedence over convention-based resolution.",
+    )
+
+    # Default TTLs by source type (in seconds)
+    default_ttl_env_seconds: int = Field(
+        default=86400,
+        ge=0,
+        description="Default TTL for environment variable secrets (24 hours).",
+    )
+    default_ttl_file_seconds: int = Field(
+        default=86400,
+        ge=0,
+        description="Default TTL for file-based secrets (24 hours).",
+    )
+    default_ttl_vault_seconds: int = Field(
+        default=300,
+        ge=0,
+        description="Default TTL for Vault secrets (5 minutes).",
+    )
+
+    # Convention fallback when no explicit mapping exists
+    enable_convention_fallback: bool = Field(
+        default=True,
+        description="Enable automatic source discovery using naming conventions. "
+        "When True, 'database.postgres.password' becomes 'DATABASE_POSTGRES_PASSWORD'.",
+    )
+    convention_env_prefix: str = Field(
+        default="",
+        description="Prefix added to environment variable names during convention lookup. "
+        "E.g., 'ONEX_' makes 'database.password' look for 'ONEX_DATABASE_PASSWORD'.",
+    )
+
+    # Bootstrap secrets (always resolved from env, never through resolver chain)
+    bootstrap_secrets: list[str] = Field(
+        default_factory=lambda: ["vault.token", "vault.addr", "vault.ca_cert"],
+        description="Secrets that are always resolved directly from environment variables, "
+        "never through the resolver chain. Used for Vault bootstrap credentials.",
+    )
+
+    # File-based secrets directory (K8s secrets volume mount)
+    secrets_dir: Path = Field(
+        default=Path("/run/secrets"),
+        description="Directory containing file-based secrets (K8s secrets volume mount).",
+    )
+
+    # NOTE: Vault configuration will be added when ModelVaultHandlerConfig is available
+    # vault_config: ModelVaultHandlerConfig | None = None
+
+
+__all__: list[str] = ["ModelSecretResolverConfig"]