docs(todo): lock-free load-mode instrumentation profile

[ianp94]

Captures the idea you green-lit (2026-07-21): keep instrumentation in play while scaling throughput — closure's thesis applied to load testing.

The problem, proven by the benchmark: load mode drives an Injected target whose valve serializes requests (DD-005/DD-010, so per-request heap/thread deltas are attributable) — which caps concurrency at 1. The k6 10-VU run showing 256ms was 10× queueing behind the lock, not app throughput. Naively uninstrumenting to go fast discards the whole availability oracle → load mode becomes plain k6.

The fix — split instrumentation by what concurrency allows, in load mode only:

• Drop the serialization lock → real concurrent throughput.
• Keep concurrency-safe per-request signals (latency, 5xx/crash — each request self-times, no lock).
• Replace per-request heap/thread deltas (need the lock) with periodic process-global sampling for drift over the soak — exactly what load mode wants, and exactly what the feat(runner): periodic CSV time-series sampler for benchmark capture #59 sampler already does.
• Net: realistic throughput + latency/5xx findings + heap/thread drift; gives up only per-request heap attribution (explore mode's job).

Composes with clustered runners (#62) and the cost-pheromone corpus (#60) into a distributed cost-guided load engine. Cross-refs DD-005/DD-010, DD-026, the sampler. Design-note-first; likely its own DD. Docs-only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LXSdVrJQy6DvELDbtptG5p

[ianp94]

@claude please review this docs-only roadmap addition: check the technical claim is sound (latency/5xx are concurrency-safe without the lock; heap/thread deltas need serialization; drift-via-sampling is the load-relevant substitute) and that the DD-005/DD-010/DD-026/#59 cross-references are accurate.

[claude]

Claude finished @ianp94's task in 4m 5s —— View job

---

Review: lock-free load-mode instrumentation profile

• Gather context (PR diff, repo structure)
• Read TODO.md addition in full
• Verify DD-005/DD-010 claims (Injected target valve serialization)
• Verify DD-026 reference
• Verify feat(runner): periodic CSV time-series sampler for benchmark capture #59 sampler reference
• Assess technical soundness of the concurrency-safety claims
• Post final review

Core thesis checks out. BasquinValve (tomcat-valve/src/main/java/com/basquin/valve/BasquinValve.java:38,49,84) does take a single global ReentrantLock around every request, so an Injected target really does cap concurrency at 1 — the queueing-not-throughput read of the 10-VU/256ms benchmark is plausible. DD-005 (docs/DESIGN-DECISIONS.md:108-127) and DD-010 (:130-157) say exactly what the entry claims: latency and the leak set are scoped per-IterationContext (confirmed — agent/IterationContext.java has no static/shared fields) and are concurrency-safe today, while heap/thread deltas are process-global and DD-010 explicitly says they "remain trustworthy only under serialized/single-flight execution." DD-026 (:899-905) and LOAD-MODE-DESIGN.md confirm load mode shares the same Injected/valve-instrumented target as explore mode. All four cross-references are accurate.

Two claims are overstated relative to what's actually built today, worth fixing before this becomes a DD:

1. "Keep... 5xx/crash" implies it already exists — it doesn't. runner/coverage/LoadRun.java:121-141 (fire()) swallows every exception and never inspects the HTTP status code; the method's own doc comment says "a load run measures behavior, not crashes." So 5xx/crash detection in load mode is new work to add, not an existing signal to preserve. Minor, but the DD should scope it as "add," not "keep."

2. The feat(runner): periodic CSV time-series sampler for benchmark capture #59 cross-reference points at the wrong existing mechanism for lock-free drift. The CSV time-series sampler (runner/util/StatusReporter.java sampleHeader/sampleLine/sampleLoop, tested in test/StatusSamplerTest.java) does sample on its own timer — but the heap columns it emits (lastHeapKb/maxHeapKb) are fed from ctx.heapDeltaBytes (agent/Agent.java:105-110,234-235), i.e. the exact per-iteration begin/end delta that DD-005/DD-010 say needs the lock to be trustworthy. Sampling that value less often doesn't make it safe under concurrency — it's still the same racy delta, just resampled at a coarser cadence.
   The mechanism that's actually already lock-free and process-global today is LoadRun's own heap read (runner/coverage/LoadRun.java:97-98,143-146): a direct Runtime.totalMemory()-freeMemory() snapshot, entirely decoupled from the Agent/valve. That's the real precedent for "periodic process-global sampling," not feat(runner): periodic CSV time-series sampler for benchmark capture #59 — though today it's a single start/end delta in the driver JVM (not periodic, not target-side), matching the "periodic drift sampling" and "target-side heap/thread" items TODO.md already lists as open follow-ups (TODO.md:426). So the right framing is: the idea is sound and the primitive (absolute Runtime reads) already exists and already avoids the lock — but building it into a periodic, target-side sampler is still greenfield, not something feat(runner): periodic CSV time-series sampler for benchmark capture #59 already delivers.

Net assessment: the split-by-concurrency-tolerance design is technically sound and well-grounded in the existing DDs — dropping the lock for real throughput while keeping context-scoped latency and moving heap/thread to periodic absolute sampling is the right shape. Just tighten the two references above (5xx/crash as new work; point the "already does this" claim at LoadRun's direct Runtime reads rather than the #59 CSV sampler, whose current heap columns are lock-dependent) when this graduates to a full DD.

No code changes made — this was a review-only request on a docs-only PR.

[ianp94]

Both corrections applied — good catches, they'd have mattered when this graduates to a DD. (1) 5xx/crash reframed as ADD (LoadRun.fire swallows exceptions today). (2) The drift primitive now correctly points at LoadRun's absolute Runtime.totalMemory()-freeMemory() read (lock-free/process-global) rather than the #59 sampler's heap columns — which, as you note, are the lock-dependent ctx.heapDeltaBytes delta just resampled coarsely. #59's contribution is reframed as the timer/CSV cadence, not the heap value; the periodic+target-side sampler is the greenfield work.