feat(api): document measured-power contract and add powerValid filter | API：文档化实测功率契约并新增 powerValid 筛选参数 - #938
Conversation
…量：导出 POWER_METRIC_KEYS 功率契约指标键列表 Derives the full documented power surface (discriminators + MEASURED_POWER_METRIC_KEY_LIST) as one exported constant and spreads it into METRIC_KEYS, keeping set membership provably unchanged. The public API documentation layer types BenchmarkRow.metrics from this export.
…enchmarks | API：为 /api/v1/benchmarks 新增 powerValid 实测功率有效性筛选参数 Pure post-cache row filter (cache keys unchanged): 1 keeps validated rows, 0 keeps explicitly invalidated rows, any is the default identity (legacy rows included), and strictV2 additionally requires power_metric_schema_version == 2 (whole-deployment energy semantics). Named strictV2 rather than certified to avoid colliding with the UI tier's product meaning. Unknown values 400; the combination with view=calculator 400s because the calculator cache stores rows already trimmed past power_valid. Route digest bumped in the review ledger.
… | 文档：为 /api/v1/benchmarks 文档化实测功率契约 Types every POWER_METRIC_KEYS entry on the BenchmarkRow metrics schema (additionalProperties still admits non-power keys), reserves the forthcoming power_invalid_reasons / power_audit row fields from the cross-plan producer contract, documents the previously-undocumented view/sequence params plus the new powerValid param, adds a bilingual measured-power schema note (tri-state power_valid, schema-version-2 whole-deployment energy, workers[] relationship, strictV2-vs-UI divergence), and mirrors the parameter list in the stable contract ledger. Cypress asserts the note and param render on /api and /zh/api.
…00 | 文档：说明 powerValid=any 可与 view=calculator 组合的例外 Review finding: the route only rejects non-any powerValid with view=calculator, but the published copy claimed the combination is always invalid. Align the operation description, the powerValid param description, and the 400 response description (EN + ZH) with actual behavior.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Claude finished @edwingao28's task in 2m 46s —— View job Review complete — 🟢 LGTM
No blocking or warning issues found. This is a clean, backward-compatible, well-tested change. What I verified at runtime (dev server, real read-only DB)
The unknown-value 400 short-circuits before the DB query, and the calculator-combination rejection is correctly ordered after it (an unknown value beats the combination error). Filter is a pure post-cache pass with no cache-key changes, so no blob-cache fragmentation. Correctness notes
Test coverageStrong. New colocated Chinese copyAll six changed zh passages reviewed against their English sources — accurate and natural for the API-reference surface. No fidelity or naturalness findings; no maintainer escalation needed. NoteStacked PR — as the description states, this must land after #937 ( |
1 participant
Important
STACKED PR — base is
feat/etl-invalid-power-scrub(#937). That PR must merge first. This PR contains only the deltas on top of #937; do not merge it intomasterbefore #937 lands, and retarget tomasterafter #937 merges.What | 内容
Adds a typed, documented public-API measured-power contract plus a
powerValidrow filter onGET /api/v1/benchmarks. | 为公开 API 提供带类型、有文档的实测功率契约，并为GET /api/v1/benchmarks新增powerValid行筛选参数。POWER_METRIC_KEYSsingle source of truth (packages/constants/src/metric-keys.ts): the two contract discriminators (power_valid,power_metric_schema_version) plusMEASURED_POWER_METRIC_KEY_LIST(from fix(etl): strip measured power metrics at ingest when power_valid=0 | ETL：power_valid=0 时在摄取阶段剥离实测功耗指标 #937), spread intoMETRIC_KEYSso set membership is provably unchanged (test-asserted).api-documentation.ts):BenchmarkRow.metricsnow types all 15 power/energy/GPU-telemetry keys with descriptions whileadditionalProperties: numberstill admits every other key.power_invalid_reasons(string array) andpower_audit(8-field object, all optional) per the producer contract — the row-level power provenance change (feat/power-row-provenancein InferenceX, PR queued) emits these fields and InferenceX-app PR feat(power): ingest and expose power audit provenance / 功率：摄取并公开功耗审计溯源字段（power_invalid_reasons、power_audit） #939 ingests them — so feat(power): ingest and expose power audit provenance / 功率：摄取并公开功耗审计溯源字段（power_invalid_reasons、power_audit） #939's rollout does not invalidate the published schema.view+sequenceparams and the newpowerValidparam onlist-benchmarks.measured-powerschema note (tri-statepower_valid, schema-version-2 whole-deployment-energy semantics,workers[]relationship, reserved fields) rendered on/apiand/zh/api.src/lib/benchmark-power-validity.ts, pure post-cache):powerValid∈ {1,0,any,strictV2}, defaultany(identity — byte-identical to today).strictV2≡power_valid == 1 && power_metric_schema_version == 2. Unknown values → 400Unknown powerValid filter; combining withview=calculator→ 400 (that cache stores rows already trimmed pastpower_valid). Cache keys unchanged — no blob-cache fragmentation.stablePublicApiContracts.list-benchmarks.parametersextended in order; route digest recomputed.Design decision:
strictV2naming (UI-vs-API divergence) | 设计决策：strictV2 命名（界面与 API 的差异）The strict filter value is named
strictV2, notcertified: the product UI's "certified" tier is a display rule that also admits validated legacy rows without a schema version, which this filter excludes. Usingcertifiedin the API would give the same word two different meanings across surfaces. The divergence is documented in themeasured-powerschema note and thepowerValidparam description.certifiedis explicitly rejected by the parser (test-pinned) so it can never silently alias. | 严格筛选值命名为strictV2而非certified：产品界面的“认证”档位还会展示无 schema 版本的已验证旧行，而此筛选会排除它们。若 API 也用certified，同一词汇将在两个界面承载不同含义。该差异已写入measured-power说明与参数描述。Backward compatibility | 向后兼容
powerValid≡powerValid=any≡ today's behavior (explicit route test asserts identical output; all 17 pre-existing route tests unchanged and green).METRIC_KEYSmembership unchanged.Tests | 测试
packages/constantsbun run test:unit: 53 passed (incl. newPOWER_METRIC_KEYSassertions inmetric-keys.test.ts).packages/appbun run test:unit: 252 files / 4476 passed, including:api-route-catalog.test.ts(digest + parameter/status/error parity, bilingual completeness, OpenAPI projection parity)route.test.ts(17 existing + 8 new filter/400/compat cases)benchmark-power-validity.test.ts,api-documentation.power.test.tspackages/dbbun run test:unit: 609 passed (no coupling).api-documentation.cy.ts(fixtures mode): 1/1 passed —/api,/zh/api, andopenapi.jsonexpose the new contract.anyresponses byte-identical.Review notes | 评审说明
powerValid"cannot be combined with view=calculator" without theanyexception, while the route acceptspowerValid=any&view=calculator(200, no-op filter). Resolved in 0e691a4: the operation description, thepowerValidparam description, and the 400 response description now state the exception (EN + ZH). The docs are no longer stricter than actual behavior. | 文档此前称powerValid不能与view=calculator组合，但未提及any例外（路由接受powerValid=any&view=calculator并返回 200）。已在 0e691a4 修复：操作描述、参数描述与 400 响应描述均已注明该例外（中英双语）。No other findings.
Rollback | 回滚
Revert this PR. No migrations, no cache-key changes, no data writes.
Note
Medium Risk
Extends a stable public read API with new optional parameters and response filtering semantics; backward compatible by default but clients relying on full row sets may be affected if they adopt strict filters.
Overview
Adds a documented measured-power contract and optional
powerValidquery parameter onGET /api/v1/benchmarks, with default behavior unchanged when the param is omitted (any).POWER_METRIC_KEYSin constants centralizes the 15 typed power/energy/telemetry metric keys for OpenAPI and docs.BenchmarkRownow documents those keys onmetrics, reserves optionalpower_invalid_reasonsandpower_audit, and adds a bilingual Measured power schema note.view,sequence, andpowerValidare formally documented onlist-benchmarks.The route applies a post-cache filter (
1,0,any,strictV2) viabenchmark-power-validity. Unknown values return 400; non-anypowerValidcannot combine withview=calculator(calculator cache stripspower_valid).strictV2is documented as stricter than the UI “certified” tier;certifiedis rejected as a param value.Tests cover filtering, validation, OpenAPI parity, Cypress on
/apiand/zh/api, and the route catalog digest/parameters update.Reviewed by Cursor Bugbot for commit c848016. Bugbot is set up for automated code reviews on this repo. Configure here.