feat(powerx): annotate measurement window and reconcile trace vs published power | PowerX：标注测量窗口并对账原始轨迹与已发布功耗

[edwingao28]

Summary

The hidden PowerX viewer (/gpu-metrics) rendered raw GPU telemetry with no indication of which part of the trace was formally measured, whether the measurement was declared valid, or whether the published avg_power_w matches the trace.

• GET /api/gpu-metrics (additive): each gpu_metrics_<X> artifact entry can now carry an optional power block assembled server-side from same-suffix sibling artifacts, cheapest first — the tiny bmk_<X> / bmk_agentic_<X> agg row (Tier 1; sufficient once the row-level power provenance change queued in InferenceX (feat/power-row-provenance) lands its power_audit object there), falling back to the power_audit_<X> bundle's power_validation sidecar (Tier 2, same 50 MB Content-Length cap as the CSV path). Tolerant in both directions: agg rows from before and after feat/power-row-provenance, single-node benchmark_window and multinode selected_window sidecars, and the agentic results/power_validation.json entry naming introduced by the AgentX power artifacts change queued in InferenceX (feat/agentx-power-artifacts) all map through the same pure helpers (src/lib/power-audit-artifacts.ts).
• Chart: a new custom D3 layer shades the measurement window with dashed bounds and labels, dims warmup/post-benchmark regions, and tracks x-zoom.
• Reconciliation panel: validity badge + verbatim reason chips, window bounds/duration, observed vs expected chip counts, published avg_power_w (with source), a viewer-side trapezoid recompute over all chips (mirroring the producer's boundary-interpolated per-device integration), and a color-coded delta (|Δ| ≤ 2% ok, ≤ 5% warn — the producer's accumulator tolerance — else alert), plus provenance (producer sha / exporter digest) when present.
• Timestamp alignment: naive nvidia-smi/ISO trace timestamps are placed via UTC parsing; a window that cannot be intersected with the trace yields an explicit message and no shading — never a silently shifted band.

Backward compatibility

• Runs with no sidecar artifacts (or oversized/malformed ones) return a response shape-identical to master — no power key, CSV view untouched; a sidecar failure can never break the trace view.
• No power block → no panel, no shading: the page renders bit-for-bit as before (covered by an intercepted legacy-degradation e2e spec).
• /api/gpu-metrics stays classified ui-artifact-read (excluded from the stable v1 catalog); the review digest was refreshed.

Tests

• src/lib/power-audit-artifacts.test.ts (new): suffix derivation, agg mapping for both legacy and feat/power-row-provenance row shapes, single-node/multinode sidecar mapping, implausible-epoch rejection, deterministic validation-entry selection, merge precedence.
• src/components/gpu-power/power-window.test.ts (new): TZ-independent UTC parsing, window alignment (inside / clamped / disjoint-null), hand-computed trapezoid integration (constant, ramp, boundary interpolation, mixed cadences), delta thresholds.
• src/app/api/gpu-metrics/route.test.ts: every pre-existing case unmodified; new cases for sidecar-only runs, Tier-1 short-circuit (asserted via fetch call count), sibling-free legacy shape, oversized bundles, malformed sidecar JSON, and no-op bmk source attribution.
• cypress/e2e/gpu-power.cy.ts: two new fixture-driven specs (token-free via cy.intercept) — window shading + reconciliation (published 402 W vs recomputed 400 W → Δ −0.5%) and legacy degradation.

Full app unit suite: 4514 passed (254 files). bunx tsc --noEmit: clean. gpu-power.cy.ts: 11/11 passed against the E2E_FIXTURES=1 dev server.

Review notes

The following issues were found during review and fixed in fe82c574:

• Corrupt sidecar epoch could crash the page: a finite-but-out-of-range start_time_unix (e.g. 1e16) reached new Date(v * 1000).toISOString() in the panel and threw RangeError. Fixed at both ends: windowFromUnixPair now rejects non-positive, ms-scale, and past-2100 epochs (unit-tested), and the panel formats bounds through a helper that falls back to the raw number outside Date's representable range.
• sources footer overstated provenance: a bmk_* artifact whose agg row carried no power fields was still credited, and a bundle agg row contributing only window/counts wasn't. Artifacts are now credited only when their parsed content contributed (hasPowerContent gate); a no-op Tier-1 row also falls through to the Tier-2 agg fallback (new route test).
• Zooming fully into warmup/post lost the dim overlay: the degenerate-band early return dropped all shading, making a fully-zoomed warmup region look like measured data. The layer now dims the whole visible region (with the warmup/post label) when the view lies wholly on one side of the window.
• Sidecar schema_version leaked into published.power_metric_schema_version: the sidecar's own schema version (1) is a different versioning axis than the agg row's power-metric schema version (2). The validation_metrics fallback now reports null.

