edda-framework 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

edda/storage/sqlalchemy_storage.py

@@ -8,7 +8,7 @@ and transactional outbox pattern.
 
 import json
 import logging
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass, field
@@ -19,6 +19,7 @@ from sqlalchemy import (
     CheckConstraint,
     Column,
     DateTime,
+    ForeignKey,
     ForeignKeyConstraint,
     Index,
     Integer,
@@ -29,18 +30,21 @@ from sqlalchemy import (
     and_,
     delete,
     func,
+    inspect,
     or_,
     select,
     text,
     update,
 )
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
-from sqlalchemy.orm import declarative_base
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 logger = logging.getLogger(__name__)
 
+
 # Declarative base for ORM models
-Base = declarative_base()
+class Base(DeclarativeBase):
+    pass
 
 
 # ============================================================================
@@ -48,25 +52,25 @@ Base = declarative_base()
 # ============================================================================
 
 
-class SchemaVersion(Base):  # type: ignore[valid-type, misc]
+class SchemaVersion(Base):
     """Schema version tracking."""
 
     __tablename__ = "schema_version"
 
-    version = Column(Integer, primary_key=True)
-    applied_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
-    description = Column(Text, nullable=False)
+    version: Mapped[int] = mapped_column(Integer, primary_key=True)
+    applied_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    description: Mapped[str] = mapped_column(Text)
 
 
-class WorkflowDefinition(Base):  # type: ignore[valid-type, misc]
+class WorkflowDefinition(Base):
     """Workflow definition (source code storage)."""
 
     __tablename__ = "workflow_definitions"
 
-    workflow_name = Column(String(255), nullable=False, primary_key=True)
-    source_hash = Column(String(64), nullable=False, primary_key=True)
-    source_code = Column(Text, nullable=False)
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    workflow_name: Mapped[str] = mapped_column(String(255), primary_key=True)
+    source_hash: Mapped[str] = mapped_column(String(64), primary_key=True)
+    source_code: Mapped[str] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
     __table_args__ = (
         Index("idx_definitions_name", "workflow_name"),
@@ -74,31 +78,34 @@ class WorkflowDefinition(Base):  # type: ignore[valid-type, misc]
     )
 
 
-class WorkflowInstance(Base):  # type: ignore[valid-type, misc]
+class WorkflowInstance(Base):
     """Workflow instance with distributed locking support."""
 
     __tablename__ = "workflow_instances"
 
-    instance_id = Column(String(255), primary_key=True)
-    workflow_name = Column(String(255), nullable=False)
-    source_hash = Column(String(64), nullable=False)
-    owner_service = Column(String(255), nullable=False)
-    status = Column(
-        String(50),
-        nullable=False,
-        server_default=text("'running'"),
+    instance_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    workflow_name: Mapped[str] = mapped_column(String(255))
+    source_hash: Mapped[str] = mapped_column(String(64))
+    owner_service: Mapped[str] = mapped_column(String(255))
+    status: Mapped[str] = mapped_column(String(50), server_default=text("'running'"))
+    current_activity_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    continued_from: Mapped[str | None] = mapped_column(
+        String(255), ForeignKey("workflow_instances.instance_id"), nullable=True
     )
-    current_activity_id = Column(String(255), nullable=True)
-    started_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
-    updated_at = Column(
-        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
     )
-    input_data = Column(Text, nullable=False)  # JSON
-    output_data = Column(Text, nullable=True)  # JSON
-    locked_by = Column(String(255), nullable=True)
-    locked_at = Column(DateTime(timezone=True), nullable=True)
-    lock_timeout_seconds = Column(Integer, nullable=True)  # None = use global default (300s)
-    lock_expires_at = Column(DateTime(timezone=True), nullable=True)  # Absolute expiry time
+    input_data: Mapped[str] = mapped_column(Text)  # JSON
+    output_data: Mapped[str | None] = mapped_column(Text, nullable=True)  # JSON
+    locked_by: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    locked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    lock_timeout_seconds: Mapped[int | None] = mapped_column(
+        Integer, nullable=True
+    )  # None = use global default (300s)
+    lock_expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )  # Absolute expiry time
 
     __table_args__ = (
         ForeignKeyConstraint(
@@ -107,7 +114,7 @@ class WorkflowInstance(Base):  # type: ignore[valid-type, misc]
         ),
         CheckConstraint(
             "status IN ('running', 'completed', 'failed', 'waiting_for_event', "
-            "'waiting_for_timer', 'compensating', 'cancelled')",
+            "'waiting_for_timer', 'waiting_for_message', 'compensating', 'cancelled', 'recurred')",
             name="valid_status",
         ),
         Index("idx_instances_status", "status"),
@@ -117,25 +124,29 @@ class WorkflowInstance(Base):  # type: ignore[valid-type, misc]
         Index("idx_instances_lock_expires", "lock_expires_at"),
         Index("idx_instances_updated", "updated_at"),
         Index("idx_instances_hash", "source_hash"),
+        Index("idx_instances_continued_from", "continued_from"),
+        # Composite index for find_resumable_workflows(): WHERE status='running' AND locked_by IS NULL
+        Index("idx_instances_resumable", "status", "locked_by"),
     )
 
 
-class WorkflowHistory(Base):  # type: ignore[valid-type, misc]
+class WorkflowHistory(Base):
     """Workflow execution history (for deterministic replay)."""
 
     __tablename__ = "workflow_history"
 
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    instance_id = Column(
-        String(255),
-        nullable=False,
-    )
-    activity_id = Column(String(255), nullable=False)
-    event_type = Column(String(100), nullable=False)
-    data_type = Column(String(10), nullable=False)  # 'json' or 'binary'
-    event_data = Column(Text, nullable=True)  # JSON (when data_type='json')
-    event_data_binary = Column(LargeBinary, nullable=True)  # Binary (when data_type='binary')
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    activity_id: Mapped[str] = mapped_column(String(255))
+    event_type: Mapped[str] = mapped_column(String(100))
+    data_type: Mapped[str] = mapped_column(String(10))  # 'json' or 'binary'
+    event_data: Mapped[str | None] = mapped_column(
+        Text, nullable=True
+    )  # JSON (when data_type='json')
+    event_data_binary: Mapped[bytes | None] = mapped_column(
+        LargeBinary, nullable=True
+    )  # Binary (when data_type='binary')
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
     __table_args__ = (
         ForeignKeyConstraint(
@@ -158,20 +169,20 @@ class WorkflowHistory(Base):  # type: ignore[valid-type, misc]
     )
 
 
-class WorkflowCompensation(Base):  # type: ignore[valid-type, misc]
-    """Compensation transactions (LIFO stack for Saga pattern)."""
+class WorkflowHistoryArchive(Base):
+    """Archived workflow execution history (for recur pattern)."""
 
-    __tablename__ = "workflow_compensations"
+    __tablename__ = "workflow_history_archive"
 
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    instance_id = Column(
-        String(255),
-        nullable=False,
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    activity_id: Mapped[str] = mapped_column(String(255))
+    event_type: Mapped[str] = mapped_column(String(100))
+    event_data: Mapped[str] = mapped_column(Text)  # JSON (includes both types for archive)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    archived_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
     )
-    activity_id = Column(String(255), nullable=False)
-    activity_name = Column(String(255), nullable=False)
-    args = Column(Text, nullable=False)  # JSON
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
 
     __table_args__ = (
         ForeignKeyConstraint(
@@ -179,24 +190,22 @@ class WorkflowCompensation(Base):  # type: ignore[valid-type, misc]
             ["workflow_instances.instance_id"],
             ondelete="CASCADE",
         ),
-        Index("idx_compensations_instance", "instance_id", "created_at"),
+        Index("idx_history_archive_instance", "instance_id"),
+        Index("idx_history_archive_archived", "archived_at"),
     )
 
 
-class WorkflowEventSubscription(Base):  # type: ignore[valid-type, misc]
-    """Event subscriptions (for wait_event)."""
+class WorkflowCompensation(Base):
+    """Compensation transactions (LIFO stack for Saga pattern)."""
 
-    __tablename__ = "workflow_event_subscriptions"
+    __tablename__ = "workflow_compensations"
 
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    instance_id = Column(
-        String(255),
-        nullable=False,
-    )
-    event_type = Column(String(255), nullable=False)
-    activity_id = Column(String(255), nullable=True)
-    timeout_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    activity_id: Mapped[str] = mapped_column(String(255))
+    activity_name: Mapped[str] = mapped_column(String(255))
+    args: Mapped[str] = mapped_column(Text)  # JSON
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
     __table_args__ = (
         ForeignKeyConstraint(
@@ -204,27 +213,21 @@ class WorkflowEventSubscription(Base):  # type: ignore[valid-type, misc]
             ["workflow_instances.instance_id"],
             ondelete="CASCADE",
         ),
-        UniqueConstraint("instance_id", "event_type", name="unique_instance_event"),
-        Index("idx_subscriptions_event", "event_type"),
-        Index("idx_subscriptions_timeout", "timeout_at"),
-        Index("idx_subscriptions_instance", "instance_id"),
+        Index("idx_compensations_instance", "instance_id", "created_at"),
     )
 
 
-class WorkflowTimerSubscription(Base):  # type: ignore[valid-type, misc]
+class WorkflowTimerSubscription(Base):
     """Timer subscriptions (for wait_timer)."""
 
     __tablename__ = "workflow_timer_subscriptions"
 
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    instance_id = Column(
-        String(255),
-        nullable=False,
-    )
-    timer_id = Column(String(255), nullable=False)
-    expires_at = Column(DateTime(timezone=True), nullable=False)
-    activity_id = Column(String(255), nullable=True)
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    timer_id: Mapped[str] = mapped_column(String(255))
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    activity_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
     __table_args__ = (
         ForeignKeyConstraint(
@@ -238,23 +241,29 @@ class WorkflowTimerSubscription(Base):  # type: ignore[valid-type, misc]
     )
 
 
-class OutboxEvent(Base):  # type: ignore[valid-type, misc]
+class OutboxEvent(Base):
     """Transactional outbox pattern events."""
 
     __tablename__ = "outbox_events"
 
-    event_id = Column(String(255), primary_key=True)
-    event_type = Column(String(255), nullable=False)
-    event_source = Column(String(255), nullable=False)
-    data_type = Column(String(10), nullable=False)  # 'json' or 'binary'
-    event_data = Column(Text, nullable=True)  # JSON (when data_type='json')
-    event_data_binary = Column(LargeBinary, nullable=True)  # Binary (when data_type='binary')
-    content_type = Column(String(100), nullable=False, server_default=text("'application/json'"))
-    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
-    published_at = Column(DateTime(timezone=True), nullable=True)
-    status = Column(String(50), nullable=False, server_default=text("'pending'"))
-    retry_count = Column(Integer, nullable=False, server_default=text("0"))
-    last_error = Column(Text, nullable=True)
+    event_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    event_type: Mapped[str] = mapped_column(String(255))
+    event_source: Mapped[str] = mapped_column(String(255))
+    data_type: Mapped[str] = mapped_column(String(10))  # 'json' or 'binary'
+    event_data: Mapped[str | None] = mapped_column(
+        Text, nullable=True
+    )  # JSON (when data_type='json')
+    event_data_binary: Mapped[bytes | None] = mapped_column(
+        LargeBinary, nullable=True
+    )  # Binary (when data_type='binary')
+    content_type: Mapped[str] = mapped_column(
+        String(100), server_default=text("'application/json'")
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    status: Mapped[str] = mapped_column(String(50), server_default=text("'pending'"))
+    retry_count: Mapped[int] = mapped_column(Integer, server_default=text("0"))
+    last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
 
     __table_args__ = (
         CheckConstraint(
@@ -276,6 +285,178 @@ class OutboxEvent(Base):  # type: ignore[valid-type, misc]
     )
 
 
+class WorkflowGroupMembership(Base):
+    """Group memberships (Erlang pg style for broadcast messaging)."""
+
+    __tablename__ = "workflow_group_memberships"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    group_name: Mapped[str] = mapped_column(String(255))
+    joined_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["instance_id"],
+            ["workflow_instances.instance_id"],
+            ondelete="CASCADE",
+        ),
+        UniqueConstraint("instance_id", "group_name", name="unique_instance_group"),
+        Index("idx_group_memberships_group", "group_name"),
+        Index("idx_group_memberships_instance", "instance_id"),
+    )
+
+
+# =============================================================================
+# Channel-based Message Queue Models
+# =============================================================================
+
+
+class ChannelMessage(Base):
+    """Channel message queue (persistent message storage)."""
+
+    __tablename__ = "channel_messages"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    channel: Mapped[str] = mapped_column(String(255))
+    message_id: Mapped[str] = mapped_column(String(255), unique=True)
+    data_type: Mapped[str] = mapped_column(String(10))  # 'json' or 'binary'
+    data: Mapped[str | None] = mapped_column(Text, nullable=True)  # JSON (when data_type='json')
+    data_binary: Mapped[bytes | None] = mapped_column(
+        LargeBinary, nullable=True
+    )  # Binary (when data_type='binary')
+    message_metadata: Mapped[str | None] = mapped_column(
+        "metadata", Text, nullable=True
+    )  # JSON - renamed to avoid SQLAlchemy reserved name
+    published_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+    __table_args__ = (
+        CheckConstraint(
+            "data_type IN ('json', 'binary')",
+            name="channel_valid_data_type",
+        ),
+        CheckConstraint(
+            "(data_type = 'json' AND data IS NOT NULL AND data_binary IS NULL) OR "
+            "(data_type = 'binary' AND data IS NULL AND data_binary IS NOT NULL)",
+            name="channel_data_type_consistency",
+        ),
+        Index("idx_channel_messages_channel", "channel", "published_at"),
+        Index("idx_channel_messages_id", "id"),
+    )
+
+
+class ChannelSubscription(Base):
+    """Channel subscriptions for workflow instances."""
+
+    __tablename__ = "channel_subscriptions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    channel: Mapped[str] = mapped_column(String(255))
+    mode: Mapped[str] = mapped_column(String(20))  # 'broadcast' or 'competing'
+    activity_id: Mapped[str | None] = mapped_column(
+        String(255), nullable=True
+    )  # Set when waiting for message
+    cursor_message_id: Mapped[int | None] = mapped_column(
+        Integer, nullable=True
+    )  # Last received message id (broadcast)
+    timeout_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )  # Timeout deadline
+    subscribed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["instance_id"],
+            ["workflow_instances.instance_id"],
+            ondelete="CASCADE",
+        ),
+        CheckConstraint(
+            "mode IN ('broadcast', 'competing')",
+            name="channel_valid_mode",
+        ),
+        UniqueConstraint("instance_id", "channel", name="unique_channel_instance_channel"),
+        Index("idx_channel_subscriptions_channel", "channel"),
+        Index("idx_channel_subscriptions_instance", "instance_id"),
+        Index("idx_channel_subscriptions_waiting", "channel", "activity_id"),
+        Index("idx_channel_subscriptions_timeout", "timeout_at"),
+    )
+
+
+class ChannelDeliveryCursor(Base):
+    """Channel delivery cursors (broadcast mode: track who read what)."""
+
+    __tablename__ = "channel_delivery_cursors"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    channel: Mapped[str] = mapped_column(String(255))
+    instance_id: Mapped[str] = mapped_column(String(255))
+    last_delivered_id: Mapped[int] = mapped_column(Integer)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["instance_id"],
+            ["workflow_instances.instance_id"],
+            ondelete="CASCADE",
+        ),
+        UniqueConstraint("channel", "instance_id", name="unique_channel_delivery_cursor"),
+        Index("idx_channel_delivery_cursors_channel", "channel"),
+    )
+
+
+class ChannelMessageClaim(Base):
+    """Channel message claims (competing mode: who is processing what)."""
+
+    __tablename__ = "channel_message_claims"
+
+    message_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    instance_id: Mapped[str] = mapped_column(String(255))
+    claimed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["message_id"],
+            ["channel_messages.message_id"],
+            ondelete="CASCADE",
+        ),
+        ForeignKeyConstraint(
+            ["instance_id"],
+            ["workflow_instances.instance_id"],
+            ondelete="CASCADE",
+        ),
+        Index("idx_channel_message_claims_instance", "instance_id"),
+    )
+
+
+# =============================================================================
+# System-level Lock Models (for background task coordination)
+# =============================================================================
+
+
+class SystemLock(Base):
+    """System-level locks for coordinating background tasks across pods.
+
+    Used to prevent duplicate execution of operational tasks like:
+    - cleanup_stale_locks_periodically()
+    - auto_resume_stale_workflows_periodically()
+    - _cleanup_old_messages_periodically()
+    """
+
+    __tablename__ = "system_locks"
+
+    lock_name: Mapped[str] = mapped_column(String(255), primary_key=True)
+    locked_by: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    locked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    lock_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    __table_args__ = (Index("idx_system_locks_expires", "lock_expires_at"),)
+
+
 # Current schema version
 CURRENT_SCHEMA_VERSION = 1
 
