Trac Notifications: ticket-read DAO methods + Trac_API caching layer

[obenland]

Summary

First of a planned multi-PR feature that surfaces WordPress.org Trac data as JSON over HTTP. This PR lays the data and caching plumbing inside the trac-notifications plugin without yet exposing any new HTTP surface — that lands in follow-up work.

Architecture context

[ api.wordpress.org/dotorg/trac/...  (FUTURE PR) ]
[ wporg-abilities MCP                (FUTURE PR) ]
                  │
                  ▼
[ Trac_API ]  ←── this PR (wp.org side)
  • memcached fresh + stale + circuit breaker
                  │
                  │ Trac_Notifications_HTTP_Client (existing)
                  ▼
[ <trac>.trac.wordpress.org/wpapi ]
                  │
                  ▼
[ Trac_Notifications_DB ]  ←── new methods in this PR (Trac-box side)
                  │
                  ▼
              Trac MySQL DB

What's in this PR

Trac_Notifications_DB gains five read methods for data the existing class did not expose:

• get_trac_ticket_full( $id, $opts ) — composite payload (one Trac round-trip per ticket)
• get_trac_ticket_comments( $id, $limit, $offset ) — ASC-ordered window of comment bodies
• get_trac_ticket_comment_count( $id ) — total, for pagination + most-recent-N math
• get_trac_ticket_changelog( $id ) — every non-comment field change (status, owner, keywords, milestone, …)
• get_trac_ticket_attachments( $id ) — filename, size, time, description, author
• get_trac_ticket_custom_fields( $id ) — full name => value map (generalises the focuses-only accessor)

The composite returns the most recent N comments in chronological order by computing offset = max(0, total - limit), so large tickets don't dump hundreds of KB by default. All time columns are returned raw (microseconds since epoch) — Trac_API converts them at the output boundary.

Trac_API (new) is the wp.org-side caching wrapper around Trac_Notifications_HTTP_Client:

• Memcached cache with separate fresh (5min) and stale (24h) TTLs
• Stale fallback when Trac is unreachable
• Per-trac circuit breaker (5min TTL): a core.trac outage cannot block meta.trac calls
• Negative caching for missing tickets (60s sentinel) to absorb 404 floods, written to both fresh and stale keys so a deletion doesn't resurface old data
• Dependency-injectable cache backend + client factory, so tests don't need memcached
• Missing TRAC_NOTIFICATIONS_API_KEY is logged loudly (operational config error ≠ transient outage)

Unit tests: new PHPUnit setup at wordpress.org/public_html/wp-content/plugins/trac-notifications/, 36 tests, 90 assertions, no WordPress dependency. Follows the existing core/serve-happy/1.0/tests and common/includes/tests/slack/trac patterns. Added a matrix entry to .github/workflows/unit-tests.yml.

What's NOT in this PR

• The HTTP endpoint at api.wordpress.org/dotorg/trac/... — separate PR
• MCP abilities in wporg-abilities — separate PR
• Decommissioning the disabled /core/trac-search/1.0/ endpoint — separate task
• Sibling endpoints (contributors/, keywords/, releases/, components/) — these mostly read Make/Handbook content rather than Trac DB, so each becomes its own small PR

Deployment notes

The DAO additions need to be deployed to the Trac boxes (core.trac and meta.trac) before the follow-up HTTP gateway PR can be tested end-to-end. The wp.org-side caching layer can be exercised against the existing wpapi endpoint as long as only existing methods are called.

Test plan

• All 36 PHPUnit tests pass locally
• BASE_REF=trunk php .github/bin/phpcs-branch.php reports no violations
• CI: Trac Notifications matrix entry passes
• CI: PHP Coding Standards passes

🤖 Generated with Claude Code