Add a charge-based connector mode with a local billing cycle engine

Scope note: the charge-outcome model here (submitted, then succeeded or failed via webhook, failures to #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications, merchant refunds via refund()) deliberately treats succeeded as terminal. Payer-initiated reversals after success — SEPA's eight-week refund right, Bacs indemnity claims, ACH/PAD consumer returns, card chargebacks — are split into #3619074: Succeeded charge records are terminal, so payer-initiated reversals (SEPA refunds, Bacs indemnity claims, chargebacks) have nowhere to land. For this issue, the only ask is that the charge-record state design leave room for a later reversed state reachable from succeeded (i.e. don't hard-code succeeded as final in the storage or state machine).

Design review ahead of implementation, resolving what the summary deferred and recording the decisions:

1. The per-period charge record is a content entity (subscription_charge), not field storage on the subscription. Every consumer wants entity affordances: the dunning framework (#3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications) queries by state, the refund admin action wants a route and list builder, the tax seam (#3618741: Add a pluggable tax/invoice service seam (calculation, evidence, invoice reference), keeping tax engines out of core) stores an invoice reference per charge, and #3619074: Succeeded charge records are terminal, so payer-initiated reversals (SEPA refunds, Bacs indemnity claims, chargebacks) have nowhere to land adds reason-code/fee fields later. Fields: subscription reference, period start/end, amount (decimal) + currency, state, remote_charge_id, refund amount/state, raw-data map. No revisions — the row itself is the audit trail.

2. State machine: submitted → succeeded | failed, with the allowed-transitions map defined once as entity-level data so #3619074: Succeeded charge records are terminal, so payer-initiated reversals (SEPA refunds, Bacs indemnity claims, chargebacks) have nowhere to land adds succeeded → reversed without rewriting logic (per the scope note in #6), and #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications models a retry as failed → submitted on the SAME record — one record per period is the invariant. A second, documented creation path makes records directly in succeeded with amount 0 and no remote id ("settled locally", for zero-amount periods below).

3. Anchor semantics and idempotency: the anchor advances only on success, per the summary — which means a pending asynchronous charge leaves the anchor in the past, so the due-query must exclude subscriptions holding an open (submitted) charge record: the charge record is the idempotency key. Its UUID is also passed to the connector in charge()'s context as the remote-side idempotency key, so a crashed-and-retried worker cannot double-charge. Anchor arithmetic clamps month-end days (Jan 31 → Feb 28 → Mar 31) by preserving the original billing day rather than recomputing from the previous charge date, and all proration math runs in integer minor units, never floats.

4. Interfaces: three small ones rather than one fat one, so connectors opt in per capability and instanceof routes. ChargeBasedConnectorInterface: charge($subscription, $amount, $currency, array $context): ChargeResult, setupInstrument() (the single method serving free-plan signup, first setup, and replacement completion — it starts the hosted flow; the connector's return path reports the instrument reference back to the engine), and refund() (a charge-based connector without refunds is not shippable). InstrumentReplacingConnectorInterface carries the optional replacement flow. ChargeResult is a value object: succeeded | pending | failed, remote id, message — pending is the async-rail answer, resolved later by the connector's webhook updating the charge record. Mode declaration: a supported_modes key on the connector attribute/annotation defaulting to ['self_scheduling'] (existing connectors untouched), plus a scheduling_mode plan field validated against the connector's set.

5. Two subscription fields the summary implies but does not name: instrument_id (the vaulted-token/mandate reference charge() draws against, and what replacement swaps — customer_id/subscription_id mean remote-service concepts and stay as they are), and pending_plan_id (where a scheduled downgrade lives until the engine applies it at the next anchor).

6. Billing intervals: monthly and yearly only for now, as an extensible allowed-values list — a third interval later is configuration and tests, not surgery.

7. Zero-amount periods: whether they produce a charge record is configurable — record_zero_amount_periods in subscription_manager.settings, default TRUE. Recording by default gives every site an audit trail while the engine bеds in (and a visible "free period renewed" history); sites can later turn it off to stop accumulating rows. Turning it off stops future rows only; a mixed history is expected and the setting description says so. With recording off the engine still logs the zero-amount anchor advance at INFO. Either way the anchor advances without contacting any connector.

8. Seams kept open, not built: computePeriodAmount() is the single documented insertion point where #3615735: Add a rating step for usage-based charges, delivered per connector scheduling mode adds rated usage and #3618741: Add a pluggable tax/invoice service seam (calculation, evidence, invoice reference), keeping tax engines out of core adds tax; its v1 returns the plan base price. A failed charge in v1 is record-and-log, explicitly interim until #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications supplies past_due and retries.

Implementation lands as one MR with staged commits (mode declaration → charge entity → interfaces → engine + QueueWorker → plan changes → tests throughout), including the test charge-based connector the remaining tasks call for.

MR opened, implementing the design from #7 as five staged commits (mode declaration → charge entity → interfaces → engine + QueueWorker → test connector and tests):

• Mode declaration: supported_modes on the connector attribute/annotation (default self-scheduling only — existing connectors untouched), a scheduling_mode plan field, and a validation constraint enforcing the connector's declared set.
• subscription_charge: one record per (subscription, period), declared with the modern ContentEntityType attribute; the state machine is a single ALLOWED_TRANSITIONS map with a guarded transitionTo(), leaving #3619074: Succeeded charge records are terminal, so payer-initiated reversals (SEPA refunds, Bacs indemnity claims, chargebacks) have nowhere to land's reversed state and #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications's failed→submitted retries as data extensions per the scope note in #6.
• Interfaces: ChargeBasedConnectorInterface (charge(), setupInstrument(), refund()), InstrumentReplacingConnectorInterface, and the ChargeResult value object (succeeded | pending | failed).
• The engine: cron enqueues due subscriptions, CycleWorker drains with per-item isolation. The anchor advances only on success; the open submitted record is the local idempotency key and its UUID travels to the connector as the remote one; resolveCharge() is the webhook-side resolution API. Billing-day clamping survives short months; money math is integer minor units end to end. Zero-amount periods advance without a connector, recording a settled-locally row per the new record_zero_amount_periods setting (default TRUE). Upgrades apply immediately with a prorated charge and an untouched anchor; downgrades store pending fields and apply at the anchor; plan changes cannot cross connectors. computePeriodAmount() is the documented seam for #3615735: Add a rating step for usage-based charges, delivered per connector scheduling mode and #3618741: Add a pluggable tax/invoice service seam (calculation, evidence, invoice reference), keeping tax engines out of core; a failed charge is record-and-log, interim until #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications.
• Tests: 12 new Kernel tests driving all four charge outcomes through a new charge-based test connector — money conversions, day clamping (Jan 31 → Feb 28 → Mar 31; leap-day yearly), duplicate-blocking while pending, webhook resolution, zero-amount recording on and off, a real cron run end to end, proration with immediate role swap, downgrade-at-anchor, the cross-connector guard, and the constraint.

Two discoveries along the way: the role-swap tests exposed a latent plan-change bug — preSave's old-role removal saves the owner, whose presave union reads the database row (still active, old snapshot) and resurrected the roles being revoked; the changing subscription is now excluded from the union during removal, the mechanism preDelete() already used. And plan validation surfaces a pre-existing primitive-type violation on the show field (nothing ever called validate() on plans before); left for the cleanup omnibus #3616937: Cleanup omnibus: dead config keys, missing token dependency, per-role user saves, page_attachments overhead, drush alias, field length, translatability, misc.

Change record drafted covering the new interfaces, entity, fields, setting, and mode declaration.