omnibase_infra 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

omnibase_infra/nodes/__init__.py

@@ -13,12 +13,15 @@ Available Submodules:
 - reducers: Reducer nodes for state aggregation
 - node_registration_reducer: Declarative FSM-driven registration reducer
 - node_registration_orchestrator: Registration workflow orchestrator
+- node_ledger_projection_compute: Event ledger projection compute node
 
 Available Classes:
 - NodeRegistrationReducer: Declarative FSM-driven reducer (ONEX pattern)
 - RegistrationReducer: Pure function reducer implementation
 - NodeRegistryEffect: Effect node for dual-backend registration execution
 - NodeRegistrationOrchestrator: Workflow orchestrator for registration
+- NodeLedgerProjectionCompute: Event ledger projection compute node
+- RegistryInfraLedgerProjection: Registry for ledger projection node
 """
 
 from omnibase_infra.nodes.effects import (
@@ -27,6 +30,10 @@ from omnibase_infra.nodes.effects import (
     ModelRegistryResponse,
     NodeRegistryEffect,
 )
+from omnibase_infra.nodes.node_ledger_projection_compute import (
+    NodeLedgerProjectionCompute,
+    RegistryInfraLedgerProjection,
+)
 from omnibase_infra.nodes.node_registration_orchestrator import (
     NodeRegistrationOrchestrator,
 )
@@ -40,9 +47,11 @@ __all__: list[str] = [
     "ModelBackendResult",
     "ModelRegistryRequest",
     "ModelRegistryResponse",
+    "NodeLedgerProjectionCompute",
     "NodeRegistrationOrchestrator",
     "NodeRegistrationReducer",
     "NodeRegistryEffect",
     "RegistrationReducer",
+    "RegistryInfraLedgerProjection",
     "RegistryInfraNodeRegistrationReducer",
 ]

omnibase_infra/nodes/contract_registry_reducer/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Registry Reducer Node.
+
+This module provides the declarative reducer node for projecting contract
+registration events to PostgreSQL. The reducer is FSM-driven and follows
+the ONEX declarative pattern.
+
+Exports:
+    NodeContractRegistryReducer: Declarative reducer node shell.
+    ContractRegistryReducer: Pure function reducer class.
+    ModelContractRegistryState: Immutable state model for the reducer.
+"""
+
+from omnibase_infra.nodes.contract_registry_reducer.models import (
+    ModelContractRegistryState,
+)
+from omnibase_infra.nodes.contract_registry_reducer.node import (
+    NodeContractRegistryReducer,
+)
+from omnibase_infra.nodes.contract_registry_reducer.reducer import (
+    ContractRegistryReducer,
+)
+
+__all__ = [
+    "ContractRegistryReducer",
+    "ModelContractRegistryState",
+    "NodeContractRegistryReducer",
+]

