feat: load as a first-class citizen (DD-033)

[basquin-bot]

What & why

Load campaigns were second-class everywhere they surfaced: the dashboard is hard-coded to explore (a load campaign showed iterations=0/crashes=0/"no coverage source" — empty explore scaffolding), and the CLI status table showed <none> coverage / 0 findings for load. The real load numbers only reached status.load via kubectl. LOAD-MODE-DESIGN.md promised a dashboard push that was never built.

DD-033 makes load first-class in the dashboard and the CLI.

How — one push path, made mode-aware

• StatusReporter gains a mode + a load block; snapshotJson() emits "mode":"explore"|"load" and, in load, "load":{throughputRps, latencyMs:{p50,p90,p99,max}, heapDriftKb, threadDrift, serverErrors, requests}. Explore JSON only gains a "mode" field — additive.
• LoadRun feeds it live: a snapshotter thread computes throughput/percentiles from the live histogram + drift, so the existing DashboardClient loop carries it and the dashboard updates during the soak. No second pusher.
• Dashboard renders a mode-aware load card (throughput/p50-p90-p99/drift/5xx) + shows mode in the campaign list.
• CLI status — a MODE column + mode-aware metrics (rps · p99 for load, cov% · finds for explore, pending for a load campaign with no results yet).

Correctness

