Tracker rebuild spec — site-wide attribution from a blank editor
Impression, click, scroll, hover, dwell, form — 11 event types, one pixel envelope

A specification you can use to rebuild the wal.sh passive-capture tracker from a blank editor. No dependency on reading the current CLJS. Every claim below is either a design constant with a stated reason, or a numbered requirement that the rebuild MUST satisfy.

The current implementation lives at src/wal_sh/site/tracker/{core.cljc,browser.cljs} and src/wal_sh/adtech/beacon/core.cljc (payload builder, shared with adtech beacon). This document freezes the contract those files implement so a rewrite in TS, Python-transcrypt, or plain JS can drop-in-replace it.

Scope: the first-party observation layer. Sponsored-slot fill, attribution audit, and A/B assignment are consumers of this layer; they are out of scope.

Eleven event names. Adding a new one requires updating the whitelist in one place (known-events in tracker.core) AND wiring a browser-side emitter for it. The whitelist is a closed set: any event name outside it is rejected at send! time.

R1. The rebuild MUST honour the closed-set rule for event names. Emitting an unknown name is a no-op. This is the boundary that lets you grep the codebase for "who fires sponsored.impression?" and get an exact answer.

R2. sponsored.* is derived, not primary. Any node whose data-track-kind is sponsored-product or chumbox-card, or that carries data-track-sponsor or data-track-creative, MUST fire the sponsored variant instead of the element variant. Same envelope, same extras — different event name. Consumers can filter on the name.

Every event, no matter which type, carries the same base envelope before the type-specific extra is merged on top:

R3. uid MUST persist across sessions in ~localStorage= under key _ab_uid, and MUST be shared with ab-engine and attribution-audit under that same key. The volume-per-uid analysis (bots emit many events per uid; humans emit few) is the whole point of the persistent id — a session-only id can't distinguish "one bot returned 400 times" from "400 users came once."

R4. uid MUST be opaque and NOT PII. No email, no IP, nothing tying it to a person. If localStorage is blocked (private browsing, or a user preference), fall back to the session id — do NOT try to reconstitute persistence via canvas/audio fingerprinting.

R5. The envelope MUST use the exact field names above. Downstream log parsers key on them.

Both the wal.sh CSP and the beacon endpoint's OpenAPI accept a GET /pixel that returns a 1×1 transparent GIF. Loading via new Image()= uses =img-src=, not =connect-src=. The wal.sh CSP is =connect-src 'self'=, so a POST via ~sendBeacon or fetch to beacon.termbox.org is refused; the pixel path is not.

Fan-out to two pixels for every event:

1. Third-party beacon: https://beacon.termbox.org/pixel?<query>
2. Same-origin: /static/tracking.gif?<query> (fires an entry in the DreamHost Apache access log; gmake logs rsyncs those; the logs REPL namespace parses them)

R6. The rebuild MUST fire both pixels for every event. The second one is the debugging surface — the beacon endpoint is opaque, but the Apache log is grep-able and joinable in a REPL.

R7. Encode the envelope as a URL query string. Skip nil/blank values. Clip the total encoded string to 1800 bytes so no CDN or proxy truncates mid-parameter.

R8. Never throw from the transport. try {} catch { return null } around ~new Image()= and every listener. A tracker that crashes the page has failed harder than a tracker that silently drops an event.

Both gates run before any pixel fires. They are cheap; they are not authoritative. A downstream analysis pass with fuller signals (JA3, network timing, etc.) is expected.

R9. bot? returns true if any of:

• navigator.webdriver === true
• userAgent contains one of: bot, Bot, crawl, spider, Spider, HeadlessChrome, Playwright, Puppeteer

R10. opt-out? returns true if the URL query has ?tracking=off. This is the user's kill switch and MUST be respected. Document it in your site's privacy page — a switch nobody knows about is not a switch.

R11. Both gates fail closed: on any exception, return false (allow). Otherwise a bad UA string knocks all analytics off the site.

Every listener is attached in capture phase so descendants that call ~stopPropagation()= (Vue widgets, React portals) don't hide events from us. The listeners themselves are pure dispatchers — signal extraction happens in helpers.

The tracker doesn't know what elements matter — the page tells it via attributes. Ten attributes, none required:

R17. Every string attribute MUST be clipped to 200 chars server-side in the pure core (clip in tracker.core) before serialization. A pathological data-track-id="{100KB of junk}" MUST NOT blow the pixel budget.

