## Problem `AuditTrailVerifier::canonicalize()` is the module's one canonical JSON encoder: recursive `ksort(SORT_STRING)` plus `JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR`. It is the public-verifiability anchor, and its byte output is load-bearing for every row, envelope and anchor already on disk. It has ten production call sites. Nine of them are not verification: - `Writer\AuditTrailChainWriter`, hashing a row it is about to write - `Writer\PendingWrite`, hashing a staged row - `Archive\ArchiveEnvelope`, four times: two NDJSON envelope lines, two archive anchors - `Archive\SegmentRestorer`, twice, recomputing a restored row's hash - `AuditTrailVerifier` itself, once So four classes import the verifier to reach a static that verifies nothing, and a reader of `hash('sha256', AuditTrailVerifier::canonicalize($payload))` in the archive writer has to work out that no verification is happening there. `Chain\ChainPayload` already owns the other half of this contract, and says so: "Every party that recomputes a row's hash has to feed `AuditTrailVerifier::canonicalize()` exactly these columns, in this shape ... so it is defined once, here." The columns are defined once, in `Chain\`. The encoding they are fed to is somewhere else. `Chain\CheckpointPayload::canonicalize()` is the same thing done correctly: a `final class` in `Chain\` holding one `public static` that builds the canonical byte form of a signed payload, carrying the same warning that changing it invalidates everything on disk. The checkpoint's canonicalization sits beside the shape it encodes; the row's does not, and nothing distinguishes the two cases. The docblock that justifies `public + static` names the wrong parties. It says the binders are "the writer (`AuditTrailLogger`), the verifier (this class), the detail-page controller". `AuditTrailLogger` never calls `canonicalize()`, and no controller calls it at all. The four classes that do bind to it are not named. ## Proposed resolution A `final class Chain\CanonicalJson` holding `encode()` and the private `ksortRecursive()` that only it uses, beside `ChainPayload` and `CheckpointPayload`: ```php $canonical = CanonicalJson::encode($canonical_payload); $hash = hash('sha256', CanonicalJson::encode($payload)); ``` Not a method on `ChainPayload`, even though the row payload is the commonest argument: `ArchiveEnvelope` encodes envelope objects (`{payload, type}` and `{id, payload, transient, type}`), which are not row column sets, so four call sites would be reading a class name that does not describe what they pass. `encode()` rather than `canonicalize()` matches core's `Component\Serialization\Json::encode()`, and the class name carries the canonical part. Naming is open to review. The move is mechanical and must not change a single byte of output. `tests/src/Unit/CanonicalizeBytesTest.php` pins that and moves with it. Afterwards `Writer\AuditTrailChainWriter`, `Writer\PendingWrite`, `Archive\ArchiveEnvelope` and `Archive\SegmentRestorer` stop importing `AuditTrailVerifier` entirely. That also retires a documented hazard: the chain writer's only reference to the verifier is this static, which is what keeps `verifier -> acknowledgment repository -> chain writer` from closing into a container cycle, and `audit_trail.services.yml` currently carries a comment warning a future contributor not to turn it into an injected dependency. With the static gone, there is nothing left to warn about. ## Remaining tasks - [ ] `Chain\CanonicalJson` with `encode()` and `ksortRecursive()` - [ ] Ten call sites repointed, four `use` statements dropped - [ ] `CanonicalizeBytesTest` moved, byte output unchanged - [ ] The stale `public + static` rationale rewritten to name the classes that actually bind to it - [ ] `docs/threat-model.md` and `docs/architecture.md` references updated - [ ] The cycle comment in `audit_trail.services.yml` removed AI-Generated: Yes (Claude Code was used to analyse the call sites and to draft this issue summary. I reviewed it before posting; there is no code on this issue yet.)