Four shipped surfaces describe something the code does not do. They are grouped because they are one defect class and one sweep, and because each of them is read by somebody deciding how to call this module. ## 1. `docs/verification.md` documents an API that does not exist The page opens with the service's API, and none of the three calls in that block run: ```php $chain_ids = $verifier->listChains(); ``` `AuditTrailVerifier` has no `listChains()`. The method is on `Chain\ChainRepository`. A consumer copying this gets `Call to undefined method`. ```php // returns ['ok' => TRUE, 'count' => 4827, 'first_broken_id' => NULL, …] ``` `first_broken_id` appears nowhere else in the module. The verdict names its failures in `broken_ranges`, and the class documents every key as always present so callers need no `??`. A consumer reading `$result['first_broken_id']` gets NULL and reads it as "no break". ```php $verifier->mintCheckpoint('notarial'); ``` `mintCheckpoint()` takes `(string $chain_id, int $last_id, string $last_hash)`. The documented call is an `ArgumentCountError`. The method also carries `@internal` and "Production callers must go through `verifyChainIncremental()`", which the page presents as a supported operation. The same section says the class "exposes three methods". There are seven public ones, and one of the three named is not among them. ## 2. The same page says the walk stops at the first break > The first mismatch wins: the result reports the row id and a human-readable diagnostic. Subsequent rows are not walked (the chain is broken from that point downstream anyway). It does not, and has not for some time. `docs/architecture.md` has a "Multi-tamper walk" section saying the opposite, `BrokenRangeCollector` exists to accumulate every contiguous range, and `formatBrokenMessage()` appends "(and N further broken range(s))" precisely so an operator does not acknowledge the first range and assume the rest is clean. The page that is named after verification is the one that tells them to. ## 3. `audit_trail_schema()` understates what the segment signatures cover Four column descriptions describe the narrower, earlier versions of these signatures, and in each case the omitted fields are the ones that were added to close a named hole. - `audit_trail_segment.hmac`: "over (chain || from_id || to_id || created || secret_id)". `SegmentSignature::computeIdentityHmac()` also signs `anchor_before`, `anchor_after`, `from_created` and `to_created`. Its docblock says why: without them, "editing `anchor_before` and waiting for the ordinary archive stage got the edit signed, and the archive then verified clean on all four checks with a fabricated anchor." - `anchor_before`, `anchor_after`, `from_created`, `to_created`: each says "Pinned in `archive_hmac`". All four are also in the identity HMAC, which is the only one of the two that exists on a bare segment. A maintainer asking "is a bare segment's anchor signed?" against the schema is told no. - `lifecycle_hmac`: the field list omits `chain`, `from_id` and `to_id`. `computeLifecycleHmac()` signs them, and says why: without the range, "widening a real, validly-signed segment with one `UPDATE audit_trail_segment SET from_id = 1` made it cover rows it had never purged, and its lifecycle signature still validated." `docs/security.md` has all of this right, so the schema is the stale copy, and it is the one a developer reads next to the columns. The same file calls a seven-item list a "sextuple". ## 4. Two class docblocks enumerate less than their class does - `AcknowledgmentAction`: "The resource is `acknowledgment:<id>`". `buildResource()` returns `acknowledgment:<from>-<to>`, and its own docblock is explicit that it is "The RANGE, not the acknowledgment." The same stale form is repeated in `AcknowledgmentRepositoryInterface` and in a comment in `AcknowledgmentRepository`. - `AuditTrailUserAuthHooks`: the class docblock presents its list as the security-relevant lifecycle it captures, and names ten events. The bridge emits fourteen. `account_created`, `account_deleted`, `password_changed` and `role_changed` are missing from the list, and are four of the more security-relevant of the set. The settings form, the config schema and the shipped config all carry all fourteen, so only the developer-facing list is short. ## Tests A documentation correction must not change behaviour, so the tests pin the behaviour the prose got wrong and which nothing asserted, which is how the prose came to drift from it: the verdict's exact key set, a chain with two separated breaks reporting two ranges, the identity and lifecycle signatures refusing an edit to each field the schema left out, and the acknowledgment resource format. AI-Generated: Yes (Claude Code was used to help draft this issue summary and the probe that confirmed the behaviour it describes. I reviewed both before posting.)