[A13xB0]

Summary

Builds on the transport view from #2167 and #2169 (both merged); rebased onto master (352a0ccd), so the diff is this PR's six commits only.

The Scope Audit was the one analysis page without the region selector. This adds the shared region filter to it, for both the declared and the transport view. ?region=SFO,SJC means what it means on every other endpoint: count only forwarding heard by observers in those regions, not repeaters located there.

• API (GET /api/scope-audit, both modes):
  • The region codes are resolved to their observers first (a handful of rows), then the audit's hop scan gets AND o.observer_idx IN (…) on v3, or o.observer_id IN (…) on v2. The 3.5M-row hop scan never joins observers.
  • All means no filter (shared normalizeRegionCodes). Codes with no observer match nothing, instead of silently widening to every observer.
  • Responses echo the normalised codes as region. The declared and transport caches and their singleflight keys now include the region, so each region set is cached separately with the existing TTLs.
  • Declared-region verification (regionEvidence) is deliberately left unfiltered: it corroborates what a repeater declares from its own traffic, which doesn't depend on where a hop was heard.
• Page: the shared RegionFilter sits with the view and window controls; a change reloads the view, and the selection persists like every other page. The transport view's text box is relabelled Scope (it already sends ?scope= since the rename in feat(scope-audit): transport view of every repeater seen forwarding (#2142, API) #2167), so the page no longer has two controls called Region.
• Docs: docs/api-spec.md (parameter, both response shapes) and the OpenAPI parameters for the route (mode, scope and region were all missing).

Partial fix for #2142 (its region filter for rollout tracking), together with #2167 and #2169.

Performance

The unfiltered path must not get slower: it's the same query with an empty clause. BenchmarkComputeScopeTransport (from #2167, 1,200 repeaters), the PR it stacks on vs this branch, -count 8:

	before	after
sec/op	220.3 ms	218.0 ms	~ (p=0.065)
B/op	43.77 MiB	43.70 MiB	~
allocs/op	833.5k	833.5k	~

Filtered requests, measured on staging (a copy of a production database): the first version drove o.observer_idx IN (…) from idx_observations_observer_idx, reading every observation the region's observers ever made. Fixed in 80414242 with a unary + (the same treatment as #2166), so the scan starts from the first_seen window and filters per row. Red test 67e063b1 asserts the query plan against a fixture with the real indexes.

scan, one region over 24h (13 observers)	plan	time	hop rows
o.observer_idx IN (…)	observer index	13.44 s	102,114
+o.observer_idx IN (…)	first_seen window	0.25 s	102,114
unfiltered	first_seen window	0.35 s	225,983

Cold end-to-end requests on staging after the fix: 24h declared, unfiltered 0.84 s · one region 0.48 s (was 16.7 s) · two regions 0.22 s · transport, one region 0.42 s · transport, six regions 0.75 s · 7d, one region 3.46 s. 24h transport, live data: 383 repeaters unfiltered, 204 heard by one country's observers.

Tests

• Red 629e4f36 (Go): extends the audit fixture with an observers table and observations.observer_idx. Covers the declared view ignoring a scope heard only by another region's observer, the transport view listing only repeaters heard in the region, region=All, per-region caching, a region with no observers, and the echoed codes. Five fail on assertions; region=All passes because the stub ignores the filter, which is the behaviour it pins.
• Green 6f1b1e1c: the implementation, plus a v2-schema case (observer_id), so both branches of the clause are covered.
• Red b4933d68 / green 08ecc172 (frontend): apiPath carries the selection in both views and adds nothing when none is selected. The region control on the page is a net-new UI surface.
• go test (cmd/server) passes. Frontend suites: 193 of 194. The one failure, test-issue-1956-release-routing.js, needs CI's GITHUB_REF_NAME and fails the same way on master locally.

Screenshot

The same transport view with the shared region filter set to SJC: only forwarding heard by San Jose observers counts, so 7 repeaters are listed instead of 44, with their carried scopes counted from those observers alone. Taken against test-fixtures/e2e-fixture.db with fictional scopes.