@@ -302,6 +483,9 @@ class TransactionContext:
     session: "AsyncSession | None" = None
     """The actual session for this transaction"""
 
+    post_commit_callbacks: list[Callable[[], Awaitable[None]]] = field(default_factory=list)
+    """Callbacks to execute after successful top-level commit"""
+
 
 # Context variable for transaction state (asyncio-safe)
 _transaction_context: ContextVar[TransactionContext | None] = ContextVar(
@@ -337,11 +521,22 @@ class SQLAlchemyStorage:
         self.engine = engine
 
     async def initialize(self) -> None:
-        """Initialize database connection and create tables."""
+        """Initialize database connection and create tables.
+
+        This method creates all tables if they don't exist, and then performs
+        automatic schema migration to add any missing columns and update CHECK
+        constraints. This ensures compatibility when upgrading Edda versions.
+        """
         # Create all tables and indexes
         async with self.engine.begin() as conn:
             await conn.run_sync(Base.metadata.create_all)
 
+        # Auto-migrate schema (add missing columns)
+        await self._auto_migrate_schema()
+
+        # Auto-migrate CHECK constraints
+        await self._auto_migrate_check_constraints()
+
         # Initialize schema version
         await self._initialize_schema_version()
 
@@ -366,6 +561,198 @@ class SQLAlchemyStorage:
                 await session.commit()
                 logger.info(f"Initialized schema version to {CURRENT_SCHEMA_VERSION}")
 
+    async def _auto_migrate_schema(self) -> None:
+        """
+        Automatically add missing columns to existing tables.
+
+        This method compares the ORM model definitions with the actual database
+        schema and adds any missing columns using ALTER TABLE ADD COLUMN.
+
+        Note: This only handles column additions, not removals or type changes.
+        For complex migrations, use Alembic.
+        """
+
+        def _get_column_type_sql(column: Column, dialect_name: str) -> str:  # type: ignore[type-arg]
+            """Get SQL type string for a column based on dialect."""
+            col_type = column.type
+
+            # Map SQLAlchemy types to SQL types
+            if isinstance(col_type, String):
+                length = col_type.length or 255
+                return f"VARCHAR({length})"
+            elif isinstance(col_type, Text):
+                return "TEXT"
+            elif isinstance(col_type, Integer):
+                return "INTEGER"
+            elif isinstance(col_type, DateTime):
+                if dialect_name == "postgresql":
+                    return "TIMESTAMP WITH TIME ZONE" if col_type.timezone else "TIMESTAMP"
+                elif dialect_name == "mysql":
+                    return "DATETIME" if not col_type.timezone else "DATETIME"
+                else:  # sqlite
+                    return "DATETIME"
+            elif isinstance(col_type, LargeBinary):
+                if dialect_name == "postgresql":
+                    return "BYTEA"
+                elif dialect_name == "mysql":
+                    return "LONGBLOB"
+                else:  # sqlite
+                    return "BLOB"
+            else:
+                # Fallback to compiled type
+                return str(col_type.compile(dialect=self.engine.dialect))
+
+        def _get_default_sql(column: Column, _dialect_name: str) -> str | None:  # type: ignore[type-arg]
+            """Get DEFAULT clause for a column if applicable."""
+            if column.server_default is not None:
+                # Handle text() server defaults - try to get the arg attribute
+                server_default = column.server_default
+                if hasattr(server_default, "arg"):
+                    default_val = server_default.arg
+                    if hasattr(default_val, "text"):
+                        return f"DEFAULT {default_val.text}"
+                    return f"DEFAULT {default_val}"
+            return None
+
+        def _run_migration(conn: Any) -> None:
+            """Run migration in sync context."""
+            dialect_name = self.engine.dialect.name
+            inspector = inspect(conn)
+
+            # Iterate through all ORM tables
+            for table in Base.metadata.tables.values():
+                table_name = table.name
+
+                # Check if table exists
+                if not inspector.has_table(table_name):
+                    logger.debug(f"Table {table_name} does not exist, skipping migration")
+                    continue
+
+                # Get existing columns
+                existing_columns = {col["name"] for col in inspector.get_columns(table_name)}
+
+                # Check each column in the ORM model
+                for column in table.columns:
+                    if column.name not in existing_columns:
+                        # Column is missing, generate ALTER TABLE
+                        col_type_sql = _get_column_type_sql(column, dialect_name)
+                        nullable = "NULL" if column.nullable else "NOT NULL"
+
+                        # Build ALTER TABLE statement
+                        alter_sql = (
+                            f'ALTER TABLE "{table_name}" ADD COLUMN "{column.name}" {col_type_sql}'
+                        )
+
+                        # Add nullable constraint (only if NOT NULL and has default)
+                        default_sql = _get_default_sql(column, dialect_name)
+                        if not column.nullable and default_sql:
+                            alter_sql += f" {default_sql} {nullable}"
+                        elif column.nullable:
+                            alter_sql += f" {nullable}"
+                        elif default_sql:
+                            alter_sql += f" {default_sql}"
+                        # For NOT NULL without default, just add the column as nullable
+                        # (PostgreSQL requires default or nullable for existing rows)
+                        else:
+                            alter_sql += " NULL"
+
+                        logger.info(f"Auto-migrating: Adding column {column.name} to {table_name}")
+                        logger.debug(f"Executing: {alter_sql}")
+
+                        try:
+                            conn.execute(text(alter_sql))
+                        except Exception as e:
+                            logger.warning(
+                                f"Failed to add column {column.name} to {table_name}: {e}"
+                            )
+
+        async with self.engine.begin() as conn:
+            await conn.run_sync(_run_migration)
+
+    async def _auto_migrate_check_constraints(self) -> None:
+        """
+        Automatically update CHECK constraints for workflow status.
+
+        This method ensures the valid_status CHECK constraint includes all
+        required status values (including 'waiting_for_message').
+        """
+        dialect_name = self.engine.dialect.name
+
+        # SQLite doesn't support ALTER CONSTRAINT easily, and SQLAlchemy create_all
+        # handles it correctly for new databases. For existing SQLite databases,
+        # the constraint is more lenient (CHECK is not enforced in many SQLite versions).
+        if dialect_name == "sqlite":
+            return
+
+        # Expected status values (must match WorkflowInstance model)
+        expected_statuses = (
+            "'running', 'completed', 'failed', 'waiting_for_event', "
+            "'waiting_for_timer', 'waiting_for_message', 'compensating', 'cancelled', 'recurred'"
+        )
+
+        def _run_constraint_migration(conn: Any) -> None:
+            """Run CHECK constraint migration in sync context."""
+            inspector = inspect(conn)
+
+            # Check if workflow_instances table exists
+            if not inspector.has_table("workflow_instances"):
+                return
+
+            # Get existing CHECK constraints
+            try:
+                constraints = inspector.get_check_constraints("workflow_instances")
+            except NotImplementedError:
+                # Some databases don't support get_check_constraints
+                logger.debug("Database doesn't support get_check_constraints inspection")
+                constraints = []
+
+            # Find the valid_status constraint
+            valid_status_constraint = None
+            for constraint in constraints:
+                if constraint.get("name") == "valid_status":
+                    valid_status_constraint = constraint
+                    break
+
+            # Check if constraint exists and needs updating
+            if valid_status_constraint:
+                sqltext = valid_status_constraint.get("sqltext", "")
+                # Check if 'waiting_for_message' is already in the constraint
+                if "waiting_for_message" in sqltext:
+                    logger.debug("valid_status constraint already includes waiting_for_message")
+                    return
+
+                # Need to update the constraint
+                logger.info("Updating valid_status CHECK constraint to include waiting_for_message")
+                try:
+                    if dialect_name == "postgresql":
+                        conn.execute(
+                            text("ALTER TABLE workflow_instances DROP CONSTRAINT valid_status")
+                        )
+                        conn.execute(
+                            text(
+                                f"ALTER TABLE workflow_instances ADD CONSTRAINT valid_status "
+                                f"CHECK (status IN ({expected_statuses}))"
+                            )
+                        )
+                    elif dialect_name == "mysql":
+                        # MySQL uses DROP CHECK and ADD CONSTRAINT CHECK syntax
+                        conn.execute(text("ALTER TABLE workflow_instances DROP CHECK valid_status"))
+                        conn.execute(
+                            text(
+                                f"ALTER TABLE workflow_instances ADD CONSTRAINT valid_status "
+                                f"CHECK (status IN ({expected_statuses}))"
+                            )
+                        )
+                    logger.info("Successfully updated valid_status CHECK constraint")
+                except Exception as e:
+                    logger.warning(f"Failed to update valid_status CHECK constraint: {e}")
+            else:
+                # Constraint doesn't exist (shouldn't happen with create_all, but handle it)
+                logger.debug("valid_status constraint not found, will be created by create_all")
+
+        async with self.engine.begin() as conn:
+            await conn.run_sync(_run_constraint_migration)
+
     def _get_session_for_operation(self, is_lock_operation: bool = False) -> AsyncSession:
         """
         Get the appropriate session for an operation.
@@ -452,7 +839,7 @@ class SQLAlchemyStorage:
         Example:
             >>> # SQLite: datetime(timeout_at) <= datetime('now')
             >>> # PostgreSQL/MySQL: timeout_at <= NOW()
-            >>> self._make_datetime_comparable(WorkflowEventSubscription.timeout_at)
+            >>> self._make_datetime_comparable(ChannelSubscription.timeout_at)
             >>>     <= self._get_current_time_expr()
         """
         if self.engine.dialect.name == "sqlite":
@@ -504,11 +891,16 @@ class SQLAlchemyStorage:
         if ctx is None or ctx.depth == 0:
             raise RuntimeError("Not in a transaction")
 
+        # Capture callbacks before any state changes
+        callbacks_to_execute: list[Callable[[], Awaitable[None]]] = []
+
         if ctx.depth == 1:
             # Top-level transaction - commit the session
             logger.debug("Committing top-level transaction")
             await ctx.session.commit()  # type: ignore[union-attr]
             await ctx.session.close()  # type: ignore[union-attr]
+            # Capture callbacks to execute after clearing context
+            callbacks_to_execute = ctx.post_commit_callbacks.copy()
         else:
             # Nested transaction - commit the savepoint
             nested_tx = ctx.savepoint_stack.pop()
@@ -520,6 +912,12 @@ class SQLAlchemyStorage:
         if ctx.depth == 0:
             # All transactions completed - clear context
             _transaction_context.set(None)
+            # Execute post-commit callbacks after successful top-level commit
+            for callback in callbacks_to_execute:
+                try:
+                    await callback()
+                except Exception as e:
+                    logger.error(f"Post-commit callback failed: {e}")
 
     async def rollback_transaction(self) -> None:
         """
@@ -559,6 +957,26 @@ class SQLAlchemyStorage:
         ctx = _transaction_context.get()
         return ctx is not None and ctx.depth > 0
 
+    def register_post_commit_callback(self, callback: Callable[[], Awaitable[None]]) -> None:
+        """
+        Register a callback to be executed after the current transaction commits.
+
+        The callback will be executed after the top-level transaction commits successfully.
+        If the transaction is rolled back, the callback will NOT be executed.
+        If not in a transaction, the callback will be executed immediately.
+
+        Args:
+            callback: An async function to call after commit.
+
+        Raises:
+            RuntimeError: If not in a transaction.
+        """
+        ctx = _transaction_context.get()
+        if ctx is None or ctx.depth == 0:
+            raise RuntimeError("Cannot register post-commit callback: not in a transaction")
+        ctx.post_commit_callbacks.append(callback)
+        logger.debug(f"Registered post-commit callback: {callback}")
+
     async def _commit_if_not_in_transaction(self, session: AsyncSession) -> None:
         """
         Commit session if not in a transaction (auto-commit mode).
@@ -605,7 +1023,7 @@ class SQLAlchemyStorage:
 
             if existing:
                 # Update
-                existing.source_code = source_code  # type: ignore[assignment]
+                existing.source_code = source_code
             else:
                 # Insert
                 definition = WorkflowDefinition(
@@ -682,6 +1100,7 @@ class SQLAlchemyStorage:
         owner_service: str,
         input_data: dict[str, Any],
         lock_timeout_seconds: int | None = None,
+        continued_from: str | None = None,
     ) -> None:
         """Create a new workflow instance."""
         session = self._get_session_for_operation()
@@ -693,6 +1112,7 @@ class SQLAlchemyStorage:
                 owner_service=owner_service,
                 input_data=json.dumps(input_data),
                 lock_timeout_seconds=lock_timeout_seconds,
+                continued_from=continued_from,
             )
             session.add(instance)
 
