Treat a charge exception as an unknown outcome, reap stale submitted charges, never bill or revive a subscription that is no longer live, and stop back-billing suspended time

Design pass, from reading every path in CycleEngine, DunningManager, the retry worker and the resolver. One finding from the summary turns out to be resolved by construction once the others are fixed (item 4 below), and one needs a cron-level sweep rather than the cycle step (item 2).

1. An exception is an unknown outcome, re-submitted with the same key

A charge record gains an attempt field (the attempt number its open submission used; 1 on creation, the claimed number on a retry) and a resubmissions counter. When charge() throws, at any of the four call sites, the record stays submitted with the message in data['last_error']; nothing enters dunning and no event fires. The next settlement sweep re-submits it to the connector with the same charge_uuid and the same attempt, so the key is identical and the processor's idempotency returns the original charge if the first submission went through. Each re-submission increments the counter; when it passes the limit (setting, default 3) the record transitions to failed with the last error and goes to dunning as a decline does today, whose retry claims a new attempt number as now. The interface's contract — stable key per attempt, distinct per retry — is unchanged and finally used as written. Connectors need no change; one that can look up a charge by idempotency key may do so inside charge(), but nothing requires it.

2. A settlement sweep on cron, not in the cycle step

Open charges are not only period charges: a proration charge from upgrade() belongs to a subscription whose anchor is in the future, so processDueSubscription() never sees it. A new CycleEngine::settleOpenCharges(), run from cron before the cycle, loads every submitted charge whose changed is older than the settlement wait (setting, default 1 hour). Those without a remote charge ID are re-submitted as in item 1 (that covers the PHP-timeout case: the record was saved, the call never returned, so nothing was recorded). Those with a remote charge ID are an asynchronous rail's charge awaiting its webhook: left alone, logged as a warning once per sweep past the wait, and listed by a new Drush command subscription_manager:stale-charges for the operator. hasOpenCharge() keeps the cycle step out while a charge is open, unchanged. A pending result that carries no remote charge ID is treated as unknown and re-submitted; with an idempotent key that is harmless, and it is the connector's bug to fix.

3. Liveness

• markRecovered() no longer sets status: recovery means "no longer past due" and applies only when status is on; on a subscription that is off it is a no-op (the charge is still recorded as settled — money moved — but nothing revives).
• suspend() clears next_retry: suspension is the end of the dunning run. billing_state stays past due for display. With the default offsets (3, 7, 14 days) and grace (21), every retry already happens before suspension, so in practice this changes nothing for default sites; it closes the door for sites with retries after grace.
• recordChargeFailure() on a subscription whose status is off marks the charge failed and logs, without entering dunning. Covers the failure webhook arriving after an immediate cancellation, and after an end() for any reason.
• rebillReversedCharge() refuses a subscription whose status is off, like its other refusals.
• DunningRetryWorker also checks status, belt and braces.

4. No back-billing after suspension — resolved by construction

With item 3, a suspended subscription cannot come back to life through the engine: nothing retries it and a late webhook success no longer flips status. A subscription that is off is never due, so no elapsed period is ever billed. Recovery within grace is unchanged and correct — the customer had access, the elapsed periods are owed. So no re-anchoring code is needed. What a suspended customer needs is a way back that does re-anchor to now: a Pay now / reactivate action on the native page. That is new self-service, and I propose it as a Phase 5 issue next to #3629796: Let a charge-based subscriber switch plans on the native management page, upgrading now and downgrading at period end rather than here; until then a suspended customer subscribes again through the chooser, as the page already offers.

5–8. The small ones

• upgrade() clears pending_plan_id and pending_amount_basis.
• The resolver calls CycleEngine::end($loser, revoke_instrument: FALSE) — it has already called remote cancellation itself — so dunning fields are cleared with the status.
• A pending refund result is recorded in a new pending_refund_amount on the charge, not in refund_amount; CycleEngine::resolveRefund($charge, bool $success) moves it into refund_amount and records the credit note, or discards it. A second refund request while one is pending is refused.
• Period guard: before opening a period charge, processDueSubscription() looks for a succeeded charge of the same subscription and period_start; if found, it advances the anchor to that charge's period_end and logs, instead of charging.

Data model, settings, tests

