Correct the commit-delta guidance: it fails loud, not silent (#991)

[erikdarlingdata]

Corrects guidance I wrote in #1703. Doc-only, no logic change.

What was wrong

#1703 lumped commit-delta triggers in with drain-time triggers and told a future implementer that both "fail SILENT rather than loud". For drain-time that is right. For commit deltas it is wrong, and wrong in the direction that matters — it would send someone to guard the suspended case and then ship a trigger that pages about every idle database.

The half I missed

ag-fixture-builder measured it while reproducing the never-latch result. On a quiet but perfectly healthy secondary — SYNCHRONIZED, is_suspended = 0, secondary_lag_seconds = 0 — last_commit_time sat 1757 seconds behind wall clock purely because nothing had committed. ag-collector-builder measured the same thing at ~7 minutes on a separate run. It grows without bound on an idle database.

So now - last_commit_time fails both ways:

• silent on a suspended row — the delta stops growing exactly when replication stops (what Say what secondary_lag_seconds actually measures (#991) #1703 described)
• loud on a quiet healthy one — grows without bound, and this is the half more likely to actually ship, because it shows up immediately in testing against any database nobody is writing to

Guarding only the suspended direction is not enough. The guidance is therefore no longer "route it through the may-fire-never-clear gate" but "do not derive lag from commit times at all". secondary_lag_seconds is the lag measure; the commit times are for showing an operator when something last happened, not for judging whether it is late.

This evaluator has never read those columns. It is simply the doc block a commit-delta trigger would be written into, which is exactly why the guidance in it has to point the right way.

Also on record

ag-fixture-builder's run is the third independent confirmation of the never-latch behavior, and more extreme than mine: zero lag across a full 60-second suspend with the last hardened log ~29 minutes stale, versus ~5 minutes on my run. So it does not depend on how stale the group already was — it simply never latched. They have corrected their own VALIDATION.md, which had described a bounded "+30s window" that someone could have reasoned about.

Testing

Darling suite green: 3252 passed, 0 failed.

🤖 Generated with Claude Code