@@ -1165,6 +1585,103 @@ class SQLAlchemyStorage:
             await session.commit()
             return workflows_to_resume
 
+    # -------------------------------------------------------------------------
+    # System-level Locking Methods (for background task coordination)
+    # -------------------------------------------------------------------------
+
+    async def try_acquire_system_lock(
+        self,
+        lock_name: str,
+        worker_id: str,
+        timeout_seconds: int = 60,
+    ) -> bool:
+        """
+        Try to acquire a system-level lock for coordinating background tasks.
+
+        Uses INSERT ON CONFLICT pattern to handle race conditions:
+        1. Try to INSERT new lock record
+        2. If exists, check if expired or unlocked
+        3. If available, acquire lock; otherwise return False
+
+        Note: ALWAYS uses separate session (not external session).
+        """
+        session = self._get_session_for_operation(is_lock_operation=True)
+        async with self._session_scope(session) as session:
+            current_time = datetime.now(UTC)
+            lock_expires_at = current_time + timedelta(seconds=timeout_seconds)
+
+            # Try to get existing lock
+            result = await session.execute(
+                select(SystemLock).where(SystemLock.lock_name == lock_name)
+            )
+            lock = result.scalar_one_or_none()
+
+            if lock is None:
+                # No lock exists - create new one
+                lock = SystemLock(
+                    lock_name=lock_name,
+                    locked_by=worker_id,
+                    locked_at=current_time,
+                    lock_expires_at=lock_expires_at,
+                )
+                session.add(lock)
+                await session.commit()
+                return True
+
+            # Lock exists - check if available
+            if lock.locked_by is None:
+                # Unlocked - acquire
+                lock.locked_by = worker_id
+                lock.locked_at = current_time
+                lock.lock_expires_at = lock_expires_at
+                await session.commit()
+                return True
+
+            # Check if expired (use SQL-side comparison for cross-DB compatibility)
+            if lock.lock_expires_at is not None:
+                # Handle timezone-naive datetime from SQLite
+                lock_expires = (
+                    lock.lock_expires_at.replace(tzinfo=UTC)
+                    if lock.lock_expires_at.tzinfo is None
+                    else lock.lock_expires_at
+                )
+                if lock_expires <= current_time:
+                    # Expired - acquire
+                    lock.locked_by = worker_id
+                    lock.locked_at = current_time
+                    lock.lock_expires_at = lock_expires_at
+                    await session.commit()
+                    return True
+
+            # Already locked by another worker
+            return False
+
+    async def release_system_lock(self, lock_name: str, worker_id: str) -> None:
+        """
+        Release a system-level lock.
+
+        Only releases the lock if it's held by the specified worker.
+
+        Note: ALWAYS uses separate session (not external session).
+        """
+        session = self._get_session_for_operation(is_lock_operation=True)
+        async with self._session_scope(session) as session:
+            await session.execute(
+                update(SystemLock)
+                .where(
+                    and_(
+                        SystemLock.lock_name == lock_name,
+                        SystemLock.locked_by == worker_id,
+                    )
+                )
+                .values(
+                    locked_by=None,
+                    locked_at=None,
+                    lock_expires_at=None,
+                )
+            )
+            await session.commit()
+
     # -------------------------------------------------------------------------
     # History Methods (prefer external session)
     # -------------------------------------------------------------------------
