## Problem Several in-code surfaces describe behaviour the module does not have. Each one was true when written and was left behind by a change that moved the behaviour. They are grouped here because the repair is one sweep and none of them is worth an issue on its own. ### Acknowledgment rows described as signed #3620349 removed the acknowledgment row's HMAC: what the walk trusts is the `acknowledgment_recorded` chain event, and the row carries no signature to invalidate. `docs/security.md` already says so, and `AuditTrailAcknowledgmentsController` says it in a comment. Four surfaces still say the opposite, and two of them are what an operator reads: - `AuditTrailHelpHooks::buildAcknowledgmentsListHelp()`: "Operator-signed acknowledgments... a record whose signature or chain anchors no longer match is ignored." There is no signature, and the status column has read "Chain anchors moved" since the change. - `AuditTrailHelpHooks::buildOverviewHelp()`: "An operator-signed record of a legitimate chain break". - `AuditTrailAcknowledgmentForm`: "Re-signs under the current secret on save." - `AuditTrailCommands::acknowledgeReset()`: "The acknowledgment is signed under the chain's signing secret and stored in the dedicated `audit_trail_acknowledgment` table". `PurgeRestoreTest`'s class docblock carries two more from the same change: "Purge DELETEs the rows and the fully-contained acks" and "fully-contained acks are snapshotted in the file". `applyLivePurge()` and `ArchiveEnvelope::writeNdjson()` each say in their own comments that neither happens any more. ### The filter suppression contract contradicts itself `AuditTrailFilterInterface` opens with: > Through `AuditTrail::record()`, a suppressed event leaves NO trace in the audit_trail table AND NO trace in any other logger that subscribes to PSR-3 (dblog, syslog). The full `record()` call is voided. Seventy lines further down, the same file documents the flag that decides it: > FALSE (default): the chain only. The row is skipped, and dblog / syslog still see the event, so operators can see what the chain is dropping. The second is what `AuditTrail::doRecord()` implements and what `docs/configuration.md` describes. The first is the contract a consumer writing a filter reads. ### Stage counts and operation lists that do not match - `AuditTrailCommands::runAutoArchive()` says "the five stages" in one paragraph and "it runs seven stages" in another. `runChain()` runs six, and `AuditTrailCronArchiveHooks` says six. - `AuditTrailSegmentsController::buildOperationsCell()` documents Transient-purge, Delete and Purge operations it never offers. Its own class docblock says the opposite, correctly: "offers only what destroys nothing". - `AuditTrailChainListBuilder` lists "Configure retention" among the operations, which the code deliberately does not add and says so, and omits Auto-archive, which it does. ## Why it matters here The module's surfaces are its contract. A consumer writing a filter reads the interface; an operator deciding whether to record an acknowledgment reads the help text and is told a signature protects it. Both are decisions taken on a description of a guarantee, and in each case the guarantee named is not the one the code offers. ## Remaining tasks - Correct the four acknowledgment surfaces and the test header. - Correct the filter suppression contract to what the flag below it already documents. - Correct the three counts and lists. ## User interface changes Two help texts and a form description are corrected. No behaviour changes. --- AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the corrections. I reviewed both.)