docs(iac): describe the fire sweep as carrying out delayed human approvals

CHANGELOG.md

@@ -54,9 +54,13 @@ are the full record until the next release.
 
 - **The fire_scheduled_purchases sweep is now on by default on every
   Terraform platform** (Lambda, Fargate, Cloud Run, GKE, Container Apps and
-  AKS), every 15 minutes. It executes delayed auto-approved purchases once
-  their scheduled time passes; until now they never ran unless the operator
-  turned the sweep on. The server refuses (and sends the purchase-failed
+  AKS), every 15 minutes. It carries out every purchase a person approves
+  while a purchase delay is set (`purchase_delay_hours` > 0; the migrated
+  default is 0, which executes approvals immediately) once the delay ends;
+  until now those approvals never executed unless the operator turned the
+  sweep on. Keep it on unless `purchase_delay_hours` stays 0. GKE deployed from `terraform/environments/gcp` still gets no Cloud
+  Scheduler jobs, this one included (that environment doesn't pass
+  `enable_scheduled_tasks` to GKE). The server refuses (and sends the purchase-failed
   alert for) any purchase due more than 24h ago, so the first run cannot buy
   a stale backlog. Set `enable_fire_scheduled_purchases_schedule = false` to
   opt out. The process_scheduled_purchases sweep stays opt-in (#712)

terraform/environments/aws/variables.tf

@@ -395,7 +395,7 @@ variable "ladder_run_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/environments/azure/variables.tf

@@ -444,7 +444,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/environments/gcp/variables.tf

@@ -370,7 +370,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/aws/fargate/variables.tf

@@ -226,7 +226,7 @@ variable "ladder_run_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/aws/lambda/main.tf

@@ -775,9 +775,9 @@ resource "aws_lambda_permission" "eventbridge_ladder_run" {
 # Frequent tick that invokes the fire_scheduled_purchases task:
 # scans purchase_executions in status=scheduled whose
 # scheduled_execution_at is in the past and fires each one. This
-# sweep is the runtime mechanism that makes auto-approve delayed
-# purchases actually execute; without it, scheduled tranches would
-# never fire between daily ladder runs. On by default (owner decision
+# sweep is what carries out a purchase a person approved while a
+# purchase delay is set (purchase_delay_hours > 0); without it those
+# approvals never execute. On by default (owner decision
 # for #712): the server refuses any row due more than 24h ago (#1549),
 # so a first tick after enabling cannot buy a stale backlog.
 

terraform/modules/compute/aws/lambda/variables.tf

@@ -246,7 +246,7 @@ variable "ladder_run_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/azure/aks/variables.tf

@@ -277,7 +277,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/azure/container-apps/variables.tf

@@ -285,7 +285,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/gcp/cloud-run/variables.tf

@@ -216,7 +216,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }

terraform/modules/compute/gcp/gke/variables.tf

@@ -306,7 +306,7 @@ variable "analytics_collect_schedule" {
 }
 
 variable "enable_fire_scheduled_purchases_schedule" {
-  description = "Schedule the fire_scheduled_purchases sweep, which executes delayed auto-approved purchases once their scheduled time has passed. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
+  description = "Schedule the fire_scheduled_purchases sweep, which carries out every purchase a person approves while a purchase delay is set (purchase_delay_hours > 0; the migrated default is 0, which executes approvals immediately) once the delay ends. With the sweep off, those approved purchases stay scheduled and never execute, with no alert, so turn it off only where purchase_delay_hours stays 0. On by default: the server refuses, and alerts on, any purchase due more than 24h ago (SCHEDULED_PURCHASE_MAX_OVERDUE, #1549), so turning it on cannot buy a stale backlog. Set false to opt out."
   type        = bool
   default     = true
 }