omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/schemas/schema_registration_projection.sql

@@ -0,0 +1,320 @@
+-- ONEX Registration Projection Schema
+-- Ticket: OMN-944 (F1: Implement Registration Projection Schema)
+-- Version: 1.0.0
+--
+-- Design Notes:
+--   - (entity_id, domain) = composite primary key for multi-domain support
+--   - Indexes optimized for orchestrator query patterns:
+--     1. Deadline scanning (ack_deadline, liveness_deadline)
+--     2. State filtering (current_state)
+--     3. Domain + state queries
+--     4. Idempotency checks (last_applied_event_id)
+--   - JSONB for capabilities (flexible schema, GIN indexable)
+--   - All timestamps are timezone-aware (TIMESTAMPTZ)
+--   - This schema is idempotent (IF NOT EXISTS used throughout)
+--
+-- Usage:
+--   Execute this SQL file to create or update the projection schema.
+--   The schema is designed to be re-run safely (idempotent).
+--
+-- Related Tickets:
+--   - OMN-940 (F0): Projector Execution Model
+--   - OMN-932 (C2): Durable Timeout Handling
+--   - OMN-888 (C1): Registration Orchestrator
+
+-- =============================================================================
+-- ENUM TYPES
+-- =============================================================================
+
+-- Create enum type for registration states (matches EnumRegistrationState in Python)
+-- Note: PostgreSQL enums are immutable - to add values, use ALTER TYPE ... ADD VALUE
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'registration_state') THEN
+        CREATE TYPE registration_state AS ENUM (
+            'pending_registration',
+            'accepted',
+            'awaiting_ack',
+            'rejected',
+            'ack_timed_out',
+            'ack_received',
+            'active',
+            'liveness_expired'
+        );
+    END IF;
+END$$;
+
+-- =============================================================================
+-- MAIN TABLE
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS registration_projections (
+    -- Identity (composite primary key)
+    entity_id UUID NOT NULL,
+    domain VARCHAR(128) NOT NULL DEFAULT 'registration',
+
+    -- FSM State
+    current_state registration_state NOT NULL,
+
+    -- Node Information (snapshot at registration time)
+    node_type VARCHAR(64) NOT NULL,
+    node_version VARCHAR(32) NOT NULL DEFAULT '1.0.0',
+    capabilities JSONB NOT NULL DEFAULT '{}',
+
+    -- Capability fields for fast discovery queries (OMN-1134)
+    -- Denormalized from capabilities for GIN-indexed array queries
+    contract_type TEXT,  -- effect, compute, reducer, orchestrator
+    intent_types TEXT[] DEFAULT ARRAY[]::TEXT[],  -- Array of intent types this node handles
+    protocols TEXT[] DEFAULT ARRAY[]::TEXT[],  -- Array of protocols this node implements
+    capability_tags TEXT[] DEFAULT ARRAY[]::TEXT[],  -- Array of capability tags for discovery
+    contract_version TEXT,  -- Contract version string
+
+    -- Timeout Deadlines (for durable timeout handling per C2)
+    ack_deadline TIMESTAMPTZ,
+    liveness_deadline TIMESTAMPTZ,
+    last_heartbeat_at TIMESTAMPTZ,
+
+    -- Timeout Emission Markers (for deduplication per C2)
+    -- These prevent emitting duplicate timeout events during replay
+    ack_timeout_emitted_at TIMESTAMPTZ,
+    liveness_timeout_emitted_at TIMESTAMPTZ,
+
+    -- Idempotency and Ordering (per F1 requirements)
+    -- These fields enable replay correctness and stale update rejection
+    last_applied_event_id UUID NOT NULL,
+    last_applied_offset BIGINT NOT NULL DEFAULT 0,
+    last_applied_sequence BIGINT,
+    last_applied_partition VARCHAR(128),
+
+    -- Timestamps
+    registered_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL,
+
+    -- Tracing
+    correlation_id UUID,
+
+    -- Constraints
+    PRIMARY KEY (entity_id, domain),
+    -- UNIQUE constraint on entity_id enables ON CONFLICT (entity_id) upserts.
+    -- Required because omnibase-core's ModelProjectorContract only supports single-column
+    -- upsert_key, but we need composite PK for multi-domain support.
+    -- See: registration_projector.yaml behavior.upsert_key comment for details.
+    UNIQUE (entity_id),
+    CONSTRAINT valid_offset CHECK (last_applied_offset >= 0),
+    CONSTRAINT valid_sequence CHECK (last_applied_sequence IS NULL OR last_applied_sequence >= 0),
+    -- Node types MUST match omnibase_core.enums.EnumNodeKind values (lowercase serialized form)
+    -- Source of truth: omnibase_core/enums/enum_node_kind.py
+    -- When EnumNodeKind changes, this constraint MUST be updated to match
+    CONSTRAINT valid_node_type CHECK (node_type IN ('effect', 'compute', 'reducer', 'orchestrator')),
+    -- Contract type validation (same valid values as node_type, but nullable)
+    CONSTRAINT valid_contract_type CHECK (
+        contract_type IS NULL
+        OR contract_type IN ('effect', 'compute', 'reducer', 'orchestrator')
+    )
+);
+
+-- =============================================================================
+-- INDEXES FOR ORCHESTRATION QUERIES
+-- =============================================================================
+
+-- Index for ack deadline scanning (C2: orchestrator queries for overdue ack)
+-- Partial index: only index rows with non-null ack_deadline
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE ack_deadline < :now
+--                AND ack_timeout_emitted_at IS NULL
+--                AND current_state = 'awaiting_ack'
+CREATE INDEX IF NOT EXISTS idx_registration_ack_deadline
+    ON registration_projections (ack_deadline)
+    WHERE ack_deadline IS NOT NULL;
+
+-- Index for liveness deadline scanning (C2: orchestrator queries for overdue liveness)
+-- Partial index: only index active nodes with non-null liveness_deadline
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE liveness_deadline < :now
+--                AND liveness_timeout_emitted_at IS NULL
+--                AND current_state = 'active'
+CREATE INDEX IF NOT EXISTS idx_registration_liveness_deadline
+    ON registration_projections (liveness_deadline)
+    WHERE liveness_deadline IS NOT NULL;
+
+-- Index for state filtering (common orchestrator query pattern)
+-- Query pattern: SELECT * FROM registration_projections WHERE current_state = 'active'
+CREATE INDEX IF NOT EXISTS idx_registration_current_state
+    ON registration_projections (current_state);
+
+-- Index for state + domain filtering (multi-domain queries)
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE domain = :domain AND current_state = :state
+CREATE INDEX IF NOT EXISTS idx_registration_domain_state
+    ON registration_projections (domain, current_state);
+
+-- Index for idempotency checks (fast lookup by event_id)
+-- Query pattern: SELECT 1 FROM registration_projections
+--                WHERE last_applied_event_id = :event_id
+CREATE INDEX IF NOT EXISTS idx_registration_last_event_id
+    ON registration_projections (last_applied_event_id);
+
+-- Index for capability queries (GIN index on JSONB)
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE capabilities @> '{"postgres": true}'
+CREATE INDEX IF NOT EXISTS idx_registration_capabilities
+    ON registration_projections USING GIN (capabilities);
+
+-- =============================================================================
+-- GIN INDEXES FOR CAPABILITY ARRAY QUERIES (OMN-1134)
+-- =============================================================================
+
+-- GIN index for capability_tags array queries
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE capability_tags @> ARRAY['postgres.storage']
+CREATE INDEX IF NOT EXISTS idx_registration_capability_tags
+    ON registration_projections USING GIN (capability_tags);
+
+-- GIN index for intent_types array queries
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE intent_types @> ARRAY['postgres.upsert']
+CREATE INDEX IF NOT EXISTS idx_registration_intent_types
+    ON registration_projections USING GIN (intent_types);
+
+-- GIN index for protocols array queries
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE protocols @> ARRAY['ProtocolDatabaseAdapter']
+CREATE INDEX IF NOT EXISTS idx_registration_protocols
+    ON registration_projections USING GIN (protocols);
+
+-- B-tree index for contract_type + state queries
+-- Query pattern: SELECT * FROM registration_projections
+--                WHERE contract_type = 'effect' AND current_state = 'active'
+CREATE INDEX IF NOT EXISTS idx_registration_contract_type_state
+    ON registration_projections (contract_type, current_state);
+
+-- Composite index for deadline + emission marker scans
+-- Optimizes the most common timeout check query
+CREATE INDEX IF NOT EXISTS idx_registration_ack_timeout_scan
+    ON registration_projections (ack_deadline, ack_timeout_emitted_at)
+    WHERE ack_deadline IS NOT NULL AND ack_timeout_emitted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_registration_liveness_timeout_scan
+    ON registration_projections (current_state, liveness_deadline, liveness_timeout_emitted_at)
+    WHERE current_state = 'active' AND liveness_deadline IS NOT NULL AND liveness_timeout_emitted_at IS NULL;
+
+-- =============================================================================
+-- TABLE AND COLUMN COMMENTS
+-- =============================================================================
+
+COMMENT ON TABLE registration_projections IS
+    'Materialized registration state for orchestrator queries (OMN-944/F1). '
+    'Stores current FSM state, timeout deadlines, and idempotency tracking fields.';
+
+COMMENT ON COLUMN registration_projections.entity_id IS
+    'Node UUID - partition key for per-entity ordering. Combined with domain forms primary key.';
+
+COMMENT ON COLUMN registration_projections.domain IS
+    'Domain namespace for multi-domain support. Default: "registration".';
+
+COMMENT ON COLUMN registration_projections.current_state IS
+    'Current FSM state. Used by orchestrators to determine workflow progression.';
+
+COMMENT ON COLUMN registration_projections.ack_deadline IS
+    'Deadline for node acknowledgment. Orchestrator emits timeout event when passed.';
+
+COMMENT ON COLUMN registration_projections.liveness_deadline IS
+    'Deadline for next heartbeat. Orchestrator emits liveness expired event when passed.';
+
+COMMENT ON COLUMN registration_projections.last_heartbeat_at IS
+    'Timestamp of last received heartbeat from the node. Updated on each HeartbeatReceived event.';
+
+COMMENT ON COLUMN registration_projections.ack_timeout_emitted_at IS
+    'Marker indicating ack timeout event was already emitted. Prevents duplicates during replay.';
+
+COMMENT ON COLUMN registration_projections.liveness_timeout_emitted_at IS
+    'Marker indicating liveness timeout event was already emitted. Prevents duplicates during replay.';
+
+COMMENT ON COLUMN registration_projections.last_applied_event_id IS
+    'message_id of last applied event - used for idempotency checks.';
+
+COMMENT ON COLUMN registration_projections.last_applied_offset IS
+    'Kafka offset of last applied event - canonical ordering for replay correctness.';
+
+COMMENT ON COLUMN registration_projections.last_applied_sequence IS
+    'Sequence number for non-Kafka transports (optional). Used when offset is not applicable.';
+
+COMMENT ON COLUMN registration_projections.last_applied_partition IS
+    'Kafka partition of last applied event. Used with offset for global ordering.';
+
+-- =============================================================================
+-- INDEX STRATEGY DOCUMENTATION
+-- =============================================================================
+--
+-- This schema defines multiple indexes for different query patterns. Some indexes
+-- may appear redundant but serve distinct purposes due to partial WHERE clauses.
+--
+-- ACK DEADLINE INDEXES:
+-- ---------------------
+-- 1. idx_registration_ack_deadline:
+--    - Single-column index on ack_deadline
+--    - WHERE: ack_deadline IS NOT NULL
+--    - Use case: General queries filtering by ack_deadline regardless of emission status
+--    - Example: SELECT * FROM registration_projections WHERE ack_deadline < :now
+--
+-- 2. idx_registration_ack_timeout_scan:
+--    - Composite index on (ack_deadline, ack_timeout_emitted_at)
+--    - WHERE: ack_deadline IS NOT NULL AND ack_timeout_emitted_at IS NULL
+--    - Use case: Timeout scanner queries that need un-emitted timeouts only
+--    - Example: SELECT * FROM registration_projections
+--               WHERE ack_deadline < :now AND ack_timeout_emitted_at IS NULL
+--
+-- WHY BOTH INDEXES EXIST:
+-- The partial WHERE clauses differ significantly:
+--   - idx_registration_ack_deadline includes ALL rows with non-null deadlines
+--   - idx_registration_ack_timeout_scan ONLY includes rows awaiting timeout emission
+--
+-- PostgreSQL's query planner selects the most selective index. For timeout scans
+-- (the common orchestrator query), idx_registration_ack_timeout_scan is optimal
+-- because it pre-filters to only candidate rows. For other deadline queries that
+-- don't filter on emission status, idx_registration_ack_deadline is used.
+--
+-- LIVENESS DEADLINE INDEXES:
+-- --------------------------
+-- Similar rationale applies to liveness indexes:
+--   - idx_registration_liveness_deadline: All rows with liveness deadlines
+--   - idx_registration_liveness_timeout_scan: Only active nodes awaiting emission
+--
+-- =============================================================================
+-- UPSERT ORDERING ENFORCEMENT PATTERN
+-- =============================================================================
+--
+-- The projector (projector_registration.py) uses an atomic INSERT-or-UPDATE with
+-- sequence validation to enforce event ordering and reject stale updates.
+--
+-- KEY CONCEPT: Stale Update Rejection
+-- ------------------------------------
+-- "Stale" means the incoming event is older than what we've already processed.
+-- The upsert's WHERE clause compares sequence/offset numbers to ensure we never
+-- regress projection state. If the incoming event is older, PostgreSQL skips
+-- the UPDATE entirely - the existing row remains unchanged.
+--
+-- ORDERING MODES (mutually exclusive):
+-- ------------------------------------
+-- 1. KAFKA-BASED ORDERING (partition IS NOT NULL):
+--    Uses last_applied_offset for ordering within a partition.
+--    Kafka guarantees ordering within a partition, so (partition, offset)
+--    provides a total order for events affecting the same entity.
+--
+-- 2. SEQUENCE-BASED ORDERING (partition IS NULL):
+--    Falls back to last_applied_sequence for non-Kafka transports (e.g., HTTP).
+--    Used when the event source doesn't provide Kafka-style partition/offset.
+--
+-- IDEMPOTENCY FIELDS:
+-- -------------------
+-- - last_applied_event_id: Message UUID for exact duplicate detection
+-- - last_applied_offset: Kafka offset for Kafka-based ordering
+-- - last_applied_sequence: Generic sequence for non-Kafka ordering
+-- - last_applied_partition: Kafka partition for partitioned ordering context
+--
+-- These fields together enable:
+-- 1. Replay correctness: Replaying events produces identical projection state
+-- 2. Stale rejection: Out-of-order events don't regress state
+-- 3. Idempotency: Duplicate events are handled gracefully
+--
+-- See projector_registration.py for the complete upsert SQL implementation.

