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

omnibase_infra/models/projection/__init__.py

@@ -8,12 +8,15 @@ by orchestrators to query current entity state.
 
 Exports:
     ModelCapabilityFields: Container for capability fields in projection persistence
+    ModelContractProjection: Contract projection for Registry API queries
     ModelRegistrationProjection: Registration projection for orchestrator state queries
     ModelRegistrationSnapshot: Compacted snapshot for read optimization
     ModelSequenceInfo: Sequence information for projection ordering and idempotency
     ModelSnapshotTopicConfig: Kafka topic configuration for snapshot publishing
+    ModelTopicProjection: Topic projection for Registry API queries
 
 Related Tickets:
+    - OMN-1845: Create ProjectionReaderContract for contract/topic queries
     - OMN-1134: Registry Projection Extensions for Capabilities
     - OMN-947 (F2): Snapshot Publishing
     - OMN-944 (F1): Implement Registration Projection Schema
@@ -23,6 +26,9 @@ Related Tickets:
 from omnibase_infra.models.projection.model_capability_fields import (
     ModelCapabilityFields,
 )
+from omnibase_infra.models.projection.model_contract_projection import (
+    ModelContractProjection,
+)
 from omnibase_infra.models.projection.model_registration_projection import (
     ModelRegistrationProjection,
 )
@@ -33,11 +39,16 @@ from omnibase_infra.models.projection.model_sequence_info import ModelSequenceIn
 from omnibase_infra.models.projection.model_snapshot_topic_config import (
     ModelSnapshotTopicConfig,
 )
+from omnibase_infra.models.projection.model_topic_projection import (
+    ModelTopicProjection,
+)
 
 __all__ = [
     "ModelCapabilityFields",
+    "ModelContractProjection",
     "ModelRegistrationProjection",
     "ModelRegistrationSnapshot",
     "ModelSequenceInfo",
     "ModelSnapshotTopicConfig",
+    "ModelTopicProjection",
 ]

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/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",