engine.EngineMetrics.Throughput is exported, documented, and assigned by no engine: it reports a plausible 0 instead of "not measured"

[FumingPower3925]

engine.EngineMetrics.Throughput is exported, documented as "the recent requests-per-second rate", and never assigned by any engine. Verified against 468ce53:

engine/engine.go:173      // Throughput is the recent requests-per-second rate.
engine/engine.go:174      Throughput float64
engine/epoll/loop.go:1150 // RequestCount (plus Throughput and the adaptive controller's   <- comment only
adaptive/engine.go:929    Throughput: pm.Throughput + sm.Throughput,                        <- 0 + 0

std, epoll and io_uring never write it. The only line that touches the field at all is adaptive's aggregation, which sums two values that are always zero. So every Metrics() call from every engine reports Throughput: 0.

The rate is computed — at adaptive/telemetry.go:85, snap.ThroughputRPS = float64(deltaReqs) / elapsed — but into adaptive's own controller snapshot, not into EngineMetrics. The exported field and the working one are different structs that happen to share a name.

Why it matters more than it looks

A field that is exported, documented, and always zero is indistinguishable from a real measurement of zero. A consumer reading Metrics().Throughput gets a plausible number and no signal that nothing measured it — which is strictly worse than the field not existing.

This is not hypothetical. probatorium's /debug/vars publisher was just widened to export all 52 EngineMetrics scalar fields (goceleris/probatorium#389), so celeris.engine_throughput now appears in every refapp's metrics endpoint, reading a flat 0 on every engine on every cell. It was published deliberately, with a comment saying so, on the reasoning that a field which exists and is never published cannot be told apart from one that is published and never moves — but the right end to fix is this one.

Options

1. Populate it. RequestCount and a timestamp are already tracked per engine; the adaptive controller derives the rate from exactly those. The awkward part is that "recent" needs a window, and Metrics() is a snapshot with no natural interval — whatever is chosen should be stated in the doc comment.
2. Remove it, and let consumers derive a rate from RequestCount and their own sampling interval, which is what probatorium already does.

Option 2 is a breaking change to an exported struct, so it belongs in v2.0.0 unless the field is judged too new to matter. Filing against v1.6.0 for the decision, not for a particular fix — if the answer is "remove", it should move to the v2.0.0 milestone rather than ship half-done.

No engine regression test would have caught this: there is nothing to assert against a field nobody writes.

[FumingPower3925]

#695 deprecates the field in v1.6.0, per the plan's D6. Removal stays with #651 (v2.0.0). goceleris/docs#73 fixes the docs examples that print it.

celeris #695

• engine/engine.go: a Deprecated: paragraph on EngineMetrics.Throughput. It says:
  • the field always reads 0, and why: no engine computes it (std, epoll and io_uring never set it; adaptive only summed their zeros), and a snapshot has no interval to compute a rate over
  • a zero here looks exactly like a measured rate of zero
  • use RequestCount sampled twice over your own interval instead
  • the field is removed in v2.0.0 (Release checklist: v2.0.0 #651)
• adaptive/engine.go:1018: the pm.Throughput + sm.Throughput pass-through is gone. Nothing in the tree touches the field any more. The reflective adaptive: Metrics() silently drops Workers, AcceptCount, CloseCount, BytesRead, BytesWritten and RecvResumeWhileCancelPending #627 aggregation test exempts it by name, with the reason.
• Tests:
  • TestThroughputIsDeprecatedAsAlwaysZero parses the field's doc. On 9f4d89b: FAIL, because the doc is Throughput is the recent requests-per-second rate. with no Deprecated paragraph.
  • TestNothingSetsThroughput walks every non-test .go file of the repository and fails on any composite-literal key or selector named Throughput, so the "always 0" claim and the code cannot drift apart. On 9f4d89b: FAIL at adaptive/engine.go:1018.
• Mutants, each killed:
  • the Deprecated paragraph removed
  • adaptive forwarding the field again. golangci-lint on that mutant also reports SA1019 … Throughput is deprecated, so readers outside the package now get a lint finding.
  • std setting it
• CI on fix(engine): deprecate EngineMetrics.Throughput, which always reads 0 (celeris#653) #695: run 36241544621, all jobs green. Its Adaptive job shows 103 --- PASS: Test lines, 0 FAIL and 0 SKIP, including TestMetricsCarriesEveryFieldReflectively.

docs #73

• engines.md:441 and observability.md:133: the rows say "Always 0 … deprecated in v1.6.0, removed in v2.0.0".
• The examples at engines.md:463 and performance.md:635 derive rps from two RequestCount samples.

probatorium

probatorium is not changed here. Its EngineKeysNotParsed entry already names #653. Its validation/refapp/internal/debugvars/debugvars.go:510 reads the field and will get an SA1019 finding at the next celeris bump, wherever golangci-lint covers that module.

Evidence: evidence/celeris-673-679-653-424/lane-20260926/653/.

• docs#73 build: green (run 36241857974).

This comment only reports. The issue closes when #695 merges; #651 keeps the removal.