R18. Element identity is extracted in the browser adapter, passed as a plain map to core/element-payload, and merged into the envelope as ~elId=, ~elKind=, ~tag=, ~href=, ~alt=, ~position=, ~sponsor=, ~creativeId=, ~unit=, ~pageIdx=, ~poolIdx=, ~isDup=. The pure core has no DOM dependency; identity extraction is host-specific.

R18a. Image fallback. An <img> (or <figure>) is trackable without a data-track-id — hovering an image is a genuine intent signal, and requiring the page template to annotate every image would leak intent whenever the annotation was forgotten. Fallback identity for an unannotated <img>:

• elId = "img:" + basename(src.split("?")[0])
• elKind = "img"
• href = the src (or the ancestor <a>'s href if the image is inside a link)
• alt = the alt attribute (never captured for non-image nodes)

Explicit ~data-track-*= attributes always win over fallbacks when present.

R19. Sampling MUST be deterministic on the session id. Given a session and an event class, either every event of that class fires for that session or none does. Random per-event sampling produces half-populated funnels and is worse than no sampling.

Implementation: ~fnv1a(sessionId) mod 100 < pct=. FNV-1a is a 32-bit hash with well-known constants; do not substitute djb2 or java-string-hash — cross-language reproducibility depends on matching bytes.

The current tracker samples at 100% (no sample function called); that constant lives at the send! site.

Exposed after init! completes:

window.__wal_tracker.send("<event-name>", {extras: "..."})
window.__wal_tracker.rescan()   // re-observe [data-track-id] nodes
window.__wal_tracker.session()  // returns opaque session id

R20. ~send= MUST reject unknown event names (silently — no throw, no console error) so a rogue caller can't inject arbitrary event types into the pipeline.

R21. ~rescan= MUST be idempotent — attaching the observer twice must not fire two impressions per view. Track observed nodes in a Set.

R22. Init MUST be idempotent — a second ~init!()= call must be a no-op (compare-and-set on an ~installed?= atom).

Ten steps. In order. Each step MUST be complete before the next begins.

1. Author a whitelist of event names. Freeze it. Reject anything else.
2. Author the envelope (§3). Every field, sourced from the same place as this doc.
3. Author the transport (§4). Dual-fan-out, GET, ~Image().src=. Never throw.
4. Author the bot filter + opt-out (§5). Both fail closed on error.
5. Author the pure core: element-payload, scroll math, sampling, event-name validation. No DOM here. Test in isolation.
6. Author the six listeners (§6.1-6.6) in the browser adapter. Each listener is a pure dispatch — extract the payload, call ~send!=.
7. Wire the [data-track-*] contract (§7). Update page templates so the elements you care about carry ~data-track-id=.
8. Wire the public API (§9). Compare-and-set-once on ~installed?=.
9. Ledger the crossing: bump ~.verify/chain.jsonl= via ~bb scripts/verify-chain add=; verifier tracker-vN-implementer, subject tracker-vN.
10. Deploy. Verify events appear in ~/logs/wal.sh/https/access.log= for the /static/tracking.gif?... path AND in the beacon endpoint (opaque, so you're verifying by shape).

Explicitly out of scope for the tracker:

• Attribution. Which touchpoint gets credit is ~wal-sh.adtech.attribution-audit=. The tracker records touches; crediting them is somebody else's job.
• A/B assignment. Which arm a user is in is ~wal-sh.adtech.ab-engine=. The tracker records events; the arm goes in via the CEDDL layer.
• Fill / ranking. Which ad serves is ~sponsored-research=. The tracker records that a sponsored unit was seen; it does not decide which unit.
• Session reconstitution. The tracker does not attempt to stitch cross-device sessions or reconstruct a user's true identity. ~uid= is opaque and per-browser.

The tracker's only job: turn DOM events into pixel GETs under a closed event vocabulary. Every additional responsibility belongs in a separate contract.

The claim is that this spec is enough to rebuild the tracker without reading ~src/wal_sh/site/tracker/=. It fails if a second implementation, written from this doc alone, produces materially different ~access.log= entries against the same interaction. Test by pointing both implementations at the same page, driving the same sequence (pageview → scroll to 50% → click a tracked link → pagehide), and diffing the ~/static/tracking.gif?…= entries in the log. Difference in envelope key order is fine; difference in which events fire, or in the values of event, depthPct, dwellMs, or elId is a specification bug.

• retrospective/index.org — build history including tracker's role
• vocabulary-binding/index.org — sponsored-research's dependence on the tracker's event vocabulary
• attribution-audit/spec.org — the consumer of every sponsored.* and element.click event
• beacon/spec.org — payload builder (beacon.core) shared with the adtech beacon
• intent-signals/spec.org — derives intent booleans from tracker events, most notably result.dwell (DR1)