test(compat): gate the ADR 0005 rename table against the deprecation registry

[wadakatu]

Summary

Adds tests/fixtures/compatibility/v3-renames.json — every old spelling ADR 0005's two tables name, the v3 spelling that replaces it, the channel it uses, and its deprecation id once staged — and V3RenameRegistryTest, which parses those tables and holds the fixture to them. v2-deprecations.json gains the machine-readable fields that let an id be matched to the rename it stages by equality, and now records the notice its own call emits.

No src/ change.

Why

Fixes #556.

DeprecationRegistryTest scans src/ for Deprecations::notice() calls and requires each one to be registered. That catches a deprecation nobody registered. It cannot catch the opposite and likelier failure: a rename that ships no notice at all. Nothing is emitted, so nothing is scanned, and the registry stays as correct — and as empty — as it was. It holds one entry today, against roughly forty renames ADR 0005 fixes.

#499 anticipated the distribution ("each entry is owned and landed by its own v3 issue, not by this one") and left the cross-check as a review rule: "a v3 PR that removes a surface with no entry has nothing to delete and is caught in review against this list." Spread across #501, #502, #503, #505, #507, #508 and #524, that is a lot of reviews for a mistake that cannot be repaired afterwards — docs/versioning.md:216-221 notes the first breaking commit on main turns the pending release into 3.0.0, after which no further v2 release can be cut. A forgotten deprecation then costs another major.

What the gate checks

