Define the performance measurement and value attribution contract

Summary

Define how Perform will report baseline, before/after, and ongoing optimization value without mixing local diagnostics, lab snapshots, and real-user field data.

This design-first issue is the measurement contract for 2.0.0. It prevents unsupported savings claims and gives the dashboard, onboarding, optimization history, and future reports one source of truth.

Measurement lanes

1. Local facts — configuration, cache counters, inventory, stored sizes, cleanup counts, and measured execution facts available inside WordPress.
2. Lab snapshots — repeatable synthetic tests for selected public URLs, with environment, run count, cache state, device profile, variance, and timestamp.
3. Field data — real-user metrics only when a valid source is available and the owner explicitly opts in to any external integration.

Required model

• Metric name, source, scope, unit, collection time, sample/window, cache state, and confidence.
• Baseline and comparison identifiers.
• Optimization events applied between measurements.
• Missing, stale, ineligible, partial, and failed states.
• Copy rules that prohibit converting proxies or estimates into Core Web Vitals claims.
• Bounded retention, redaction, export, and deletion behavior.

Acceptance criteria

• A technical design defines the three measurement lanes and which metrics belong in each.
• Lab and field data are labeled distinctly in UI and exported data.
• The model cannot present immediate lab results as real-user Core Web Vitals.
• Unsupported metrics show why they are unavailable instead of a synthetic score.
• Before/after comparisons require compatible URL, environment, device profile, cache state, and measurement source.
• Every displayed value includes provenance and freshness.
• Automatic and manual Perform changes can be correlated through #179 without storing sensitive values.
• Privacy, consent, retention, failure, and deletion behavior are documented.
• Tests cover stale data, missing field eligibility, incompatible comparisons, partial runs, outliers, and redaction.

Validation and proof

• Approved schema examples for local, lab, and field records.
• Copy review for every unavailable and confidence state.
• Fixture-backed dashboard and report screenshots.
• Privacy/security review before any external integration.
• Reproducibility note showing how a comparison can be independently checked.

Dependencies

• #178 consumes the contract for dashboard summaries.
• #179 supplies the optimization event timeline.
• #144 implements the lab snapshot workflow after this contract is approved.
• #140 and #180 supply local database facts.
• #214 supplies site context.
• Any field-data integration requires a separate issue and explicit owner approval.

Non-goals

• Inventing a universal performance score.
• Promising traffic, ranking, revenue, or Core Web Vitals improvement.
• Uploading site data by default.
• Treating total blocking time as a measured interaction-to-next-paint value.
• Shipping an external measurement service in this issue.

Target and decision

• Target release: 2.0.0 trustworthy measurement and value reporting.
• Implementation base: release/2.0.0.
• Owner decision needed: approve the measurement contract before implementation of #144 or any value-reporting UI.