Three charge fields (attempt integer default 1, resubmissions integer default 0, pending_refund_amount decimal nullable), installed by update 10028 through the entity definition update manager; the update-path tests extend their schema expectations. Two settings under dunning: resubmission_limit (3) and settlement_wait_hours (1), on the dunning section of the settings form, defaults set by the same update. Kernel tests: each item above, plus the existing testRetryTransportFailureReentersSchedule rewritten for the new semantics (a throw during a retry leaves the charge submitted with the same attempt; the sweep re-submits with the same key, asserted through the test connector's recorded context; the limit turns it into a failure that re-enters the schedule). A change record covers the behaviour and the two settings; no connector interface changes.

Decisions to ratify

1. Unknown outcomes stay submitted and are re-submitted with the same key up to a limit, rather than a new charge state.
2. The settlement sweep runs on cron over all open charges, with a settlement wait of 1 hour and a limit of 3 re-submissions as defaults.
3. Suspension ends the dunning run, and recovery never changes status; a Pay now / reactivate action for suspended subscriptions becomes a Phase 5 issue rather than part of this one.
4. No re-anchoring code: back-billing of suspended time is impossible once 3 holds.
5. Pending refunds get a field and resolveRefund() now, rather than waiting for a connector that needs it.
6. The period guard advances the anchor past an already-paid period instead of charging.

Implemented in the MR, in eight commits, following the six decisions ratified in #2 with one deviation on the defaults in decision 2, explained under Data model and settings.

Unknown outcomes and the settlement sweep

All four charge call sites (period, retry, proration, re-bill) go through one CycleEngine::submit() that reads the attempt number from the charge record — the new attempt field, 1 on creation and the claimed dunning attempt on a retry, stored before the call. An exception from the connector leaves the record submitted with the message in data['last_error']; nothing enters dunning and no event fires.

CycleEngine::settleOpenCharges(), run from cron before the cycle, loads every submitted charge whose changed is older than the settlement wait. Those without a remote charge ID are re-submitted with the same charge_uuid and attempt — the test connector records every context it receives, and the tests assert the key is identical across the original and the re-submission — incrementing resubmissions; at the limit the record transitions to failed with the last error and enters dunning as a decline does. Those with a remote ID are logged once per sweep and listed by drush subscription_manager:stale-charges (sm-stale-charges). The sweep also covers a record saved before a call that never returned, which used to block the cycle forever.

Liveness

markRecovered() no longer sets status and is a no-op on a subscription that is off; suspend() clears next_retry; recordChargeFailure() on an inactive subscription settles the record without dunning; rebillReversedCharge() refuses an inactive subscription; the retry worker checks status. The tests cover the three triggers from the summary: a suspended subscription whose forced retry is refused and whose late webhook success does not revive it (and does not end a replacement subscription the customer bought meanwhile), a failure webhook after an immediate cancellation, and a re-bill on an ended subscription.

As the design pass said, no re-anchoring code was needed: with the above, nothing bills a suspended subscription's elapsed periods because nothing revives it. The settings-form description of the dunning section now says so. The Pay now / reactivate action from decision 3 is filed as #3630230: Add a "Pay now" action for past-due subscriptions and a "Reactivate" action for suspended ones to the management page.

The rest

• upgrade() clears the pending plan; a test schedules a downgrade, upgrades, and asserts the upgraded basis bills at the anchor.
• The duplicates resolver ends a charge-based loser through CycleEngine::end($loser, revoke_instrument: FALSE) (it has already revoked remotely); a test seeds a past-due loser and asserts the schedule is gone and cron retries nothing.
• Period guard: processDueSubscription() advances the anchor past a period that already has a succeeded charge instead of charging. One existing reversal test had to move its seeded paid charge back a period, since it rewound the anchor onto a paid period to force a second charge.
• Pending refunds: pending_refund_amount and CycleEngine::resolveRefund($charge, bool $success); one refund pending at a time; the test connector gained a pending refund behaviour.

Data model and settings

Update 10028 installs attempt, resubmissions and pending_refund_amount on the charge entity and sets dunning.settlement_wait_hours and dunning.resubmission_limit; both are on the settings form. The update-path tests expect the fields and the settings.

Deviation from decision 2: the defaults are 4 hours and 5, not 1 hour and 3. Three re-submissions an hour apart gave a provider outage about four hours before every open charge turned into a failure, with a "payment failed" mail to the subscriber and, three days later, a dunning retry under a new key, which is the double-charge the issue set out to prevent. The sweep also only runs on cron, so on a site with Drupal's default three-hourly automated cron the real window was twelve hours and on an hourly one four, which the setting should not hide. Six four-hour windows give about a day on either, and a day is also about how long processors remember idempotency keys (Stripe: 24 hours), so a longer budget would not add protection; past it, a same-key re-submission is a fresh charge anyway. The subscriber keeps access throughout, since an open charge keeps the cycle out and nothing is past due until the record fails. Both descriptions on the form say this.

SubscriptionChargeEntityInterface gains getAttempt(), getResubmissions() and getLastError().

Tests

Three tests that encoded the old behaviour are rewritten (a throw during a retry; a late success after suspension; the mails scenario, which now recovers within grace and suspends in a second episode) and ten added; the settlement tests age charges by the engine's configured wait, so they do not encode the default. across DunningTest, CycleEngineTest, ChargeRecordTest, ChargeReversalTest, SubscriptionCancellationTest and MaintenanceServicesTest. Suite: 209 Kernel tests, 6 Functional tests; phpcs clean. Change record drafted. The README's dunning and operator sections describe the new behaviour and the command.

Added missing reference.