omnibase_infra/nodes/contract_registry_reducer/contract.yaml

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# ONEX Node Contract - Contract Registry Reducer Node
+#
+# This reducer follows the pure function pattern for contract registry workflows:
+#   reduce(state, event) -> ModelReducerOutput[state + intents]
+#
+# The FSM defines state transitions for the contract registry lifecycle:
+#   ready -> processing -> ready (simple cycle for event processing)
+#
+# All state transition logic is driven by this contract.
+# =============================================================================
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "1.0.0"
+name: "contract_registry_reducer"
+node_type: "REDUCER_GENERIC"
+# Enum Usage (CLAUDE.md reference):
+#   - node_type uses EnumNodeOutputType.REDUCER for validation
+#   - Reducer outputs are PROJECTION type (state + intents) via EnumNodeOutputType
+#   - Incoming messages are routed via EnumMessageCategory (EVENT/COMMAND)
+#   - PROJECTION exists only in EnumNodeOutputType and is only valid for REDUCER nodes
+#   - See: docs/decisions/adr-enum-message-category-vs-node-output-type.md
+description: |
+  Reducer node that consumes contract registration events from Kafka
+  and materializes them to Postgres for discovery and observability.
+
+  This reducer tracks:
+  - Contract registrations from nodes on startup
+  - Contract deregistrations for graceful shutdown
+  - Node heartbeats for liveness tracking and last_seen_at updates
+  - Runtime ticks for staleness computation (marking stale contracts inactive)
+
+  The reducer emits intents for PostgreSQL writes via the Effect layer,
+  following the pure reducer pattern where state changes and side effects
+  are separated.
+# Event Consumption Configuration
+# ================================
+# Topics follow 5-segment naming: {env}.onex.{category}.{domain}.{event-name}.v{version}
+# Categories: evt (external events), int (internal events), cmd (commands)
+consumed_events:
+  - topic: "{env}.onex.evt.platform.contract-registered.v1"
+    event_type: "ModelContractRegisteredEvent"
+    description: "Contract registration from nodes on startup"
+  - topic: "{env}.onex.evt.platform.contract-deregistered.v1"
+    event_type: "ModelContractDeregisteredEvent"
+    description: "Explicit contract deregistration on graceful shutdown"
+  - topic: "{env}.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"
+    event_type: "ModelRuntimeTick"
+    internal: true
+    description: "Periodic tick for staleness computation - marks contracts as stale/inactive"
+# Input/Output Model Configuration
+# =================================
+input_model:
+  name: "ModelReducerInput"
+  module: "omnibase_core.models.reducer.model_reducer_input"
+  description: "Reducer input containing contract event and trigger."
+output_model:
+  name: "ModelReducerOutput"
+  module: "omnibase_core.models.reducer.model_reducer_output"
+  description: "Reducer output containing new state and PostgreSQL intents."
+# FSM State Machine Definition
+# ============================
+# The contract registry reducer uses a simple FSM for event processing.
+# Unlike the registration reducer which tracks a multi-step workflow,
+# this reducer processes individual events and returns to ready state.
+#
+# State Diagram:
+#   +-------+   event received   +------------+
+#   | ready | -----------------> | processing |
+#   +-------+                    +------------+
+#      ^                              |
+#      |        event processed       |
+#      +------------------------------+
+#
+state_machine:
+  state_machine_name: "contract_registry_fsm"
+  initial_state: "ready"
+  states:
+    - state_name: "ready"
+      description: "Ready to process contract events"
+      entry_actions: []
+      exit_actions: []
+      required_data: []
+    - state_name: "processing"
+      description: "Currently processing a contract event"
+      entry_actions: []
+      exit_actions: []
+      required_data:
+        - "event_id"
+        - "correlation_id"
+  transitions:
+    # ready -> processing: On any contract event
+    - from_state: "ready"
+      to_state: "processing"
+      trigger: "contract_event_received"
+      description: "Start processing contract registration event"
+      conditions:
+        - expression: "event_id is_present"
+          required: true
+      actions:
+        - action_name: "process_contract_event"
+          action_type: "intent_emission"
+    # processing -> ready: After event processed
+    - from_state: "processing"
+      to_state: "ready"
+      trigger: "event_processed"
+      description: "Return to ready state after processing"
+      actions: []
+  persistence_enabled: true
+  terminal_states: []
+# Intent Emission Configuration
+# ============================
+# The reducer emits intents for Effect layer execution.
+# These intents are NOT executed by the reducer - they are returned
+# in the ModelReducerOutput for the Runtime to publish.
+intent_emission:
+  enabled: true
+  # Intent Type Clarification:
+  # These intent_type values (e.g., "postgres.upsert_contract") are PAYLOAD intent types,
+  # stored in `payload.intent_type` on typed payload models like ModelPayloadUpsertContract.
+  # The outer ModelIntent.intent_type is always "extension" for extension-based intents.
+  # Effect layer routing uses payload.intent_type to dispatch to the correct handler.
+  # See: CLAUDE.md "Intent Model Architecture" for the two-layer intent pattern.
+  intents:
+    - intent_type: "postgres.upsert_contract"
+      target_pattern: "postgres://contracts/{contract_id}"
+      payload_model: "ModelPayloadUpsertContract"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_upsert_contract"
+      description: "Upsert contract record in PostgreSQL"
+    - intent_type: "postgres.update_topic"
+      target_pattern: "postgres://topics/{topic_suffix}"
+      payload_model: "ModelPayloadUpdateTopic"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_update_topic"
+      description: "Update topic record in PostgreSQL"
+    - intent_type: "postgres.mark_stale"
+      target_pattern: "postgres://contracts/stale"
+      payload_model: "ModelPayloadMarkStale"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_mark_stale"
+      description: "Mark stale contracts as inactive"
+    - intent_type: "postgres.update_heartbeat"
+      target_pattern: "postgres://contracts/{contract_id}/heartbeat"
+      payload_model: "ModelPayloadUpdateHeartbeat"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_update_heartbeat"
+      description: "Update last_seen_at timestamp from heartbeat"
+    - intent_type: "postgres.deactivate_contract"
+      target_pattern: "postgres://contracts/{contract_id}"
+      payload_model: "ModelPayloadDeactivateContract"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_deactivate_contract"
+      description: "Mark contract as inactive on deregistration"
+    - intent_type: "postgres.cleanup_topic_references"
+      target_pattern: "postgres://topics/cleanup/{contract_id}"
+      payload_model: "ModelPayloadCleanupTopicReferences"
+      payload_module: "omnibase_infra.nodes.contract_registry_reducer.models.model_payload_cleanup_topic_references"
+      description: "Remove contract references from topics on deregistration"
+# State Model Configuration
+# =========================
+# The reducer uses ModelContractRegistryState for immutable state management.
+state_model:
+  name: "ModelContractRegistryState"
+  module: "omnibase_infra.nodes.contract_registry_reducer.models.model_contract_registry_state"
+  description: "Immutable state model for contract registry reducer"
+# Validation Configuration
+# ========================
+# Event validation rules applied before state transitions.
+validation:
+  enabled: true
+  rules:
+    - field: "contract_id"
+      required: true
+      error_code: "missing_contract_id"
+      error_message: "contract_id is required for contract identity"
+    - field: "node_id"
+      required: true
+      error_code: "missing_node_id"
+      error_message: "node_id is required to associate contract with source node"
+    - field: "node_type"
+      required: false
+      valid_values:
+        - "effect"
+        - "compute"
+        - "reducer"
+        - "orchestrator"
+      invalid_error_code: "invalid_node_type"
+      error_message: "node_type must be a valid ONEX node archetype"
+# Performance Configuration
+# =========================
+# Performance thresholds for monitoring.
+# Values can be overridden via environment variables.
+performance:
+  thresholds:
+    reduce_ms:
+      default: 300.0
+      env_var: "ONEX_PERF_THRESHOLD_CONTRACT_REDUCE_MS"
+      description: "Target processing time for reduce() method"
+    intent_build_ms:
+      default: 50.0
+      env_var: "ONEX_PERF_THRESHOLD_CONTRACT_INTENT_BUILD_MS"
+      description: "Target processing time for intent building"
+    staleness_check_ms:
+      default: 100.0
+      env_var: "ONEX_PERF_THRESHOLD_STALENESS_CHECK_MS"
+      description: "Target processing time for staleness computation on tick"
+# Idempotency Configuration
+# =========================
+# The reducer supports idempotent event processing via Kafka offset tracking.
+idempotency:
+  enabled: true
+  strategy: "kafka_offset_tracking"
+  derivation: "topic_partition_offset"
+  tracking_fields:
+    - "topic"
+    - "partition"
+    - "offset"
+  description: "Skip duplicate events based on Kafka position (topic:partition -> offset). State tracks last processed offset per (topic, partition) for multi-topic idempotency."
+# Staleness Configuration
+# =======================
+# Configuration for staleness computation on runtime-tick events.
+staleness:
+  threshold_seconds: 300 # 5 minutes without heartbeat = stale
+  env_var: "ONEX_CONTRACT_STALENESS_THRESHOLD_SECONDS"
+  description: "Contracts without heartbeat for this duration are marked stale"
+# Dependencies
+# ============
+dependencies:
+  - name: "container"
+    type: "ModelONEXContainer"
+    module: "omnibase_core.models.container.model_onex_container"
+    description: "ONEX dependency injection container"
+# Health Check
+# ============
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+# Metadata
+# ========
+metadata:
+  author: "OmniNode Team"
+  created: "2026-01-29"
+  updated: "2026-01-29"
+  tags:
+    - "reducer"
+    - "contract-registry"
+    - "fsm"
+    - "pure-function"
+    - "kafka-consumer"
+    - "postgres-projector"
+  related_tickets:
+    - "OMN-1653"

