>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3615856. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !46 >>> <p>Found by a full read of <code>1.x</code> at 16b77e7 while preparing the next alpha, alongside <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3615854" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3615854</a></span> and <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/kessai/-/work_items/3615855" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/kessai/-/work_items/3615855</a></span>. The documentation half of the same audit.</p> <h3>events.md contradicts the current expiry design</h3> <p>The warning under <em>The deadline: EXPIRED</em> in <code>docs/events.md</code> states that expiry never asks the provider, that money can be taken while the payment reads expired with no CAPTURED event, and advises the reader to reconcile from the provider rather than trusting expiry. The sweep has reconciled before expiring since the reconciliation work landed, and <code>docs/architecture.md</code> documents that at length under <em>Reconciling before writing a payment off</em>. Two pages, opposite claims, and the stale one is the one a consumer author reads first.</p> <h3>The metrics page measures a codebase that no longer exists</h3> <p><code>docs/metrics.md</code> presents a <em>measured</em> snapshot dated 2026-07-31: 102 files and 7,931 lines of code. <code>cloc</code> now reports 115 files and 10,913. Regenerate it with <code>scripts/generate-metrics.php</code> before the release, since a page whose whole value is that it was measured must not be stale.</p> <h3>Smaller drift, all in the same pass</h3> <ul> <li><code>architecture.md</code> omits <code>authenticated</code> from the payment field table, though it is a shipped base field carrying real behaviour as the card-on-file chain anchor. Its <em>Four amounts</em> section then omits <code>reversed</code> and mixes the four stored fields with two derived accessors.</li> <li>Nothing explains why <code>WorldlineGateway::returnToken()</code> and <code>SimulatorCheckoutForm::checkoutToken()</code> sign only the payment id while <code>handoffToken()</code> is deliberately bound to the deadline. The asymmetry is correct and should stay: a token baked into a URL the provider holds, or into a stored session URL, cannot die when a deadline is re-stamped without stranding the payer. It just needs saying, or someone will "fix" it.</li> <li><code>docs/worldline.md</code> uses "revisitable", which is not a word and is not in the project dictionary. cspell is allow_failure on the CI template, so it goes red under a green badge.</li> <li><code>WorldlineGateway::returnUrl()</code> points its docblock at <code>rememberReturnUrl</code>, deleted when the checkout session moved into the engine.</li> <li><code>KessaiSettingsForm</code> calls it "the hourly sweep"; cron frequency is a site decision.</li> <li><code>index.md</code> never mentions the three movement records, and its Next steps omits Worldline and Metrics though both are in the nav.</li> <li><code>architecture.md</code> says "A refund takes a kind of its own" under <em>Naming a kind</em>; claims and reversals take one too.</li> </ul>