## Problem Three changes landed in the code without the prose that describes them, and two of the three are in the documents an auditor reads to decide what the module guarantees. **The segment's three HMACs are named wrongly.** `docs/security.md` § "Three-layered archive HMAC" and the matching bullet in `docs/threat-model.md` both describe the triple as "chain-content, file, lifecycle". `SegmentSignature` computes identity, archive-content and lifecycle. The difference is not a wording one: - There is no signature over the on-disk NDJSON bytes. The file is bound only through the `file_sha256` column, which sits *inside* the archive-content envelope. A reader told there is a file HMAC will look for a guarantee that is not there. - The identity envelope goes unmentioned in both documents, and it is the one that stops a segment row being forged outright or re-pointed at a different range — the attack `computeIdentityHmac()`'s own docblock exists to describe. - `security.md` adds that forging a covering segment "requires the operator secret to sign all three segment HMACs AND the mutual `segment_transient_purged` chain event". `AuditTrailVerifier::findAttestedSegment()` checks the lifecycle HMAC and nothing else. - `threat-model.md`'s cryptographic inventory lists `audit_trail_secret.identity_hmac`. No such column exists; the identity HMAC is `audit_trail_segment.hmac`. **The acknowledgment row's own HMAC went with #3620349** and four places still describe it. One of them is a contract rather than a comment: `AuditTrailVerifier::verifyChainPublic()` tells a reader that an acknowledged break "reads as BROKEN here and as verified under `verifyChain()`", because the acknowledgment's HMAC cannot be re-derived without the operator's secrets. The index row carries no HMAC any more, and the walk checks the candidate against the chain's own `acknowledgment_recorded` event, which needs no secret: ``` same chain, same acknowledgment over a tampered row verifyChainPublic() ok = true verifyChain() ok = true ``` The two walks now agree, and the paragraph explaining why they do not is the only thing telling an auditor otherwise. **The `ack` envelope left the NDJSON format** in the same issue. `ArchiveEnvelope` still documents writing one, still documents `replayRows()` counting one, and still lists `ack` as an envelope discriminator, while `writeNdjson()` writes rows only and both readers refuse any other type — deliberately, as `ArchiveEnvelopeShapeTest::testThereIsNoAcknowledgmentEnvelopeType()` pins. `SegmentRestorer` carries the same in three docblocks plus a branch in `replayArchivedRows()` that computes a diagnostic id for an envelope type it then rejects. Smaller drifts found alongside: `AuditTrailCronArchiveHooks` says "six sequential stages" and lists five (compaction is missing), `runChainLifecycle()` says four, `getBucketEndMicroseconds()` says it is used by the archive stage when it is used by coverage, `SegmentReader::buildSegmentRow()` lists an "ack count" among the fields the archive HMAC covers, and `AuditTrailChain`'s class docblock lists four of the seven per-chain overrides. ## Proposed resolution Correct each site against what the code does. Nothing here changes behaviour. ## Remaining tasks - [ ] Name the three segment HMACs correctly in both security documents, and say what each one actually binds. - [ ] Drop the acknowledgment HMAC from the four places that still describe it, and state what the walk checks instead. - [ ] Drop the `ack` envelope from the format documentation and remove the dead branch it left in the restorer. - [ ] Correct the stage counts and the smaller drifts listed above. AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the changes on the merge request. I reviewed the work myself before posting it.)