@@ -1231,6 +1748,107 @@ class SQLAlchemyStorage:
                 for row in rows
             ]
 
+    async def archive_history(self, instance_id: str) -> int:
+        """
+        Archive workflow history for the recur pattern.
+
+        Moves all history entries from workflow_history to workflow_history_archive.
+        Binary data is converted to base64 for JSON storage in the archive.
+
+        Returns:
+            Number of history entries archived
+        """
+        import base64
+
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Get all history entries for this instance
+            result = await session.execute(
+                select(WorkflowHistory)
+                .where(WorkflowHistory.instance_id == instance_id)
+                .order_by(WorkflowHistory.created_at.asc())
+            )
+            history_rows = result.scalars().all()
+
+            if not history_rows:
+                return 0
+
+            # Archive each history entry
+            for row in history_rows:
+                # Convert event_data to JSON string for archive
+                event_data_json: str | None
+                if row.data_type == "binary" and row.event_data_binary is not None:
+                    # Convert binary to base64 for JSON storage
+                    event_data_json = json.dumps(
+                        {
+                            "_binary": True,
+                            "data": base64.b64encode(row.event_data_binary).decode("ascii"),
+                        }
+                    )
+                else:
+                    # Already JSON, use as-is
+                    event_data_json = row.event_data
+
+                archive_entry = WorkflowHistoryArchive(
+                    instance_id=row.instance_id,
+                    activity_id=row.activity_id,
+                    event_type=row.event_type,
+                    event_data=event_data_json,
+                    created_at=row.created_at,
+                )
+                session.add(archive_entry)
+
+            # Delete original history entries
+            await session.execute(
+                delete(WorkflowHistory).where(WorkflowHistory.instance_id == instance_id)
+            )
+
+            await self._commit_if_not_in_transaction(session)
+            return len(history_rows)
+
+    async def find_first_cancellation_event(self, instance_id: str) -> dict[str, Any] | None:
+        """
+        Find the first cancellation event in workflow history.
+
+        Uses LIMIT 1 optimization to avoid loading all history events.
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Query for cancellation events using LIMIT 1
+            result = await session.execute(
+                select(WorkflowHistory)
+                .where(
+                    and_(
+                        WorkflowHistory.instance_id == instance_id,
+                        or_(
+                            WorkflowHistory.event_type == "WorkflowCancelled",
+                            func.lower(WorkflowHistory.event_type).contains("cancel"),
+                        ),
+                    )
+                )
+                .order_by(WorkflowHistory.created_at.asc())
+                .limit(1)
+            )
+            row = result.scalars().first()
+
+            if row is None:
+                return None
+
+            # Parse event_data based on data_type
+            if row.data_type == "binary" and row.event_data_binary is not None:
+                event_data: dict[str, Any] | bytes = row.event_data_binary
+            else:
+                event_data = json.loads(row.event_data) if row.event_data else {}
+
+            return {
+                "id": row.id,
+                "instance_id": row.instance_id,
+                "activity_id": row.activity_id,
+                "event_type": row.event_type,
+                "event_data": event_data,
+                "created_at": row.created_at,
+            }
+
     # -------------------------------------------------------------------------
     # Compensation Methods (prefer external session)
     # -------------------------------------------------------------------------
@@ -1271,7 +1889,7 @@ class SQLAlchemyStorage:
                     "instance_id": row.instance_id,
                     "activity_id": row.activity_id,
                     "activity_name": row.activity_name,
-                    "args": json.loads(row.args),  # type: ignore[arg-type]
+                    "args": json.loads(row.args) if row.args else [],
                     "created_at": row.created_at.isoformat(),
                 }
                 for row in rows
@@ -1287,224 +1905,25 @@ class SQLAlchemyStorage:
             await self._commit_if_not_in_transaction(session)
 
     # -------------------------------------------------------------------------
-    # Event Subscription Methods (prefer external session for registration)
+    # Timer Subscription Methods
     # -------------------------------------------------------------------------
 
-    async def add_event_subscription(
+    async def register_timer_subscription_and_release_lock(
         self,
         instance_id: str,
-        event_type: str,
-        timeout_at: datetime | None = None,
+        worker_id: str,
+        timer_id: str,
+        expires_at: datetime,
+        activity_id: str | None = None,
     ) -> None:
-        """Register an event wait subscription."""
-        session = self._get_session_for_operation()
-        async with self._session_scope(session) as session:
-            subscription = WorkflowEventSubscription(
-                instance_id=instance_id,
-                event_type=event_type,
-                timeout_at=timeout_at,
-            )
-            session.add(subscription)
-            await self._commit_if_not_in_transaction(session)
+        """
+        Atomically register timer subscription and release workflow lock.
 
