Inbox change feed v1 (STATE-WP-0098-T05); close out open waits

- migration c4d5e6f7a8b9: inbox revision sequence, per-transaction revision
  trigger with advisory lock, message tombstones
- GET /messages/feed/snapshot and /messages/feed?after= per the accepted
  contract; archived_at is now first-write-wins
- STATE-WP-0098 blocked: T02/T04 qualified waits on owners and HUB-WP-0011-T01
- STATE-WP-0094-T05: correct the cited CCR, wait on railiance-platform
- legacy-meter review evidence 2026-10-14

Not deployed; the migration deploy is a separate confirmed step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 356991@bnt-lap001
Assistant-Session: 5d99ea69-ed55-4a1e-8d97-f4f312db247f

api/models/agent_message.py

@@ -1,7 +1,19 @@
 import uuid
 from datetime import datetime
 
-from sqlalchemy import DateTime, ForeignKey, Index, String, Text, text
+from sqlalchemy import (
+    DDL,
+    BigInteger,
+    DateTime,
+    FetchedValue,
+    ForeignKey,
+    Index,
+    Sequence,
+    String,
+    Text,
+    event,
+    text,
+)
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -11,12 +23,28 @@ from api.models.base import Base, new_uuid
 BROADCAST = "broadcast"
 MESSAGE_KINDS = ("message", "news", "standing")
 
+# STATE-WP-0098-T05: inbox change feed (docs/inbox-change-feed-contract.md).
+# ``revision`` is owned by the database trigger below; application code never
+# sets it. Every inbox write transaction gets exactly one revision.
+INBOX_REVISION_SEQ = Sequence("inbox_revision_seq", metadata=Base.metadata)
+
+
+def _revision_column() -> Mapped[int]:
+    return mapped_column(
+        BigInteger,
+        nullable=False,
+        index=True,
+        server_default=FetchedValue(),
+        server_onupdate=FetchedValue(),
+    )
+
 
 class AgentMessage(Base):
     __tablename__ = "agent_messages"
     __table_args__ = (
         Index("ix_agent_messages_to_kind_archived", "to_agent", "kind", "archived_at"),
     )
+    __mapper_args__ = {"eager_defaults": True}
 
     id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, default=new_uuid
@@ -55,6 +83,7 @@ class AgentMessage(Base):
         server_default=text("now()"),
         nullable=False,
     )
+    revision: Mapped[int] = _revision_column()
 
     thread_root: Mapped["AgentMessage | None"] = relationship(
         "AgentMessage",
@@ -72,6 +101,7 @@ class MessageReceipt(Base):
     """
 
     __tablename__ = "message_receipts"
+    __mapper_args__ = {"eager_defaults": True}
 
     message_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True),
@@ -88,3 +118,103 @@ class MessageReceipt(Base):
     acknowledged_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
+    revision: Mapped[int] = _revision_column()
+
+
+class MessageTombstone(Base):
+    """A deleted ``agent_messages`` row, written by the delete trigger.
+
+    Bodies are never kept. Served by the inbox feed within the 90-day horizon
+    (contract D1).
+    """
+
+    __tablename__ = "message_tombstones"
+
+    message_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    revision: Mapped[int] = mapped_column(BigInteger, nullable=False, index=True)
+    deleted_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
+# Trigger DDL for ``Base.metadata.create_all`` (the test suite). Production
+# gets the same objects from migration c4d5e6f7a8b9_inbox_feed_revision, which
+# keeps its own frozen copy; tests/test_message_feed.py checks they agree.
+INBOX_ADVISORY_LOCK_KEY = 5_348_490_098
+
+INBOX_FEED_FUNCTIONS_SQL = f"""
+CREATE OR REPLACE FUNCTION inbox_feed_revision() RETURNS bigint
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    tx text := txid_current()::text;
+    cached text := coalesce(current_setting('statehub.inbox_rev', true), '');
+    rev bigint;
+BEGIN
+    PERFORM pg_advisory_xact_lock({INBOX_ADVISORY_LOCK_KEY});
+    IF split_part(cached, ':', 1) = tx THEN
+        RETURN split_part(cached, ':', 2)::bigint;
+    END IF;
+    rev := nextval('inbox_revision_seq');
+    PERFORM set_config('statehub.inbox_rev', tx || ':' || rev::text, true);
+    RETURN rev;
+END
+$fn$;
+
+CREATE OR REPLACE FUNCTION inbox_feed_stamp_revision() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+BEGIN
+    IF TG_OP = 'UPDATE' THEN
+        IF NEW IS NOT DISTINCT FROM OLD THEN
+            RETURN NEW;
+        END IF;
+    END IF;
+    NEW.revision := inbox_feed_revision();
+    RETURN NEW;
+END
+$fn$;
+
+CREATE OR REPLACE FUNCTION inbox_feed_tombstone() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+BEGIN
+    INSERT INTO message_tombstones (message_id, revision, deleted_at, reason)
+    VALUES (
+        OLD.id,
+        inbox_feed_revision(),
+        now(),
+        nullif(current_setting('statehub.delete_reason', true), '')
+    )
+    ON CONFLICT (message_id) DO UPDATE
+        SET revision = EXCLUDED.revision,
+            deleted_at = EXCLUDED.deleted_at,
+            reason = EXCLUDED.reason;
+    RETURN OLD;
+END
+$fn$;
+"""
+
+event.listen(
+    AgentMessage.__table__,
+    "after_create",
+    DDL(
+        INBOX_FEED_FUNCTIONS_SQL
+        + """
+CREATE TRIGGER agent_messages_inbox_revision
+    BEFORE INSERT OR UPDATE ON agent_messages
+    FOR EACH ROW EXECUTE FUNCTION inbox_feed_stamp_revision();
+CREATE TRIGGER agent_messages_inbox_tombstone
+    BEFORE DELETE ON agent_messages
+    FOR EACH ROW EXECUTE FUNCTION inbox_feed_tombstone();
+"""
+    ),
+)
+event.listen(
+    MessageReceipt.__table__,
+    "after_create",
+    DDL(
+        INBOX_FEED_FUNCTIONS_SQL
+        + """
+CREATE TRIGGER message_receipts_inbox_revision
+    BEFORE INSERT OR UPDATE ON message_receipts
+    FOR EACH ROW EXECUTE FUNCTION inbox_feed_stamp_revision();
+"""
+    ),
+)