gateway metrics: unvalidated --granularity, pending returns count, and two smaller inconsistencies

[leggetter]

Summary

Four smaller gateway metrics defects found while exercising the v2.6.0 release candidate. None is ship-blocking, and none is covered by #382 or the fixes in #392, so recording them rather than losing them.

1. --granularity is not validated client-side, and the 422 leaks a server regex

hookdeck gateway metrics events --start ... --end ... --measures count --granularity 3x
# → granularity with value 3x fails to match the required pattern: /^(\d+)(s|m|h|d|w|M)$/

3x, abc, 1, -1h and 0h are all forwarded. --help already states the exact format, so a client-side check is cheap and would stop exposing the server's internal pattern in user-facing output. Valid values (1s 5m 1h 1d 1w 1M) all work.

2. --measures pending returns a metric named count

hookdeck gateway metrics events ... --measures pending --granularity 1h --output json
# → [{"time_bucket":"...","metrics":{"count":54}}, ...]

pending selects the route; the API is sent measures[]=count and the response passes through unrenamed. So a script that asks for pending must read .metrics.count. Defensible, but undocumented — worth a line in --help, or renaming the key on the way out.

3. --dimensions issue_id is guarded on events but not on transformations

hookdeck gateway metrics events ... --dimensions issue_id
# → per-issue metrics require --issue-id  [exit 1]

hookdeck gateway metrics transformations ... --dimensions issue_id
# → exit 0, request sent

metrics transformations --help gives --issue-id the identical description ("required for per-issue metrics, e.g. when using --dimensions issue_id") but does not enforce it. The API accepts it, so this may be deliberate — the mismatch is between the two help texts and the two behaviours, not necessarily a bug.

4. A reversed date range silently returns the forward-range result

--start 2026-09-15T00:00:00Z --end 2026-09-14T00:00:00Z  → count 323
--start 2026-09-14T00:00:00Z --end 2026-09-15T00:00:00Z  → count 323

Debug output confirms the CLI passes both verbatim, so the normalisation is server-side. A client-side start < end check would be a reasonable guard — silently answering a different question than the one asked is the same failure shape as #382.

Related

• gateway metrics accepts filters the endpoint ignores, returning unfiltered totals as if filtered #382 — metrics accepting filters the endpoint ignores (fixed)
• fix: delivery-group data loss and metrics defects, plus the missing acceptance coverage #392 — --measures pending routing, queue_depth, and per-route help vocabularies (fixed)

---

Filed by Claude on Phil's behalf, from release-candidate testing.