-    async def find_waiting_instances(self, event_type: str) -> list[dict[str, Any]]:
-        """Find workflow instances waiting for a specific event type."""
-        session = self._get_session_for_operation()
-        async with self._session_scope(session) as session:
-            result = await session.execute(
-                select(WorkflowEventSubscription).where(
-                    and_(
-                        WorkflowEventSubscription.event_type == event_type,
-                        or_(
-                            WorkflowEventSubscription.timeout_at.is_(None),
-                            self._make_datetime_comparable(WorkflowEventSubscription.timeout_at)
-                            > self._get_current_time_expr(),
-                        ),
-                    )
-                )
-            )
-            rows = result.scalars().all()
-
-            return [
-                {
-                    "id": row.id,
-                    "instance_id": row.instance_id,
-                    "event_type": row.event_type,
-                    "activity_id": row.activity_id,
-                    "timeout_at": row.timeout_at.isoformat() if row.timeout_at else None,
-                    "created_at": row.created_at.isoformat(),
-                }
-                for row in rows
-            ]
-
-    async def remove_event_subscription(
-        self,
-        instance_id: str,
-        event_type: str,
-    ) -> None:
-        """Remove event subscription after the event is received."""
-        session = self._get_session_for_operation()
-        async with self._session_scope(session) as session:
-            await session.execute(
-                delete(WorkflowEventSubscription).where(
-                    and_(
-                        WorkflowEventSubscription.instance_id == instance_id,
-                        WorkflowEventSubscription.event_type == event_type,
-                    )
-                )
-            )
-            await self._commit_if_not_in_transaction(session)
-
-    async def cleanup_expired_subscriptions(self) -> int:
-        """Clean up event subscriptions that have timed out."""
-        session = self._get_session_for_operation()
-        async with self._session_scope(session) as session:
-            result = await session.execute(
-                delete(WorkflowEventSubscription).where(
-                    and_(
-                        WorkflowEventSubscription.timeout_at.isnot(None),
-                        self._make_datetime_comparable(WorkflowEventSubscription.timeout_at)
-                        <= self._get_current_time_expr(),
-                    )
-                )
-            )
-            await self._commit_if_not_in_transaction(session)
-            return result.rowcount or 0  # type: ignore[attr-defined]
-
-    async def find_expired_event_subscriptions(self) -> list[dict[str, Any]]:
-        """Find event subscriptions that have timed out."""
-        session = self._get_session_for_operation()
-        async with self._session_scope(session) as session:
-            result = await session.execute(
-                select(
-                    WorkflowEventSubscription.instance_id,
-                    WorkflowEventSubscription.event_type,
-                    WorkflowEventSubscription.activity_id,
-                    WorkflowEventSubscription.timeout_at,
-                    WorkflowEventSubscription.created_at,
-                ).where(
-                    and_(
-                        WorkflowEventSubscription.timeout_at.isnot(None),
-                        self._make_datetime_comparable(WorkflowEventSubscription.timeout_at)
-                        <= self._get_current_time_expr(),
-                    )
-                )
-            )
-            rows = result.all()
-
-            return [
-                {
-                    "instance_id": row[0],
-                    "event_type": row[1],
-                    "activity_id": row[2],
-                    "timeout_at": row[3].isoformat() if row[3] else None,
-                    "created_at": row[4].isoformat() if row[4] else None,
-                }
-                for row in rows
-            ]
-
-    async def register_event_subscription_and_release_lock(
-        self,
-        instance_id: str,
-        worker_id: str,
-        event_type: str,
-        timeout_at: datetime | None = None,
-        activity_id: str | None = None,
-    ) -> None:
-        """
-        Atomically register event subscription and release workflow lock.
-
-        This performs THREE operations in a SINGLE transaction:
-        1. Register event subscription
-        2. Update current activity
-        3. Release lock
-
-        This ensures distributed coroutines work correctly - when a workflow
-        calls wait_event(), the subscription is registered and lock is released
-        atomically, so ANY worker can resume the workflow when the event arrives.
-
-        Note: Uses LOCK operation session (separate from external session).
-        """
-        session = self._get_session_for_operation(is_lock_operation=True)
-        async with self._session_scope(session) as session, session.begin():
-            # 1. Verify we hold the lock (sanity check)
-            result = await session.execute(
-                select(WorkflowInstance.locked_by).where(
-                    WorkflowInstance.instance_id == instance_id
-                )
-            )
-            row = result.one_or_none()
-
-            if row is None:
-                raise RuntimeError(f"Workflow instance {instance_id} not found")
-
-            current_lock_holder = row[0]
-            if current_lock_holder != worker_id:
-                raise RuntimeError(
-                    f"Cannot release lock: worker {worker_id} does not hold lock "
-                    f"for {instance_id} (held by: {current_lock_holder})"
-                )
-
-            # 2. Register event subscription (INSERT OR REPLACE equivalent)
-            # First delete existing
-            await session.execute(
-                delete(WorkflowEventSubscription).where(
-                    and_(
-                        WorkflowEventSubscription.instance_id == instance_id,
-                        WorkflowEventSubscription.event_type == event_type,
-                    )
-                )
-            )
-
-            # Then insert new
-            subscription = WorkflowEventSubscription(
-                instance_id=instance_id,
-                event_type=event_type,
-                activity_id=activity_id,
-                timeout_at=timeout_at,
-            )
-            session.add(subscription)
-
-            # 3. Update current activity (if provided)
-            if activity_id is not None:
-                await session.execute(
-                    update(WorkflowInstance)
-                    .where(WorkflowInstance.instance_id == instance_id)
-                    .values(current_activity_id=activity_id, updated_at=func.now())
-                )
-
-            # 4. Release lock
-            await session.execute(
-                update(WorkflowInstance)
-                .where(
-                    and_(
-                        WorkflowInstance.instance_id == instance_id,
-                        WorkflowInstance.locked_by == worker_id,
-                    )
-                )
-                .values(
-                    locked_by=None,
-                    locked_at=None,
-                    updated_at=func.now(),
-                )
-            )
-
-    async def register_timer_subscription_and_release_lock(
-        self,
-        instance_id: str,
-        worker_id: str,
-        timer_id: str,
-        expires_at: datetime,
-        activity_id: str | None = None,
-    ) -> None:
-        """
-        Atomically register timer subscription and release workflow lock.
-
-        This performs FOUR operations in a SINGLE transaction:
-        1. Register timer subscription
-        2. Update current activity
-        3. Update status to 'waiting_for_timer'
-        4. Release lock
+        This performs FOUR operations in a SINGLE transaction:
+        1. Register timer subscription
+        2. Update current activity
+        3. Update status to 'waiting_for_timer'
+        4. Release lock
 
         This ensures distributed coroutines work correctly - when a workflow
         calls wait_timer(), the subscription is registered and lock is released
@@ -1580,7 +1999,11 @@ class SQLAlchemyStorage:
             )
 
     async def find_expired_timers(self) -> list[dict[str, Any]]:
-        """Find timer subscriptions that have expired."""
+        """Find timer subscriptions that have expired.
+
+        Returns timer info including workflow status to avoid N+1 queries.
+        The SQL query already filters by status='waiting_for_timer'.
+        """
         session = self._get_session_for_operation()
         async with self._session_scope(session) as session:
             result = await session.execute(
@@ -1590,6 +2013,7 @@ class SQLAlchemyStorage:
                     WorkflowTimerSubscription.expires_at,
                     WorkflowTimerSubscription.activity_id,
                     WorkflowInstance.workflow_name,
+                    WorkflowInstance.status,  # Include status to avoid N+1 query
                 )
                 .join(
                     WorkflowInstance,
@@ -1612,6 +2036,7 @@ class SQLAlchemyStorage:
                     "expires_at": row[2].isoformat(),
                     "activity_id": row[3],
                     "workflow_name": row[4],
+                    "status": row[5],  # Always 'waiting_for_timer' due to WHERE clause
                 }
                 for row in rows
             ]
@@ -1831,12 +2256,17 @@ class SQLAlchemyStorage:
         Only running or waiting_for_event workflows can be cancelled.
         This method atomically:
         1. Checks current status
-        2. Updates status to 'cancelled' if allowed
+        2. Updates status to 'cancelled' if allowed (with atomic status check)
         3. Clears locks
         4. Records cancellation metadata
         5. Removes event subscriptions (if waiting for event)
         6. Removes timer subscriptions (if waiting for timer)
 
+        The UPDATE includes a status condition in WHERE clause to prevent
+        TOCTOU (time-of-check to time-of-use) race conditions. If the status
+        changes between SELECT and UPDATE, the UPDATE will affect 0 rows
+        and the cancellation will fail safely.
+
         Args:
             instance_id: Workflow instance to cancel
             cancelled_by: Who/what triggered the cancellation
@@ -1846,6 +2276,14 @@ class SQLAlchemyStorage:
 
         Note: Uses LOCK operation session (separate from external session).
         """
+        cancellable_statuses = (
+            "running",
+            "waiting_for_event",
+            "waiting_for_timer",
+            "waiting_for_message",
+            "compensating",
+        )
+
         session = self._get_session_for_operation(is_lock_operation=True)
         async with self._session_scope(session) as session, session.begin():
             # Get current instance status
@@ -1862,41 +2300,42 @@ class SQLAlchemyStorage:
 
             # Only allow cancellation of running, waiting, or compensating workflows
             # compensating workflows can be marked as cancelled after compensation completes
-            if current_status not in (
-                "running",
-                "waiting_for_event",
-                "waiting_for_timer",
-                "compensating",
-            ):
+            if current_status not in cancellable_statuses:
                 # Already completed, failed, or cancelled
                 return False
 
             # Update status to cancelled and record metadata
+            # IMPORTANT: Include status condition in WHERE clause to prevent TOCTOU race
+            # If another worker changed the status between SELECT and UPDATE,
+            # this UPDATE will affect 0 rows and we'll return False
             cancellation_metadata = {
                 "cancelled_by": cancelled_by,
                 "cancelled_at": datetime.now(UTC).isoformat(),
                 "previous_status": current_status,
             }
 
