feat(gates): gate-83 contract-surface-shift — declaring a magic method breaks every consumer

[rubenvdlinde]

What

Adds gate-83 contract-surface-shift: a diff-scoped gate that fails when a method on a published contract moves between the MAGIC surface (an @method docblock tag routed through __call()) and the DECLARED surface, unless the change is annotated.

Why

PHPUnit picks its mock builder on exactly that distinction:

addMethods()   throws CannotUseAddMethodsException  if the method EXISTS
onlyMethods()  throws CannotUseOnlyMethodsException if it does NOT

So every consumer that doubles the class has hard-coded an assumption about which surface each method sits on. Moving one breaks them with no commit in their repositories.

Measured, not hypothetical. On 2026-08-15 openregister#2498 published the ObjectService/ObjectEntity interfaces, which forced getUuid(), getRegister() and getSchema() to be declared:

repo	fallout
opencatalogi	42 errors, all 6 PHPUnit matrix cells red
decidesk	1 failure

Both development branches went red on commits that had passed hours earlier, and the failures first surfaced on unrelated dependency PRs, where they read as those PRs' fault. Finding that out cost a full baseline-comparison pass across 19 repositories.

Why it lives on the producer side

It cannot be written in the consuming repo. The hydra-gates job checks out exactly two things — the app and the gates package — so a consumer-side checker has no access to the real class and would resolve every external double as "unknown". It would report ZERO findings for the one change that matters, which reads as a pass. The authority for what is declared lives with the class, so the check lives there too.

The escape hatch

@contract-shift <category> — <reason>

Categories are closed: announced, internal-only, new-contract. Same shape as gate-16's @spec exclude and gate-61's @listener-placement. A bare tag or an unknown category fails.

Verification

In a real runner run, against the commit that caused the outage:

[gate-83] contract-surface-shift: FAIL — 5 undeclared shift(s) ...
[hydra-gates] COVERAGE: 64 of 69 declared gates reported a result

It names all five shifted methods — the three that broke consumers plus getOwner/getOrganisation, which nobody happened to have doubled.

Negative control, a diff touching no contract file:

[gate-83] contract-surface-shift: NOT APPLICABLE — the diff against 'HEAD~1'
touched no published-contract file, so no surface shift could occur.

Named, not silent, and still counted in COVERAGE.

Suite (scripts/lib/test_check_contract_surface_shift.sh, auto-discovered by run-helper-suites.sh) — 9 assertions, all paired positive/negative: both shift directions, the annotation grammar, empty scope, not-applicable, unresolvable-base-fails-closed, and the terminal summary the runner greps for.

One of those assertions earned its place immediately

The bare-annotation case caught a live bug in the first draft. The separator was \s*, which matches newlines — so on a reason-less @contract-shift announced the match ran past the line end and captured the docblock's closing */ as the "reason". Non-empty, so the no-reason branch never fired and the escape hatch was silently open to any bare tag. Nothing else would have found it.