1.6.43 items 1-3: internal traffic never reaches the read table

ITEM 1 (applied — the accruing one). `record_read` now drops a request
carrying INTERNAL_UA_TOKEN BEFORE it reads any field, exactly as
`track_visit` has since the internal-traffic contract existed. The hook
arrived with the 2.8.0 floor and never learned the rule, so the hub's health
sweep, every satellite's link audit and every post-deploy battery have been
landing in `reads` — the busiest "vendor" on the board. "Counted nowhere"
includes the read table; this repo was holding half its own contract.

Keyed on `ua`, checked against the RESOLVED package rather than assumed:
EVENT_FIELDS has `ua`, not `user_agent`, and a drop keyed on the wrong name
is a silent no-op — this item's own failure mode. tests pin the field name
against `_ledger.EVENT_FIELDS` so a rename fails here, not in production.

Five tests, both directions, counts PRINTED beside every result because a
bare "no rows" is the negative this round learned not to trust:

    internal probes  : reads 1 -> 1  (delta 0 expected)
    crawler probe    : reads 1 -> 2  (delta 1 expected)
    token neutralised: reads 2 -> 3  (delta 1 expected)

That third line is the one that makes the first mean anything. A `delta 0`
proves the drop only if the package WOULD have emitted a row for that
request; if an internal UA happened not to reach the crawler lane, the
assertion would pass while record_read did nothing. So the mutation check
neutralises the token, sends the identical probe, and requires the row to
appear. It does.

ITEM 2 (already-present, verified rather than assumed).
  (a) relying on item 18's PER-CALL-SITE UA pin, which is green — not the
      file-scoped form, which this fork already replaced after proving it
      false-passes when `headers=` sits on an unrelated code path.
  (c) tests/test_analytics_classifier.py is here as cargo and its three
      fork-owned seams were diffed against this tracker rather than trusted
      to a passing run: the row-key set {timestamp, path, device_type,
      user_agent, ip_address, location} matches what track_visit writes;
      `flush()` exists; `ANALYTICS_GEO_LOOKUP` is read by the tracker.