omnibase_infra/schemas/schema_transition_notification_outbox.sql

@@ -0,0 +1,245 @@
+-- SPDX-License-Identifier: MIT
+-- Copyright (c) 2025 OmniNode Team
+--
+-- Transition Notification Outbox Schema
+-- Ticket: OMN-1139 (TransitionNotificationOutbox implementation)
+-- Version: 1.0.0
+--
+-- Design Notes:
+--   - Implements the outbox pattern for guaranteed notification delivery
+--   - Stores notifications in same transaction as projections for atomicity
+--   - Supports concurrent processing via SELECT FOR UPDATE SKIP LOCKED
+--   - Includes retry tracking with error recording
+--   - Indexes optimized for processor query patterns:
+--     1. Pending notification queries (processed_at IS NULL)
+--     2. Aggregate-specific queries (aggregate_type, aggregate_id)
+--     3. Retry processing (high retry counts for monitoring)
+--     4. Cleanup of old processed records
+--   - All timestamps are timezone-aware (TIMESTAMPTZ)
+--   - This schema is idempotent (IF NOT EXISTS used throughout)
+--
+-- Usage:
+--   Execute this SQL file to create or update the outbox schema.
+--   The schema is designed to be re-run safely (idempotent).
+--
+-- Related:
+--   - TransitionNotificationOutbox: src/omnibase_infra/runtime/transition_notification_outbox.py
+--   - ModelStateTransitionNotification: omnibase_core.models.notifications
+--   - ProtocolTransitionNotificationPublisher: omnibase_core.protocols.notifications
+
+-- =============================================================================
+-- MAIN TABLE
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS transition_notification_outbox (
+    -- Identity
+    id BIGSERIAL PRIMARY KEY,
+
+    -- Notification Payload (serialized ModelStateTransitionNotification)
+    notification_data JSONB NOT NULL,
+
+    -- Timestamps
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    -- processed_at encodes both "pending" and "processed" states in a single column:
+    --   NULL = pending (not yet processed, eligible for processing)
+    --   non-NULL = processed (successfully published, timestamp of completion)
+    -- Note: No separate "processed_implies_no_pending" constraint is needed because
+    -- the single-column semantic makes the states mutually exclusive by design -
+    -- a row cannot be both pending (NULL) and processed (non-NULL) simultaneously.
+    processed_at TIMESTAMPTZ,
+
+    -- Retry Tracking
+    retry_count INT NOT NULL DEFAULT 0,
+    last_error TEXT,  -- Most recent error message (sanitized, max 1000 chars)
+
+    -- Aggregate Information (for queries and debugging)
+    aggregate_type TEXT NOT NULL,
+    aggregate_id UUID NOT NULL,
+
+    -- Constraints
+    CONSTRAINT valid_retry_count CHECK (retry_count >= 0)
+);
+
+-- =============================================================================
+-- INDEXES FOR OUTBOX PROCESSING
+-- =============================================================================
+
+-- Index for efficient pending notification queries (PRIMARY query pattern)
+-- The processor uses: SELECT ... WHERE processed_at IS NULL ORDER BY created_at
+-- Partial index: only index rows with NULL processed_at (pending notifications)
+-- Query pattern: SELECT id, notification_data FROM transition_notification_outbox
+--                WHERE processed_at IS NULL ORDER BY created_at LIMIT :batch_size
+--                FOR UPDATE SKIP LOCKED
+CREATE INDEX IF NOT EXISTS idx_outbox_pending
+    ON transition_notification_outbox (created_at)
+    WHERE processed_at IS NULL;
+
+-- Index for aggregate-specific queries (debugging and monitoring)
+-- Enables queries like "show all notifications for entity X"
+-- Query pattern: SELECT * FROM transition_notification_outbox
+--                WHERE aggregate_type = :type AND aggregate_id = :id
+CREATE INDEX IF NOT EXISTS idx_outbox_aggregate
+    ON transition_notification_outbox (aggregate_type, aggregate_id);
+
+-- Index for retry monitoring (identify stuck/failing notifications)
+-- Partial index: only pending notifications with retries
+-- Query pattern: SELECT * FROM transition_notification_outbox
+--                WHERE processed_at IS NULL AND retry_count > :threshold
+CREATE INDEX IF NOT EXISTS idx_outbox_retry_pending
+    ON transition_notification_outbox (retry_count, created_at)
+    WHERE processed_at IS NULL AND retry_count > 0;
+
+-- Index for cleanup queries (delete old processed records)
+-- Enables efficient deletion of processed records older than a threshold
+-- Query pattern: DELETE FROM transition_notification_outbox
+--                WHERE processed_at IS NOT NULL AND processed_at < :cutoff_time
+CREATE INDEX IF NOT EXISTS idx_outbox_cleanup
+    ON transition_notification_outbox (processed_at)
+    WHERE processed_at IS NOT NULL;
+
+-- Index for aggregate type filtering with pending status
+-- Useful for monitoring specific aggregate types
+-- Query pattern: SELECT COUNT(*) FROM transition_notification_outbox
+--                WHERE aggregate_type = :type AND processed_at IS NULL
+CREATE INDEX IF NOT EXISTS idx_outbox_aggregate_type_pending
+    ON transition_notification_outbox (aggregate_type)
+    WHERE processed_at IS NULL;
+
+-- =============================================================================
+-- TABLE AND COLUMN COMMENTS
+-- =============================================================================
+
+COMMENT ON TABLE transition_notification_outbox IS
+    'Outbox pattern table for guaranteed state transition notification delivery (OMN-1139). '
+    'Stores notifications in same transaction as projections for atomicity. '
+    'Background processor publishes pending notifications asynchronously.';
+
+COMMENT ON COLUMN transition_notification_outbox.id IS
+    'Auto-incrementing primary key. Used for efficient row locking with FOR UPDATE SKIP LOCKED.';
+
+COMMENT ON COLUMN transition_notification_outbox.notification_data IS
+    'Serialized ModelStateTransitionNotification as JSONB. Contains all notification fields: '
+    'aggregate_type, aggregate_id, transition (from_state, to_state, event_type), '
+    'correlation_id, timestamp, and optional metadata.';
+
+COMMENT ON COLUMN transition_notification_outbox.created_at IS
+    'Timestamp when notification was stored in outbox. Used for FIFO ordering of pending notifications.';
+
+COMMENT ON COLUMN transition_notification_outbox.processed_at IS
+    'Timestamp when notification was successfully published. NULL indicates pending status.';
+
+COMMENT ON COLUMN transition_notification_outbox.retry_count IS
+    'Number of failed publish attempts. Incremented on each failure, not reset on success. '
+    'Use for monitoring and alerting on stuck notifications.';
+
+COMMENT ON COLUMN transition_notification_outbox.last_error IS
+    'Most recent error message from failed publish attempt (sanitized, max 1000 chars). '
+    'Updated on each failure for debugging. May contain value even when processed_at is set '
+    'if earlier retries failed before final success.';
+
+COMMENT ON COLUMN transition_notification_outbox.aggregate_type IS
+    'Type of aggregate this notification is for (e.g., "registration", "workflow"). '
+    'Denormalized from notification_data for efficient indexing and filtering.';
+
+COMMENT ON COLUMN transition_notification_outbox.aggregate_id IS
+    'UUID of the aggregate entity this notification is for. '
+    'Denormalized from notification_data for efficient indexing and aggregate-specific queries.';
+
+-- =============================================================================
+-- INDEX STRATEGY DOCUMENTATION
+-- =============================================================================
+--
+-- This schema defines multiple indexes optimized for different query patterns
+-- used by the TransitionNotificationOutbox processor and operators.
+--
+-- PENDING NOTIFICATION PROCESSING:
+-- --------------------------------
+-- 1. idx_outbox_pending:
+--    - Single-column index on created_at
+--    - WHERE: processed_at IS NULL
+--    - Use case: Main processor query - fetch pending notifications in FIFO order
+--    - Critical for: process_pending() batch retrieval
+--
+-- The partial WHERE clause keeps this index small and fast by excluding
+-- all processed records.
+--
+-- AGGREGATE QUERIES (Debugging):
+-- ------------------------------
+-- 2. idx_outbox_aggregate:
+--    - Composite index on (aggregate_type, aggregate_id)
+--    - Use case: Query notifications for a specific entity
+--    - Example: "Show all notifications for registration entity X"
+--
+-- RETRY MONITORING:
+-- -----------------
+-- 3. idx_outbox_retry_pending:
+--    - Composite index on (retry_count, created_at)
+--    - WHERE: processed_at IS NULL AND retry_count > 0
+--    - Use case: Identify stuck or failing notifications
+--    - Example: Alert when retry_count > 5 for pending notifications
+--
+-- CLEANUP OPERATIONS:
+-- -------------------
+-- 4. idx_outbox_cleanup:
+--    - Single-column index on processed_at
+--    - WHERE: processed_at IS NOT NULL
+--    - Use case: Efficient deletion of old processed records
+--    - Example: DELETE ... WHERE processed_at < NOW() - INTERVAL '7 days'
+--
+-- TYPE-SPECIFIC MONITORING:
+-- -------------------------
+-- 5. idx_outbox_aggregate_type_pending:
+--    - Single-column index on aggregate_type
+--    - WHERE: processed_at IS NULL
+--    - Use case: Count pending notifications by type for monitoring dashboards
+--
+-- =============================================================================
+-- CONCURRENT PROCESSING PATTERN
+-- =============================================================================
+--
+-- The outbox processor uses SELECT FOR UPDATE SKIP LOCKED to enable safe
+-- concurrent processing by multiple instances:
+--
+--   SELECT id, notification_data
+--   FROM transition_notification_outbox
+--   WHERE processed_at IS NULL
+--   ORDER BY created_at
+--   LIMIT :batch_size
+--   FOR UPDATE SKIP LOCKED;
+--
+-- SKIP LOCKED ensures that if another processor has locked a row, this query
+-- skips it rather than blocking. This prevents:
+-- - Duplicate processing
+-- - Deadlocks between processors
+-- - Head-of-line blocking
+--
+-- The id column (BIGSERIAL PRIMARY KEY) provides an efficient row lock target.
+--
+-- =============================================================================
+-- CLEANUP RECOMMENDATIONS
+-- =============================================================================
+--
+-- Processed records should be periodically deleted to prevent table bloat.
+-- Recommended cleanup query (run periodically via cron or pg_cron):
+--
+--   DELETE FROM transition_notification_outbox
+--   WHERE processed_at IS NOT NULL
+--   AND processed_at < NOW() - INTERVAL '7 days';
+--
+-- Alternatively, implement as a PostgreSQL function:
+--
+--   CREATE OR REPLACE FUNCTION cleanup_outbox(retention_interval INTERVAL)
+--   RETURNS BIGINT AS $$
+--   DECLARE
+--     deleted_count BIGINT;
+--   BEGIN
+--     DELETE FROM transition_notification_outbox
+--     WHERE processed_at IS NOT NULL
+--     AND processed_at < NOW() - retention_interval;
+--     GET DIAGNOSTICS deleted_count = ROW_COUNT;
+--     RETURN deleted_count;
+--   END;
+--   $$ LANGUAGE plpgsql;
+--
+-- Usage: SELECT cleanup_outbox(INTERVAL '7 days');
+--