• Explore is behaviorally unchanged (JSON additive-only; the explore #sub elapsed/rate line stays independent of the /clusters fetch — a regression found and fixed in review; CLI explore row identical).
• One drift poller, no hot-path lock. The snapshotter is the sole periodic /__basquin/drift poller; the terminal drift reuses its last poll; the per-request worker loop gains zero synchronization (DD-029 lock-free load preserved).
• Live converges to terminal — same post-warmup window, same percentile()/histogram, and the final snapshot equals the terminal number. Live is approximate (torn reads, by design); status.load is the authoritative terminal record (the dashboard shows the last live snapshot, converged).

OTel-shaped, export deferred

Per the design discussion, metrics are typed for a future OTLP export (request latency = histogram basquin.load.request.duration, unit ms, the MAX_MS+2 bucket boundaries as the contract; throughput/5xx = counters; drift/coverage = gauges; campaign.id = resource attribute, mode = metric attribute) so the exporter is a thin adapter. No OTel dependency added — the OTLP export is its own roadmap DD, tied to clustered-runners histogram merge.

Verification

Unit: StatusReporterLoadTest, LoadSnapshotTest (live math == terminal), CampaignRow{Explore,Load,LoadPending}. Full suite 124/124; Go cmd/basquin + controller green. The in-cluster e2e asserts the load campaign's dashboard received mode=load + a non-empty load block (CI runs it).

Spec: docs/superpowers/specs/2026-07-21-load-first-class-design.md · Plan: docs/superpowers/plans/2026-07-21-load-first-class.md

🤖 Generated with Claude Code

[ianp94]

@claude please review — load as a first-class citizen (DD-033): mode-aware dashboard (live during the soak, one push path) + CLI status. Explore is behaviorally unchanged; status.load stays the authoritative terminal record.

[claude]

Claude finished @ianp94's task in 3m 40s —— View job

---

Review: DD-033 — load as a first-class citizen

Todo list

• Gather context (PR description, changed files)
• Read repo conventions
• Review runner/util/StatusReporter.java
• Review runner/coverage/LoadRun.java (snapshotter thread, drift/percentile math)
• Review runner/util/DashboardServer.java
• Review resources/dashboard.html
• Review operator/cmd/basquin/status.go + tests
• Review new tests (StatusReporterLoadTest, LoadSnapshotTest, status_test.go)
• Review docs (DESIGN-DECISIONS.md, spec/plan, TODO.md)
• Check e2e script change
• Post final review

CI is green (CI, Operator CI passed; Operator e2e (kind) still running as of this review).

---

Summary

Solid, well-documented change. The "make the one push path mode-aware" approach is the right call — no second pusher, additive JSON, and the DD-029 lock-free load-hot-path guarantee is genuinely preserved (only the snapshotter thread and the final terminal call touch StatusReporter.recordLoad; the per-request worker loop only touches the existing AtomicLongArray/AtomicLong counters). computeLoadSnapshot being shared between the live snapshotter and the terminal push is a nice way to guarantee live-converges-to-terminal, and LoadSnapshotTest exercises the bucket math directly. Docs (DESIGN-DECISIONS.md, TODO.md, spec/plan) are thorough and match the code.

One real finding, plus a couple of minor nits:

1. c.mode is rendered into the fleet view without HTML-escaping (resources/dashboard.html)

In tickFleet():

'<div class="s" style="margin-top:8px">iters '+c.iterations+' · crashes '+c.crashes+
  ' · cov '+(c.coveragePct>=0?c.coveragePct+'%':'—')+' · '+(c.mode||'explore')+'</div>'+

Every other field here (c.id, c.kind, c.classification, c.campaignNames elsewhere in the file) goes through the file's own esc() helper before hitting innerHTML; c.mode doesn't. On the server side, DashboardServer.strField() (the new helper backing this field) pulls the raw regex capture out of whatever body was POSTed to /ingest/status and embeds it unescaped into the /api/campaigns JSON — it only guards against breaking out of the JSON string ([^"]*), not against </>.

In normal operation this is harmless: mode is only ever set by StatusReporter.setMode("load"|"explore") with hardcoded literals. But /ingest/status is a shared-token-authenticated endpoint, not something that validates the JSON shape of the body (schema-agnostic scrape by design, per DD-013), so this is one write path away from stored XSS in the fleet view if that assumption ever slips (e.g. a modified/compromised driver). Given the file already treats every other reflected field as untrusted, this one should match: wrap with esc() at the render site (resources/dashboard.html, the tickFleet() template).

Fix this →

2. StatusReporterLoadTest relies on unreset static state (test/StatusReporterLoadTest.java)

StatusReporter's new loadRecorded/loadThroughputRps/etc. fields are static and never reset. recordLoadEmitsModeLoadAndAWellFormedLoadBlock resets mode back to "explore" at the end but leaves loadRecorded=true — so defaultModeIsExploreAndCarriesNoLoadBlock's assertion that there's no "load": block only holds if it happens to run before the other test in the same JVM. JUnit4's default method ordering isn't declaration order (it's a deterministic-but-unspecified hash order), so this is a latent order dependency rather than a guaranteed pass. Every other static-state test file in this repo (LoadModeTest, LoadModeControlTest, CostCorpusTest, RequestBoundaryTest) resets via @After; this one doesn't follow that convention. Low risk today (only 2 tests, likely stable ordering in practice), but worth a @After reset for consistency and to stop it from becoming a flaky test later if more cases are added to this file.

Nits / confirmed non-issues (for the record, since they looked suspicious at first read)

• "throughputRps":"%.1f" being emitted as a quoted JSON string (not a number) in both StatusReporter.loadBlockJson() and LoadRun's terminal JSON looked off at first, but it's intentional and pre-existing: LoadStatus.ThroughputRps in the CRD (operator/api/v1alpha1/basquincampaign_types.go:171) is itself typed string ("formatted, e.g. 713.4"), and the dashboard JS does string concatenation either way. Consistent, not a bug.
• The explore-JSON mutation in StatusReporter.snapshotJson() (strip trailing }, append ,"mode":... + load block, re-close) is string surgery rather than a JSON builder, but it matches the file's existing String.format-based JSON assembly style — not a new anti-pattern introduced by this PR.
• The #sub timing-independence regression mentioned in the PR description (commit 3eb96a8) is correctly fixed in the current diff — the explore branch still sets #sub before the /clusters fetch, matching pre-PR behavior exactly.

Nothing here blocks merging — #1 is worth fixing before this ships to be consistent with the rest of the file's escaping discipline, #2 is a cheap test-hygiene follow-up.
· branch

[basquin-bot]

Both findings addressed in 2fb7f70 (verified, not rebutted):

1. Fleet c.mode unescaped — wrapped with the existing esc() in tickFleet(), matching every other reflected field. You're right that /ingest/status is schema-agnostic (DD-013), so an untrusted mode was one write-path from stored XSS in the fleet view.
2. StatusReporterLoadTest static-state ordering — went one better than an @After alone: loadBlockJson now gates on "load".equals(mode) as well as loadRecorded, so the block appears iff mode==load (explicit invariant, no stale block on an explore snapshot) — which also makes the test order-independent — plus an @After mode reset for convention. Full suite 124/124.

Nits #1–3 confirmed as intentional/non-issues, thanks for recording them.

[ianp94]

Approving. Both Claude App findings verified as genuinely addressed in code, not just replied to:

1. Fleet XSS: tickFleet now renders esc(c.mode||'explore') — checked the actual diff hunk, consistent with every other reflected field.
2. Static-state ordering: loadBlockJson() gates on "load".equals(mode) && loadRecorded with the invariant documented in-code (a load block appears iff mode==load), plus the conventional @After reset — the stronger fix, as claimed.

Review highlights (practices + efficiency lenses):

• The snapshotter honors every design commitment: one drift poller (terminal reuses lastDrift, single-poll fallback only if the snapshotter never ran), the live window anchored at measureFromNanos exactly like the terminal computation so live converges to terminal rather than diverging, torn-reads documented on the shared computeLoadSnapshot (and shared code means the "live matches terminal" test is testing the real thing), daemon thread interrupted+joined cleanly, terminal push before mode revert.
• OTel table commitments all recorded: basquin.load.request.duration (not "latency"), UCUM unit field never in the name, the 1ms×30000+overflow bucket layout as a hard exporter contract, campaign.id as resource attribute vs mode as metric attribute.
• CLI: the pending state for a load campaign with no Status.Load yet is exactly right — falling through to explore-shaped "0 finds" would have implied a fuzz search found nothing. Go tests cover both modes and the negative case (explore row must not show rps).
• e2e closes the loop for real: queries the load campaign's own dashboard (token-authed) for mode:load + a non-empty load block before campaign GC. Green in CI.
• strField defaulting to "explore" keeps pre-DD-033 payloads rendering — good back-compat thinking in a schema-agnostic scrape.

One observation, no change requested: throughputRps is a JSON string ("%.1f") in both the load block and status.load. That's consistency with the existing DD-029 CRD contract (ThroughputRps is a string field), so changing it here would be a schema break for no gain — but the future OTLP exporter must read the registry doubles, never parse this JSON, which the DD record already mandates. Just flagging so it stays deliberate.

(reviewed at 2fb7f70)