## Problem/Motivation A full read of every file on `1.x` found six things. Three of them are money, and all three are a rule this module already states being kept in one place and not in the next. ### A gateway's own settlement writes the whole payment object it was handed `WorldlinePaymentHandler::settle()` records the provider reference, and then the cardholder-authenticated flag, with two plain `save()` calls on the object its caller came in with. Saving an entity writes every one of its fields, so each of those also writes that request's idea of every other column. The settle lock keeps the three settlement channels apart from each other; a handoff request is not one of them. So a payer who clicks pay again while a webhook is settling has the onward URL the handoff just recorded against the locked row put back by the webhook's stale copy, and after paying they are sent to the front page instead of to what they were paying for. `docs/architecture.md` already states the rule: *every write to a payment goes against the locked row, not just the ones that read it first*. The engine was brought to it in #3621922; its own gateway and the simulator were not. - `modules/kessai_worldline/src/WorldlinePaymentHandler.php:262`, `:344` - `modules/kessai_worldline/src/Plugin/PaymentGateway/WorldlineGateway.php:700` - `modules/kessai_simulator/src/Form/SimulatorCheckoutForm.php:206` ### The fourth movement door takes an amount the other three refuse `recordTakenAndGivenBack()` is how a gateway records money the provider took and handed straight back. It checks that the amount is positive and nothing else, where `capture()`, `refund()` and `cancel()` all pass theirs through `assertMovementAmount()` — the guard those three gained in #3621921, which never reached this one. The two halves of a movement then round one figure differently. The row goes through core's decimal field, which rounds through a float on save; the payment's captured total accumulates with bcmath at two decimals, which truncates. An amount of `10.005` is a claim row of 10,01 against a total that grew 10,00, so the captured total stops being the sum of its completed claims — the invariant the whole record rests on. A malformed amount gets as far as bcmath, which raises naming a function rather than the caller. ### `create()` answers with a payment on a gateway the caller did not ask for A payment is created once per subject, kind **and amount**, the amount having been added because reuse must not answer with a figure nobody asked for. The gateway and the currency were left out of the same question, and that argument covers them word for word: a caller asking for an offline payment is handed the card payment already pending for the same subject and amount, hands the payer off to the wrong provider, and `capture()` then records a direct sale against a provider that never took anything. Asking in one currency can be answered with a pending payment in another. `authorizeToken()` and `chargeToken()` reuse on subject and kind alone, which is deliberate — a re-entry must not place a second hold — but a guarantee recomputed upward is then answered with the older, smaller hold and read as held, with nothing saying so. ### The metrics page counts a hook the module deliberately does not implement `docs/metrics.md` publishes "Hook implementations: 7". There are six. `scripts/generate-metrics.php` counts every occurrence of `#[Hook(` in a production `src/` file, and the seventh is a sentence of prose in `KessaiRuntimeRequirements` — the docblock whose whole point is that core refuses `#[Hook('requirements')]` and that the check has to be a class under `src/Install/Requirements/` instead. ### An over-long onward URL turns the pay button into a fatal Where the payer goes after paying arrives in a query string and is recorded on the payment. `OnwardUrl` hardened that value against an external target and against one `Url` cannot parse, on the stated grounds that a payer-supplied value must not be allowed to throw on the payer's critical path. The length was never guarded: the column holds 2,048 characters, and on MySQL the insert raises *Data too long* inside the handoff request, so the payer meets an error page at the moment they clicked pay. SQLite enforces no length, which is why no kernel test on the default backend can see it. ### The French calls the subject two different things on one screen The payment `kind` description reads « pour un même **objet** » where the field labels beside it, and the payments view's own column list, say « type de **sujet** » and « identifiant du **sujet** ». ## Proposed resolution - Three named doors on the manager that write against the locked row and reflect the write onto the caller's object, the way `recordReturnUrl()` already does: the provider reference, the payer authentication and the stored token. `recordReturnUrl()` and the three of them share one writer. The gateway guide gains the rule, so the next author does not have to rediscover it. - `recordTakenAndGivenBack()` scales the figure to the two decimals money is recorded in once, at the door, so both halves of the movement record the same number, and says at error severity when the caller's figure was finer than that. It refuses a malformed amount as the caller's mistake. It does not refuse an unrecordable one outright, and that asymmetry with the other three doors is deliberate: by the time this is called the money has already moved, so the row is the last chance to write anything down. - The gateway and the currency join the reuse question on all three creation doors. The token paths keep reusing an in-flight hold whatever its amount, and now warn when the figure differs from the one asked for. - The metrics generator counts the attribute where an attribute can appear, so a docblock mentioning one is prose again, and the page is regenerated. - The onward URL is measured against the field definition's own `max_length`, so the guard cannot drift from the column, and one that does not fit is refused with a warning naming both lengths. An unusable onward value already means the front page; this one means it too instead of meaning a fatal. - « sujet », which is the word the rest of the catalogs use. Every linter is clean before and after: phpcs at the templates' own ruleset and again at DrupalPractice, the alphabetical-imports sniff core runs on itself, phpstan level 5, cspell at the templates' expanded configuration, and potx per project in both directions across the five catalogs. ## The engine's vocabulary kessai is gateway-agnostic, so a card is a gateway's word and not the engine's. What the engine holds is a token, and the human at the other end is the payer. Every mention of a card is gone from the base module, its documentation and its French catalog; the two bundled gateways keep theirs, because a card is what they really take. **This renames public API.** On `PaymentInterface`: - `shouldStoreCard()` / `setStoreCard()` become `shouldStoreToken()` / `setStoreToken()`, and the base field `store_card` becomes `store_token`. - `getCardValidUntil()` / `setCardValidUntil()` become `getTokenValidUntil()` / `setTokenValidUntil()`, and the base field `card_valid_until` becomes `token_valid_until`. On `PaymentManagerInterface`, `deleteStoredCard()` becomes `deleteStoredTokens()`, which is also what it does: it takes a batch and deletes each distinct alias once. Three base-field labels move with them, and "Cardholder authenticated" becomes "Payer authenticated", since every method beside it already said payer and only the label said cardholder. The French follows. **Two base fields are renamed, so this is reinstall-only**, as every pre-1.0 change to this entity is, and four call sites outside this project have to move with it: `orchestra_payment` calls `deleteStoredCard()` and `setStoreCard()->setCardValidUntil()`, and `yoyaku` calls `deleteStoredCard()` twice. ## Naming A method name takes the base form of the verb, only the fixed predicate prefixes `is`, `has`, `should` and `can` may read as third person, and no method name starts with a noun. Two names this branch itself had added broke that, and a scan of all 199 method names in the module found three more that always had: `truncateMovementAmount()` (which also says what bcmath's scale really does, since it cuts and never rounds), `findReusablePayment()`, `hasExtraPrecision()`, `getSubjectLockName()`, `getReconcileBatch()` and `createPayment()`. In `kessai_worldline`, `callContext()`, `amountMatches()` and `cardExpiresBeforeDeadline()` become `buildCallContext()`, `hasMatchingAmount()` and `isTokenExpiringBeforeDeadline()`, the last because what it compares against is the payment's token deadline and the card expiry is only how Worldline answers that. A hook implementation carries the phrase core writes: `cron()`, the three `runtime()` methods and `paymentPredelete()` lead with *Implements hook_cron().* and its siblings. ## Two more the same read found on this branch's own diff **A forgotten token was written by saving the sibling payment whole.** `deleteStoredTokens()` asks the gateway to delete the alias before it clears anything locally, which is a network call, and the siblings come back through the storage's static cache: a settlement landing in that window is written by another request, which invalidates the shared cache and never this process's own. Saving the sibling therefore wrote this request's idea of the state and the totals back over the settlement, leaving a payment reading pending with a claim row saying money moved. It goes through the same locked-row writer as the doors above. **The line the undo door writes when it records nothing explained only half of what reaches it.** A zero or a negative amount is one case; a positive figure below a cent is the other, and for that one *only a positive amount moves money* is untrue: the money did move at the provider and it is this site that cannot write it down, so an operator sent to the merchant console looking for a zero finds four tenths of a cent. The line now names what the caller said and what it came to once cut to two decimals, which is true of both. ## The public API, shaped by audience An audit of the whole `@api` surface, method by method, against every caller in kessai, in orchestra and in yoyaku. Nothing changes at runtime: one service still answers and every call site does what it did. `PaymentManagerInterface` becomes the consumer's contract and nothing else. It carried 23 methods, 13 of which neither consumer had ever called. It carries 16, and each of them is something a consumer calls or reads. The 13 were not one thing. Five are called only by a gateway, and those are the *most* public methods in the module rather than internals: shipping an integration as a plugin is what kessai is for, so a gateway author is a second audience and kessai_worldline is only the first member of it. They are now `PaymentRecorderInterface`, which **extends** `PaymentManagerInterface` rather than sitting beside it, because a gateway settles as well as records and `capture()`, `authorize()`, `fail()` and `cancelPending()` are the consumer's own doors, not duplicates of them. Two had no audience at all. `openPaymentSession()` has exactly one caller, kessai's own handoff route, and `docs/events.md` already told consumers not to call it: announcing a departure when a URL is generated would lock an order for a page nobody acted on. `expireDuePayments()` has exactly one caller, kessai's own cron hook. Each is now its own `@internal` role interface, `PaymentSessionOpenerInterface` and `PaymentExpirySweepInterface`, which the manager also implements and which the route and the hook ask for by name. An `@internal` tag on a method of a public interface is a comment; a role interface is the type system saying it. Two more moved for their own reasons. `isReturnSecretValid()` goes to `PaymentInterface`: it only ever read the payment's own stored session secret and compared it, so it is a question about a payment and the payment answers it. And how a consumer *begins* a payment was a static method on an HTTP controller, next to `handle()` and its 403 branch, which orchestra imports today to build a URL and which both bundled gateways import for a constant; the link, the token and the two query-argument names are now `Drupal\kessai\PaymentHandoff`. `InternalPaymentManagerInterface` unions the four contracts and adds nothing of its own. It is what `PaymentManager` implements and what a kernel test driving the engine type-hints, so the set of internal roles can grow or shrink in one place without the implementation or its tests moving. That cheapness is deliberately internal: `PaymentManagerInterface` is published, so taking anything off *it* is still a break. `PaymentStorageSchema` keeps its `@api`. Its docblock documents the extension point, a kernel test pins it with a stub, and `orchestra_payment/src/PaymentStorageSchema.php` really does extend it. ## Consumers move with this Five call sites outside this project stop compiling the moment it lands, and they have to land with it: - `orchestra_payment`: `deleteStoredCard()`, `setStoreCard()->setCardValidUntil()`, and `PaymentHandoffController::getHandoffUrl()`. - `yoyaku`: `deleteStoredCard()`, in `DeleteCardAction` and in `BookingPaymentHooks`. AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the code and tests on the merge request. I reviewed and ran the work myself before posting it.)