fix(authz): route checkAccess/can/batchCheck through the instrumented path (F3)

[ilpanich]

The example found a real bug

Writing the F3 example for this SDK found a defect in the already-merged D5 work — which is the whole reason the example exists.

examples/telemetry_hook.php drives the ordinary public API. Its first run, against an unreachable server, printed:

--- telemetry ---
  retries: (none)
  refreshes: 0

No retries. No request events. One attempt.

Cause

checkAccess(), can() and batchCheck() posted directly through private helpers with no §16 retry budget, no §17 memo and no §19 request pair. Only checkAccessDecision() was reachable from the instrumented path — and batchCheckDecisions() was itself uninstrumented, so batch had no retry on either surface despite §16.2 naming batch_check as eligible.

The D5 conformance suite drives checkAccessDecision exclusively, so it was green throughout.

That is precisely what §16.7 was written about:

"A tested surface nobody calls is worse than an absent one: the passing tests are exactly what stop anyone from looking."

…reproduced in the very fan-out that introduced the clause, and visible only from the surface a caller actually reaches. The clause said to count requests on the wire through the public surface; the suite counted them through a public surface, and picked the one callers use least.

Fix

• checkAccess → delegates to checkAccessDecision, takes .allowed
• batchCheck → delegates to batchCheckDecisions
• batchCheckDecisions → now wraps its send in RetryPolicy::execute with a §19 span (new sendBatch, mirroring sendCheck) and its own BATCH_PATH template
• dead decodeAllowed helper removed

Delegating rather than duplicating the instrumentation is the point: there is now one instrumented path per operation and no second one to forget.

The memo is deliberately still not applied to batch — the §17 key is per-check, so a batch would split into n entries with n keys, changing what a partial hit means. §17 says nothing about batch, so this takes the conservative reading rather than inventing semantics.

Tests

Six cases added, all counting requests on the wire through the bare-bool surface:

Case	Asserts
checkAccess retries	2 requests on a 503→200 script
checkAccess attempt cap	exactly MAX_ATTEMPTS on persistent 503
can alias retries	an alias that didn't would be a hole in the policy
checkAccess telemetry	start, end, retry, start, end
batchCheck retries	2 requests
batchCheck telemetry	operation batchCheck, path template /api/v1/authz/check/batch

Verification

PHPUnit cannot be installed in this sandbox — composer still fails Could not authenticate against github.com through the proxy. CI is the verifier for the suite, PHPStan and the docblock gate.

The fix itself is demonstrated directly by re-running the example:

--- telemetry ---
  checkAccess/failure: count=3 mean=3ms
  retries checkAccess: 2
  refreshes: 0

Three attempts, two retries, events emitted — matching the C, C++ and C# SDKs. For this defect that is the stronger evidence anyway: the bug was that the ordinary path was uninstrumented, and the example is the only check that exercises the ordinary path.

I also verified every touched method still sits directly under its own docblock — the orphaned-docblock mistake that has broken the docblock gate in this repo before.

---

Generated by Claude Code