# spec-tracker — The Tracking Pipeline

The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as described in RFC 2119.

## 1. Tracker construction

A client tracker is created from:

- `catalog` — the app's event catalog (spec-event-model §1).
- `destinations` — the fan-out list (spec-destinations).
- `anonymousId` — a **callable** returning the visitor id, not a pre-resolved value. It is invoked per allowed event, so
  id minting stays lazy (spec-identity §1) and never happens as a construction side effect.
- `isAnalyticsAllowed` — an optional **callable** consent gate. Omitted means "always allowed".

## 2. The `track(name, properties)` algorithm

1. **Resolve the definition.** `catalog[name]`; unknown → raise `Unknown event: <name>`. This is a programmer error and
   MUST propagate (unlike delivery errors).
2. **Validate.** Run schema validation per spec-event-model §2; failures propagate. The parsed output replaces the raw
   input from here on.
3. **Evaluate the gate — per event, at track time.** Never cache the gate result at construction: a consent change
   mid-session MUST apply to the very next event.
4. **Short-circuit.** If the gate is closed and no destination is exempt, return — nothing is built, nothing is sent,
   and no id is minted.
5. **Build the envelope** (spec-event-model §3):
   - `anonymousId`: if the gate is open, invoke the `anonymousId` callable (this is the one place minting may happen);
     if closed, the empty string — the callable MUST NOT be invoked, so no id is ever minted as a side effect of a gated
     event.
   - `eventId`: fresh random UUID. `timestamp`: now. `type`: `"track"`. `properties`: the parsed output.
6. **Fan out.** Gate open → every destination receives the envelope; gate closed → only exempt destinations receive it.
   All destinations receive the same envelope value.

## 3. The exempt lane

Destinations marked `consentRequirement: "exempt"` (spec-destinations §2) keep receiving events while the gate is
closed, under strict conditions:

- Gated envelopes are **identifier-free**: `anonymousId` is `""` and no id is minted for them.
- Nothing is persisted on the visitor's device for the exempt delivery.
- Exemption is only for cookieless, identifier-free sinks; it is the destination author's assertion, and the default is
  `"required"` so pre-consent delivery stays an explicit opt-in.

## 4. Delivery error handling

Tracking MUST never break the tracked interaction:

- A destination's `send` is fire-and-forget at track time; the tracker does not await it.
- Both failure shapes MUST be contained: an asynchronous rejection **and** a synchronous throw from a non-conforming
  destination (the interface says `send` returns a deferred value, but a third-party implementation may violate that).
  Neither may propagate to the `track()` caller, and a failing destination MUST NOT prevent the remaining destinations
  from receiving the event.
- Contrast with steps 1–2: unknown-event and validation errors are caller bugs and MUST propagate.

## Conformance vectors

Setup for all vectors: catalog `{ "signup": schema {plan: string} }`; destinations `D_req` (required) and `D_ex`
(exempt); id callable returns `A` and counts invocations.

**V1 — gate open.** Gate → true. `track("signup", {"plan":"pro"})` → both `D_req` and `D_ex` receive one envelope with
`anonymousId == A`; id callable invoked once.

**V2 — gate closed, exempt lane.** Gate → false. Same call → only `D_ex` receives the envelope, with
`anonymousId == ""`; id callable invoked zero times.

**V3 — gate closed, no exempt destinations.** Destinations `[D_req]`, gate → false. Same call → no delivery, no
envelope, id callable invoked zero times, caller sees no error.

**V4 — mid-session consent change.** Gate returns false for the first call, true for the second → first delivers per
V2/V3 semantics, second per V1. No construction-time caching.

**V5 — destination failure isolation.** `D_req.send` throws synchronously; a second destination `D_ok` is registered.
`track()` returns normally and `D_ok` still receives the event. Same outcome when `D_req.send` rejects asynchronously.

**V6 — validation failures propagate.** `track("signup", {"plan": 5})` raises; `track("nope", {})` raises; no
destination receives anything in either case.

## License

Released under the [MIT License](../LICENSE).