### Problem/Motivation A full read of the module from its first file rather than a diff against the last tag: all 142 tracked files, plus phpcs at the ruleset CI fetches and again at DrupalPractice, phpstan at level 5, cspell at CI's own configuration, potx per project against each of the five catalogs in both directions, a duplicate scan over every PHP file, an import-order sniff and a docblock-parameter scan. Every linter is clean and the translations are complete. Eight findings. One is a defect, and it moves money: - **`capture()` records a claim for an amount `refund()` and `cancel()` refuse.** An amount above the hold is clamped down to it and nothing bounds the other end, so `capture($payment, '-5.00')` writes a completed claim of −5,00, sends −500 minor units to the provider, takes the captured total below zero and *grows* the hold derived from it. Every later refund of that payment is then refused as more than is refundable: money the engine believes it took and will never let back out. That is the defect #3621919 closed at `create()`'s door, still standing at the capture door. - **The same door lets through an amount money cannot be recorded in.** A movement of `'10.005'` is stored two different ways by the two halves that record it: the row goes through core's decimal field, whose `preSave()` rounds through a float, while the payment's total accumulates with `bcadd(…, 2)`, which truncates. So the row says 10,01, the captured total grows by 10,00, and the total stops being the sum of the completed claims — an invariant the README and the architecture page both state. `refund()` and `cancel()` refuse a non-positive amount but bound the precision no better. Two are documentation that contradicts the module: - **The gateway guide's own example tells an author to do what the section below it forbids.** The sample `initiate()` says to return NULL when "an offline gateway, or the provider refused"; the section three lines under it is titled *NULL means "I never redirect", not "I could not"* and says a provider that refused must raise `GatewayDeclinedException`. An author copying the sample ships the failure the page then explains: the payer clicks pay, lands back where they started, and nothing tells them the payment never began. - **The audit-trail chain still cites the write API renamed in #3621920.** The comment that explains why the chain is in `flag` mode rather than `auto` names `event()`, which the subscriber stopped calling in `097421b`. It is the one place a reader goes to find out why the mode is what it is. One is a contract the reference gateway does not keep: - **The simulator hands back a relative checkout URL** where `CheckoutSession::$url` is documented as absolute, and a real provider's always is. The redirect resolves in a browser, so nothing fails today; a checkout link re-sent in a mail, which the documentation names as a case, does not. The simulator is also the worked example a gateway author reads. Two are prose that stopped describing the module and started describing its diffs: - **The Worldline page narrates its own changes**: "That is the point of the change", "Before it, an abandoned checkout was recorded failed…", "the case … no longer loses the chain", "The status report now says so", "behaves exactly as it did before". None of it is the design, and all of it dates the page for a reader who was not there. - **The metrics page was measured two commits back**, and the events page passes two defaults positionally (`capture($payment, NULL, TRUE, 'no_show')`) where the project's own idiom, used in the architecture page, is a named argument. Two are standards the contrib CI ruleset does not carry: - **Three files import their namespaces out of alphabetical order**, most visibly a controller importing `Drupal\kessai\PaymentInterface` before `Drupal\kessai\Controller\PaymentHandoffController`. The sniff core runs on itself (`SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses`) reports all three; the contrib ruleset has no ordering sniff, so the pipeline stays green. - **Six functions document no parameters** — the simulator's two submit handlers and four helpers in the metrics script — in a codebase that documents every parameter of every other function. phpcs stopped asking once a parameter is natively typed, which is how they survived. One is duplication of the kind #3619740 and #3621919 each fixed one of: - **The payment-event listener is written out four times.** Four kernel classes each declare the same `$events` property and the same eight-line loop registering a listener per event name. The suite already extracted `PaymentReloadTrait` for exactly this, and its docblock says thirteen classes had written that one out. ### Proposed resolution - One rule for a caller-named movement amount, at the three doors that take one: it has to be money this engine can record, and something has to actually move. `assertAmount()` gains the precision half (an amount is refused when recording it to two decimals would change it; a trailing zero is not extra precision, so `'10.000'` passes), and `assertMovementAmount()` adds the positive half for `capture()`, `refund()` and `cancel()`. NULL never reaches it: it means "whatever is still held" or "whatever is still refundable", which each operation resolves against the payment and guards for itself. - Make the gateway sample's comment name the one case NULL is for, and point at the section that explains it. - Name `record()` in the chain comment, which is what the subscriber calls. - Ask the simulator for the absolute URL the contract describes. - State the rule and drop the before-and-after in the Worldline page; regenerate the metrics page; use the named argument in the events page. - Insert the three import blocks in order. - Document the six parameters. - One `PaymentEventBufferTrait` beside the other four test traits, taking the event names to collect. ### Remaining tasks Review and merge. ### User interface changes None. ### API changes `PaymentManagerInterface::capture()`, `::refund()` and `::cancel()` now raise `InvalidArgumentException` for an amount that is not positive or that carries more precision than the two decimals money is recorded in; `capture()` previously took any amount at or below the hold, including a negative one. `::create()`, `::authorizeToken()` and `::chargeToken()` apply the same precision rule to the amount they already validated. Nothing is removed and no signature changes. ### Data model changes None. ### Release notes snippet A capture is refused when the amount is negative or carries more precision than money is recorded in, rather than being written as a claim that takes the payment's captured total below zero or leaves it no longer the sum of its claims; a refund and a reversal apply the same precision rule. The gateway guide no longer shows a sample that contradicts its own rule about returning NULL, and the bundled simulator hands back the absolute checkout URL its contract describes. AI-Generated: Yes (Claude Code was used to read the module, to draft this issue summary, and to write the fixes and their tests on the merge request. I reviewed all of it, and the new tests were confirmed to fail against the unfixed code.)