Build the membership portal page on capability interfaces, replacing the unused inline-actions API

Design pass before implementation, checked against 1.0.x as of 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). The summary's direction holds; this pins down the interfaces, the cancellation semantics, and what stays out.

What the code says today

• The manage route (/user/{user}/manage-subscription) loads the user's subscription and returns $connector->redirectToPortal($user), unconditionally. redirectToPortal() is on the base connector interface, so a charge-based connector must implement it with nowhere to send anyone. The api/portal-url endpoint does the same.
• The four portal methods have one remaining caller: the executeAction('cancel') fallback in RemoteCancellation (#3616934: Deleting a user deletes local subscription entities but never cancels the remote contract, so billing continues), which exists only for them.
• The cycle engine bills every subscription with status = 1 and a due cycle_anchor. Nothing sets cancel_date; nothing stops renewal. The cron expiry sweep already deactivates any active subscription whose expiry has passed, and deactivation already revokes the granted roles.
• InstrumentReplacingConnectorInterface::replaceInstrument() exists and nothing calls it; the dunning mails link to the manage route, where today there is nothing to click.
• There is no price model upstream: amount_basis is whatever the connector's return path stored, and CycleEngine::upgrade()/scheduleDowngrade() take the new amount as an argument. The plan's prices field is an opaque per-connector map.

Proposal

1. Hosted portals become a capability. redirectToPortal() moves off SubscriptionManagerConnectorInterface into a new HostedPortalConnectorInterface. The manage route redirects when the subscription's connector implements it (today's behaviour for Stripe, Recharge, Chargebee, Shopify — they add the interface to their implements list) and renders the native page otherwise. api/portal-url returns the hosted URL or the native page's URL accordingly. The existing manage_route setting still lets a site substitute its own page.

2. The four portal methods are removed from the connector interface, with no replacement for getSubscriptionDisplayData(): the page is built from the local entity (plan, status, billing state, next charge, pending cancellation), which is the same for every connector, and nothing has ever consumed the remote version. If a connector later wants to add remote details, an optional interface is a small additive change then. RemoteCancellation loses its executeAction('cancel') fallback and becomes: the interface, or "cannot cancel by API".

3. Cancellation for charge-based subscriptions — new cycle-engine operations, the only place billing state changes:

• CycleEngine::cancel($subscription) — cancels at period end: records cancel_date (when it was requested) and sets expiry to the cycle anchor, i.e. the end of the period already paid for. status stays 1, so access continues; the engine stops billing it (findDueSubscriptionIds() and processDueSubscription() both skip a subscription with a pending cancellation, explicitly, rather than relying on cron ordering); a scheduled downgrade is dropped. No refund, no proration: the current period stays as paid, as with downgrades.
• CycleEngine::resume($subscription) — before the expiry, clears cancel_date and expiry; renewal continues as if nothing happened. The stored instrument was never touched, so no new setup is needed.
• At expiry the existing sweep deactivates the subscription (roles revoked). New: for a cancelled charge-based subscription it then calls RemoteCancellation::cancel(), so a connector implementing RemoteCancellingConnectorInterface revokes the mandate or vaulted card. Until then the instrument is kept, which is what makes resuming free.
• Cancelling while past due ends the subscription immediately. There is no paid period left to honour — the current one is the one whose charge failed. Dunning is cleared (no further retries), the subscription is deactivated, the instrument is revoked as above. The failed charge record stays failed; collecting it is out of scope.
• cancel() takes an $immediately flag for administrators and site code (same path as the past-due case). The page offers users period-end cancellation only.
• SubscriptionEntity::willRenew() learns the local answer: FALSE with a pending cancellation, TRUE for an active charge-based subscription without one; the remote-status logic remains for self-scheduling subscriptions.
• Two events, CANCELLATION_SCHEDULED and CANCELLATION_REVERTED, so a site can send a confirmation or react. No built-in mails here; the end of the subscription is already observable as the status change.

