Register Live Activity push-to-start error code 40182, add LiveActivity push stats

[JoaoDiasAbly]

Summary

ably-common side of LiveActivity production readiness (ADR-157, follow-up): registers the one LiveActivity error code still missing from the error registry, and adds the customer stats for Live Activity broadcasts and per-outcome notification delivery. Unblocks ably/realtime#8527, which bumps its ably-common submodule once this merges.

Restructured after #348 ("Error code documentation registry"): codes are now registered as errors/codes/<code>.md files and protocol/errors.json is generated from them. Of the six codes this PR originally set out to add, #344 had already registered 103004–103007 and #348 registered 103008 — leaving only 40182.

Error code

• errors/codes/40182.md (new) — apns_token_authentication_required_for_push_to_start. Push-to-start of a Live Activity requires the app's APNs credentials to use token-based authentication. realtime#8527 rejects non-compliant apps with 40182 at /start request time and uses it for the push-worker transport skip (both previously fell under location's 40180).
• errors/codes/40180.md — scoped back to location notifications only, since realtime#8527 moves the live-activity case onto 40182: summary narrowed, and identifier/title renamed to apns_token_authentication_required_for_location / "APNs token authentication required for location notification" so the pair reads symmetrically (per review). There's a brief window between the two merges where production still emits 40180 for live-activity skips; realtime#8527 closes it.
• protocol/errors.json — regenerated via npm run generate:errors (not hand-edited).

Stats schema

Adds push.apnsBroadcasts to json-schemas/src/app-stats.json and json-schemas/src/account-stats.json, alongside push.directPublishes. Each broadcast is a single request to Apple that Apple fans out to every subscribed device (Ably has no per-device visibility), so the counter tracks issuance, not deliveries, and includes the final broadcast sent by an end request.

Also adds the ten per-outcome entries push.notifications.{delivered,refused.retriable,refused.final,skipped,all}.apnsLiveActivity to both schemas, mirroring the apnsLocation wording and placement. These are emitted by the push-worker's apnsLiveActivity stats block in ably/realtime#8527, which counts the expected no-push-to-start-token drops as skips.

Additive fields only — no versions.json bump, following 50412f0 ("Add missing objects stats").

Related

• AIT-989 — error-code registration
• AIT-990 — stats counters
• AIT-804 — 40182 push-to-start precondition
• ably/realtime#8527 — realtime side (merge this PR first, then the submodule bump lands there)

🤖 Generated with Claude Code

[lmars]

@JoaoDiasAbly we recently updated how error codes are maintained in this repo, so if these new codes are still needed, they need to be registered by creating a Markdown file in the errors/codes directory.

[lmars]

If this one is now just about location push, I think we should make the two errors a bit more symmetrical, so here:

apns_token_authentication_required_for_location
"APNs token authentication required for location notification"

and below:

apns_token_authentication_required_push_to_start
"APNs token authentication required for push-to-start Live Activities notification"