omnibase_infra/nodes/contract_registry_reducer/models/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for the contract registry reducer node.
+
+This module exports the state model and intent payloads used by NodeContractRegistryReducer.
+"""
+
+from omnibase_infra.nodes.contract_registry_reducer.models.model_contract_registry_state import (
+    ModelContractRegistryState,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_cleanup_topic_references import (
+    ModelPayloadCleanupTopicReferences,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_deactivate_contract import (
+    ModelPayloadDeactivateContract,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_mark_stale import (
+    ModelPayloadMarkStale,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_update_heartbeat import (
+    ModelPayloadUpdateHeartbeat,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_update_topic import (
+    ModelPayloadUpdateTopic,
+)
+from omnibase_infra.nodes.contract_registry_reducer.models.model_payload_upsert_contract import (
+    ModelPayloadUpsertContract,
+)
+
+__all__ = [
+    "ModelContractRegistryState",
+    "ModelPayloadCleanupTopicReferences",
+    "ModelPayloadDeactivateContract",
+    "ModelPayloadMarkStale",
+    "ModelPayloadUpdateHeartbeat",
+    "ModelPayloadUpdateTopic",
+    "ModelPayloadUpsertContract",
+]

omnibase_infra/nodes/contract_registry_reducer/models/model_contract_registry_state.py

@@ -0,0 +1,266 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Immutable state model for contract registry reducer.
+
+This module provides ModelContractRegistryState, an immutable state model for the
+contract registry projection reducer. The state follows the pure reducer pattern
+where state is passed in and returned from reduce(), with no internal mutation.
+
+Architecture:
+    ModelContractRegistryState is designed for projection to PostgreSQL. The reducer
+    processes contract registration events and emits intents for persistence. The state
+    tracks:
+
+    - Processed positions per (topic, partition) for multi-topic idempotency
+    - Last processed event ID (for correlation/debugging)
+    - Staleness tracking (for TTL-based garbage collection)
+    - Processing statistics (for observability)
+
+    State transitions are performed via `with_*` methods that return new instances,
+    ensuring the reducer remains pure and deterministic.
+
+Idempotency:
+    The state uses Kafka-based idempotency (topic, partition, offset) rather than
+    event ID-based idempotency. This is more robust for replay scenarios since
+    Kafka guarantees ordering within a partition.
+
+    **Multi-Topic Support**: The reducer consumes from 4 different Kafka topics
+    (contract-registered, contract-deregistered, heartbeat, runtime-tick). The state
+    tracks the last processed offset **per (topic, partition)** to correctly detect
+    duplicates even when events arrive interleaved from different topics.
+
+    The `is_duplicate_event` method checks if an event was already processed by
+    looking up the (topic, partition) key in `processed_positions` and comparing
+    offsets.
+
+Related:
+    - NodeContractRegistryReducer: Declarative reducer that uses this state model
+    - OMN-1653: Contract registry reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractRegistryState(BaseModel):
+    """Immutable state for contract registry projection.
+
+    This state tracks processed positions per (topic, partition) for multi-topic
+    idempotency and provides statistics for observability. The actual registry
+    data lives in PostgreSQL (this reducer projects to it).
+
+    The state is immutable (frozen=True) to enforce the pure reducer pattern.
+    All state transitions create new instances via `with_*` methods.
+
+    Multi-Topic Idempotency:
+        The reducer consumes from 4 different Kafka topics. A naive single-position
+        tracker would fail when events arrive interleaved:
+
+        1. Process topic A, partition 0, offset 100 -> track (A, 0, 100)
+        2. Process topic B, partition 0, offset 50 -> track (B, 0, 50)
+        3. Replay topic A, partition 0, offset 100 -> NOT detected as duplicate!
+
+        This model uses `processed_positions` to track the last offset per
+        (topic, partition) combination, ensuring correct duplicate detection
+        across all consumed topics.
+
+    Persistence Integration:
+        This model is persisted to PostgreSQL by the Projector component:
+
+        - **Stored**: By Runtime calling Projector.persist() after reduce() returns
+        - **Retrieved**: By Orchestrator via ProtocolProjectionReader before reduce()
+        - **Idempotency**: Kafka offset tracking enables duplicate detection
+
+        The reducer does NOT persist state directly - it returns the new state
+        in ModelReducerOutput.result. The Runtime handles persistence.
+
+    Immutability:
+        This model uses frozen=True to enforce strict immutability:
+
+        - All fields are immutable after construction
+        - Transition methods (with_*) return NEW instances
+        - Original state is never modified
+        - Safe for concurrent access and comparison
+
+    Attributes:
+        last_event_id: UUID of last processed event (for correlation/debugging).
+        processed_positions: Dict mapping "topic:partition" to last processed offset.
+        last_staleness_check_at: Timestamp of last staleness check run.
+        contracts_processed: Count of contract registration events processed.
+        heartbeats_processed: Count of heartbeat events processed.
+        deregistrations_processed: Count of deregistration events processed.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> state = ModelContractRegistryState()  # Initial state
+        >>> state.contracts_processed
+        0
+        >>> state = state.with_event_processed(
+        ...     uuid4(), "contracts", 0, 1
+        ... ).with_contract_registered()
+        >>> state.contracts_processed
+        1
+        >>> # Multi-topic: positions are tracked independently
+        >>> state = state.with_event_processed(uuid4(), "heartbeats", 0, 50)
+        >>> state.is_duplicate_event("contracts", 0, 1)  # Still detected
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # Last processed event ID (for correlation/debugging only, not idempotency)
+    last_event_id: UUID | None = Field(
+        default=None,
+        description="UUID of the last processed event for correlation",
+    )
+
+    # Multi-topic idempotency: track last offset per (topic, partition)
+    # Key format: "topic:partition" -> last processed offset
+    processed_positions: dict[str, int] = Field(
+        default_factory=dict,
+        description="Last processed offset per (topic:partition) for multi-topic idempotency",
+    )
+
+    # Staleness tracking
+    last_staleness_check_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of the last staleness check run",
+    )
+
+    # Statistics (for observability)
+    contracts_processed: int = Field(
+        default=0,
+        description="Count of contract registration events processed",
+    )
+    heartbeats_processed: int = Field(
+        default=0,
+        description="Count of heartbeat events processed",
+    )
+    deregistrations_processed: int = Field(
+        default=0,
+        description="Count of deregistration events processed",
+    )
+
+    @staticmethod
+    def _position_key(topic: str, partition: int) -> str:
+        """Generate dict key for (topic, partition) combination.
+
+        Args:
+            topic: Kafka topic name.
+            partition: Kafka partition number.
+
+        Returns:
+            String key in format "topic:partition".
+        """
+        return f"{topic}:{partition}"
+
+    def is_duplicate_event(self, topic: str, partition: int, offset: int) -> bool:
+        """Check if event was already processed (Kafka-based idempotency).
+
+        Uses per-(topic, partition) offset tracking for duplicate detection.
+        An event is considered a duplicate if:
+        - The (topic, partition) has been processed before
+        - The event's offset is <= the last processed offset for that combination
+
+        This correctly handles multi-topic consumption where events from different
+        topics arrive interleaved.
+
+        Args:
+            topic: Kafka topic of the event.
+            partition: Kafka partition of the event.
+            offset: Kafka offset of the event.
+
+        Returns:
+            True if this event was already processed (is a duplicate).
+        """
+        key = self._position_key(topic, partition)
+        last_offset = self.processed_positions.get(key)
+        if last_offset is None:
+            return False
+        return offset <= last_offset
+
+    def with_event_processed(
+        self,
+        event_id: UUID,
+        topic: str,
+        partition: int,
+        offset: int,
+    ) -> ModelContractRegistryState:
+        """Return new state with event marked as processed.
+
+        Creates a new immutable state instance with the Kafka offset tracking
+        updated for the specific (topic, partition) combination. Statistics are
+        preserved; use the specific `with_*` methods to increment them.
+
+        Multi-Topic Support:
+            Each (topic, partition) combination has its own tracked offset.
+            This ensures correct idempotency when the reducer consumes from
+            multiple topics (contract-registered, contract-deregistered,
+            heartbeat, runtime-tick).
+
+        Args:
+            event_id: UUID of the processed event.
+            topic: Kafka topic of the event.
+            partition: Kafka partition of the event.
+            offset: Kafka offset of the event.
+
+        Returns:
+            New ModelContractRegistryState with updated offset tracking.
+        """
+        key = self._position_key(topic, partition)
+        # Create new dict with updated position (immutable pattern)
+        new_positions = {**self.processed_positions, key: offset}
+        return self.model_copy(
+            update={
+                "last_event_id": event_id,
+                "processed_positions": new_positions,
+            }
+        )
+
+    def with_contract_registered(self) -> ModelContractRegistryState:
+        """Return new state with contract registration count incremented.
+
+        Returns:
+            New ModelContractRegistryState with contracts_processed + 1.
+        """
+        return self.model_copy(
+            update={"contracts_processed": self.contracts_processed + 1}
+        )
+
+    def with_heartbeat_processed(self) -> ModelContractRegistryState:
+        """Return new state with heartbeat count incremented.
+
+        Returns:
+            New ModelContractRegistryState with heartbeats_processed + 1.
+        """
+        return self.model_copy(
+            update={"heartbeats_processed": self.heartbeats_processed + 1}
+        )
+
+    def with_deregistration_processed(self) -> ModelContractRegistryState:
+        """Return new state with deregistration count incremented.
+
+        Returns:
+            New ModelContractRegistryState with deregistrations_processed + 1.
+        """
+        return self.model_copy(
+            update={"deregistrations_processed": self.deregistrations_processed + 1}
+        )
+
+    def with_staleness_check(self, check_time: datetime) -> ModelContractRegistryState:
+        """Return new state with staleness check timestamp updated.
+
+        Args:
+            check_time: Timestamp of the staleness check.
+
+        Returns:
+            New ModelContractRegistryState with updated staleness check time.
+        """
+        return self.model_copy(update={"last_staleness_check_at": check_time})
+
+
+__all__ = ["ModelContractRegistryState"]

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_cleanup_topic_references.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Cleanup topic references intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPayloadCleanupTopicReferences(BaseModel):
+    """Payload for PostgreSQL cleanup topic references intents.
+
+    Used when a contract-deregistered event is processed to remove
+    the contract_id from all topics.contract_ids JSONB arrays.
+
+    Note: contract_id is a derived natural key (node_name:major.minor.patch),
+    not a UUID. This is intentional per the contract registry design.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.cleanup_topic_references".
+        correlation_id: Correlation ID for distributed tracing.
+        contract_id: Contract ID to remove from all topic references.
+        node_name: Contract node name (for logging/debugging).
+        cleaned_at: Cleanup timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.cleanup_topic_references"] = Field(
+        default="postgres.cleanup_topic_references",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(..., description="Contract ID to remove from topics.")
+
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(..., description="Contract node name.")
+
+    cleaned_at: datetime = Field(..., description="Cleanup timestamp.")
+
+
+__all__ = ["ModelPayloadCleanupTopicReferences"]