Browser validation

The branch's server was run locally with 14 configured regions (dropdown layout), checked in headless Chromium at 1280, 900, 700 and 390 px (touch):

check	1280	900	700	390 touch
ticking SJC re-requests with &region=SJC	yes	yes	yes	yes
menu fully on screen	yes	yes	yes	yes
page wider than viewport	no	no	no	no
page errors	none	none	none	none

Found and fixed this way: the filter is the right-most control on desktop, and the menu (which opens rightwards) ran 66 px off the page. It now opens leftwards above 640 px. On a phone the controls wrap, the filter starts a line, and the default applies.

SonarLint

SonarQube Community rules (the SonarLint engine) were run on the files this PR touches, and only issues on lines it adds are listed.

• S3776 on ScopeAuditForwardingHeardIn: complexity 55. The function it generalises, ScopeAuditForwarding, is 54 on master; the region clause adds one point.
• S3776 on computeScopeAudit: complexity 65, unchanged from master.
• Both pre-date this PR. Splitting them is better as a refactor PR of its own than mixed into a feature.
• The page code's findings were fixed in the transport-view PR it stacks on.

Checked against the repo rules

• Rebased onto master (673442cc). Each red commit was re-run and still fails on its assertions; each green commit passes (TDD.md).
• make test: all 16 modules pass. Frontend suites: all pass except test-issue-1956-release-routing.js, which needs CI's GITHUB_REF_NAME and fails the same way on master locally (test: make local validation independent of runner environment #2160 addresses it).
• No private data: test fixtures and examples use the codes the existing tests use (SJC/SFO/LAX, #be-style scopes).
• No new map[string]interface{}, no hard-coded colours. git add was explicit, and there is one logical change per commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KaR4xu8gVykQBkH8yG8m6H

[efiten]

#2167 and #2169 are merged (squashed as 6969063 and deb55dc), together with #2170 (352a0cc). Because of the squash, the commits this branch still carries now conflict with master in docs/api-spec.md, public/scope-audit.css, public/scope-audit.js and tests/unit/test-frontend-helpers.js. Could you rebase onto master so that only the region-filter commits are left? I'll merge it once CI is green.

The re-run of the failed jobs was green on all three E2E shards, so the test-issue-1648-m2-icons-e2e.js failure was the race you described. The cause: theme-refresh re-runs showNodeDetail (live.js) and briefly swaps #nodeDetailContent to "Loading...", and the test calls row.isVisible() right after waiting for the table. A row.waitFor({ state: 'visible' }) would close it; happy to take that PR.

One follow-up I'd like after this merges, under AGENTS.md's "no unbounded data structures". It doesn't block this PR:

scopeAuditCache and scopeTransportCache are now keyed by window + "|" + region, where region is the raw normalizeRegionCodes output. The codes are not sorted, de-duplicated or checked against known regions, and no entry is ever removed. Before this PR each cache had at most 3 keys.

Failure scenario: an unauthenticated client sending region=X1, region=X2, ... gets a new permanent entry per value, and SFO,SJC vs SJC,SFO are two entries. Each cold value pays a full-window meta scan, plus a hop scan when the codes are valid, which takes seconds at 7d.

Could you send a follow-up that canonicalises the codes (sort, de-duplicate, drop unknown codes) and bounds the caches (evict expired entries, or cap the size)?

[A13xB0]

Rebased onto master (352a0ccd), now that #2167 and #2169 are merged. The branch is down to this PR's own six commits, and the merge conflict is gone.

• Replaying them onto master produced no conflicts.
• After the rebase, the cmd/server suite and all standalone frontend suites pass.
• The "requires feat(scope-audit): transport view of every repeater seen forwarding (#2142, API) #2167 / feat(scope-audit): transport view on the Scope Audit page (#2142, page) #2169 first" note is removed from the description.