Data verification reference

Verification states

Every entity (model, provider, comparison, observation, pricing tier) declares a verificationStatus drawn from a fixed enum:

Lifecycle status (active, preview, deprecated, retired) is a separate field; a model may be verified and retired at the same time.

SourceType allow-list

Citations carry a type field drawn from a closed union:

Blog posts, social posts, leaderboard pages, and AI-generated summaries are not on the allow-list. The constructor at lib/verified.ts rejects any citation whose URL is not absolute and rejects any field without a non-empty name and retrievedAt.

VerifiedField and MaybeVerified

type SourceType =
  | 'official-vendor-docs'
  | 'official-vendor-pricing'
  | 'official-vendor-site'
  | 'regulatory-filing'
  | 'research-paper'
  | 'public-dataset'
  | 'unknown';

interface SourceCitation {
  url: string;            // absolute URL
  name: string;
  type: SourceType;
  retrievedAt: string;    // ISO-8601 datetime
  notes?: string;
}

interface VerifiedField<T> {
  value: T;
  citation: SourceCitation;
  confidenceLevel: 'high' | 'medium' | 'low' | 'unverified';
  notes?: string;
}

type MaybeVerified<T> = VerifiedField<T> | null;

Metric fields on entities are typed MaybeVerified<T>. The type system blocks unsourced rendering: a renderer cannot access field.value without first calling the isVerified() type guard.

Citation requirements

• url — must be absolute (^https?:\/\/); the citation helper rejects relative URLs at module load.
• retrievedAt — ISO-8601 datetime documenting when the page was visually inspected or fetched successfully. Not the commit time.
• type — one of the allow-listed source types above.
• notes — free text describing what specifically was used from the source page. Recommended; not required.

The canonical unverified-data label

A single phrase is the platform-wide unverified-data label — rendered through the <DataNotVerified /> component and exported from lib/verified.ts as the UNVERIFIED_LABEL constant. It appears like this when a metric is unverified: Data not yet verified.. The literal string may not appear elsewhere in the codebase — an integrity guard refuses to ship a build that duplicates it outside the renderer, the constant declaration, and the policy docs.

Freshness lifecycle and reverification

Verification is a moment-in-time act. Sprint 21 added a source-freshness layer that pairs every verified record with a freshness state computed deterministically against siteConfig.buildDate.

• Fresh — checked recently (standard cadence: within 30 days; pricing cadence: within 14 days).
• Review due — past the fresh window but within the stale window. The value is still considered verified for rendering; a manual reviewer is suggested.
• Stale — past the stale window. Still not asserted as false; the queue marks it for a mandatory manual re-check before reuse on a new surface.
• Blocked — a vendor URL that returned 403/401/429/JS-required to automated retrieval. The reverification queue retries every SOURCE_FRESHNESS_DAYS.blockedRetry days against a manual browser pass.
• Unknown — no timestamp on record.

Reverification policy. The catalogue does not automatically scrape sources. It does not mutate verified values in the background. It does not publish unreviewed fetched data. The /reverification queue (and machine-readable /api/reverification) lists every record due for a manual re-check, the source URL, and a suggested action. The reviewer confirms the value against the vendor's own page, updates retrievedAt or lastCheckedAt with the date of the manual review, and re-runs the integrity guards.

Stale is not false. A row marked stale is a row whose source has not been confirmed for longer than the window allows — it is not a claim the value is wrong. The renderer keeps showing it (the value was verified at the time) but pairs it with a chip so any reader can see how recently it was last checked.

Allowed vs disallowed content

Allowed. Verified metric rendering through VerifiedField. Methodology and educational content (like the page you are reading). Source-aware comparison tables. The canonical unverified-data label for any unverified metric.

Disallowed. Estimated, averaged, or interpolated values rendered as if verified. Provider-reported claims rendered as model properties (rather than as cited statements). Benchmark scores without a primary-source citation. Uptime percentages without durable observations. Latency numbers without a measurement harness. "Best model" rankings of any kind. See comparison methodology for the no-winner discipline as it applies to /compare.