docs(push): clarify acceptable enrollment overlap

Signed-off-by: Tom Brow <tomb@block.xyz>

crates/buzz-db/src/runtime/push_enqueue.rs

@@ -158,9 +158,9 @@ async fn enqueue(pool: &PgPool, job: &Job) -> crate::Result<()> {
         .bind(crate::push::push_gate_lock_key(job.community))
         .execute(&mut *tx)
         .await?;
-    // Do not enqueue solely because a lease first appeared after the
-    // message arrived. Updates racing this check may drop a wake, which is
-    // permitted by the best-effort contract; message storage is authoritative.
+    // Compare recorded receipt/update times without imposing commit ordering.
+    // Registration overlapping message arrival may send or suppress a wake.
+    // This bounded job never scans historical messages on lease activation.
     sqlx::query(
         "INSERT INTO push_match_queue (community_id, event_id) \
          SELECT $1, $2 FROM events e \

crates/buzz-db/src/store/event_follow_up_postgres_tests.rs

@@ -998,8 +998,9 @@ async fn assert_async_isolation(db: &Db, community: CommunityId, keys: &Keys) {
         .unwrap();
     assert_eq!(match_count(&isolated, community, &healthy).await, 1);
 
-    // If activation finishes while a post-commit job waits, it must not create
-    // a wake solely for a lease that appeared after the message was received.
+    // Exercise the timestamp filter with a lease timestamp explicitly newer
+    // than this message. This is not a production activation-order regression:
+    // registration overlapping message arrival may send or suppress a wake.
     let later = create_community(db.pool()).await;
     let mut activation = db.pool().begin().await.unwrap();
     sqlx::query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))")

docs/push-gateway-deployment.md

@@ -294,8 +294,11 @@ reject or roll back a committed message, and there is no replay/backfill of
 in-memory work. Monitor `buzz_push_enqueue_total` by result (`completed`, `full`,
 `transaction_full`, `closed`, `error`, `timeout`, `shutdown`). `completed` includes
 jobs with no eligible lease. Database enqueue is conditional on a live event and
-an eligible lease last updated no later than event receipt. A concurrent lease
-update can suppress a notification under this best-effort contract.
+an eligible lease whose recorded update timestamp is no later than event receipt.
+These timestamps do not establish transaction commit order. When registration
+and message arrival overlap, either sending or suppressing the notification is
+acceptable; there is no exact enrollment-order guarantee. Activation never scans
+historical messages or deliberately backfills older notifications.
 
 This isolation requires the overlap migration and updated writers. Old images
 and raw SQL writers can still run the legacy transactional trigger until replaced.