One residual limitation is deliberate: a non-UTC runner with a clock offset smaller than the trace span would still intersect and shade a shifted window. Heuristic timezone snapping was rejected in favor of the intersection-check-or-refuse design, and benchmark containers run UTC in practice; this is documented as a known residual risk rather than guessed at.

Out of scope

Multinode traces (no gpu_metrics_* artifact exists to attach to), DB-vs-artifact drift checks (InferenceX-app PR #939), and AgentX artifact publication (feat/agentx-power-artifacts — once it uploads gpu_metrics_<X>/power_audit_<X> for agentic lanes, this viewer lights up with zero app changes).

---

Note

Medium Risk
Adds GitHub artifact downloads and JSON parsing on a live UI route; failures are guarded but wrong window alignment could mislead reviewers of benchmark power.

Overview
PowerX now surfaces formal benchmark power metadata alongside raw GPU traces: validity, measurement window, published vs viewer-recomputed average power, and chart shading for warmup vs measured regions.

GET /api/gpu-metrics optionally attaches a normalized power object per gpu_metrics_* artifact by reading same-suffix bmk_* / power_audit_* ZIPs (prefer agg row; fall back to validation sidecar when window bounds are missing). Sidecar failures are isolated so CSV-only responses stay unchanged.

The UI adds a reconciliation card (verdict, window, chip counts, published vs trapezoid recompute, delta bands) and extends the line chart with a measurement-window band, dashed bounds, and dimmed warmup/post regions that follow x-zoom.

New pure helpers live in power-audit-artifacts.ts and power-window.ts, with unit tests, route tests, a Cypress fixture, and three new e2e cases (full flow, window-less power, legacy without power).

^{Reviewed by Cursor Bugbot for commit ed6294c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
inferencemax-app	Ready	Preview	Aug 31, 2026 9:13pm

[github-actions]

Claude finished @edwingao28's task in 3m 32s —— View job

---

Review: PowerX window reconciliation — 🟢 LGTM

• Read the diff & new files
• Review artifact-mapping helpers (power-audit-artifacts.ts)
• Review window math (power-window.ts)
• Review API route changes
• Review chart + reconciliation UI
• Check CI status
• Runtime verification (localhost)
• Post findings

No blocking issues. This is a careful, well-tested change; the two prior review passes already caught and fixed the realistic failure modes (corrupt-epoch RangeError, provenance over-crediting, lost dim-overlay on deep zoom).

What I verified

• Runtime: /gpu-metrics renders cleanly with 0 console errors (feature gate open in this env). The new power block can't be exercised against a live run because the sidecar artifacts it reads don't exist in production yet (PLAN-06 pending) — which is exactly why the PR ships fixture-driven e2e (gpu-power.cy.ts) plus a legacy "no power key" degradation spec. Backward-compat render path confirmed intact.
• CI: Lint & Format ✅, Tests (Unit) ✅ (E2E still in progress at review time). Fold in the E2E result before merge.
• Math correctness: window bounds and trace samples are both compared in absolute UTC seconds (window.start_unix vs ms/1000), so the trapezoid recompute and the producer's per-device integration are on the same clock. Boundary interpolation (interpolatePower) is only ever called with clamped in-range boundaries (deviceStart ≥ samples[0], deviceEnd ≤ last), so no out-of-bounds destructure. ?? is used correctly around the falsy-but-valid power_valid: 0. formatWindowBound guards Date's representable range.
• Additive contract: a sidecar failure is caught per-artifact and can never break the CSV trace view; hasPowerContent gating keeps the sources footer and Tier-1→Tier-2 fallback honest.
• Tests present for all new lib/UI code (power-audit-artifacts.test.ts, power-window.test.ts, expanded route.test.ts, gpu-power.cy.ts) — no test-coverage gap.

Non-blocking observation (no action required)

• The chart's data path (GpuPowerChart.buildGroupedData) parses naive nvidia-smi timestamps with local new Date(), while window alignment (power-window.parseTimestampUtcMs) parses them as UTC. As the code comments correctly note, this only shifts every sample by a constant, so relative-seconds agree — except across a viewer-timezone DST boundary within a single trace, where the local offset isn't constant and the shaded band could sit off by up to the DST delta for post-transition samples. Impact is negligible (traces are minutes-long, never a crash), and the intersection-or-refuse design already documents the UTC-clock assumption as a residual risk. Flagging only for the record.

Nice work — the reconciliation panel, delta thresholds tied to the producer's tolerance, and the intersection-check-or-refuse alignment are all sound.
· feat/gpu-power-window-reconciliation

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit eb9868a. Configure here.}