track_relay 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ef792bdf08a7044b2505ba7d864b6efd9e52300227bd90ba6d4556833ea4317
+  data.tar.gz: d5fa187c552b77560ccb373546702ae563b692708ac0e3aebee4b8ee96d9a90f
+SHA512:
+  metadata.gz: d092e315a251dd34b3d29f2b61042dd6b05deadd4bd1b99cad515b28502bdb049bc4009ca2e71a3b6c3375791dc37a81e93c451ad90756d0e846142525d2fa84
+  data.tar.gz: d9c406cdda1cf1517fc568b6f0589ce3d3655c0402c33151cc520fe2f2f054f242f4e35cd3d98b9f911919bb25da3be6dca07f80a192f084d404bab20c56542b

data/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-07
+
+### Added
+- `rails g track_relay:install` — opinionated scaffold: richly commented
+  initializer (`config/initializers/track_relay.rb`), sample catalog
+  (`config/track_relay/sample.rb`), ApplicationSubscriber base class
+  (`app/track_relay/subscribers/application_subscriber.rb`), and
+  `include TrackRelay::ControllerTracking` injected idempotently into
+  ApplicationController. `bundle exec rake test` passes cleanly
+  immediately after running this generator.
+- `rails g track_relay:event NAME` — scaffolds a typed catalog entry
+  stub at `config/track_relay/<name>.rb`. Each event is its own file;
+  the Railtie merges them at boot.
+- `rails g track_relay:subscriber NAME` — scaffolds a subscriber class
+  stub at `app/track_relay/subscribers/<name>_subscriber.rb`.
+- Getting-started guide at [USAGE.md](USAGE.md) (now shipped inside the gem).
+- Migration notes at [UPGRADING.md](UPGRADING.md) (now shipped inside the gem).
+- E2E happy-path test exercising the install generator's output through
+  the live Combustion harness (controller call → Test subscriber capture).
+- README sections: Generators, Ahoy subscriber, Public API stability.
+
+### Changed
+- Public-API stability is established for this release. See
+  [UPGRADING.md](UPGRADING.md) for migration paths from 0.1.0 / 0.2.0
+  / 0.3.0 to 1.0.0.
+
+### Fixed
+- `TrackRelay::ClientId::AhoyVisitor` now reads
+  `controller.ahoy.visitor_token` directly. The previous chain
+  (`controller.ahoy.current_visit.visitor_token`) raised
+  `NoMethodError` on `ahoy_matey >= 5.0` because `Ahoy::Tracker` does
+  not define `current_visit`. The error was rescued by the resolver
+  chain so the gem did not crash, but the resolver always fell through
+  to a random GA4 `client_id` instead of a stable Ahoy visitor token.
+
+### Documentation
+- README and USAGE: note that `ahoy_matey` silently drops events from
+  non-browser user-agents (`[ahoy] Event excluded`) — visible when
+  smoke-testing via `curl`/Postman.
+
+### Notes
+- **Public API stability:** Public-API stability for `TrackRelay.track`, `.configure`,
+  `.catalog`, `.subscribe`, `.identify`, `.test_mode!`,
+  `TrackRelay::Subscribers::Base` (and the `synchronous!`,
+  `filter only:`, `filter except:` macros),
+  `TrackRelay::Subscribers::{Test,Logger,Ga4MeasurementProtocol,Ahoy}`,
+  `TrackRelay::ControllerTracking`, `TrackRelay::JobTracking`,
+  `TrackRelay::Testing::Helpers`, the catalog DSL
+  (`event`, `integer`, `string`, `float`, `boolean`, `datetime`,
+  `user_property` + `required:`/`max:`/`in:`/`format:`/`sanitize:`
+  validators), the three generators, and the four rake tasks
+  (`track_relay:lint`, `track_relay:lint:json`,
+  `track_relay:lint:ga4`, `track_relay:manifest`) is established for
+  the 1.0.0 release. Internal classes (`EventPayload`, `Instrumenter`,
+  `Dispatcher`, `Catalog`, `Current`, `DeliveryJob`, `ClientId::*`)
+  are not part of the public API contract.
+- No breaking changes from 0.3.0. The `init({ manifestUrl })`
+  JS-client breaking change recorded in 0.3.0 still applies — see the
+  [0.3.0] entry below.
+
+## [0.3.0] - 2026-05-06
+
+### Added
+
+- `TrackRelay::Subscribers::Ahoy` — server-side synchronous subscriber that routes catalog events through `controller.ahoy.track(payload.name.to_s, payload.params)` (Ahoy's only public tracking surface — there is no `Ahoy::Visit#track`). Duck-types `controller.respond_to?(:ahoy, true)` so the gem loads cleanly in non-Ahoy host apps; calls without a controller in scope (background jobs, rake tasks, console) skip-log via `Rails.logger.warn` rather than fabricate a write. Stateless — no constructor args; reads `TrackRelay::Current.controller` directly at deliver time (safe on the synchronous path, mandatory because `payload.context[:controller]` is the controller class name as a String, not the live instance).
+- `AhoyJs` named export in `@track_relay/client` — client-side mirror of `Subscribers::Ahoy`. `Object.freeze({ name: "AhoyJs", handle(eventName, params) })` shape matches the existing `Ga4Gtag` export. Validates against the manifest (typed events: dev-throws / prod-warns-and-drops per REQ-05; untyped passes through per REQ-06), then dispatches via `window.ahoy.track(eventName, params)`. Guards on `typeof window.ahoy?.track === "function"` and emits `console.warn` + drops when missing — never throws when `ahoy.js` is absent.
+- `ahoy_matey` added as a development dependency in `track_relay.gemspec`. Resolves to 5.4.2 under Rails 7.1 and 5.5.0 under Rails 7.2 / 8.0; lockfiles in `gemfiles/` confirm. The gem is required by the unit/integration test suites only; runtime hosts pull `ahoy_matey` themselves via their own Gemfile.
+
+### Changed (BREAKING)
+
+- `init({ manifestUrl })` no longer requires `measurementId`. Hosts using only `AhoyJs` (no GA4 subscriber in use) can now omit the GA4 measurement ID and call `init({ manifestUrl: "/track_relay_catalog.json" })`. Previously this threw synchronously; now it succeeds and leaves the GA4 dispatch surface dormant (`_flushConfigOnce()` already short-circuits on missing `_measurementId`, so `track()` and `Ga4Gtag.handle()` continue to validate but do not emit `gtag('config', ...)`). Hosts that relied on the missing-`measurementId` throw to detect misconfiguration must migrate — assert their own `measurementId` (or any other host-app-side invariant) before calling `init`. The error message thrown when `manifestUrl` is missing is also reworded to mention `manifestUrl` only.
+- `client/src/index.d.ts`: `InitOptions.measurementId` typed as `measurementId?: string` (was required `string`). Existing TypeScript hosts that pass `measurementId` continue to typecheck unchanged; AhoyJs-only hosts can now omit it without a type error.
+
+### Notes
+
+- REQ-09 success criteria mention `Ahoy::Visit#track` as a fallback dispatch path. This method does not exist on `Ahoy::Visit` (the ActiveRecord model). The `Ahoy::Tracker` is the sole public tracking surface, and it is bound to the request lifecycle (it wraps the controller cookie jar / visit auto-create). The Ahoy subscriber therefore routes through `controller.ahoy.track` only; the no-controller skip path (with a `Rails.logger.warn` line) is the substitute for the missing `visit.track` route. See `phases/03-ahoy-subscribers/03-RESEARCH.md` §"The visit.track question" for full rationale.
+- Cross-subscriber name parity: server `TrackRelay::Subscribers::Ahoy.name` returns `"TrackRelay::Subscribers::Ahoy"` (Ruby `Class#name`); client `AhoyJs.name` returns `"AhoyJs"`. The names differ but the dispatched event-name strings are byte-identical on both sides — server `payload.name.to_s` → `tracker.track`, client `eventName` → `window.ahoy.track`. REQ-09's "same event names as the server" criterion is about the event-name string, not the subscriber class name.
+
+## [0.2.0] - 2026-05-06
+
+### Added
+
+- `@track_relay/client` v0.2.0 — companion JS package living at `client/` in the repo. Ships dual ESM (`dist/index.mjs`) + real CommonJS (`dist/index.cjs`) builds via `tsup` so both `import "@track_relay/client"` and `require("@track_relay/client")` work; the `package.json` `exports` map points at the built artifacts (not the unbuilt source). Hand-written `src/index.d.ts` documents the public types.
+- `init({measurementId, manifestUrl, env, onValidationError})` is the single entry point — both `measurementId` and `manifestUrl` are REQUIRED and the function throws synchronously (not via a rejected promise) when either is nullish or empty-string, so misconfiguration is loud at the call site. The Rails layer is the source of truth: `measurementId` from `TrackRelay.config.ga4_measurement_id`, `manifestUrl` from `asset_path('track_relay_catalog.json')` — wire both via an inline ERB `<script type="module">` block in the layout (see `client/README.md`).
+- `track(name, params)` validates against the manifest entry and dispatches via `window.gtag("event", name, params)`. Untyped events pass through unchanged (REQ-06). Missing `window.gtag` warns and drops the event without throwing. `Ga4Gtag.handle(name, params)` is a server-subscriber-shaped wrapper around `track()` for hosts that prefer object dispatch — covers REQ-08's client-side half.
+- JS-side validation mirrors REQ-05: `env: "development"` throws on validation failure (missing required, wrong type), `env: "production"` calls `console.warn` and silently drops. The optional `onValidationError(errors)` callback fires before the throw/warn branch so hosts can route errors to a logging pipeline.
+- `setClientId(id)` updates the resolved `client_id`; the next `track()` re-emits `gtag("config", measurementId, {client_id})` so GA4 attributes events to the right user. The `config` call fires once per page lifecycle until the client_id changes.
+- CI: new `js-test` job in `.github/workflows/ci.yml` runs `npm ci && npm run build && npm test` on Node 22 (build BEFORE test so `build_smoke.test.js` sees a populated `dist/`). Vitest + happy-dom test harness with 31 test cases covering init/track/validation/Ga4Gtag.
+- `TrackRelay::Subscribers::Ga4MeasurementProtocol` — async server-side GA4 Measurement Protocol subscriber. POSTs to `https://www.google-analytics.com/mp/collect?measurement_id=...&api_secret=...` with the canonical Scout §2 web-stream body shape (`{client_id, user_id?, timestamp_micros, events: [{name, params}]}`). EU-region toggle via `config.ga4_use_eu_endpoint = true` switches to `region1.google-analytics.com`. Net::HTTP from Ruby stdlib (no new gem dependency). Default 5s open / 10s read timeout. Async-by-default; hosts opt in inline via `Ga4MeasurementProtocol.synchronous!` per REQ-11. When `client_id` is missing from `payload.context`, falls back to a synthesized `<rand>.<unix_ts>` value so server-only events without a `_ga` cookie still post.
+- `TrackRelay::DeliveryRetriableError` and `TrackRelay::DeliveryDiscardableError` — typed exceptions raised by `Ga4MeasurementProtocol#deliver` to signal retriable (HTTP 5xx, `Net::OpenTimeout`, `Net::ReadTimeout`, `Errno::ECONNREFUSED`, `SocketError`) vs. permanent (HTTP 4xx — defensive coverage) failures. `DeliveryJob` declares `retry_on TrackRelay::DeliveryRetriableError, wait: :polynomially_longer, attempts: TrackRelay::DeliveryJob::DEFAULT_GA4_DELIVERY_ATTEMPTS` (`= 5`) and `discard_on TrackRelay::DeliveryDiscardableError`. The attempt cap is a class-local constant (NOT `config.ga4_delivery_attempts`) because `retry_on` runs at class-body load time before any host initializer fires — runtime configurability is deferred to a future minor.
+- `Subscribers::Base#safe_deliver` carve-out for the typed retry/discard exceptions: those two classes RE-RAISE through the rescue boundary even when `config.swallow_subscriber_errors = true` (the production default). Without this narrow exception to the REQ-23 blanket-rescue, ActiveJob's `retry_on`/`discard_on` macros would never see the typed exceptions because `safe_deliver` would catch them and return them as values. Arbitrary `StandardError`s still flow through the existing log-and-return path — REQ-23's contract is preserved for everything outside the carve-out.
+- Configurable `config.ga4_measurement_id` / `config.ga4_api_secret` (read at delivery time so credentials lambdas / late-bound configs work) and `config.ga4_use_eu_endpoint` (default `false`). When either credential is `nil` at delivery time the subscriber emits a single `Rails.logger.warn` and returns — gem-loaded-but-not-configured apps must not crash. `config.ga4_delivery_attempts` is INTENTIONALLY NOT shipped in 0.2.0 (load-order hazard documented above).
+- Call-time GA4 payload validation in `Ga4MeasurementProtocol#deliver` (REQ-27 split, call-time half): `payload.params.size <= 25` and param-name reserved-prefix check (`firebase_`, `ga_`, `google_`). Honors `config.raise_on_validation_error` — raises `Ga4ConstraintError` in dev/test, `Rails.logger.warn` + skip-POST in prod. Boot-time event-name validation (snake_case + reserved-name list) is the existing `Validators::Ga4Constraints` check at catalog load — Plan 02-04 does not duplicate it.
+- `rake track_relay:lint:ga4` audits the JSONL untyped sink for GA4 event-name violations (snake_case shape, max length, reserved names) and exits non-zero when any are found, so CI can gate on it. The new `TrackRelay::Linter#ga4_violations` and `#print_ga4` methods power the task; both honor the same `untyped_log_path`-must-be-set abort contract as the existing `track_relay:lint` tasks.
+- Subscriber-side `only:` / `except:` event-name filters via the `filter` class DSL or the new `TrackRelay.subscribe(klass_or_instance, only:, except:)` registration helper. Filters short-circuit at the top of `Subscribers::Base#handle` BEFORE the sync/async branch and BEFORE `safe_deliver`'s rescue boundary, so a filtered event with a buggy `#deliver` neither runs nor logs. Per-instance overrides on `TrackRelay.subscribe` are stored on the singleton class so they do not mutate either the class-level defaults or other instances of the same subscriber.
+- `webmock ~> 3.23` as a development dependency. `test_helper.rb` requires `webmock/minitest` and calls `WebMock.disable_net_connect!(allow_localhost: true)` so HTTP-stubbed subscriber tests (Phase 02 GA4 measurement protocol) can register expected calls without leaking to the live network.
+- JSON manifest generation: `rake track_relay:manifest` writes a typed `public/track_relay_catalog.json` (version + `generated_at` + `events: { name => { params: {key => type}, required: [...] } }`) for the `@track_relay/client` JS package to validate events client-side. The task aborts with a nonzero exit when the catalog is empty (RISK-04 footgun guard). The Railtie auto-runs `track_relay:manifest` before `assets:precompile` for production / CI builds and regenerates the file on every `to_prepare` reload in development, so editing `config/track_relay/*.rb` produces a fresh manifest without a server restart. `Manifest.write!` `mkdir_p`s the parent directory so a fresh checkout without a `public/` directory does not crash on first run.
+- Configurable `config.client_id_resolvers` chain (`ClientId::Ga`, `ClientId::AhoyVisitor`, `ClientId::Session` defaults). First non-nil wins; resolved once per request inside `ControllerTracking#_resolve_client_id`; resolver exceptions are isolated (each `#call` is wrapped in `rescue StandardError` and logged via `Rails.logger.warn`, so a single buggy resolver cannot block the chain). `ClientId::Ga` reproduces Phase 01's `_ga`-cookie parser bit-for-bit, preserving existing behavior; the new `Session` fallback mints a `SecureRandom.uuid` into `session[:track_relay_client_id]` so visitors without a `_ga` cookie still get a session-stable identifier. Hosts can prepend custom resolvers via `TrackRelay.config.client_id_resolvers.unshift(...)` for native-app traffic, request-header overrides, etc.
+
+## [0.1.0] - 2026-05-06
+
+### Added
+
+- Catalog DSL with `event` blocks and typed params (`integer`, `string`, `float`, `boolean`, `datetime`) plus validators (`required`, `max`, `in`, `format`, `sanitize`).
+- `TrackRelay::EventDefinition` (catalog metadata) and `TrackRelay::EventPayload` (runtime instance) as separate classes.
+- `TrackRelay::Current` via `ActiveSupport::CurrentAttributes` with `:user, :request, :visit, :controller, :client_id`.
+- `TrackRelay::Configuration` with `subscribe`, `swallow_subscriber_errors`, `untyped_log_path`, `untyped_events_allowed`, `force_synchronous`, `raise_on_validation_error`.
+- `TrackRelay.track(name, **params)` — validates against catalog (when defined) or accepts untyped, instruments `track_relay.event` via `ActiveSupport::Notifications`.
+- `TrackRelay.identify(user, **properties)` — instruments `track_relay.identify`.
+- Reserved-key partitioning: `:user, :visitor_token, :client_id, :request` are routed to `Current` / payload context, never appear in `payload.params`.
+- Reserved-key collision detection at catalog load (`TrackRelay::ReservedKeyError`).
+- GA4 constraint enforcement: snake_case event names, max 40 chars, max 25 custom params, refusal of GA4-reserved names.
+- `TrackRelay::Subscribers::Base` with `synchronous!` macro and per-subscriber rescue (`safe_deliver` returns the StandardError on failure rather than re-raising inline).
+- `TrackRelay::Subscribers::Test` — in-memory capture, synchronous, per-instance state.
+- `TrackRelay::Subscribers::Logger` — writes to `Rails.logger`; appends untyped-event JSONL (`{event, params, controller, action, timestamp}` — param NAMES only, never values) to `config.untyped_log_path`.
+- `TrackRelay::DeliveryJob < ActiveJob::Base` for async subscriber delivery.
+- `TrackRelay::Dispatcher` — single `ActiveSupport::Notifications` subscription that fans out to `config.subscribers` with collect-then-reraise semantics; idempotent `start!` / `stop!`.
+- `TrackRelay::Railtie` — autoloads `config/track_relay/**/*.rb` via `Rails.autoloaders.main.ignore` + `config.to_prepare` + `Dir.glob`/`load`; clears the catalog before each reload for hot-reload safety; starts the Dispatcher on `after_initialize`; loads rake tasks via the `rake_tasks` block.
+- `TrackRelay::ControllerTracking` concern — `track` instance method + `before_action` that sets `Current.controller` / `Current.request` / `Current.client_id` (from the `_ga` cookie).
+- `TrackRelay::JobTracking` concern — `track` instance method (job authors use `Current.set` block form for context, since the Rails Executor clears `CurrentAttributes` before every job).
+- `TrackRelay.test_mode!` / `test_mode_off!` — atomic subscriber swap for test isolation. **Opt-in**: load via `require "track_relay/testing"` (not auto-required by `lib/track_relay.rb`).
+- `TrackRelay::Testing::Helpers` (Minitest assertions) — `assert_tracked`, `refute_tracked`, with auto setup/teardown.
+- RSpec matchers — `have_tracked(:event).with(**params)` (gated by `defined?(RSpec)`).
+- `TrackRelay::Linter` + `rake track_relay:lint` and `rake track_relay:lint:json` — audit untyped events from the JSONL sink with dedupe by event name + sorted-param-signature. Both rake tasks abort with a nonzero exit when `config.untyped_log_path` is unset (footgun prevention).
+- Collect-then-reraise dispatcher: peer subscribers always receive each event; in dev/test (`swallow_subscriber_errors=false`) the first failed subscriber's exception is re-raised AFTER fan-out, so loudness is preserved without breaking the bus.
+- CI matrix: Ruby 3.2/3.3/3.4 × Rails 7.1/7.2/8.0 (9 combinations) via Appraisal + `ruby/setup-ruby@v1` + `bundler-cache: true`.
+- Combustion-backed Minitest test harness; `ActiveSupport::CurrentAttributes::TestHelper` mixed into `ActiveSupport::TestCase` for automatic `Current` reset between tests.
+- StandardRB linting via `bundle exec standardrb` (and `bundle exec rake` default = standard + test).
+
+### Notes
+
+- Privacy: untyped JSONL captures param NAMES only (never VALUES) to avoid leaking PII.
+- Naming: `track_relay` availability on RubyGems will be re-validated before 1.0.
+
+[1.0.0]: https://github.com/dchuk/track_relay/compare/v0.3.0...v1.0.0
+[0.3.0]: https://github.com/dchuk/track_relay/releases/tag/v0.3.0
+[0.2.0]: https://github.com/dchuk/track_relay/releases/tag/v0.2.0
+[0.1.0]: https://github.com/dchuk/track_relay/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darrin Demchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,458 @@
+# track_relay
+
+Unified, typed event tracking for Rails apps. One catalog, multiple destinations, built on `ActiveSupport::Notifications`.
+
+## Status
+
+**Version:** 1.0.0 (pending release) — public API is being stabilized for the 1.0.0 cut. See [CHANGELOG.md](CHANGELOG.md) for release history and [UPGRADING.md](UPGRADING.md) for migration notes.
+
+## Why
+
+Modern Rails apps that want both marketing analytics (GA4) and product analytics (your DB) end up with two parallel event vocabularies. `track_relay` defines events once in a typed catalog and fans them out to every destination, server-side and client-side, without copy-paste.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "track_relay", "~> 1.0"
+```
+
+Then `bundle install`.
+
+Then run the install generator to scaffold a working configuration:
+
+```bash
+bin/rails generate track_relay:install
+bundle exec rake test  # passes cleanly out of the box
+```
+
+See [USAGE.md](USAGE.md) for a full walkthrough.
+
+Requires Ruby 3.2+ and Rails 7.1, 7.2, or 8.0.
+
+For client-side tracking, also install the companion JS package:
+
+```bash
+npm install @track_relay/client
+```
+
+See [GA4 + client-side tracking](#ga4--client-side-tracking) below.
+
+## Quick start
+
+> **Tip:** `bin/rails g track_relay:install` scaffolds the five files below for you. Read on if you'd rather wire them up by hand.
+
+```ruby
+# config/initializers/track_relay.rb
+TrackRelay.configure do |c|
+  c.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+  c.subscribe TrackRelay::Subscribers::Logger.new
+end
+
+# config/track_relay/articles.rb
+TrackRelay.catalog do
+  event :article_viewed do
+    integer :article_id, required: true
+    string  :slug,       required: true
+    string  :category
+  end
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include TrackRelay::ControllerTracking
+end
+
+# app/controllers/articles_controller.rb
+class ArticlesController < ApplicationController
+  def show
+    @article = Article.find(params[:id])
+    track :article_viewed, article_id: @article.id, slug: @article.slug
+    # ...
+  end
+end
+```
+
+That is the full path from `bundle install` to a fired event — five files, no generators required.
+
+## Catalog DSL
+
+Declare events in `config/track_relay/*.rb`. The Railtie autoloads the directory at boot and reloads it on every code reload in development (Zeitwerk-friendly: the directory is explicitly ignored by the autoloader so DSL files never look like constant definitions).
+
+| Type | Example |
+|------|---------|
+| integer | `integer :count, required: true` |
+| string | `string :name, max: 100` |
+| float | `float :amount` |
+| boolean | `boolean :flag` |
+| datetime | `datetime :occurred_at` |
+
+Validators: `required:`, `max:`, `in:`, `format:`, `sanitize:` (callable, runs before validation — no silent truncation). Validation runs at `track` time on the calling thread; failures raise `TrackRelay::ValidationError` when `config.raise_on_validation_error` is true (the default in dev/test).
+
+Each catalog entry produces a `TrackRelay::EventDefinition` (the schema) which is used at `track` time to build a `TrackRelay::EventPayload` (the runtime instance). `EventDefinition` and `EventPayload` are intentionally separate classes so the schema is shareable and immutable across calls while the payload owns the per-call params, context, and timestamp.
+
+### GA4 constraints (applied automatically)
+
+- snake_case event names
+- max 40 characters per event name
+- max 25 custom params per event
+- GA4 reserved names (`page_view`, `session_start`, `screen_view`, etc.) are refused at catalog load with `TrackRelay::Ga4ConstraintError`
+
+### Reserved keys
+
+Four keys are reserved and partitioned out of `params` automatically by `TrackRelay.track`:
+
+- `:user`, `:request`, `:client_id` — bound on `TrackRelay::Current` for the duration of the call (block-scoped via `Current.set`).
+- `:visitor_token` — written directly to `payload.context[:visitor_token]`. It is intentionally **not** a `Current` attribute: `Current` carries `:visit` (an Ahoy-style visit record), not a raw token.
+
+Defining any of these four as a catalog param raises `TrackRelay::ReservedKeyError` at boot, so the conflict surfaces before any event is fired.
+
+### Identify
+
+```ruby
+TrackRelay.identify(current_user, plan: "pro", country: "US")
+```
+
+`identify` is a thin pass-through in 0.1.0: it instruments `track_relay.identify` with `{user:, properties:}` so subscribers can route the user property update wherever they need to. Per-adapter user-property validation (GA4 `user_properties`, etc.) lands in 0.2.0.
+
+## Subscribers
+
+`TrackRelay::Subscribers::Base` is the base class for every subscriber. It exposes a `synchronous!` macro (opts the subclass out of the async `DeliveryJob` path) and a per-subscriber `safe_deliver` rescue that returns the exception instead of re-raising — so one bad subscriber never blocks peers from receiving the event.
+
+```ruby
+class MySubscriber < TrackRelay::Subscribers::Base
+  synchronous!  # opt out of async DeliveryJob
+
+  def deliver(payload)
+    # payload.name, payload.params, payload.context, payload.timestamp
+  end
+end
+```
+
+Async subscribers automatically dispatch via `TrackRelay::DeliveryJob` (an `ActiveJob::Base` subclass). Use Solid Queue, Sidekiq, or any other ActiveJob adapter as your backend.
+
+`TrackRelay::Dispatcher` is the single `ActiveSupport::Notifications` subscription that fans `track_relay.event` notifications out to `config.subscribers`. Its **collect-then-reraise** error contract means: every peer receives the payload, then if `config.swallow_subscriber_errors` is `false` (the default in dev/test), the first collected exception is re-raised after fan-out completes. In production (`swallow_subscriber_errors=true`), exceptions are logged and swallowed so a single broken adapter doesn't take the application down. The Dispatcher is started automatically by the Railtie on `after_initialize`.
+
+Built-in subscribers:
+
+- `Subscribers::Test` — in-memory capture for specs. Per-instance state, no class-level globals.
+- `Subscribers::Logger` — writes a one-line summary to `Rails.logger`; appends untyped events to `config.untyped_log_path` JSONL with the canonical shape `{event, params, controller, action, timestamp}` (param NAMES only — values are never written, by design, to avoid leaking PII).
+
+### Ahoy subscriber (server-side)
+
+`TrackRelay::Subscribers::Ahoy` routes events through the host app's
+ahoy_matey instrumentation using only the public Ahoy API
+(`controller.ahoy.track`). It never calls `Ahoy::Event.create!`
+directly.
+
+Requires the `ahoy_matey` gem in your Gemfile. Wire it in the
+initializer:
+
+```ruby
+TrackRelay.configure do |config|
+  config.subscribe TrackRelay::Subscribers::Ahoy.new
+end
+```
+
+Job-context calls (no controller, no visit) are logged and skipped;
+the Ahoy subscriber will never fabricate a write without a real visit.
+
+> **Heads up — Ahoy bot exclusion.** ahoy_matey silently drops events
+> from requests whose user-agent doesn't look like a real browser
+> (logged as `[ahoy] Event excluded`). If you're smoke-testing via
+> `curl` or Postman and no row appears in `ahoy_events`, pass a real
+> browser User-Agent header. This is Ahoy's default behavior — see
+> ahoy_matey's `exclude_method` config to customize.
+
+### Subscribing directly to AS::Notifications
+
+Because every event is published through `ActiveSupport::Notifications.instrument("track_relay.event", event: payload)`, host apps can subscribe directly without writing a `Subscribers::Base` subclass at all:
+
+```ruby
+ActiveSupport::Notifications.subscribe("track_relay.event") do |*, payload|
+  Rails.logger.tagged("analytics") { Rails.logger.info(payload[:event].name) }
+end
+```
+
+This is useful for one-off integrations and for debugging — your existing `ActiveSupport::Notifications` tooling (lograge, the Rails event reporter, etc.) just works.
+
+## Generators
+
+`track_relay` ships three Rails generators.
+
+- `bin/rails g track_relay:install` — opinionated scaffold: richly
+  commented initializer (`config/initializers/track_relay.rb`),
+  sample catalog (`config/track_relay/sample.rb`),
+  ApplicationSubscriber base class
+  (`app/track_relay/subscribers/application_subscriber.rb`), and
+  `include TrackRelay::ControllerTracking` injected into
+  ApplicationController (idempotent — no-ops if the include already
+  exists).
+
+- `bin/rails g track_relay:event NAME` — scaffolds a typed catalog
+  entry stub at `config/track_relay/<name>.rb` with a
+  `TrackRelay.catalog do event :name do ... end end` block. Each
+  event lives in its own file; the Railtie merges them at boot.
+
+- `bin/rails g track_relay:subscriber NAME` — scaffolds a subscriber
+  class stub at
+  `app/track_relay/subscribers/<name>_subscriber.rb`.
+
+See [USAGE.md](USAGE.md) for a full walkthrough.
+
+### Controller and Job helpers
+
+```ruby
+class ApplicationController < ActionController::Base
+  include TrackRelay::ControllerTracking
+  # adds a `track` instance method + a before_action that populates
+  # Current.controller / Current.request / Current.client_id (from the _ga cookie)
+end
+
+class WelcomeEmailJob < ApplicationJob
+  include TrackRelay::JobTracking
+  # adds a `track` instance method; use Current.set { ... } block form
+  # inside `perform` to populate context (the Rails Executor clears
+  # CurrentAttributes before every job, by design).
+
+  def perform(user)
+    TrackRelay::Current.set(user: user) do
+      track :welcome_email_sent, template_version: "v3"
+    end
+  end
+end
+```
+
+## Test helpers
+
+The testing surface is **opt-in**. Add `require "track_relay/testing"` to your `test_helper.rb` (Minitest) or `rails_helper.rb` (RSpec) — `lib/track_relay.rb` does NOT require it automatically, so the `Subscribers::Test` swap and RSpec matchers stay out of production runtime.
+
+`TrackRelay.test_mode!` atomically replaces the configured subscriber list with a single `Subscribers::Test` instance and forces synchronous delivery; `TrackRelay.test_mode_off!` restores the previous list. Tests assert against the captured events without spinning up real adapters or external services.
+
+### Minitest
+
+```ruby
+# test/test_helper.rb
+require "track_relay/testing"
+# OR (just the Minitest helpers)
+require "track_relay/testing/helpers"
+
+class MyTest < ActiveSupport::TestCase
+  include TrackRelay::Testing::Helpers  # auto test_mode! / test_mode_off! per test
+
+  test "fires article_viewed" do
+    get article_path(@article)
+    assert_tracked :article_viewed, article_id: @article.id
+  end
+
+  test "does not double-fire" do
+    refute_tracked :article_viewed, article_id: 99
+  end
+end
+```
+
+### RSpec
+
+```ruby
+# spec/rails_helper.rb
+require "track_relay/testing"
+
+RSpec.configure do |c|
+  c.before(:each) { TrackRelay.test_mode! }
+  c.after(:each)  { TrackRelay.test_mode_off! }
+end
+
+it "fires outbound_click" do
+  click_link "External"
+  expect(track_relay).to have_tracked(:outbound_click).with(destination_domain: "example.com")
+end
+```
+
+The RSpec matchers are loaded only when `RSpec` is already defined, so the gem stays test-framework-agnostic.
+
+## Untyped events + linter
+
+Untyped events (events that aren't in the catalog) are allowed by default — `config.untyped_events_allowed = true` — so teams can adopt the catalog incrementally. Set `config.untyped_log_path` to capture every untyped fire to a JSONL file:
+
+```ruby
+TrackRelay.configure do |c|
+  c.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+end
+```
+
+Then audit with the bundled rake tasks:
+
+```bash
+$ bundle exec rake track_relay:lint
+# track_relay untyped event audit
+# events: 3; total occurrences: 47
+event :outbound_click  (32 total)
+  - params=[destination_url, link_text, source_path]  count=32
+event :search_executed  (12 total)
+  - params=[filters, query]  count=12
+event :modal_dismissed  (3 total)
+  - params=[modal_id]  count=3
+```
+
+`bundle exec rake track_relay:lint:json` emits the same data as JSON for consumption by external tooling (Slack notifiers, dashboards, CI gates).
+
+The linter (`TrackRelay::Linter`) dedupes by event name + sorted-param-name signature: two firings of `:outbound_click` with the same param names collapse into one row, while different param shapes count separately so you can spot drift.
+
+If `config.untyped_log_path` is unset, both rake tasks abort with a nonzero exit code and a configuration message — by design, so a misconfigured audit pipeline doesn't silently exit 0.
+
+The JSONL captures only sorted, stringified parameter NAMES (never values) for the same privacy reason.
+
+## GA4 + client-side tracking
+
+0.2.0 ships a complete GA4 path — server-side via `Subscribers::Ga4MeasurementProtocol`, client-side via the [`@track_relay/client`](client/README.md) JS package. They share one catalog and one validation contract.
+
+### Server-side: GA4 Measurement Protocol subscriber
+
+```ruby
+# config/initializers/track_relay.rb
+TrackRelay.configure do |c|
+  c.ga4_measurement_id = ENV.fetch("GA4_MEASUREMENT_ID")
+  c.ga4_api_secret     = ENV.fetch("GA4_API_SECRET")
+  # c.ga4_use_eu_endpoint = true  # opt-in for EU residency
+
+  # Send all events that need server-side fan-out
+  c.subscribe TrackRelay::Subscribers::Ga4MeasurementProtocol.new
+end
+```
+
+The subscriber POSTs to `https://www.google-analytics.com/mp/collect` with the canonical `{client_id, user_id?, timestamp_micros, events: [{name, params}]}` body. Async-by-default through `TrackRelay::DeliveryJob` (an `ActiveJob::Base` subclass) — typed `DeliveryRetriableError` / `DeliveryDiscardableError` exceptions wire `retry_on :polynomially_longer, attempts: 5` and `discard_on` so 5xx errors retry and 4xx errors are dropped without retrying. Hosts can opt the subscriber into synchronous delivery for in-process consistency: `Ga4MeasurementProtocol.synchronous!`.
+
+When either credential is `nil` at delivery time the subscriber emits a single `Rails.logger.warn` and returns — gem-loaded-but-not-configured apps must not crash.
+
+Subscriber-side filters via `only:` / `except:` keep noisy events out of GA4:
+
+```ruby
+TrackRelay.subscribe(
+  TrackRelay::Subscribers::Ga4MeasurementProtocol.new,
+  only: %i[purchase signup outbound_click]
+)
+```
+
+### `client_id` resolver chain
+
+`TrackRelay::Current.client_id` is resolved via a configurable chain of `client_id_resolvers`. The default chain checks the GA `_ga` cookie, then any Ahoy visitor token, then mints a session-stable UUID into `session[:track_relay_client_id]` so visitors without a `_ga` cookie still get a stable identifier. First non-nil wins; per-resolver exceptions are isolated so a single buggy resolver cannot block the chain.
+
+```ruby
+TrackRelay.configure do |c|
+  # Prepend a custom resolver for native-app traffic
+  c.client_id_resolvers.unshift(->(req) { req.headers["X-Native-App-Id"] })
+end
+```
+
+### JSON manifest
+
+`rake track_relay:manifest` writes a typed JSON snapshot of the catalog to `public/track_relay_catalog.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "generated_at": "2026-05-06T12:00:00Z",
+  "events": {
+    "purchase": {
+      "params": {"value": "float", "currency": "string", "coupon": "string"},
+      "required": ["value", "currency"]
+    }
+  }
+}
+```
+
+The Railtie auto-runs `track_relay:manifest` before `assets:precompile` (production / CI) and regenerates the file on every `to_prepare` reload in development. The manifest is the contract the JS package consumes for client-side validation.
+
+### Client-side: `@track_relay/client`
+
+The JS package fetches the manifest at boot and dispatches events via `window.gtag` after validating against the same typed schema as the server. The Rails layer owns the configuration; the layout wires both `measurementId` and `manifestUrl`:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<script type="module">
+  import { init } from "@track_relay/client";
+  init({
+    measurementId: "<%= TrackRelay.config.ga4_measurement_id %>",
+    manifestUrl: "<%= asset_path('track_relay_catalog.json') %>"
+  });
+</script>
+```
+
+Then track events from anywhere in your JS:
+
+```javascript
+import { track } from "@track_relay/client";
+
+document.querySelector("#buy-button").addEventListener("click", () => {
+  track("purchase", { value: 9.99, currency: "USD" });
+});
+```
+
+Validation behavior mirrors REQ-05: in development a missing required field or wrong type throws an Error; in production it calls `console.warn` and silently drops the event. Untyped events (not in the manifest) pass through unchanged. See [`client/README.md`](client/README.md) for the full API and the `Ga4Gtag` named export.
+
+## Compatibility
+
+- Ruby 3.2, 3.3, 3.4
+- Rails 7.1, 7.2, 8.0
+- Test framework: any (gem ships matchers for both Minitest and RSpec; gem itself uses Minitest)
+
+CI runs the full Ruby × Rails matrix (9 combinations) on every push via Appraisal + GitHub Actions.
+
+## Roadmap
+
+### Shipped
+- 0.1.0 — Core (catalog DSL, dispatch, Test + Logger subscribers, Minitest/RSpec helpers)
+- 0.2.0 — GA4 (server-side Measurement Protocol subscriber, client-side `Ga4Gtag`, JSON manifest)
+- 0.3.0 — Ahoy (server-side `Subscribers::Ahoy`, client-side `AhoyJs`)
+
+### Pending release
+- 1.0.0 (pending release) — Polish: generators, doc audit, public-API stability guarantee
+
+### Future (post-1.0.0)
+- Additional v2 subscribers: PostHog, Mixpanel, Plausible, Webhook, Segment
+- Optional engine mount for `/track_relay/events` POST endpoint (ad-blocker resilience)
+- Performance benchmarks
+- Companion `rubocop-track_relay` cop for raw `gtag` / `ahoy.track` call detection
+
+## Public API stability
+
+As of 1.0.0, the following surface is covered by SemVer guarantees:
+
+- Module entry points: `TrackRelay.track`, `.configure`, `.catalog`,
+  `.subscribe`, `.identify`, `.test_mode!`, `.test_mode_off!`
+- Subscriber base class and class macros: `TrackRelay::Subscribers::Base`,
+  `synchronous!`, `filter only:`, `filter except:`
+- Built-in subscribers: `TrackRelay::Subscribers::Test`, `Logger`,
+  `Ga4MeasurementProtocol`, `Ahoy`
+- Concerns: `TrackRelay::ControllerTracking`, `TrackRelay::JobTracking`
+- Test helpers: `TrackRelay::Testing::Helpers`, `assert_tracked`,
+  `refute_tracked`
+- Catalog DSL keywords (`event`, `integer`, `string`, `float`,
+  `boolean`, `datetime`, `user_property`) and validators
+  (`required:`, `max:`, `in:`, `format:`, `sanitize:`)
+- Generators: `track_relay:install`, `track_relay:event`,
+  `track_relay:subscriber`
+- Rake tasks: `track_relay:lint`, `track_relay:lint:json`,
+  `track_relay:lint:ga4`, `track_relay:manifest`
+
+Internal classes (`TrackRelay::EventPayload`, `Instrumenter`,
+`Dispatcher`, `Catalog`, `Current`, `DeliveryJob`, `ClientId::*`)
+are not part of the public API contract and may change without a
+major version bump.
+
+See [UPGRADING.md](UPGRADING.md) for migration notes from 0.x.
+
+## Contributing
+
+```bash
+bundle install
+bundle exec rake          # default = standard + test
+bundle exec appraisal install   # one-time, generates gemfiles/*.gemfile
+```
+
+The test harness boots a minimal Combustion-backed dummy app under `test/internal/`. CI runs Ruby 3.2/3.3/3.4 × Rails 7.1/7.2/8.0 (9 combinations) via Appraisal. Linting uses StandardRB (`bundle exec standardrb`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).