ITEM 3 (applied). The traps section is ported verbatim per DIVERGENCES 11's
sync rule — 176 -> 248 lines, pure addition, no conflicts. Four traps
arrive: headless browsers are crawler-lane from dimll 2.9.0; branch-by-
timing on a green push (this fork's own measurement, now fleet doctrine);
verify the artifact the claim is about; and assert the corpus is non-empty
before trusting a negative.

Suite 322 -> 327 passed / 1 skipped. Exit codes captured directly rather
than through a pipe — `pytest … | tail` reports tail's status, which is how
the template seat committed over a red suite an hour after writing the note
warning about it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P6tDZymsTt73Z4xFW1M5JX

Author: pip-install-python

.claude/CLAUDE.md

@@ -280,3 +280,75 @@ they win.
   to main, built by Render inside the minute, red in CD at 14:13Z,
   served for ~6 minutes. A host whose DIVERGENCES.md posture fence has
   no `deploy:` key still watches main — there the trap is the old one.
+- Headless browsers are CRAWLER-lane from dash-improve-my-llms 2.9.0
+  (measured on the wheel, 2026-08-29: `HeadlessChrome/…` and a
+  Playwright UA classify `lane: crawler, bot_type: monitor,
+  vendor_key: headless`; 2.8.0 said browser). A host that screenshots
+  ITSELF for social cards — Playwright, Puppeteer, a headless Chrome
+  in a job — now receives the crawler document, not the app shell,
+  unless the screenshot service sends its own non-headless UA. If a
+  card went blank or textual after a floor bump, look here before
+  the template. Same class as the two lane traps above: name the UA,
+  confirm from the body which document answered.
+- Which branch Render actually builds can be measured on a GREEN push,
+  by TIMING, without waiting for a red one (leaflet, 2026-08-31 — the
+  method, not just its answer). `main == release == wire` at every step
+  of a promote tells you nothing: both refs hold the same sha, so the
+  wire cannot separate them, and four promotes across three hosts said
+  nothing at all. Sample `/healthz` every ~45 s from the moment of the
+  push and note when the swap lands relative to the PROMOTE, not the
+  push. leaflet measured build+swap at 2m03s from the promote; had
+  Render reacted to the push instead, the same 2m03s would have put the
+  build live ~1m52s earlier than it appeared, and the wire was still
+  serving the old sha well past that point. That is STRONG EVIDENCE
+  that Render is building `release` — not proof, since a queued or slow
+  build could in principle produce the same shape. The canonical
+  discriminator is unchanged and still owed: the first push that goes
+  RED on main must leave `release` unmoved and the wire unchanged.
+  Worth taking on every SECOND promote — it costs one background
+  sampler and converts "asserted" into "strongly evidenced".
+- Verify the artifact the claim is about, and say which one you
+  measured. Three hosts got this wrong in one round while holding the
+  rule: a skip link checked in the received HTML lives in the RENDERED
+  DOM (muicharts, twice inside an hour, having written the rule
+  itself); a props table absent from the crawler document is a defect
+  of the site, not of the harness — pannellum moved that assertion onto
+  the rendered layout and the pin passed for a fortnight over a corpus
+  serving zero props. WHEN A LANE DISAGREES, THAT IS THE FINDING; never
+  relocate the assertion to the lane that passes. And an owner-gated
+  section needs BOTH cookie states to be a measurement at all
+  (modelviewer: `credentials: 'include'` → 2,962 B with admin hrefs,
+  `'omit'` → 108 B with none — hidden, not merely styled away).
+  The error runs BOTH ways and the second one is worse, because it
+  sends someone hunting a bug that does not exist: `curl https://…/ |
+  grep -c skip-link` returns **0** on a host where the skip link is
+  shipped and working (excalidraw, 2026-08-31) — it is a Dash
+  component in `app.layout`, so React renders it and the served HTML
+  never contains it. A fork "verifying the skip link on the wire" with
+  curl reports a missing feature that is present. Anything built by
+  the layout rather than written into the template is invisible to the
+  two artifacts curl can reach; assert it through the layout or a real
+  browser, and say which you used.
+- Assert the corpus is NON-EMPTY before trusting any negative, and print
+  the count beside the result (note 88). A sweep that found nothing and a
+  sweep that swept nothing produce the same green, and only one of them
+  is evidence. Measured here 2026-09-01: this repo's `.flake8` excludes
+  `docs/*/`, so `flake8 docs/` exits 0 with a file in `docs/` containing
+  `def broken(:` — the linter is not passing that file, it is not reading
+  it; `py_compile` sees it at once. Same family, same day: a naive
+  substring count read fenced documentation as defects (this seat), a
+  file-scoped grep matched prose ABOUT the defect it was hunting
+  (muicharts, clerkhook), a `git show … && diff` printed "(empty = same)"
+  on a comparison that never ran (llms), and `pytest … | tail -2 && git
+  commit` committed over a red suite because a pipeline's exit status is
+  the LAST command's (this seat, one hour after writing the note above).
+  Capture the exit code; count what you swept; say both.
+- And the same family one turn later, worth keeping because it nearly
+  shipped a wrong fact into a spec: extracting a package constant with
+  `re.search(r"EVENT_FIELDS = \((.*?)\)", src, re.S)` truncated at a `)`
+  inside a COMMENT in the middle of the tuple, printed eight of sixteen
+  fields, and reported `'ua' present: False` — confidently, with a
+  number beside it. Caught only because eight looked too few. When you
+  parse a language construct out of source with a regex, check the count
+  against something independent (the file, `python -c "from … import X;
+  print(len(X))"`, the CHANGELOG) before you believe a negative.

lib/analytics_tracker.py

@@ -396,9 +396,27 @@ def record_read(self, event):
         it appends; the flush does the disk work.
 
         ``client_ip`` is dropped unless ``ANALYTICS_KEEP_CLIENT_IP=1``.
+
+        INTERNAL TRAFFIC IS DROPPED FIRST, before any field is read (1.6.43
+        item 1). The network's internal-traffic contract says a request
+        carrying ``INTERNAL_UA_TOKEN`` is counted NOWHERE, and "nowhere"
+        includes this table — ``track_visit`` has honoured that since the
+        contract existed, and this hook, added with the 2.8.0 floor, never
+        learned it. Until this fix the hub's health sweep, every satellite's
+        link audit and every post-deploy battery landed in ``reads`` and were
+        the busiest "vendor" on the board.
+
+        Keyed on ``ua``: ``EVENT_FIELDS`` has ``ua``, NOT ``user_agent``, and
+        a drop keyed on the wrong name is a silent no-op — which is this
+        item's own failure mode, so the name is checked against the resolved
+        package rather than assumed (tests/test_internal_traffic.py).
         """
         if not isinstance(event, dict):
             return
+        from lib.constants import INTERNAL_UA_TOKEN
+
+        if INTERNAL_UA_TOKEN in (event.get("ua") or "").lower():
+            return
         row = {k: event.get(k) for k in EVENT_FIELDS}
         if not KEEP_CLIENT_IP:
             row.pop("client_ip", None)

tests/test_internal_traffic.py

@@ -164,6 +164,139 @@ def test_real_traffic_is_still_counted(client):
     assert after["bot_hits"] == before["bot_hits"] + 1
 
 
+# ------------------------------------------------------- the READ table -----
+#
+# "Counted nowhere" includes the `reads` table (1.6.43 item 1). Everything
+# above this point tests `visits`, which `track_visit` has guarded since the
+# internal-traffic contract existed. `record_read` — the `on_document_read`
+# hook the 2.8.0 floor added — never learned the rule, so until this round the
+# hub's health sweep, every satellite's link audit and every post-deploy
+# battery landed in `reads` and were the busiest "vendor" on the board.
+
+
+def _ledger_reads():
+    tracker.flush()
+    try:
+        with open(analytics_path()) as f:
+            return json.load(f).get("reads", [])
+    except FileNotFoundError:
+        return []
+
+
+def test_the_drop_keys_on_the_field_the_package_actually_sends():
+    """This item's own failure mode, guarded.
+
+    The drop reads `event["ua"]`. `EVENT_FIELDS` has `ua`, NOT `user_agent` —
+    a drop keyed on the wrong name is a silent no-op that passes every
+    "no rows" assertion below by dropping nothing and being asked nothing.
+    Checked against the RESOLVED package rather than a literal, so a rename
+    between versions fails here rather than in production.
+    """
+    import importlib.metadata as md
+
+    from dash_improve_my_llms import _ledger
+
+    from pathlib import Path
+
+    assert "ua" in _ledger.EVENT_FIELDS, (
+        f"the package resolved here ({md.version('dash-improve-my-llms')}) has "
+        f"no `ua` field: {_ledger.EVENT_FIELDS}"
+    )
+    tracker_src = (Path(__file__).resolve().parent.parent
+                   / "lib" / "analytics_tracker.py").read_text()
+    body = tracker_src.split("def record_read")[1].split("def _enqueue")[0]
+    assert 'event.get("ua")' in body, "record_read does not key the drop on `ua`"
+    assert "INTERNAL_UA_TOKEN" in body, "record_read never checks the token"
+
+
+def test_an_internal_probe_writes_no_read_row(client, capsys):
+    """One probe carrying the token -> ZERO read rows, count PRINTED.
+
+    A bare "no rows" is the negative this round learned not to trust, so the
+    count goes next to the result and the positive control below proves the
+    pin cannot pass by dropping everything.
+    """
+    before = len(_ledger_reads())
+    client.get("/llms.txt", user_agent=internal_ua("network-smoke"))
+    client.get("/llms.txt", user_agent=f"{CRAWLER_UA} {INTERNAL_UA}")
+    after = len(_ledger_reads())
+    with capsys.disabled():
+        print(f"\n    internal probes: reads {before} -> {after} (delta 0 expected)")
+    assert after == before, (
+        f"internal traffic reached the read table: {after - before} row(s)"
+    )
+
+
+def test_a_real_crawler_probe_writes_exactly_one_read_row(client, capsys):
+    """The positive control, in the same file as the negative.
+
+    A `record_read` that returned unconditionally would satisfy the test
+    above; this is what stops that passing.
+    """
+    before = len(_ledger_reads())
+    client.get("/llms.txt", user_agent=CRAWLER_UA)
+    after = len(_ledger_reads())
+    with capsys.disabled():
+        print(f"    crawler probe  : reads {before} -> {after} (delta 1 expected)")
+    assert after == before + 1, (
+        f"expected exactly one read row, got {after - before}"
+    )
+
+
+def test_the_zero_above_is_the_drop_working_not_the_probe_being_silent(
+    client, monkeypatch, capsys
+):
+    """MUTATION CHECK, and the reason this file has one.
+
+    `delta 0` proves the drop only if the package WOULD have emitted a row
+    for that request. If an internal UA happened not to reach the crawler
+    lane, the assertion above would pass while `record_read` did nothing —
+    the vacuous negative this round has now produced three times.
+
+    So: neutralise the token, send the identical probe, and require the row
+    to appear. If it does, the zero above was the drop.
+    """
+    from lib import constants
+
+    monkeypatch.setattr(constants, "INTERNAL_UA_TOKEN", "\x00-never-matches")
+    before = len(_ledger_reads())
+    client.get("/llms.txt", user_agent=internal_ua("network-smoke"))
+    after = len(_ledger_reads())
+    with capsys.disabled():
+        print(f"    token neutralised: reads {before} -> {after} (delta 1 expected)")
+    assert after == before + 1, (
+        "with the token neutralised the identical probe STILL wrote no row — "
+        "so the zero in the test above says nothing about the drop"
+    )
+
+
+def test_internal_reads_never_reach_the_rollups_vendor_block(client):
+    """The number the hub actually charts.
+
+    `vendors[]` and `reads` in the daily rollup are built from this table, so
+    a token-carrying probe must not appear as a vendor row either.
+    """
+    from lib.traffic_rollup import daily_rollup, load_reads
+
+    # Scoped to the rows THIS test causes. The mutation check above
+    # deliberately writes one internal row (with the token neutralised) to
+    # prove the drop is load-bearing, so a whole-table assertion here would
+    # fail on another test's intentional fixture rather than on a defect.
+    before = len(_ledger_reads())
+    for _ in range(3):
+        client.get("/llms.txt", user_agent=internal_ua("link-audit"))
+    tracker.flush()
+    new_rows = load_reads(str(analytics_path()))[before:]
+    internal = [r for r in new_rows
+                if INTERNAL_UA_TOKEN in (r.get("ua") or "").lower()]
+    assert internal == [], f"{len(internal)} internal row(s) in the read table"
+    assert new_rows == [], f"3 internal probes wrote {len(new_rows)} row(s)"
+
+    payload = daily_rollup("leaflet", datetime.now().date()) or {}
+    for v in payload.get("vendors", []):
+        assert INTERNAL_UA_TOKEN not in str(v.get("key") or "").lower()
+
+
 # ----------------------------------------------------------------- outbound --