-            await session.execute(
+            update_result = await session.execute(
                 update(WorkflowInstance)
-                .where(WorkflowInstance.instance_id == instance_id)
+                .where(
+                    and_(
+                        WorkflowInstance.instance_id == instance_id,
+                        WorkflowInstance.status == current_status,  # Atomic check
+                    )
+                )
                 .values(
                     status="cancelled",
                     output_data=json.dumps(cancellation_metadata),
                     locked_by=None,
                     locked_at=None,
+                    lock_expires_at=None,
                     updated_at=func.now(),
                 )
             )
 
-            # Remove event subscriptions if waiting for event
-            if current_status == "waiting_for_event":
-                await session.execute(
-                    delete(WorkflowEventSubscription).where(
-                        WorkflowEventSubscription.instance_id == instance_id
-                    )
-                )
+            if update_result.rowcount == 0:  # type: ignore[attr-defined]
+                # Status changed between SELECT and UPDATE (race condition)
+                # Another worker may have resumed/modified the workflow
+                return False
 
             # Remove timer subscriptions if waiting for timer
             if current_status == "waiting_for_timer":
@@ -1906,4 +2345,1103 @@ class SQLAlchemyStorage:
                     )
                 )
 
+            # Clear channel subscriptions if waiting for event/message
+            if current_status in ("waiting_for_event", "waiting_for_message"):
+                await session.execute(
+                    update(ChannelSubscription)
+                    .where(ChannelSubscription.instance_id == instance_id)
+                    .values(activity_id=None, timeout_at=None)
+                )
+
             return True