Check	Source it compares against
Every old spelling the ADR names is listed	ADR 0005's two tables
Each replacement is exactly the target its → gives it	ADR 0005, byte-for-byte
A target names this row's key and this row's members	the target parsed whole into key + members, both compared exactly, on every row
surface is right	which ADR table the row sits under; which LegacyIdentity map the spelling is in
owner is the issue that owns that name	ADR 0005 rule 4, applied to the division of labour the ADR sets out
removed_in is right	one version per channel: 3.0, LegacyIdentity::REMOVED_IN, or none
A staged entry is staged by the notice that announces it	v2-deprecations.json by equality
A registry entry records the notice it claims to	Deprecations::notice() in src/, argument by argument
One id names one call	all of src/ and bin/ in one pass; a reused id fails
The channel has one emitter	trigger_error(E_USER_DEPRECATED) and #[\Deprecated] sites, counted per file against a named allowlist, with imports and relative names resolved, user_error included, the severity evaluated in every base, and an unevaluable one counted
A call the scan cannot read fails, rather than vanishing	anything but a literal Deprecations::notice( — computed class, computed member, ::class callable, any static string naming the emitter (heredoc and nowdoc included), a second namespace, an unreadable literal
A shipped notice is claimed by the rename it stages	the registry, in both directions
The ADR row count and the ratchet ceiling	two constants in the test, not numbers the fixture keeps about itself
The notice announces the surface the ADR assigns	the derived surface, against the notice's own subject
Accepted spellings are wired up	LegacyIdentity::ENV_NAMES + COMMAND_NAMES, as a set
unchanged-spelling membership	a one-name constant, as a set
No entry answers to neither source	the two above, together
Unstaged count only goes down	the fixture's own ratchet, asserted both ways

Verification

Ten review rounds, each finding reproduced before it was fixed and re-run afterwards. Round seven also ran an adversarial sweep of the gate — three independent lenses (token scanner, ADR parser, fixture semantics), each candidate reproduced or refuted by a separate agent against a pristine checkout. 16 candidates, 15 reproduced; 6 were already closed by the round-seven fixes, the other 9 are fixed here.

The current battery is 86 mutations, each failing its intended assertion:

• fixture — deleted entries (ADR-derived, hand-listed, accepted), stale and lowered counts, a borrowed deprecation id, two spellings sharing one id, a mislabelled channel in both directions, a wrong surface on three surface kinds, a malformed owner, a re-dated removed_in on two channels, the wrong member of the right key, an in-row swap, a cross-row key move, a key differing from the row's only by a suffix, a subscript and a grammar member added to rows that enumerate neither, a nested and a repeated subscript, a repeated grammar member, a declared value dropped and an undeclared one added, an array row answered in the CLI grammar, a shipped notice unlinked by nulling its id, a row deleted from the ADR and the fixture together, an owner pointing at no issue, an owner swapped to a different real ADR issue on three surfaces, a removed row recording a successor, and a config key smuggled into LegacyIdentity to leave the deprecation channel.
• notice — subject, replacement and removedIn each changed in src/ alone, then with the registry edited to agree, then with v3-renames.json edited to agree as well; plus a notice naming the sibling spelling, and a target with prose trailing it.
• scan — a wrong notice parked in front of a correct one under the same id (and the reverse order); an unregistered call reached through a grouped use A\{B} import, a comma-separated use A, B;, a namespace\Deprecations:: reference, a second namespace block, $class::notice(), ::{'notice'}(), a [Deprecations::class, 'notice'] callable, or bin/gesso; a trigger_error(E_USER_DEPRECATED) and a #[\Deprecated] beside the emitter; the method name held in a variable; trigger_error and E_USER_DEPRECATED each reached through an import alias; #[\Deprecated] written second in a group, under an alias, and in lower case; a numeric 16384 severity, one held in a variable, and trigger_error reached through call_user_func; ::${'notice'} and a string callable naming the emitter; a severity held in a user-defined constant and written in hex, binary, octal, 0o and digit-separated form; user_error() and a relative namespace\trigger_error() in bin/gesso; a nowdoc spelling out the callable, and a heredoc whose escapes build the emitter's name and trigger_error's (\x53tudio\Gesso\…).
• literals — a hex escape in an id and a single-quoted backslash in a subject, both of which stripslashes() decoded to a string the notice never prints.
• ADR markup — a row with no leading pipe, a row with no outer pipes at all, a Replaces cell naming a spelling without backticks, an arrow hidden in a parenthetical, a "removed" row delimited with ASCII dashes, a surviving flag quietly given a value grammar.
• ADR — a removed arrow, a repointed target, two spellings sharing a target, a member the row never enumerates, a key that is a prefix of the row's, a target with trailing prose, a row with a literal |.

The parsers are guarded by their own tests, so a drifted ADR table or a silently-stopped scan cannot make the coverage checks pass vacuously; the target split is pinned against all five target shapes ADR 0005 writes and the declaration side against all three, the literal decoder against fourteen escape spellings PHP defines and the one a heredoc leaves alone, and the call scan against eleven import and call spellings that all reach the same emitter.

ADR 0004 reduction-PR check: git diff origin/main...HEAD over both conformance baselines is empty. src/, bin/ and composer.json are untouched.

lychee and the docs toolchain are not installed locally, so npm run docs:links / docs:build were not run; CI covers both and they pass.

• composer test passes — 3368 tests, 28111 assertions (CI, PHP 8.3 / PHPUnit 12)
• composer stan passes
• composer cs-check passes

What still gets through

An in-row swap performed in ADR 0005 and the fixture together. The ADR is the source of truth, so editing it is a change to the answer rather than a drift away from it, and no test comparing the two can tell those apart. Reading the ADR diff is the only control, which is why the arrow rows are worth reviewing on their own.

Deleting a row from both is no longer in that category: the number of spellings the ADR names is pinned in the test, so a spelling leaving the gate costs an edit there too.

The equivalent trick on the registry side is closed. Every prose argument a notice passes is compared to src/ verbatim, and the facts that give those arguments meaning — the target, the removal version, the surface — are each pinned to the ADR through v3-renames.json. A coordinated edit across both fixtures and the call site still fails, on whichever of those three it contradicts. What a notice may still add freely is a trailing parenthetical aside; everything before it is the v3 name exactly.

Notes for reviewers

This branch edits ADR 0005, which is Accepted. Fifteen rows, all editorial: they spell out pairings the ADR already decided and change no v3 key name, member name, flag name, or removal. One cell read same name, both surfaces and now names the spelling; thirteen grouped rows now write `old` → `new` per spelling instead of listing old spellings and new members in two parallel columns; and the console_report row gains (#502), the marker the removed rows already use, recording the owner the ADR's own section C decides in prose. The → is the ADR's own notation for this meaning (:51, :255). The spelling set the parser derives is identical before and after; three fixture replacements change to match what the ADR now states literally. Under ADR 0004 a contradicting change needs a superseding record — none of these contradict anything, but the diff is worth reading as a decision rather than as a detail.

v2-deprecations.json was restructured. Its two prose fields are now one notice object holding the call's subject, replacement and removedIn verbatim, compared to src/ argument by argument, alongside the bare spelling and v3_target the rename gate compares by equality. Changing the wording, the target or the date of a notice is now a change to this fixture too — which is the point, since the fixture is the list a major deletes from.

The ratchet is hard from day one, not a reported count that flips later. #556 proposed starting soft on the grounds that a red gate gets skipped. It is green today — 53 unstaged, unstaged_count: 53 — so there is nothing to flip. It is asserted in both directions: a stale number left high after staging leaves room for the next omission to slip in under the old ceiling.

unchanged-spelling membership is hand-listed, deliberately. Four ADR rows keep their spelling, but three of them (baseline_stale and the two --strict-* flags) replace the value that spelling accepts, which is a removal to anyone who wrote the old value down. Telling that apart from a placeholder like --output-file=<path> is a guess, so the channel that stages nothing and counts toward nothing costs a deliberate edit to enter. The constant's docblock records the rejected derivation.

The ADR checks live inside the scan, not in a test of their own, so a test that only wants the spelling list still cannot read a malformed table. The same now holds for the registry's shape, which is validated where it is loaded. The cost is that their failures are attributed to whichever test called first; the message names the row and the reason.