omnibase_infra/services/__init__.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Services Module.
+
+Provides high-level services that compose infrastructure components for
+use by orchestrators and runtime hosts. Services provide clean interfaces
+for common operations and encapsulate complexity.
+
+Exports:
+    DEFAULT_SELECTION_KEY: Default key for round-robin state tracking
+    EnumSelectionStrategy: Selection strategies for capability-based discovery
+    ModelTimeoutEmissionConfig: Configuration for timeout emitter
+    ModelTimeoutEmissionResult: Result model for timeout emission processing
+    ModelTimeoutQueryResult: Result model for timeout queries
+    ServiceCapabilityQuery: Query nodes by capability, not by name
+    ServiceNodeSelector: Select nodes from candidates using various strategies
+    ServiceSnapshot: Generic snapshot service for point-in-time state capture
+    ServiceTimeoutEmitter: Emitter for timeout events with markers
+    ServiceTimeoutScanner: Scanner for querying overdue registration entities
+    StoreSnapshotInMemory: In-memory snapshot store for testing
+    StoreSnapshotPostgres: PostgreSQL snapshot store for production
+    TimeoutEmitter: Alias for ServiceTimeoutEmitter
+    TimeoutScanner: Alias for ServiceTimeoutScanner
+"""
+
+from omnibase_infra.enums import EnumSelectionStrategy
+from omnibase_infra.services.corpus_capture import CorpusCapture
+from omnibase_infra.services.service_capability_query import ServiceCapabilityQuery
+from omnibase_infra.services.service_node_selector import (
+    DEFAULT_SELECTION_KEY,
+    ServiceNodeSelector,
+)
+from omnibase_infra.services.service_timeout_emitter import (
+    ModelTimeoutEmissionConfig,
+    ModelTimeoutEmissionResult,
+    ServiceTimeoutEmitter,
+)
+from omnibase_infra.services.service_timeout_scanner import (
+    ModelTimeoutQueryResult,
+    ServiceTimeoutScanner,
+)
+
+# Session services (moved from omniclaude in OMN-1526)
+from omnibase_infra.services.session import (
+    ConfigSessionConsumer,
+    ConfigSessionStorage,
+    ConsumerMetrics,
+    EnumCircuitState,
+    ProtocolSessionAggregator,
+    SessionEventConsumer,
+    SessionSnapshotStore,
+    SessionStoreNotInitializedError,
+)
+from omnibase_infra.services.snapshot import (
+    ServiceSnapshot,
+    StoreSnapshotInMemory,
+    StoreSnapshotPostgres,
+)
+
+# Aliases for convenience
+TimeoutEmitter = ServiceTimeoutEmitter
+TimeoutScanner = ServiceTimeoutScanner
+
+__all__ = [
+    "DEFAULT_SELECTION_KEY",
+    "EnumSelectionStrategy",
+    "ModelTimeoutEmissionConfig",
+    "ModelTimeoutEmissionResult",
+    "ModelTimeoutQueryResult",
+    "ServiceCapabilityQuery",
+    "CorpusCapture",
+    "ServiceNodeSelector",
+    "ServiceSnapshot",
+    "ServiceTimeoutEmitter",
+    "ServiceTimeoutScanner",
+    "StoreSnapshotInMemory",
+    "StoreSnapshotPostgres",
+    "TimeoutEmitter",
+    "TimeoutScanner",
+    # Session services (OMN-1526)
+    "ConfigSessionConsumer",
+    "ConfigSessionStorage",
+    "ConsumerMetrics",
+    "EnumCircuitState",
+    "ProtocolSessionAggregator",
+    "SessionEventConsumer",
+    "SessionSnapshotStore",
+    "SessionStoreNotInitializedError",
+]