feat(campaign): background reconciliation of scheduled, sending, and unknown campaigns

[TheAggressive]

Closes #171. Part of #66 (M5). Based on master.

What this adds

• Campaign_Reconciler::reconcile_in_background() reconciles acting for no user. It uses the same campaign lock, rules, and provider reads as an operator's reconcile. Its audit events have no actor and carry automatic: true. It's the reconciler's only entry point without a user, so the system can reconcile but never send or schedule. No system user with delivery authority was introduced.

• Campaign_Reconcile_Job watches one campaign on Reconcile_Cadence:

  • scheduled: first read two minutes after the send time, then every five minutes;
  • sending: every five minutes while fresh, backing off to hourly;
  • unknown: read soon, then on the reconciler's own wait (the settle window or the provider's retry_after).

  Each outcome maps to a next step:

  Outcome	Next step
  Campaign locked or changed	Look again shortly; uses no attempt
  Transient provider error	Retry with backoff and retry_after
  missing, untracked, inconclusive, contradiction, duplicate_drafts, or a refused credential	Stop: the campaign needs operator action until it changes
  Terminal state	Watch ends

• Job_Outcome::again() puts a job that did its work back in the queue with its attempts reset, so a long-running watch never uses them up.

• Reconciliation_Sweep is a recurring job. The dispatcher queues it on each tick, with dedupe, and it runs every five minutes. It queues one watch per scheduled, sending, or unknown campaign without one, skipping campaigns whose watch stopped since they last changed. Schema 9 adds campaigns.state_updated for its query.

• Operator surfaces:

  • GET /campaigns/{id}/remote returns watch (watching, stopped, or idle; schema added);
  • the campaign page says when the next automatic check runs, or why checks stopped, using the same per-reason guidance as a manual reconcile;
  • the timeline marks automatic checks;
  • Status counts campaigns needing operator action.

Evidence (#171)

Background_Reconciliation_Test uses the real reconciler, real HTTP client, and scripted Mailchimp:

• Scheduled → sent in the background. Nothing is read before the send time. After it, the watch reconciles to sent, the audit event has no actor and is marked automatic, and no send action is made.
• An unknown send settles only after the settle window. An unsent draft seen too early leaves the campaign unknown and reschedules the check. After the window it settles as provider_draft, and there is still only one send.
• An unresolvable reason stops automatic checks and is flagged. A deleted Mailchimp campaign leads to missing: the watch stops and nothing changes locally. The sweep doesn't restart it, and a day later there are still no reads. /remote reports stopped/missing (validated against the schema), and Status counts the campaign.
• Delayed cron: after a six-hour gap, two ticks in quick succession make exactly one overdue read.
• Locked campaign: checked again later with no provider call, and without using an attempt.
• Also tested:
  • unit tests for the cadence;
  • a migration test from schema 8 on a populated table, with the index check;
  • the dispatcher queues the sweep once, not once per tick;
  • updated tick query budgets: one dedupe lookup added in steady state;
  • Jest tests for the watch summary and the timeline's "Checked automatically".

Verification

• pnpm qa:fast passes.
• Unit (1139), integration (471), security (117), accessibility (25), and performance (9) suites: all pass.

Note for Studio

After this merges, Studio's WP-Cron reconciles any campaign left scheduled, sending, or unknown against the real Mailchimp account, using read-only requests. Leftovers from browser tests that have simulated Mailchimp IDs will come back missing, stop, and show as needing operator action. That's the intended behaviour; archive them to clear the warning.

🤖 Generated with Claude Code