+
+    # -------------------------------------------------------------------------
+    # Message Subscription Methods
+    # -------------------------------------------------------------------------
+
+    async def find_waiting_instances_by_channel(self, channel: str) -> list[dict[str, Any]]:
+        """
+        Find all workflow instances waiting on a specific channel.
+
+        Args:
+            channel: Channel name to search for
+
+        Returns:
+            List of subscription info dicts with instance_id, channel, activity_id, timeout_at
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Query ChannelSubscription table for waiting instances
+            result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.channel == channel,
+                        ChannelSubscription.activity_id.isnot(None),  # Only waiting subscriptions
+                    )
+                )
+            )
+            subscriptions = result.scalars().all()
+            return [
+                {
+                    "instance_id": sub.instance_id,
+                    "channel": sub.channel,
+                    "activity_id": sub.activity_id,
+                    "timeout_at": sub.timeout_at.isoformat() if sub.timeout_at else None,
+                    "created_at": sub.subscribed_at.isoformat() if sub.subscribed_at else None,
+                }
+                for sub in subscriptions
+            ]
+
+    async def remove_message_subscription(
+        self,
+        instance_id: str,
+        channel: str,
+    ) -> None:
+        """
+        Remove a message subscription.
+
+        This method clears waiting state from the ChannelSubscription table.
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Clear waiting state from ChannelSubscription table
+            # Don't delete the subscription - just clear the waiting state
+            await session.execute(
+                update(ChannelSubscription)
+                .where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+                .values(activity_id=None, timeout_at=None)
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def deliver_message(
+        self,
+        instance_id: str,
+        channel: str,
+        data: dict[str, Any] | bytes,
+        metadata: dict[str, Any],
+        worker_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Deliver a message to a waiting workflow using Lock-First pattern.
+
+        This method:
+        1. Checks if there's a subscription for this instance/channel
+        2. Acquires lock (Lock-First pattern) - if worker_id provided
+        3. Records the message in history
+        4. Removes the subscription
+        5. Updates status to 'running'
+        6. Releases lock
+
+        Args:
+            instance_id: Target workflow instance ID
+            channel: Channel name
+            data: Message payload (dict or bytes)
+            metadata: Message metadata
+            worker_id: Worker ID for locking. If None, skip locking (legacy mode).
+
+        Returns:
+            Dict with delivery info if successful, None otherwise
+        """
+        import uuid
+
+        # Step 1: Check if subscription exists (without lock)
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                        ChannelSubscription.activity_id.isnot(None),  # Only waiting subscriptions
+                    )
+                )
+            )
+            subscription = result.scalar_one_or_none()
+
+            if subscription is None:
+                return None
+
+            activity_id = subscription.activity_id
+
+        # Step 2: Acquire lock (Lock-First pattern) if worker_id provided
+        lock_acquired = False
+        if worker_id is not None:
+            lock_acquired = await self.try_acquire_lock(instance_id, worker_id)
+            if not lock_acquired:
+                # Another worker is processing this workflow
+                return None
+
+        try:
+            # Step 3-5: Deliver message atomically
+            session = self._get_session_for_operation()
+            async with self._session_scope(session) as session:
+                # Re-check subscription (may have been removed by another worker)
+                result = await session.execute(
+                    select(ChannelSubscription).where(
+                        and_(
+                            ChannelSubscription.instance_id == instance_id,
+                            ChannelSubscription.channel == channel,
+                            ChannelSubscription.activity_id.isnot(
+                                None
+                            ),  # Only waiting subscriptions
+                        )
+                    )
+                )
+                subscription = result.scalar_one_or_none()
+
+                if subscription is None:
+                    # Already delivered by another worker
+                    return None
+
+                activity_id = subscription.activity_id
+
+                # Get workflow info for return value
+                instance_result = await session.execute(
+                    select(WorkflowInstance).where(WorkflowInstance.instance_id == instance_id)
+                )
+                instance = instance_result.scalar_one_or_none()
+                workflow_name = instance.workflow_name if instance else "unknown"
+
+                # Build message data for history
+                message_id = str(uuid.uuid4())
+                message_data = {
+                    "id": message_id,
+                    "channel": channel,
+                    "data": data if isinstance(data, dict) else None,
+                    "metadata": metadata,
+                }
+
+                # Handle binary data
+                if isinstance(data, bytes):
+                    data_type = "binary"
+                    event_data_json = None
+                    event_data_binary = data
+                else:
+                    data_type = "json"
+                    event_data_json = json.dumps(message_data)
+                    event_data_binary = None
+
+                # Record in history
+                history_entry = WorkflowHistory(
+                    instance_id=instance_id,
+                    activity_id=activity_id,
+                    event_type="ChannelMessageReceived",
+                    data_type=data_type,
+                    event_data=event_data_json,
+                    event_data_binary=event_data_binary,
+                )
+                session.add(history_entry)
+
+                # Clear waiting state from subscription (don't delete)
+                await session.execute(
+                    update(ChannelSubscription)
+                    .where(
+                        and_(
+                            ChannelSubscription.instance_id == instance_id,
+                            ChannelSubscription.channel == channel,
+                        )
+                    )
+                    .values(activity_id=None, timeout_at=None)
+                )
+
+                # Update status to 'running' (ready for resumption)
+                await session.execute(
+                    update(WorkflowInstance)
+                    .where(WorkflowInstance.instance_id == instance_id)
+                    .values(status="running", updated_at=func.now())
+                )
+
+                await self._commit_if_not_in_transaction(session)
+
+                return {
+                    "instance_id": instance_id,
+                    "workflow_name": workflow_name,
+                    "activity_id": activity_id,
+                }
+
+        finally:
+            # Step 6: Release lock if we acquired it
+            if lock_acquired and worker_id is not None:
+                await self.release_lock(instance_id, worker_id)
+
+    async def find_expired_message_subscriptions(self) -> list[dict[str, Any]]:
+        """
+        Find all message subscriptions that have timed out.
+
+        JOINs with WorkflowInstance to ensure instance exists and avoid N+1 queries.
+
+        Returns:
+            List of dicts with instance_id, channel, activity_id, timeout_at, created_at, workflow_name
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Query ChannelSubscription table with JOIN
+            result = await session.execute(
+                select(
+                    ChannelSubscription.instance_id,
+                    ChannelSubscription.channel,
+                    ChannelSubscription.activity_id,
+                    ChannelSubscription.timeout_at,
+                    ChannelSubscription.subscribed_at,
+                    WorkflowInstance.workflow_name,
+                )
+                .join(
+                    WorkflowInstance,
+                    ChannelSubscription.instance_id == WorkflowInstance.instance_id,
+                )
+                .where(
+                    and_(
+                        ChannelSubscription.timeout_at.isnot(None),
+                        ChannelSubscription.activity_id.isnot(None),  # Only waiting subscriptions
+                        self._make_datetime_comparable(ChannelSubscription.timeout_at)
+                        <= self._get_current_time_expr(),
+                    )
+                )
+            )
+            rows = result.all()
+            return [
+                {
+                    "instance_id": row[0],
+                    "channel": row[1],
+                    "activity_id": row[2],
+                    "timeout_at": row[3],
+                    "created_at": row[4],  # subscribed_at as created_at for compatibility
+                    "workflow_name": row[5],
+                }
+                for row in rows
+            ]
+
+    # -------------------------------------------------------------------------
+    # Group Membership Methods (Erlang pg style)
+    # -------------------------------------------------------------------------
+
+    async def join_group(self, instance_id: str, group_name: str) -> None:
+        """
+        Add a workflow instance to a group.
+
+        Groups provide loose coupling for broadcast messaging.
+        Idempotent - joining a group the instance is already in is a no-op.
+
+        Args:
+            instance_id: Workflow instance ID
+            group_name: Group to join
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Check if already a member (for idempotency)
+            result = await session.execute(
+                select(WorkflowGroupMembership).where(
+                    and_(
+                        WorkflowGroupMembership.instance_id == instance_id,
+                        WorkflowGroupMembership.group_name == group_name,
+                    )
+                )
+            )
+            if result.scalar_one_or_none() is not None:
+                # Already a member, nothing to do
+                return
+
+            # Add membership
+            membership = WorkflowGroupMembership(
+                instance_id=instance_id,
+                group_name=group_name,
+            )
+            session.add(membership)
+            await self._commit_if_not_in_transaction(session)
+
+    async def leave_group(self, instance_id: str, group_name: str) -> None:
+        """
+        Remove a workflow instance from a group.
+
+        Args:
+            instance_id: Workflow instance ID
+            group_name: Group to leave
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            await session.execute(
+                delete(WorkflowGroupMembership).where(
+                    and_(
+                        WorkflowGroupMembership.instance_id == instance_id,
+                        WorkflowGroupMembership.group_name == group_name,
+                    )
+                )
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def get_group_members(self, group_name: str) -> list[str]:
+        """
+        Get all workflow instances in a group.
+
+        Args:
+            group_name: Group name
+
+        Returns:
+            List of instance IDs in the group
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(WorkflowGroupMembership.instance_id).where(
+                    WorkflowGroupMembership.group_name == group_name
+                )
+            )
+            return [row[0] for row in result.fetchall()]
+
+    async def leave_all_groups(self, instance_id: str) -> None:
+        """
+        Remove a workflow instance from all groups.
+
+        Called automatically when a workflow completes or fails.
+
+        Args:
+            instance_id: Workflow instance ID
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            await session.execute(
+                delete(WorkflowGroupMembership).where(
+                    WorkflowGroupMembership.instance_id == instance_id
+                )
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    # -------------------------------------------------------------------------
+    # Workflow Resumption Methods
+    # -------------------------------------------------------------------------
+
+    async def find_resumable_workflows(self) -> list[dict[str, Any]]:
+        """
+        Find workflows that are ready to be resumed.
+
+        Returns workflows with status='running' that don't have an active lock.
+        Used for immediate resumption after message delivery.
+
+        Returns:
+            List of resumable workflows with instance_id and workflow_name.
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(
+                    WorkflowInstance.instance_id,
+                    WorkflowInstance.workflow_name,
+                ).where(
+                    and_(
+                        WorkflowInstance.status == "running",
+                        WorkflowInstance.locked_by.is_(None),
+                    )
+                )
+            )
+            return [
+                {
+                    "instance_id": row.instance_id,
+                    "workflow_name": row.workflow_name,
+                }
+                for row in result.fetchall()
+            ]
+
+    # -------------------------------------------------------------------------
+    # Subscription Cleanup Methods (for recur())
+    # -------------------------------------------------------------------------
+
+    async def cleanup_instance_subscriptions(self, instance_id: str) -> None:
+        """
+        Remove all subscriptions for a workflow instance.
+
+        Called during recur() to clean up event/timer/message subscriptions
+        before archiving the history.
+
+        Args:
+            instance_id: Workflow instance ID to clean up
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Remove timer subscriptions
+            await session.execute(
+                delete(WorkflowTimerSubscription).where(
+                    WorkflowTimerSubscription.instance_id == instance_id
+                )
+            )
+
+            # Remove channel subscriptions
+            await session.execute(
+                delete(ChannelSubscription).where(ChannelSubscription.instance_id == instance_id)
+            )
+
+            # Remove channel message claims
+            await session.execute(
+                delete(ChannelMessageClaim).where(ChannelMessageClaim.instance_id == instance_id)
+            )
+
+            await self._commit_if_not_in_transaction(session)
+
+    # -------------------------------------------------------------------------
+    # Channel-based Message Queue Methods
+    # -------------------------------------------------------------------------
+
+    async def publish_to_channel(
+        self,
+        channel: str,
+        data: dict[str, Any] | bytes,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """
+        Publish a message to a channel.
+
+        Messages are persisted to channel_messages and available for subscribers.
+
+        Args:
+            channel: Channel name
+            data: Message payload (dict or bytes)
+            metadata: Optional message metadata
+
+        Returns:
+            Generated message_id (UUID)
+        """
+        import uuid
+
+        message_id = str(uuid.uuid4())
+
+        # Determine data type and serialize
+        if isinstance(data, bytes):
+            data_type = "binary"
+            data_json = None
+            data_binary = data
+        else:
+            data_type = "json"
+            data_json = json.dumps(data)
+            data_binary = None
+
+        metadata_json = json.dumps(metadata) if metadata else None
+
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            msg = ChannelMessage(
+                channel=channel,
+                message_id=message_id,
+                data_type=data_type,
+                data=data_json,
+                data_binary=data_binary,
+                message_metadata=metadata_json,
+            )
+            session.add(msg)
+            await self._commit_if_not_in_transaction(session)
+
+        return message_id
+
+    async def subscribe_to_channel(
+        self,
+        instance_id: str,
+        channel: str,
+        mode: str,
+    ) -> None:
+        """
+        Subscribe a workflow instance to a channel.
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+            mode: 'broadcast' or 'competing'
+
+        Raises:
+            ValueError: If mode is invalid
+        """
+        if mode not in ("broadcast", "competing"):
+            raise ValueError(f"Invalid mode: {mode}. Must be 'broadcast' or 'competing'")
+
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Check if already subscribed
+            result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+            )
+            existing = result.scalar_one_or_none()
+
+            if existing is not None:
+                # Already subscribed, update mode if different
+                if existing.mode != mode:
+                    existing.mode = mode
+                    await self._commit_if_not_in_transaction(session)
+                return
+
+            # For broadcast mode, set cursor to current max message id
+            # So subscriber only sees messages published after subscription
+            cursor_message_id = None
+            if mode == "broadcast":
+                result = await session.execute(
+                    select(func.max(ChannelMessage.id)).where(ChannelMessage.channel == channel)
+                )
+                max_id = result.scalar()
+                cursor_message_id = max_id if max_id is not None else 0
+
+            # Create subscription
+            subscription = ChannelSubscription(
+                instance_id=instance_id,
+                channel=channel,
+                mode=mode,
+                cursor_message_id=cursor_message_id,
+            )
+            session.add(subscription)
+            await self._commit_if_not_in_transaction(session)
+
+    async def unsubscribe_from_channel(
+        self,
+        instance_id: str,
+        channel: str,
+    ) -> None:
+        """
+        Unsubscribe a workflow instance from a channel.
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            await session.execute(
+                delete(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def get_channel_subscription(
+        self,
+        instance_id: str,
+        channel: str,
+    ) -> dict[str, Any] | None:
+        """
+        Get the subscription info for a workflow instance on a channel.
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+
+        Returns:
+            Subscription info dict with: mode, activity_id, cursor_message_id
+            or None if not subscribed
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+            )
+            subscription = result.scalar_one_or_none()
+
+            if subscription is None:
+                return None
+
+            return {
+                "mode": subscription.mode,
+                "activity_id": subscription.activity_id,
+                "cursor_message_id": subscription.cursor_message_id,
+            }
+
+    async def register_channel_receive_and_release_lock(
+        self,
+        instance_id: str,
+        worker_id: str,
+        channel: str,
+        activity_id: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> None:
+        """
+        Atomically register that workflow is waiting for channel message and release lock.
+
+        Args:
+            instance_id: Workflow instance ID
+            worker_id: Worker ID that currently holds the lock
+            channel: Channel name being waited on
+            activity_id: Current activity ID to record
+            timeout_seconds: Optional timeout in seconds for the message wait
+
+        Raises:
+            RuntimeError: If the worker doesn't hold the lock
+            ValueError: If workflow is not subscribed to the channel
+        """
+        async with self.engine.begin() as conn:
+            session = AsyncSession(bind=conn, expire_on_commit=False)
+
+            # Verify lock ownership
+            result = await session.execute(
+                select(WorkflowInstance).where(WorkflowInstance.instance_id == instance_id)
+            )
+            instance = result.scalar_one_or_none()
+
+            if instance is None:
+                raise RuntimeError(f"Instance not found: {instance_id}")
+
+            if instance.locked_by != worker_id:
+                raise RuntimeError(
+                    f"Worker {worker_id} does not hold lock for {instance_id}. "
+                    f"Locked by: {instance.locked_by}"
+                )
+
+            # Verify subscription exists
+            sub_result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+            )
+            subscription: ChannelSubscription | None = sub_result.scalar_one_or_none()
+
+            if subscription is None:
+                raise ValueError(f"Instance {instance_id} is not subscribed to channel {channel}")
+
+            # Update subscription to mark as waiting
+            current_time = datetime.now(UTC)
+            subscription.activity_id = activity_id
+            # Calculate timeout_at if timeout_seconds is provided
+            if timeout_seconds is not None:
+                subscription.timeout_at = current_time + timedelta(seconds=timeout_seconds)
+            else:
+                subscription.timeout_at = None
+
+            # Update instance: set activity, status, release lock
+            await session.execute(
+                update(WorkflowInstance)
+                .where(WorkflowInstance.instance_id == instance_id)
+                .values(
+                    current_activity_id=activity_id,
+                    status="waiting_for_message",
+                    locked_by=None,
+                    locked_at=None,
+                    lock_expires_at=None,
+                    updated_at=current_time,
+                )
+            )
+
+            await session.commit()
+
+    async def get_pending_channel_messages(
+        self,
+        instance_id: str,
+        channel: str,
+    ) -> list[dict[str, Any]]:
+        """
+        Get pending messages for a subscriber on a channel.
+
+        For broadcast mode: messages with id > cursor_message_id
+        For competing mode: unclaimed messages
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+
+        Returns:
+            List of pending messages
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Get subscription info
+            sub_result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+            )
+            subscription = sub_result.scalar_one_or_none()
+
+            if subscription is None:
+                return []
+
+            if subscription.mode == "broadcast":
+                # Get messages after cursor
+                cursor = subscription.cursor_message_id or 0
+                msg_result = await session.execute(
+                    select(ChannelMessage)
+                    .where(
+                        and_(
+                            ChannelMessage.channel == channel,
+                            ChannelMessage.id > cursor,
+                        )
+                    )
+                    .order_by(ChannelMessage.published_at.asc())
+                )
+            else:  # competing
+                # Get unclaimed messages (not in channel_message_claims)
+                subquery = select(ChannelMessageClaim.message_id)
+                msg_result = await session.execute(
+                    select(ChannelMessage)
+                    .where(
+                        and_(
+                            ChannelMessage.channel == channel,
+                            ChannelMessage.message_id.not_in(subquery),
+                        )
+                    )
+                    .order_by(ChannelMessage.published_at.asc())
+                )
+
+            messages = msg_result.scalars().all()
+            return [
+                {
+                    "id": msg.id,
+                    "message_id": msg.message_id,
+                    "channel": msg.channel,
+                    "data": (
+                        msg.data_binary
+                        if msg.data_type == "binary"
+                        else json.loads(msg.data) if msg.data else {}
+                    ),
+                    "metadata": json.loads(msg.message_metadata) if msg.message_metadata else {},
+                    "published_at": msg.published_at.isoformat() if msg.published_at else None,
+                }
+                for msg in messages
+            ]
+
+    async def claim_channel_message(
+        self,
+        message_id: str,
+        instance_id: str,
+    ) -> bool:
+        """
+        Claim a message for competing consumption.
+
+        Uses INSERT with conflict check to ensure only one subscriber claims.
+
+        Args:
+            message_id: Message ID to claim
+            instance_id: Workflow instance claiming the message
+
+        Returns:
+            True if claim succeeded, False if already claimed
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            try:
+                # Check if already claimed
+                result = await session.execute(
+                    select(ChannelMessageClaim).where(ChannelMessageClaim.message_id == message_id)
+                )
+                if result.scalar_one_or_none() is not None:
+                    return False  # Already claimed
+
+                claim = ChannelMessageClaim(
+                    message_id=message_id,
+                    instance_id=instance_id,
+                )
+                session.add(claim)
+                await self._commit_if_not_in_transaction(session)
+                return True
+            except Exception:
+                return False
+
+    async def delete_channel_message(self, message_id: str) -> None:
+        """
+        Delete a message from the channel queue.
+
+        Args:
+            message_id: Message ID to delete
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Delete claim first (foreign key)
+            await session.execute(
+                delete(ChannelMessageClaim).where(ChannelMessageClaim.message_id == message_id)
+            )
+            # Delete message
+            await session.execute(
+                delete(ChannelMessage).where(ChannelMessage.message_id == message_id)
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def update_delivery_cursor(
+        self,
+        channel: str,
+        instance_id: str,
+        message_id: int,
+    ) -> None:
+        """
+        Update the delivery cursor for broadcast mode.
+
+        Args:
+            channel: Channel name
+            instance_id: Subscriber instance ID
+            message_id: Last delivered message's internal ID
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # Update subscription cursor
+            await session.execute(
+                update(ChannelSubscription)
+                .where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+                .values(cursor_message_id=message_id)
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def get_channel_subscribers_waiting(
+        self,
+        channel: str,
+    ) -> list[dict[str, Any]]:
+        """
+        Get channel subscribers that are waiting (activity_id is set).
+
+        Args:
+            channel: Channel name
+
+        Returns:
+            List of waiting subscribers
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(ChannelSubscription).where(
+                    and_(
+                        ChannelSubscription.channel == channel,
+                        ChannelSubscription.activity_id.isnot(None),
+                    )
+                )
+            )
+            subscriptions = result.scalars().all()
+            return [
+                {
+                    "instance_id": sub.instance_id,
+                    "channel": sub.channel,
+                    "mode": sub.mode,
+                    "activity_id": sub.activity_id,
+                }
+                for sub in subscriptions
+            ]
+
+    async def clear_channel_waiting_state(
+        self,
+        instance_id: str,
+        channel: str,
+    ) -> None:
+        """
+        Clear the waiting state for a channel subscription.
+
+        Args:
+            instance_id: Workflow instance ID
+            channel: Channel name
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            await session.execute(
+                update(ChannelSubscription)
+                .where(
+                    and_(
+                        ChannelSubscription.instance_id == instance_id,
+                        ChannelSubscription.channel == channel,
+                    )
+                )
+                .values(activity_id=None)
+            )
+            await self._commit_if_not_in_transaction(session)
+
+    async def deliver_channel_message(
+        self,
+        instance_id: str,
+        channel: str,
+        message_id: str,
+        data: dict[str, Any] | bytes,
+        metadata: dict[str, Any],
+        worker_id: str,
+    ) -> dict[str, Any] | None:
+        """
+        Deliver a channel message to a waiting workflow.
+
+        Uses Lock-First pattern for distributed safety.
+
+        Args:
+            instance_id: Target workflow instance ID
+            channel: Channel name
+            message_id: Message ID being delivered
+            data: Message payload
+            metadata: Message metadata
+            worker_id: Worker ID for locking
+
+        Returns:
+            Delivery info if successful, None if failed
+        """
+        try:
+            # Try to acquire lock
+            if not await self.try_acquire_lock(instance_id, worker_id):
+                logger.debug(f"Failed to acquire lock for {instance_id}")
+                return None
+
+            try:
+                async with self.engine.begin() as conn:
+                    session = AsyncSession(bind=conn, expire_on_commit=False)
+
+                    # Get subscription info
+                    result = await session.execute(
+                        select(ChannelSubscription).where(
+                            and_(
+                                ChannelSubscription.instance_id == instance_id,
+                                ChannelSubscription.channel == channel,
+                            )
+                        )
+                    )
+                    subscription = result.scalar_one_or_none()
+
+                    if subscription is None or subscription.activity_id is None:
+                        logger.debug(f"No waiting subscription for {instance_id} on {channel}")
+                        return None
+
+                    activity_id = subscription.activity_id
+
+                    # Get instance info for return value
+                    result = await session.execute(
+                        select(WorkflowInstance.workflow_name).where(
+                            WorkflowInstance.instance_id == instance_id
+                        )
+                    )
+                    row = result.one_or_none()
+                    if row is None:
+                        return None
+                    workflow_name = row[0]
+
+                    # Prepare message data for history
+                    # Use "id" key to match what context.py expects when loading history
+                    current_time = datetime.now(UTC)
+                    message_result = {
+                        "id": message_id,
+                        "channel": channel,
+                        "data": data if isinstance(data, dict) else None,
+                        "metadata": metadata,
+                        "published_at": current_time.isoformat(),
+                    }
+
+                    # Record to history
+                    if isinstance(data, bytes):
+                        history = WorkflowHistory(
+                            instance_id=instance_id,
+                            activity_id=activity_id,
+                            event_type="ChannelMessageReceived",
+                            data_type="binary",
+                            event_data=None,
+                            event_data_binary=data,
+                        )
+                    else:
+                        history = WorkflowHistory(
+                            instance_id=instance_id,
+                            activity_id=activity_id,
+                            event_type="ChannelMessageReceived",
+                            data_type="json",
+                            event_data=json.dumps(message_result),
+                            event_data_binary=None,
+                        )
+                    session.add(history)
+
+                    # Handle mode-specific logic
+                    if subscription.mode == "broadcast":
+                        # Get message internal id to update cursor
+                        result = await session.execute(
+                            select(ChannelMessage.id).where(ChannelMessage.message_id == message_id)
+                        )
+                        msg_row = result.one_or_none()
+                        if msg_row:
+                            subscription.cursor_message_id = msg_row[0]
+                    else:  # competing
+                        # Claim and delete the message
+                        claim = ChannelMessageClaim(
+                            message_id=message_id,
+                            instance_id=instance_id,
+                        )
+                        session.add(claim)
+
+                        # Delete the message (competing mode consumes it)
+                        await session.execute(
+                            delete(ChannelMessage).where(ChannelMessage.message_id == message_id)
+                        )
+
+                    # Clear waiting state
+                    subscription.activity_id = None
+
+                    # Update instance status to running
+                    current_time = datetime.now(UTC)
+                    await session.execute(
+                        update(WorkflowInstance)
+                        .where(WorkflowInstance.instance_id == instance_id)
+                        .values(
+                            status="running",
+                            updated_at=current_time,
+                        )
+                    )
+
+                    await session.commit()
+
+                return {
+                    "instance_id": instance_id,
+                    "workflow_name": workflow_name,
+                    "activity_id": activity_id,
+                }
+
+            finally:
+                # Always release lock
+                await self.release_lock(instance_id, worker_id)
+
+        except Exception as e:
+            logger.error(f"Error delivering channel message: {e}")
+            return None
+
+    async def cleanup_old_channel_messages(self, older_than_days: int = 7) -> int:
+        """
+        Clean up old messages from channel queues.
+
+        Args:
+            older_than_days: Message retention period in days
+
+        Returns:
+            Number of messages deleted
+        """
+        cutoff_time = datetime.now(UTC) - timedelta(days=older_than_days)
+
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            # First delete claims for old messages
+            await session.execute(
+                delete(ChannelMessageClaim).where(
+                    ChannelMessageClaim.message_id.in_(
+                        select(ChannelMessage.message_id).where(
+                            self._make_datetime_comparable(ChannelMessage.published_at)
+                            < self._get_current_time_expr()
+                        )
+                    )
+                )
+            )
+
+            # Delete old messages
+            result = await session.execute(
+                delete(ChannelMessage)
+                .where(ChannelMessage.published_at < cutoff_time)
+                .returning(ChannelMessage.id)
+            )
+            deleted_ids = result.fetchall()
+            await self._commit_if_not_in_transaction(session)
+
+            return len(deleted_ids)