[tracking202]

Stacked on #285 (9BA0, 1.9.79-ltv-maintenance-scheduled, at e2d4680), which is stacked on #273. Review and merge this after #285. Until #285 merges, this diff includes #273's and #285's commits. This PR's own change is commit 9eeae73; 217450c is the merge of #285's branch (no conflicts).

Backlog: 2RBE

What was wrong

Every subscription status change made through the API queues a subscription.changed webhook event:

• POST /ltv/subscriptions queues it with action: upsert;
• the renewal, cancel and refund events queue it with action the event type.

The sweep that lapses and cancels subscriptions queued none. That is LtvMaintenance, which #285 runs hourly on every install. So a CRM, or the Landing Page Optimizer (whose pairing webhook takes every event), never heard that a subscription lapsed.

What changed

• Each status the sweep writes queues the event the API's change of that status queues. It goes through the same MysqlWebhookRepository::enqueue(), with the same envelope (event, occurred_at, data) and the same body (subscription_id, customer_id, action, as integers and a string):

  • past_due gets action: "upsert". The API reaches past_due only through POST /ltv/subscriptions with status: past_due, which queues exactly that.
  • canceled gets action: "cancel", as the cancel event (POST /ltv/subscriptions/{ref}/events) queues it.

• In the batch's own transaction. Each batch now reads its rows again under FOR UPDATE, still asking status = ? and the lapse condition. The rows it moves are the rows that read returned, and only those are announced.

  • A renewal that commits while the sweep waits still wins, as 1.9.79: the cron job sweeps lapsed LTV subscriptions hourly and runs the rest of LTV maintenance daily #285's race test holds, and nothing is announced for it.
  • The status writes, the events and the customers' rollups commit or roll back together, so a batch rolled back queues nothing. A write that moves fewer rows than were locked throws, and the batch rolls back rather than announce a change that was not made.

• Only a change that took effect in the last 7 days is announced (LtvMaintenance::EVENT_WINDOW_SECONDS = WebhookDispatcher::MAX_AGE_SECONDS). "Took effect" is the moment the rule set the status:

  • for past_due, period end + grace;
  • for canceled, period end + grace + 30 days, the canceled_at 1.9.79: the cron job sweeps lapsed LTV subscriptions hourly and runs the rest of LTV maintenance daily #285 writes.

  The status is written whatever its age.

• The run's line says what it announced and what it did not: subscriptions 1 to past_due, 2 to canceled, 3 customer rollups refreshed, 1 announced as subscription.changed (2 that took effect more than 7 days ago not announced). The report gains announced and unannounced.

• Docs:

  • documentation/api/20-ltv.md: what subscription.changed carries, and the sweep's events under "When a subscription stops renewing";
  • docs/openapi.yaml: the two subscription writes;
  • docs/cli-agent.md;
  • the upgrading guide;
  • both changelogs;
  • CLAUDE.md [Setup] Remove undefined variable from template calls #25, on what a second writer owes.

Decision: the backlog (measured)

