Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

perf(email): index mailbox work queues in claim order (#8376)

teo5bb070b3bee6
diff --git a/.sqlx/query-1e72b10c08a7b495492512a36be3d1d9057a3803356993216e75dce1cb30fb2a.json b/.sqlx/query-28e0b8e8520f2029d3b81041bff508919b7678e6165f90fb4939979d5cb40279.json
similarity index 61%
rename from .sqlx/query-1e72b10c08a7b495492512a36be3d1d9057a3803356993216e75dce1cb30fb2a.json
rename to .sqlx/query-28e0b8e8520f2029d3b81041bff508919b7678e6165f90fb4939979d5cb40279.json
index 48008b2dcb..faea130a76 100644
--- a/.sqlx/query-1e72b10c08a7b495492512a36be3d1d9057a3803356993216e75dce1cb30fb2a.json
+++ b/.sqlx/query-28e0b8e8520f2029d3b81041bff508919b7678e6165f90fb4939979d5cb40279.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n WITH candidate AS (\n SELECT q.link_id,q.generation,q.provider_id FROM email_message_reconciliation q\n JOIN email_links l ON l.id = q.link_id\n WHERE q.generation = l.sync_generation AND l.is_sync_active AND l.provider = 'OUTLOOK'\n AND q.available_at <= now() AND (q.lease_until IS NULL OR q.lease_until < now())\n ORDER BY q.is_import,q.available_at,q.link_id,q.provider_id LIMIT 1 FOR UPDATE OF q SKIP LOCKED\n )\n UPDATE email_message_reconciliation q SET lease_id = $1, lease_until = now() + interval '3 minutes', attempts = attempts + 1\n FROM candidate c,email_links l\n WHERE q.link_id = c.link_id AND q.generation = c.generation AND q.provider_id = c.provider_id AND l.id = q.link_id\n RETURNING q.link_id,q.generation,l.grant_generation,q.provider_id,q.revision,q.is_import,q.attempts\n ",
+ "query": "\n WITH candidate AS (\n SELECT q.link_id,q.generation,q.provider_id FROM email_message_reconciliation q\n JOIN email_links l ON l.id = q.link_id\n WHERE q.generation = l.sync_generation AND l.is_sync_active AND l.provider = 'OUTLOOK'\n AND q.is_import IN (false,true)\n AND q.available_at <= now() AND (q.lease_until IS NULL OR q.lease_until < now())\n ORDER BY q.is_import,q.available_at,q.link_id,q.provider_id LIMIT 1 FOR UPDATE OF q SKIP LOCKED\n )\n UPDATE email_message_reconciliation q SET lease_id = $1, lease_until = now() + interval '3 minutes', attempts = attempts + 1\n FROM candidate c,email_links l\n WHERE q.link_id = c.link_id AND q.generation = c.generation AND q.provider_id = c.provider_id AND l.id = q.link_id\n RETURNING q.link_id,q.generation,l.grant_generation,q.provider_id,q.revision,q.is_import,q.attempts\n ",
"describe": {
"columns": [
{
@@ -54,5 +54,5 @@
false
]
},
- "hash": "1e72b10c08a7b495492512a36be3d1d9057a3803356993216e75dce1cb30fb2a"
+ "hash": "28e0b8e8520f2029d3b81041bff508919b7678e6165f90fb4939979d5cb40279"
}
diff --git a/.sqlx/query-91e6c916303ecf9964057ee4e1049e17d6e75ab6e3b987b0da910d30138422fa.json b/.sqlx/query-91e6c916303ecf9964057ee4e1049e17d6e75ab6e3b987b0da910d30138422fa.json
deleted file mode 100644
index 5d1e13eb2f..0000000000
--- a/.sqlx/query-91e6c916303ecf9964057ee4e1049e17d6e75ab6e3b987b0da910d30138422fa.json
+++ /dev/null
@@ -1,34 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "WITH candidate AS (SELECT o.id FROM email_mailbox_lifecycle_outbox o WHERE o.available_at <= now()\n AND (o.lease_until IS NULL OR o.lease_until < now())\n AND NOT EXISTS (SELECT 1 FROM email_mailbox_lifecycle_outbox prerequisite WHERE prerequisite.link_id=o.link_id\n AND ((o.payload->>'kind'='revoke_microsoft_grant' AND prerequisite.payload->>'kind'='cleanup_microsoft_watches')\n OR (o.payload->>'kind'='delete_mailbox' AND prerequisite.payload->>'kind' IN ('cleanup_microsoft_watches','revoke_microsoft_grant'))))\n ORDER BY (o.payload->>'kind' = 'gmail_history'),o.available_at,o.id LIMIT 1 FOR UPDATE OF o SKIP LOCKED)\n UPDATE email_mailbox_lifecycle_outbox o SET lease_id = $1,lease_until = now() + interval '3 minutes',attempts = attempts + 1\n FROM candidate c WHERE o.id = c.id RETURNING o.id,o.link_id,o.payload",
- "describe": {
- "columns": [
- {
- "ordinal": 0,
- "name": "id",
- "type_info": "Uuid"
- },
- {
- "ordinal": 1,
- "name": "link_id",
- "type_info": "Uuid"
- },
- {
- "ordinal": 2,
- "name": "payload",
- "type_info": "Jsonb"
- }
- ],
- "parameters": {
- "Left": [
- "Uuid"
- ]
- },
- "nullable": [
- false,
- false,
- false
- ]
- },
- "hash": "91e6c916303ecf9964057ee4e1049e17d6e75ab6e3b987b0da910d30138422fa"
-}
diff --git a/.sqlx/query-fada3bb2a6108876b0dd4bddd004a6a05ee8f6aeae7d9d7fbfcd8275d6d7c2a7.json b/.sqlx/query-fada3bb2a6108876b0dd4bddd004a6a05ee8f6aeae7d9d7fbfcd8275d6d7c2a7.json
new file mode 100644
index 0000000000..2701a08adf
--- /dev/null
+++ b/.sqlx/query-fada3bb2a6108876b0dd4bddd004a6a05ee8f6aeae7d9d7fbfcd8275d6d7c2a7.json
@@ -0,0 +1,34 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "WITH candidate AS (SELECT o.id FROM email_mailbox_lifecycle_outbox o WHERE o.available_at <= now()\n AND (o.payload->>'kind' = 'gmail_history') IN (false,true)\n AND (o.lease_until IS NULL OR o.lease_until < now())\n AND NOT EXISTS (SELECT 1 FROM email_mailbox_lifecycle_outbox prerequisite WHERE prerequisite.link_id=o.link_id\n AND ((o.payload->>'kind'='revoke_microsoft_grant' AND prerequisite.payload->>'kind'='cleanup_microsoft_watches')\n OR (o.payload->>'kind'='delete_mailbox' AND prerequisite.payload->>'kind' IN ('cleanup_microsoft_watches','revoke_microsoft_grant'))))\n ORDER BY (o.payload->>'kind' = 'gmail_history'),o.available_at,o.id LIMIT 1 FOR UPDATE OF o SKIP LOCKED)\n UPDATE email_mailbox_lifecycle_outbox o SET lease_id = $1,lease_until = now() + interval '3 minutes',attempts = attempts + 1\n FROM candidate c WHERE o.id = c.id RETURNING o.id,o.link_id,o.payload",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 1,
+ "name": "link_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 2,
+ "name": "payload",
+ "type_info": "Jsonb"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Uuid"
+ ]
+ },
+ "nullable": [
+ false,
+ false,
+ false
+ ]
+ },
+ "hash": "fada3bb2a6108876b0dd4bddd004a6a05ee8f6aeae7d9d7fbfcd8275d6d7c2a7"
+}
diff --git a/crates/calendar_events/src/outbound/pg/test/outlook.rs b/crates/calendar_events/src/outbound/pg/test/outlook.rs
index 99ae0c0619..a3927dc058 100644
--- a/crates/calendar_events/src/outbound/pg/test/outlook.rs
+++ b/crates/calendar_events/src/outbound/pg/test/outlook.rs
@@ -450,6 +450,31 @@ async fn publication_ack_preserves_a_concurrent_projection_revision(pool: PgPool
);
}
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn projection_claims_take_due_changes_in_order_and_skip_backed_off_ones(pool: PgPool) {
+ let (repo, link, owner) = mailbox(&pool).await;
+ let [later, second, first] = [Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7()];
+ sqlx::query!(
+ "INSERT INTO calendar_projection_outbox(event_id,owner_id,link_id,change_kind,next_run_at) VALUES
+ ($1,$4,$5,'created',now() + interval '1 hour'),
+ ($2,$4,$5,'updated',now() - interval '1 minute'),
+ ($3,$4,$5,'deleted',now() - interval '2 minutes')",
+ later,
+ second,
+ first,
+ owner,
+ link
+ )
+ .execute(&pool)
+ .await
+ .unwrap();
+ let mut claimed = Vec::new();
+ while let Some(lease) = repo.claim_projection(Uuid::now_v7()).await.unwrap() {
+ claimed.push(lease.event_id);
+ }
+ assert_eq!(claimed, [first, second]);
+}
+
#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
async fn simultaneous_workers_do_not_share_a_calendar_lease(pool: PgPool) {
let (repo, _, _) = mailbox(&pool).await;
diff --git a/crates/email/src/outbound/mailbox_pg.rs b/crates/email/src/outbound/mailbox_pg.rs
index 8ba70e1c35..ed57f9f8bd 100644
--- a/crates/email/src/outbound/mailbox_pg.rs
+++ b/crates/email/src/outbound/mailbox_pg.rs
@@ -211,11 +211,14 @@ impl MailboxSyncRepository for PgMailboxSync {
}
async fn claim_message(&self, lease_id: Uuid) -> Result<Option<MessageLease>, MailboxError> {
+ // Naming both `is_import` values lets `available_at <= now()` end the claim index scan.
+ // Without it, Postgres before 18 reads every backed-off row on each poll.
let row = sqlx::query!(r#"
WITH candidate AS (
SELECT q.link_id,q.generation,q.provider_id FROM email_message_reconciliation q
JOIN email_links l ON l.id = q.link_id
WHERE q.generation = l.sync_generation AND l.is_sync_active AND l.provider = 'OUTLOOK'
+ AND q.is_import IN (false,true)
AND q.available_at <= now() AND (q.lease_until IS NULL OR q.lease_until < now())
ORDER BY q.is_import,q.available_at,q.link_id,q.provider_id LIMIT 1 FOR UPDATE OF q SKIP LOCKED
)
diff --git a/crates/email/src/outbound/mailbox_pg/contacts/test.rs b/crates/email/src/outbound/mailbox_pg/contacts/test.rs
index ca3d4c7f2f..72c9f29df3 100644
--- a/crates/email/src/outbound/mailbox_pg/contacts/test.rs
+++ b/crates/email/src/outbound/mailbox_pg/contacts/test.rs
@@ -237,3 +237,24 @@ async fn an_in_flight_photo_cannot_restore_a_deleted_contact(db: PgPool) {
None
);
}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn photo_claims_take_due_sources_in_order_and_skip_backed_off_and_deleted_ones(db: PgPool) {
+ let (repo, link) = fixture(&db).await;
+ sqlx::query!(r#"
+ INSERT INTO email_address_book_sources(link_id,folder_id,provider_id,emails,scan_id,photo_due_at,deleted_at) VALUES
+ ($1,'contacts','later','{}',gen_random_uuid(),now() + interval '1 hour',NULL),
+ ($1,'contacts','deleted','{}',gen_random_uuid(),now() - interval '3 minutes',now()),
+ ($1,'contacts','second','{}',gen_random_uuid(),now() - interval '1 minute',NULL),
+ ($1,'contacts','first','{}',gen_random_uuid(),now() - interval '2 minutes',NULL)
+ "#,link).execute(&db).await.unwrap();
+ let mut claimed = Vec::new();
+ while let Some(lease) = repo
+ .claim_photo(macro_uuid::generate_uuid_v7())
+ .await
+ .unwrap()
+ {
+ claimed.push(lease.contact.as_str().to_owned());
+ }
+ assert_eq!(claimed, ["first", "second"]);
+}
diff --git a/crates/email/src/outbound/mailbox_pg/lifecycle.rs b/crates/email/src/outbound/mailbox_pg/lifecycle.rs
index 2b536a47c6..46b0dbdc43 100644
--- a/crates/email/src/outbound/mailbox_pg/lifecycle.rs
+++ b/crates/email/src/outbound/mailbox_pg/lifecycle.rs
@@ -338,7 +338,10 @@ impl InboxLifecycleRepository for PgMailboxSync {
&self,
lease_id: Uuid,
) -> Result<Option<InboxLifecycleLease>, MailboxError> {
+ // Naming both values of the claim index's leading expression lets `available_at <= now()`
+ // end the scan. Without it, Postgres before 18 reads every backed-off row on each poll.
let row=sqlx::query!(r#"WITH candidate AS (SELECT o.id FROM email_mailbox_lifecycle_outbox o WHERE o.available_at <= now()
+ AND (o.payload->>'kind' = 'gmail_history') IN (false,true)
AND (o.lease_until IS NULL OR o.lease_until < now())
AND NOT EXISTS (SELECT 1 FROM email_mailbox_lifecycle_outbox prerequisite WHERE prerequisite.link_id=o.link_id
AND ((o.payload->>'kind'='revoke_microsoft_grant' AND prerequisite.payload->>'kind'='cleanup_microsoft_watches')
diff --git a/crates/email/src/outbound/mailbox_pg/lifecycle/test.rs b/crates/email/src/outbound/mailbox_pg/lifecycle/test.rs
index e6a80b67cc..c3257af318 100644
--- a/crates/email/src/outbound/mailbox_pg/lifecycle/test.rs
+++ b/crates/email/src/outbound/mailbox_pg/lifecycle/test.rs
@@ -339,3 +339,33 @@ async fn subscription_cleanup_precedes_revoke_and_delete_even_with_parallel_publ
}
panic!("disconnect must eventually publish deletion");
}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn effect_claims_take_due_mailbox_effects_before_gmail_history_and_skip_backed_off_rows(
+ db: PgPool,
+) {
+ let (repo, link) = super::super::test::fixture(&db).await;
+ let history = InboxLifecycleEffect::GmailHistory {
+ work: crate::domain::mailbox::gmail_history::HistoryWork::Delete {
+ provider_id: "history-due".into(),
+ },
+ };
+ let later = InboxLifecycleEffect::AccessRemoved {
+ viewer: "later".into(),
+ };
+ let due = InboxLifecycleEffect::AccessRemoved {
+ viewer: "due".into(),
+ };
+ for (effect, delay) in [(later, 3600.0), (history, -120.0), (due, -60.0)] {
+ sqlx::query!("INSERT INTO email_mailbox_lifecycle_outbox(id,link_id,payload,available_at) VALUES($1,$2,$3,now() + make_interval(secs => $4))",Uuid::now_v7(),link,serde_json::to_value(effect).unwrap(),delay).execute(&db).await.unwrap();
+ }
+ let mut claimed = Vec::new();
+ while let Some(lease) = repo.claim_effect(Uuid::now_v7()).await.unwrap() {
+ claimed.push(match lease.effect {
+ InboxLifecycleEffect::AccessRemoved { viewer } => viewer,
+ InboxLifecycleEffect::GmailHistory { .. } => "history".into(),
+ other => panic!("unexpected effect {other:?}"),
+ });
+ }
+ assert_eq!(claimed, ["due", "history"]);
+}
diff --git a/crates/email/src/outbound/mailbox_pg/test.rs b/crates/email/src/outbound/mailbox_pg/test.rs
index d6f47fb09f..2dd3383d74 100644
--- a/crates/email/src/outbound/mailbox_pg/test.rs
+++ b/crates/email/src/outbound/mailbox_pg/test.rs
@@ -741,3 +741,19 @@ async fn native_outlook_attachment_identity_survives_metadata_collisions_and_emp
}
}
}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn message_claims_take_due_live_changes_before_imports_and_skip_backed_off_rows(db: PgPool) {
+ let (repo, link) = fixture(&db).await;
+ sqlx::query!(r#"
+ INSERT INTO email_message_reconciliation(link_id,generation,provider_id,is_import,available_at) VALUES
+ ($1,1,'live-later',false,now() + interval '1 hour'),
+ ($1,1,'import-due',true,now() - interval '2 minutes'),
+ ($1,1,'live-due',false,now() - interval '1 minute')
+ "#,link).execute(&db).await.unwrap();
+ let mut claimed = Vec::new();
+ while let Some(work) = repo.claim_message(Uuid::new_v4()).await.unwrap() {
+ claimed.push(work.provider_id.as_str().to_owned());
+ }
+ assert_eq!(claimed, ["live-due", "import-due"]);
+}
diff --git a/crates/macro_db_client/migrations/20261020183426_email_message_reconciliation_claim_index.sql b/crates/macro_db_client/migrations/20261020183426_email_message_reconciliation_claim_index.sql
new file mode 100644
index 0000000000..9a11303b2f
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183426_email_message_reconciliation_claim_index.sql
@@ -0,0 +1,5 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+-- Columns follow the ORDER BY of the reconciliation claim so it reads the first due row.
+CREATE INDEX CONCURRENTLY email_message_reconciliation_claim
+ ON email_message_reconciliation (is_import, available_at, link_id, provider_id);
diff --git a/crates/macro_db_client/migrations/20261020183427_drop_email_message_reconciliation_due_index.sql b/crates/macro_db_client/migrations/20261020183427_drop_email_message_reconciliation_due_index.sql
new file mode 100644
index 0000000000..08c2ce5e96
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183427_drop_email_message_reconciliation_due_index.sql
@@ -0,0 +1,3 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+DROP INDEX CONCURRENTLY IF EXISTS email_message_reconciliation_due;
diff --git a/crates/macro_db_client/migrations/20261020183428_email_mailbox_lifecycle_outbox_claim_index.sql b/crates/macro_db_client/migrations/20261020183428_email_mailbox_lifecycle_outbox_claim_index.sql
new file mode 100644
index 0000000000..7b13fe9f06
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183428_email_mailbox_lifecycle_outbox_claim_index.sql
@@ -0,0 +1,5 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+-- Columns follow the ORDER BY of the lifecycle claim so it reads the first due row.
+CREATE INDEX CONCURRENTLY email_mailbox_lifecycle_outbox_claim
+ ON email_mailbox_lifecycle_outbox (((payload->>'kind') = 'gmail_history'), available_at, id);
diff --git a/crates/macro_db_client/migrations/20261020183429_email_mailbox_lifecycle_outbox_prerequisites_index.sql b/crates/macro_db_client/migrations/20261020183429_email_mailbox_lifecycle_outbox_prerequisites_index.sql
new file mode 100644
index 0000000000..c627232633
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183429_email_mailbox_lifecycle_outbox_prerequisites_index.sql
@@ -0,0 +1,6 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+-- Lets the lifecycle claim check a link for pending cleanup or revocation without scanning the outbox.
+CREATE INDEX CONCURRENTLY email_mailbox_lifecycle_outbox_prerequisites
+ ON email_mailbox_lifecycle_outbox (link_id)
+ WHERE (payload->>'kind') IN ('cleanup_microsoft_watches', 'revoke_microsoft_grant');
diff --git a/crates/macro_db_client/migrations/20261020183430_drop_email_mailbox_lifecycle_outbox_due_index.sql b/crates/macro_db_client/migrations/20261020183430_drop_email_mailbox_lifecycle_outbox_due_index.sql
new file mode 100644
index 0000000000..3bba775f1d
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183430_drop_email_mailbox_lifecycle_outbox_due_index.sql
@@ -0,0 +1,3 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+DROP INDEX CONCURRENTLY IF EXISTS email_mailbox_lifecycle_outbox_due;
diff --git a/crates/macro_db_client/migrations/20261020183431_email_address_book_sources_photo_claim_index.sql b/crates/macro_db_client/migrations/20261020183431_email_address_book_sources_photo_claim_index.sql
new file mode 100644
index 0000000000..9dc7a09939
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183431_email_address_book_sources_photo_claim_index.sql
@@ -0,0 +1,6 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+-- Columns follow the ORDER BY of the photo claim so it reads the first due row.
+CREATE INDEX CONCURRENTLY email_address_book_sources_photo_claim
+ ON email_address_book_sources (photo_due_at, link_id, folder_id, provider_id)
+ WHERE deleted_at IS NULL;
diff --git a/crates/macro_db_client/migrations/20261020183432_drop_email_address_book_sources_photo_due_index.sql b/crates/macro_db_client/migrations/20261020183432_drop_email_address_book_sources_photo_due_index.sql
new file mode 100644
index 0000000000..356e0bc6dc
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183432_drop_email_address_book_sources_photo_due_index.sql
@@ -0,0 +1,3 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+DROP INDEX CONCURRENTLY IF EXISTS email_address_book_sources_photo_due;
diff --git a/crates/macro_db_client/migrations/20261020183433_calendar_projection_outbox_due_index.sql b/crates/macro_db_client/migrations/20261020183433_calendar_projection_outbox_due_index.sql
new file mode 100644
index 0000000000..481ce43c15
--- /dev/null
+++ b/crates/macro_db_client/migrations/20261020183433_calendar_projection_outbox_due_index.sql
@@ -0,0 +1,4 @@
+-- no-transaction
+-- Keep this a single statement: SQLx batches would create an implicit transaction.
+CREATE INDEX CONCURRENTLY calendar_projection_outbox_due
+ ON calendar_projection_outbox (next_run_at);
diff --git a/docs/design/outlook-email-support.md b/docs/design/outlook-email-support.md
index 9d076c83ce..efc5a5c239 100644
--- a/docs/design/outlook-email-support.md
+++ b/docs/design/outlook-email-support.md
@@ -901,12 +901,29 @@ reminder tables, and the follow-up `User` indexes on `macro_user_id` and
existing attachment lookup and reminder keys remain until their replacement
indexes are ready. New, empty Outlook runtime tables keep ordinary index builds.
+Follow-up queue tuning builds claim-order indexes for the message
+reconciliation, mailbox lifecycle outbox, and address-book photo queues, a
+partial lifecycle outbox index on `link_id` for pending cleanup and revocation
+effects, and a calendar projection outbox `next_run_at` index. Environments that
+ran the original migrations already hold queue rows, so these use the same
+single-statement concurrent form. Each claim index replaces a `_due` index,
+which a later migration drops with `DROP INDEX CONCURRENTLY IF EXISTS`. SQLx
+stops at the first failed migration, so a `_due` index is dropped only after its
+replacement is valid. The message and lifecycle claims name both values of their
+index's leading boolean, so Postgres versions without skip scan stop at the
+first row that isn't due yet.
+
After an interrupted or failed concurrent build, inspect `pg_index.indisvalid`
and `indisready` for the named index and check the migration ledger. An invalid
index must be dropped with `DROP INDEX CONCURRENTLY` outside a transaction before
retrying. If the index is valid but its migration was not recorded, investigate
-the interrupted ledger write before retrying. Do not use `IF NOT EXISTS` to hide
-either state: existence does not establish that an index is valid or correct.
+the interrupted ledger write before retrying. Killing the migration runner does
+not stop a build that is waiting on older transactions: the server finishes it
+and leaves a valid, unrecorded index. Once `pg_stat_progress_create_index` shows
+no build for the table, drop the index concurrently and rerun. A cancelled
+`DROP INDEX CONCURRENTLY` can leave the old index invalid; rerunning the
+migration finishes the drop. Do not use `IF NOT EXISTS` to hide either state:
+existence does not establish that an index is valid or correct.
The reminder-key cutover requires a coordinated deployment: old calendar writers
infer the keys without `method` in their `ON CONFLICT` clauses. Quiesce and drain