omnibase_infra 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

omnibase_infra/models/projection/model_contract_projection.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Projection Model.
+
+Provides the Pydantic model for contract projections stored in PostgreSQL.
+Used by the Registry API to query registered contracts and their metadata.
+
+The contracts table stores registered ONEX contracts with full YAML content
+for replay capability and Kafka position tracking for exactly-once semantics.
+
+Related Tickets:
+    - OMN-1845: Create ProjectionReaderContract for contract/topic queries
+    - OMN-1653: Contract registry state materialization
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractProjection(BaseModel):
+    """Contract projection for Registry API queries.
+
+    Represents a registered ONEX contract stored in PostgreSQL. This model
+    maps to the contracts table created by migration 005.
+
+    Primary Key:
+        contract_id - derived natural key: node_name:major.minor.patch
+
+    Attributes:
+        contract_id: Derived natural key (e.g., "my-node:1.0.0")
+        node_name: ONEX node name from contract metadata
+        version_major: Semantic version major component
+        version_minor: Semantic version minor component
+        version_patch: Semantic version patch component
+        contract_hash: SHA-256 hash of contract YAML for change detection
+        contract_yaml: Full contract YAML content for replay capability
+        registered_at: Timestamp when contract was first registered
+        deregistered_at: Timestamp when contract was deregistered (None if active)
+        last_seen_at: Timestamp of most recent heartbeat or registration event
+        is_active: Whether contract is currently active (soft delete)
+        last_event_topic: Kafka topic of last processed event (for dedupe)
+        last_event_partition: Kafka partition of last processed event (for dedupe)
+        last_event_offset: Kafka offset of last processed event (for dedupe)
+        created_at: Timestamp when row was created
+        updated_at: Timestamp when row was last updated
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> now = datetime.now(UTC)
+        >>> projection = ModelContractProjection(
+        ...     contract_id="node-registry-effect:1.0.0",
+        ...     node_name="node-registry-effect",
+        ...     version_major=1,
+        ...     version_minor=0,
+        ...     version_patch=0,
+        ...     contract_hash="abc123...",
+        ...     contract_yaml="name: node-registry-effect\\n...",
+        ...     registered_at=now,
+        ...     last_seen_at=now,
+        ...     is_active=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Identity
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ...,
+        min_length=1,
+        description="Derived natural key: node_name:major.minor.patch",
+    )
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(
+        ...,
+        min_length=1,
+        description="ONEX node name from contract metadata",
+    )
+    version_major: int = Field(
+        ...,
+        ge=0,
+        description="Semantic version major component",
+    )
+    version_minor: int = Field(
+        ...,
+        ge=0,
+        description="Semantic version minor component",
+    )
+    version_patch: int = Field(
+        ...,
+        ge=0,
+        description="Semantic version patch component",
+    )
+
+    # Contract content
+    contract_hash: str = Field(
+        ...,
+        min_length=1,
+        description="SHA-256 hash of contract YAML for change detection",
+    )
+    contract_yaml: str = Field(
+        ...,
+        description="Full contract YAML content for replay capability",
+    )
+
+    # Lifecycle
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp when contract was first registered",
+    )
+    deregistered_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when contract was deregistered (None if active)",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp of most recent heartbeat or registration event",
+    )
+    is_active: bool = Field(
+        default=True,
+        description="Whether contract is currently active (soft delete)",
+    )
+
+    # Kafka position tracking (for exactly-once semantics)
+    last_event_topic: str | None = Field(
+        default=None,
+        description="Kafka topic of last processed event (for dedupe)",
+    )
+    last_event_partition: int | None = Field(
+        default=None,
+        description="Kafka partition of last processed event (for dedupe)",
+    )
+    last_event_offset: int | None = Field(
+        default=None,
+        description="Kafka offset of last processed event (for dedupe)",
+    )
+
+    # Audit timestamps
+    created_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when row was created",
+    )
+    updated_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when row was last updated",
+    )
+
+    @property
+    def version_string(self) -> str:
+        """Return semantic version as string.
+
+        Returns:
+            Semantic version string (e.g., "1.0.0")
+
+        Example:
+            >>> proj = ModelContractProjection(version_major=1, version_minor=2, version_patch=3, ...)
+            >>> proj.version_string
+            '1.2.3'
+        """
+        return f"{self.version_major}.{self.version_minor}.{self.version_patch}"
+
+
+__all__: list[str] = ["ModelContractProjection"]

omnibase_infra/models/projection/model_topic_projection.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Topic Projection Model.
+
+Provides the Pydantic model for topic projections stored in PostgreSQL.
+Used by the Registry API to query topic suffixes referenced by contracts
+for routing discovery.
+
+Topics use 5-segment naming (e.g., onex.evt.platform.contract-registered.v1)
+and store SUFFIXES only - environment prefix is applied at runtime.
+
+Related Tickets:
+    - OMN-1845: Create ProjectionReaderContract for contract/topic queries
+    - OMN-1653: Contract registry state materialization
+    - OMN-1709: Topic orphan handling documentation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Valid direction values for topic routing
+TopicDirection = Literal["publish", "subscribe"]
+
+
+class ModelTopicProjection(BaseModel):
+    """Topic projection for Registry API queries.
+
+    Represents a topic suffix referenced by contracts for routing discovery.
+    This model maps to the topics table created by migration 005.
+
+    Primary Key:
+        (topic_suffix, direction) - composite key allowing same topic with
+        both publish and subscribe directions
+
+    Topic Orphan Handling (OMN-1709):
+        When all contracts referencing a topic are deregistered, the topic
+        record remains with an empty contract_ids list. This is intentional:
+        - Preserves topic routing history for auditing and debugging
+        - Allows topic reactivation if a new contract references the same topic
+        - Avoids complex cascading deletes during high-volume deregistration
+
+    Attributes:
+        topic_suffix: Topic suffix without environment prefix
+        direction: Whether contracts publish to or subscribe from this topic
+        contract_ids: List of contract_id strings that reference this topic
+        first_seen_at: Timestamp when topic was first seen in any contract
+        last_seen_at: Timestamp when topic was last seen in any contract
+        is_active: Whether topic is currently referenced by any active contract
+        created_at: Timestamp when row was created
+        updated_at: Timestamp when row was last updated
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> now = datetime.now(UTC)
+        >>> projection = ModelTopicProjection(
+        ...     topic_suffix="onex.evt.platform.contract-registered.v1",
+        ...     direction="publish",
+        ...     contract_ids=["node-registry-effect:1.0.0"],
+        ...     first_seen_at=now,
+        ...     last_seen_at=now,
+        ...     is_active=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Identity (composite primary key)
+    topic_suffix: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Topic suffix without environment prefix, "
+            "e.g., onex.evt.platform.contract-registered.v1"
+        ),
+    )
+    direction: TopicDirection = Field(
+        ...,
+        description="Whether contracts publish to or subscribe from this topic",
+    )
+
+    # Contract references (JSONB array in database)
+    contract_ids: list[str] = Field(
+        default_factory=list,
+        description="List of contract_id strings that reference this topic",
+    )
+
+    # Lifecycle
+    first_seen_at: datetime = Field(
+        ...,
+        description="Timestamp when topic was first seen in any contract",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp when topic was last seen in any contract",
+    )
+    is_active: bool = Field(
+        default=True,
+        description="Whether topic is currently referenced by any active contract",
+    )
+
+    # Audit timestamps
+    created_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when row was created",
+    )
+    updated_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when row was last updated",
+    )
+
+    @property
+    def contract_count(self) -> int:
+        """Return number of contracts referencing this topic.
+
+        Returns:
+            Count of contract IDs
+
+        Example:
+            >>> proj = ModelTopicProjection(contract_ids=["a:1.0.0", "b:1.0.0"], ...)
+            >>> proj.contract_count
+            2
+        """
+        return len(self.contract_ids)
+
+    @property
+    def is_orphaned(self) -> bool:
+        """Check if topic is orphaned (no contracts reference it).
+
+        Returns:
+            True if contract_ids is empty and topic is inactive
+
+        Example:
+            >>> proj = ModelTopicProjection(contract_ids=[], is_active=False, ...)
+            >>> proj.is_orphaned
+            True
+        """
+        return len(self.contract_ids) == 0 and not self.is_active
+
+
+__all__: list[str] = ["ModelTopicProjection", "TopicDirection"]