An install whose sweep never ran before 1.9.79 has every subscription that stopped renewing still active. I seeded 30,000 subscriptions, one per customer, with period ends spread evenly over 4–700 days ago (#285's shape), and one webhook taking every event. MariaDB 10.11, PHP 8.3.6.

first sweep	time	events queued
#285 (no events)	1.70 s	0
this PR (last 7 days)	2.28 s	561 (1,250 → past_due, 28,750 → canceled; 29,439 older not announced)
announcing every change (measured by widening the window)	11.44 s	30,000 per subscribed webhook

The next sweep took 0.01 s and announced nothing.

Why 7 days, and not every change:

• The dispatcher would put a burst ahead of everything. 1.9.79: the minutely cron sends LTV webhooks, within a budget #273's dispatcher sends oldest first, for 15 s a minute. 30,000 deliveries per webhook would hold every live event behind them for hours: at a few hundred milliseconds a send, ~75 a minute, that is about 6–7 hours. And a slow receiver gets one send per run.
• A year-old lapse is noise. "Subscription X changed" about something a year ago reads to a CRM as news, and can overwrite newer state there, which is 1.9.79: the minutely cron sends LTV webhooks, within a budget #273's reason for its own 7 days.
• It matches what an always-running install would have sent. The dispatcher never sends a delivery more than 7 days after it was queued. A sweep that had run all along would have queued each event when the change happened, so only the last week's could still be sent today. A cron job stopped for 3 weeks behaves the same way: on its return, the last week's changes are announced and the rest are not, as the dispatcher's own expiry would have it.
• It is bounded by a week's worth of lapses, not by the install's history. It is all within the sweep's 20 s hourly budget, and the burst drains in minutes.

Tests

• tests/Ltv/SweepAnnouncesSubscriptionChangesIntegrationTest.php (@group integration, scratch database, strict sql_mode, 3 tests):

  • Twins.
    • For each status, one subscription is moved by the sweep and its twin through the real LtvController: upsertSubscription() with status: past_due, and subscriptionEvent() with cancel.
    • The delivery bodies queued for a webhook taking every event are compared: envelope keys, data keys and value types, the action and the ids.
    • A past_due subscription past its cancel point is announced as cancel. A webhook subscribed only to revenue.recorded gets nothing. A second sweep announces nothing.
  • The window. A lapse an hour inside 7 days is announced. One an hour outside, and a cancel a year ago, are written and not announced, and the line says 2 were not.
  • A rolled-back batch. A trigger refuses the rollup refresh, the batch's last write, after its event is queued. The status and the event both roll back. Without the trigger, the retry moves it and queues once.

• LtvMaintenanceIntegrationTest (1.9.79: the cron job sweeps lapsed LTV subscriptions hourly and runs the rest of LTV maintenance daily #285's): its renewal race now registers a webhook and holds that nothing is announced for the renewed row. All 10 pass.

• tests/Ltv/SubscriptionWritesAreAnnouncedTest.php (structural). Every statement in the served tree that writes 202_subscriptions is listed with who announces it:

  • the repository's three, which LtvController announces after;
  • the sweep's, announced in its transaction;
  • UserDataPurge's, with nobody left to tell.

  The listed announcers must still queue the event. A new writer fails it until it says how its change is announced.

• Updated: LtvMaintenanceSummaryTest (the line), and LtvFieldErrorsTest, which lists the sweep's new server failure.

• Plants. 11, all caught by a named test. For each, the file was backed up to mktemp, compared with cmp and restored:

plant	caught by
the sweep queues nothing	testEachStatusTheSweepWritesIsQueuedAsTheApisChangeOfItIs
the event named otherwise in the sweep	SubscriptionWritesAreAnnouncedTest::testTheListedWritersQueueTheEvent
the events committed apart from the batch	testABatchRolledBackQueuesNothingAndItsRetryQueuesOnce
no window	testAChangeThatTookEffectBeforeTheWindowIsWrittenAndNotAnnounced
the window asked of the sweep's time, not the change's	same
past_due announced as another action	testEachStatusTheSweepWrites…
canceled announced as another action	same
the locked read does not ask the row again	LtvMaintenanceIntegrationTest::testARenewalBetweenTheSweepsReadAndItsWriteWins
another body shape (customer_id as a string)	testEachStatusTheSweepWrites…
a new writer of 202_subscriptions	SubscriptionWritesAreAnnouncedTest::testEveryWriteOfASubscriptionRowIsListed
the line hides what was not announced	LtvMaintenanceSummaryTest::testTheLineNamesOnlyTheJobsThatRan

Live pass

tests/live/ltv-sweep-subscription-changed.sh (new) ran on an instance from this branch: PHP 8.3.6 php -S through the eval router, MariaDB 10.11, port 8321. The cron ran as the installer's line runs it: curl …/202-cronjobs/index.php, with this hour's and minute's records cleared first, as #285's pass does. 13 passed, 0 failed. The same script against #285's sweep gave 8 passed and 5 failed: no events, and the old line.

1. A webhook subscribed to subscription.changed, and five subscriptions recorded through POST /ltv/subscriptions:
   • twins lapsed 2 days ago;
   • twins past their cancel point 2 days ago;
   • one that lapsed 400 days ago.
2. One of each twin changed through the API: POST /ltv/subscriptions with status: past_due, and the cancel event (changed: true).
3. One cron run:
   • its line reads …, 3 customer rollups refreshed, 2 announced as subscription.changed (1 that took effect more than 7 days ago not announced);
   • the three are past_due, canceled, canceled;
   • each sweep-moved twin has one delivery, equal to its API twin's: subscription.changed upsert subscription_id:int,customer_id:int,action:string event,occurred_at,data, and the same with cancel;
   • the 400-day one has none.
4. The next run queues nothing.

The bodies were read from 202_ltv_webhook_deliveries, because GET /ltv/webhooks/{id}/deliveries leaves the payload out. The webhook's address answers nothing, so the minutely sender only recorded attempts.

#285's tests/live/ltv-subscription-lapse.sh, with its expected line updated, also ran on this branch: 28 passed, 0 failed. Its Go CLI checks were skipped, as in #285's own run: the licence, below. Its PHP CLI check (bin/p202 ltv:mrr) ran.

Licence (the stub is down)

• Install. install.php's POST checks the key with my.tracking202.com, so I did not run it. A scratch script ran the installer's own steps without the licence form: INSTALL::install_databases(), InstallAccount::create(), the 202_api_keys row and install_database_partitions(). AutoCron and the daily email registration, which call outside services, were left out.
• The web server ran with every proxy variable (HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy) pointed at http://127.0.0.1:9, a closed port, and with NO_PROXY=localhost,127.0.0.1. Every licence check in its log is Failed to connect to 127.0.0.1 port 9, so nothing reached the licence service. No signed-in page is part of this pass: it uses the API and the cron line only.
• The Go CLI was not used.

Verification

.claude/skills/p202-verify/scripts/verify.sh --since origin/1.9.79 --changed, on 9eeae73, PHP 8.3.6. The schema tier ran on a scratch MariaDB 10.11 database. The unit tier ran 6,122 tests with 5 skipped: the 4 documented "User class requires DB singleton" skips, and CronEntryPointsFailLoudlyTest's executed case, which skips while the worktree holds the live instance's 202-config.php. The range includes #273's and #285's changes.

Scope report
------------
  openapi    PASS
  patterns   PASS
  phpcs      PASS
  phpstan    PASS
  schema     PASS
  syntax     PASS
  unit       PASS

Not covered by this script:
  live      stand up an instance, drive the path a user would take
  agent     add and run a case under tests/fixtures/agent-eval/cases/
  ci        a workflow still in_progress has not passed; read the run

Report the lines above verbatim. Do not write "tests pass".

The first run of the ladder had unit FAIL: LtvFieldErrorsTest caught the sweep's new RuntimeException ("The sweep locked …"), which was not listed. It is listed now, with why it is the server's.

Beyond the script, each suite against a scratch MariaDB 10.11 database:

suite	result
SweepAnnouncesSubscriptionChangesIntegrationTest	3 tests OK
LtvMaintenanceIntegrationTest	10 tests OK
WebhookDispatchIntegrationTest	15 tests OK
LtvDatabaseIntegrationTest	43 tests OK

shellcheck --severity=warning on both live scripts: clean.

Not run:

• CI's MySQL 8.0 (only MariaDB 10.11 here). The new tests use DROP TRIGGER IF EXISTS and CREATE TRIGGER … FOR EACH ROW IF … END IF, which TrackerLinkTransactionIntegrationTest already runs in CI, and no RENAME TABLE. The sweep's SELECT … FOR UPDATE by primary key is plain MySQL;
• the Go CLI checks of 1.9.79: the cron job sweeps lapsed LTV subscriptions hourly and runs the rest of LTV maintenance daily #285's pass (licence);
• an agent-eval case;
• the full tests/run-integration-suites.sh;
• CI, until it runs on this PR.

For the reviewer to check

• past_due → action: "upsert". This mirrors the only API path to that status, as the item asks ("the same event, with the same payload shape, that the API's change of that status would"). A new action such as lapse would read more naturally, but it would be a value no subscriber has seen from the API. The body carries no status; a subscriber reads the subscription, as for every subscription.changed.
• The window is on when the change took effect, not on when it is queued. The dispatcher's 7 days apply to the queueing, so the two together send nothing about a change more than about two weeks old.
• FOR UPDATE on the batch's rows. 1.9.79: the cron job sweeps lapsed LTV subscriptions hourly and runs the rest of LTV maintenance daily #285's writes asked the row again in the UPDATE. They now ask it in a locking read by primary key, and the UPDATE names exactly the rows that read returned, so the events match the writes. Measured cost: +0.6 s on 30,000 rows, including the 561 enqueues.
• The occurred_at envelope is the time the event was queued, as for every API event (enqueue() sets it), not the time the change took effect.

Found outside this item (not fixed here)

• subscription.changed's body carries no status, from the API or the sweep. Every subscriber has to read the subscription back to know what changed. (Its shape was documented nowhere; this PR adds it to documentation/api/20-ltv.md.)
• MysqlWebhookRepository::enqueue() reads the account's webhooks through prepareRead(), the replica where one is configured, even when called inside a transaction on the primary.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VRoS2SViuxaucFaKWsFnLr

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-28T09:15:48.036356Z We couldn’t complete this review. Comment @codex review to try again.	9eeae73	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[github-actions]

Code review: CLEAN

For 9eeae73: 0 issue(s). The review is encrypted for the maintainers in the review-findings artifact of this run.

[github-actions]

Adversarial review: NON-BLOCKING

For 704d2eb: 4 finding(s). The report is encrypted for the maintainers in the review-findings artifact of this run.

Rewritten on every push; the check fails on BLOCKING.