4. The native page. Rendered at the manage route for a connector without a hosted portal: plan name, status, billing state (reusing the past-due notice from the billing history page), next charge date and base amount, or "Cancels on date"; a link to the billing history (#3621282: Show subscribers their invoice history in the membership portal); and actions, each present only when it can work:

• Cancel subscription / Keep my subscription — charge-based subscriptions; confirm forms at …/manage-subscription/cancel and …/resume.
• Replace payment method — when the connector implements InstrumentReplacingConnectorInterface; a CSRF-protected route that returns replaceInstrument()'s redirect. This is the landing spot the dunning mails have been linking to.
• Change plan — a link to the subscribe route. See 5.

A theme hook and template (no inline markup), cached per user with the subscription_list tag, access through the existing manageSubscriptionAccess() (owner with manage own subscriptions, or an administrator). A self-scheduling connector that has neither a hosted portal nor these capabilities gets the read-only page.

5. Plan changes are a link, not a form — for now — and the link has to work across connectors. Two cases:

• Same connector. The page links to the subscribe route, which hands an existing subscriber to their connector's own flow. That flow knows its prices and changes the existing subscription through upgrade() (immediately, prorated) or scheduleDowngrade() (at period end); nothing is cancelled. Doing this in the page itself — a list of plans, the price difference, the effective date — needs to know what a plan costs, and there is no upstream way to ask: prices are an opaque per-connector map and amount_basis is supplied by the connector. That price-resolution seam is a design of its own and gets a follow-up issue.
• Different connector (a free rail and a paid rail, say). The engine side exists: the user signs up on the target connector, and saving the new subscription deactivates the old one through the single-active rule (#3616778: Define and enforce single-active-subscription semantics (loadLocalSubscription() returns an arbitrary first match)). But the subscribe route cannot get an existing subscriber there: it sends anyone with a subscription — active or lapsed — to their current connector, and honours ?connector= only for users who have none. That is fixed here, since the portal's link is useless without it: ?connector= is honoured for existing subscribers; the portal's link opens the chooser (when more than one connector is available) with the current connector marked; and a user whose only subscription has lapsed gets the chooser like a new user rather than being pinned to the old connector.

A cross-connector switch is immediate: the old subscription is deactivated when the new one is saved, and the remainder of its paid period is not carried over (a customer who wants to keep it cancels at period end and switches afterwards). New here: when the single-active rule supersedes a charge-based subscription, its stored instrument is revoked through RemoteCancellation, as at any other end of a subscription; today the superseded row is only marked inactive.

6. Self-scheduling connectors are otherwise untouched. A user-facing cancel through RemoteCancellingConnectorInterface would cancel immediately (that is its contract, for discarded subscriptions), which is the wrong default for a customer who has paid through the month; period-end cancellation on a remote contract is a different remote operation. Those connectors keep their hosted portals. Out of scope too: pause, refunds, and collecting failed charges.

Data model

No new fields. cancel_date (described today as the upstream cancellation timestamp) becomes "when cancellation was requested", for both modes; expiry is already the access-until date the sweep acts on. A pending cancellation is: active, cancel_date set, expiry in the future.

Tests

Kernel: cancel sets the fields and the engine does not bill at the anchor; resume restores renewal; expiry deactivates, revokes roles and calls the connector's remote cancellation once; past-due cancel is immediate and stops retries; the immediate flag; events; a pending downgrade is dropped; willRenew(). Page: redirect for a hosted-portal connector, native render otherwise, each action's presence per capability, access (owner, other user, administrator), confirm forms through the form builder, the replace-instrument route's redirect and CSRF requirement, cache metadata, api/portal-url in both shapes. Subscribe route: ?connector= honoured for an existing subscriber, the chooser for a lapsed one, the current connector marked, and a superseded charge-based subscription's instrument revoked. The inline-action tests added in #3616934: Deleting a user deletes local subscription entities but never cancels the remote contract, so billing continues/#3616937: Cleanup omnibus: dead config keys, missing token dependency, per-role user saves, page_attachments overhead, drush alias, field length, translatability, misc are reworked onto the interfaces.

Connector impact (breaking, for the catch-up issues)

Every connector: delete the four portal methods; add HostedPortalConnectorInterface to keep redirectToPortal() working. Charge-based connectors: implement RemoteCancellingConnectorInterface and InstrumentReplacingConnectorInterface to light up the corresponding actions; drop any stub redirectToPortal().

Decisions to ratify: (1) redirectToPortal() moves to HostedPortalConnectorInterface; (2) the four methods go, with no replacement for display data; (3) cancellation at period end, immediate when past due, resumable until expiry, instrument revoked at the end, two events and no built-in mails; (4) the page as described; (5) plan change as a link to the subscribe flow, which is opened up to existing and lapsed subscribers so cross-connector switches are reachable, with the superseded instrument revoked; in-page same-connector switching deferred to a follow-up; (6) native actions for charge-based subscriptions only.

Implemented in the MR as ratified in #2, in eight commits — four themes, each followed by its tests — meant to be reviewed in order.

1. Cancellation in the cycle engine. CycleEngine::cancel($subscription, $immediately = FALSE) schedules the end of a charge-based subscription for the end of the period already paid for: cancel_date records the request, expiry the cycle anchor, a scheduled downgrade is dropped, and both findDueSubscriptionIds() and processDueSubscription() skip it explicitly. resume() withdraws that before the expiry. end() deactivates, clears dunning (so no retry can charge or revive it) and asks the connector to revoke the instrument through RemoteCancellation; it runs for immediate and past-due cancellations and from the cron expiry sweep. Two cases the design did not spell out, handled the conservative way:
   • a period whose asynchronous charge is still settling counts as paid for, so cancelling then sets the expiry to that charge's period end rather than ending on the spot;
   • if that charge then fails, the subscription ends instead of entering dunning — a customer who has cancelled is not chased, and gets no past-due mail.

   Plan changes are refused while a cancellation is pending. SubscriptionEntity gains getCancelDate(), getExpiry(), hasPendingCancellation() and isChargeBased(), and willRenew() answers locally for charge-based subscriptions. Events: CancellationEvents::SCHEDULED and ::REVERTED.

2. The native page. redirectToPortal() moves to the new HostedPortalConnectorInterface; the manage route and api/portal-url use the hosted portal when the connector implements it and the native page otherwise. The page is built by a PortalBuilder service (the controller was long enough) and a subscription-manager-portal.html.twig template: plan, state (active / cancelling / past due / ended), next charge and base amount or the end date, the past-due warning shared with the billing history, and the actions the subscription supports. Cancel and resume are confirm forms; Update payment method is a CSRF-protected route into replaceInstrument() — the landing spot the dunning mails have been linking to since #3618740: Add a dunning framework: past_due state, scheduled retries, grace period, and lifecycle notifications.
3. The four portal methods are gone from SubscriptionManagerConnectorInterface, and RemoteCancellation no longer falls back to executeAction('cancel').
4. Switching connectors. The page and the API now share one decision (subscribeTarget()): an explicit ?connector= is honoured for everyone, ?change=1 (the page's Change plan link) reopens the chooser for an active subscriber with their current connector marked, and a lapsed subscriber chooses like a new one instead of being pinned to the old connector. When the single-active rule supersedes a charge-based subscription, the engine ends it — out of dunning, instrument revoked — with one guard the design did not mention: not when the replacement charges the same instrument on the same connector, which would have revoked the new subscription's own mandate.

Tests. SubscriptionCancellationTest (11) and SubscriptionPortalTest (8) are new; ConnectorChooserTest gains the switching and lapsed-subscriber cases; the duplicate-resolution and user-deletion tests move off the removed fallback. The test connector splits into a portal-less base and a hosted-portal subclass so the charge-based test connectors exercise the native page. Suite: 198 kernel tests, 2820 assertions; phpcs clean.

Not here, as agreed: in-page switching between plans of one connector (needs a price-resolution seam; follow-up if wanted), period-end cancellation of remote contracts, pause, refunds. No update hook: no schema or config changes.

Change record drafted; every connector is affected (see it for the checklist).

Updated issue summary.