omnibase_infra/models/runtime/__init__.py

@@ -26,6 +26,9 @@ from omnibase_infra.models.runtime.model_plugin_load_context import (
 from omnibase_infra.models.runtime.model_plugin_load_summary import (
     ModelPluginLoadSummary,
 )
+from omnibase_infra.models.runtime.model_resolved_dependencies import (
+    ModelResolvedDependencies,
+)
 
 # ModelContractLoadResult and ModelRuntimeContractConfig are exported from
 # omnibase_infra.runtime.models (canonical location for runtime loader models)
@@ -45,5 +48,6 @@ __all__ = [
     "ModelLoadedHandler",
     "ModelPluginLoadContext",
     "ModelPluginLoadSummary",
+    "ModelResolvedDependencies",
     "ModelRuntimeContractConfig",
 ]

omnibase_infra/models/runtime/model_resolved_dependencies.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for resolved protocol dependencies.
+
+This module provides ModelResolvedDependencies, a container for protocol
+instances resolved from the container service_registry at node creation time.
+
+Part of OMN-1732: Runtime dependency injection for zero-code nodes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelResolvedDependencies(BaseModel):
+    """Container for resolved protocol dependencies.
+
+    Holds protocol instances resolved from ModelONEXContainer.service_registry
+    for injection into node constructors. This model is immutable after creation.
+
+    The protocols dict maps protocol class names to their resolved instances:
+    - Key: Protocol class name (e.g., "ProtocolPostgresAdapter")
+    - Value: Resolved instance from container
+
+    Example:
+        >>> resolved = ModelResolvedDependencies(
+        ...     protocols={
+        ...         "ProtocolPostgresAdapter": postgres_adapter,
+        ...         "ProtocolCircuitBreakerAware": circuit_breaker,
+        ...     }
+        ... )
+        >>> adapter = resolved.get("ProtocolPostgresAdapter")
+
+    .. versionadded:: 0.x.x
+        Part of OMN-1732 runtime dependency injection.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,  # Required for protocol instances
+    )
+
+    # ONEX_EXCLUDE: any_type - dict[str, Any] required for heterogeneous protocol instances
+    # resolved from container.service_registry. Type varies by protocol (ProtocolPostgresAdapter,
+    # ProtocolCircuitBreakerAware, etc.). Cannot use Union as protocols are open-ended.
+    protocols: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Map of protocol class names to resolved instances",
+    )
+
+    # ONEX_EXCLUDE: any_type - returns heterogeneous protocol instance from protocols dict
+    def get(self, protocol_name: str) -> Any:
+        """Get a resolved protocol by name.
+
+        Args:
+            protocol_name: The protocol class name (e.g., "ProtocolPostgresAdapter")
+
+        Returns:
+            The resolved protocol instance.
+
+        Raises:
+            KeyError: If protocol_name is not in the resolved protocols.
+
+        Example:
+            >>> adapter = resolved.get("ProtocolPostgresAdapter")
+        """
+        if protocol_name not in self.protocols:
+            raise KeyError(
+                f"Protocol '{protocol_name}' not found in resolved dependencies. "
+                f"Available: {list(self.protocols.keys())}"
+            )
+        return self.protocols[protocol_name]
+
+    # ONEX_EXCLUDE: any_type - returns heterogeneous protocol instance, default can be any type
+    def get_optional(self, protocol_name: str, default: Any = None) -> Any:
+        """Get a resolved protocol by name, returning default if not found.
+
+        Args:
+            protocol_name: The protocol class name
+            default: Value to return if protocol not found
+
+        Returns:
+            The resolved protocol instance or default.
+        """
+        return self.protocols.get(protocol_name, default)
+
+    def has(self, protocol_name: str) -> bool:
+        """Check if a protocol is available.
+
+        Args:
+            protocol_name: The protocol class name
+
+        Returns:
+            True if protocol is resolved, False otherwise.
+        """
+        return protocol_name in self.protocols
+
+    def __len__(self) -> int:
+        """Return number of resolved protocols."""
+        return len(self.protocols)
+
+    def __bool__(self) -> bool:
+        """Return True if any protocols are resolved.
+
+        Warning:
+            **Non-standard __bool__ behavior**: Returns True only when
+            at least one protocol is resolved.
+        """
+        return len(self.protocols) > 0
+
+
+__all__ = ["ModelResolvedDependencies"]

omnibase_infra/nodes/contract_registry_reducer/__init__.py

@@ -9,9 +9,13 @@ the ONEX declarative pattern.
 Exports:
     NodeContractRegistryReducer: Declarative reducer node shell.
     ContractRegistryReducer: Pure function reducer class.
+    ContractRegistrationEventRouter: Event router for Kafka messages.
     ModelContractRegistryState: Immutable state model for the reducer.
 """
 
+from omnibase_infra.nodes.contract_registry_reducer.contract_registration_event_router import (
+    ContractRegistrationEventRouter,
+)
 from omnibase_infra.nodes.contract_registry_reducer.models import (
     ModelContractRegistryState,
 )
@@ -23,6 +27,7 @@ from omnibase_infra.nodes.contract_registry_reducer.reducer import (
 )
 
 __all__ = [
+    "ContractRegistrationEventRouter",
     "ContractRegistryReducer",
     "ModelContractRegistryState",
     "NodeContractRegistryReducer",

omnibase_infra/nodes/contract_registry_reducer/contract.yaml

@@ -38,19 +38,20 @@ description: |
   are separated.
 # Event Consumption Configuration
 # ================================
-# Topics follow 5-segment naming: {env}.onex.{category}.{domain}.{event-name}.v{version}
+# Topics are realm-agnostic: onex.{category}.{domain}.{event-name}.v{version}
 # Categories: evt (external events), int (internal events), cmd (commands)
+# Note: Environment/realm is enforced via envelope identity, not topic naming.
 consumed_events:
-  - topic: "{env}.onex.evt.platform.contract-registered.v1"
+  - topic: "onex.evt.platform.contract-registered.v1"
     event_type: "ModelContractRegisteredEvent"
     description: "Contract registration from nodes on startup"
-  - topic: "{env}.onex.evt.platform.contract-deregistered.v1"
+  - topic: "onex.evt.platform.contract-deregistered.v1"
     event_type: "ModelContractDeregisteredEvent"
     description: "Explicit contract deregistration on graceful shutdown"
-  - topic: "{env}.onex.evt.platform.node-heartbeat.v1"
+  - topic: "onex.evt.platform.node-heartbeat.v1"
     event_type: "ModelNodeHeartbeatEvent"
     description: "Heartbeat for liveness tracking and last_seen_at updates"
-  - topic: "{env}.onex.int.platform.runtime-tick.v1"
+  - topic: "onex.int.platform.runtime-tick.v1"
     event_type: "ModelRuntimeTick"
     internal: true
     description: "Periodic tick for staleness computation - marks contracts as stale/inactive"