Run the audit from your own product.

TypeScript

// pagespeed-audit findings document v1 — generated from /docs/findings.schema.json. Do not edit by hand.
// Join runs on run.url + run.date + run.strategy; join findings across runs on findings[].slug, never on findings[].id.

export interface AdjudicationCounts {
  confirmed: number;
  false_positive: number;
  deprioritized: number;
  platform_blocked: number;
  readout: number;
}

export interface RunInfo {
  run_id: string;
  generated_at: string;
  skill_version: string;
  site: string;
  url: string;
  final_url?: string | null;
  strategy: "mobile" | "desktop";
  date: string;
  lighthouse_version?: string | null;
  data_sources?: string[];
  field_available: boolean;
  binding_constraint: string;
  missing_from_psi?: string | null;
  adjudication_counts: AdjudicationCounts;
  /** Public naming layer applied to this run's report, e.g. 'noise-silence/four-verdicts@1' (Real=confirmed, Wrong=false_positive, Trivial=deprioritized, Locked=platform_blocked) */
  framework?: string;
  /** Noise & Silence framework: (false_positive + deprioritized + platform_blocked) / adjudicated flags, readout excluded */
  noise_rate?: number | null;
}

export interface MetricRow {
  metric: "LCP" | "INP" | "CLS" | "FCP" | "TTFB";
  source: "field_page" | "field_origin" | "lab";
  value: number | null;
  unit?: "ms" | "";
  category?: string | null;
  good?: number | null;
  poor?: number | null;
}

export interface HistoryRow {
  date: string;
  metric: "LCP" | "INP" | "CLS" | "FCP" | "TTFB";
  p75: number | null;
  unit?: "ms" | "";
}

export interface QuickFix {
  lang?: string;
  code?: string;
  note?: string;
}

export interface Adjudication {
  audit_id: string;
  disposition: "confirmed" | "false_positive" | "deprioritized" | "platform_blocked" | "readout";
  claim: string;
  evidence: string;
  finding_ref?: string | null;
  metric_savings?: Record<string, unknown> | null;
  has_quick_fix?: boolean;
  fix?: QuickFix | null;
}

export interface Coupling {
  finding: string;
  kind: "invalidates" | "invalidated_by" | "depends_on" | "required_by" | "co-requisite" | "interacts";
  note?: string | null;
  /** true = generated from the other finding's declaration, not authored here */
  mirrored?: boolean;
}

export interface FindingFix {
  lang?: string;
  before?: string | null;
  after?: string;
  note?: string | null;
}

export interface Impact {
  narrative: string;
  arithmetic?: string | null;
  metric?: "LCP" | "INP" | "CLS" | "FCP" | "TTFB" | null;
  unit?: "ms" | "" | null;
  min?: number | null;
  max?: number | null;
  direction?: "decrease" | "increase" | null;
  confidence?: "HIGH" | "MEDIUM-HIGH" | "MEDIUM" | "LOW" | null;
}

export interface Finding {
  /** Positional in-report anchor, re-assigned every run (F1, F2, …) and the target of adjudications[].finding_ref. NOT stable across runs — never join on it. Use slug for that. */
  id: string;
  /** Stable cross-run identifier for the PROBLEM CLASS, not the wording: the same underlying problem on the same site produces the same slug in every future audit, even when title, prose, severity or measured numbers change. Never encodes run-specific data (no values, dates, run numbers, ordering, Lighthouse version). Unique within a run; a class that legitimately recurs is disambiguated with a stable discriminator derived from the resource itself, e.g. 'render-blocking-css:fonts.googleapis.com' — never a positional counter. Join findings across runs on run.url (or run.final_url) + findings[].slug. Authoring vocabulary and the fallback rule live in SKILL.md. */
  slug: string;
  title: string;
  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
  confidence: "HIGH" | "MEDIUM-HIGH" | "MEDIUM" | "LOW";
  effort?: string | null;
  tags?: string[];
  evidence?: string;
  /** What the defect was VERIFIED to affect, in the words of what was tested: 'origin-wide (verified on / /pricing /blog)' or 'this route only (tested / only)'. Never an inference from a single route. */
  scope?: string | null;
  /** Human-readable falsification note. When the graded arrays below are present this is their flattened rendering ('Measured: … | Reasoned (inference): … | Verify before shipping: …'), so a v1 consumer that only reads this field keeps working. */
  falsification?: string | null;
  /** Claims the audit OBSERVED — header, byte count, snippet, response. Optional; added additively to @1. */
  falsification_measured?: string[] | null;
  /** Claims the audit INFERRED from those observations. Presenting an inference as a confirmed check overstates the evidence grade, so the two are carried apart. Optional; added additively to @1. */
  falsification_reasoned?: string[] | null;
  /** The concrete test that settles a reasoned inference. REQUIRED (validate_findings) whenever falsification_reasoned is non-empty on a finding that ships a fix. */
  verify_before_shipping?: string | null;
  /** Interactions with other findings in this run: one finding's fix changing a precondition another rests on, a prerequisite, or a co-requisite. Mirrored onto the other finding by the renderer and re-checked for symmetry by validate_findings — an interaction stated on only one side is an error. Optional; added additively to @1. */
  coupling?: Coupling[] | null;
  chain?: string | null;
  fix?: FindingFix | null;
  impact: Impact;
  sequencing?: string | null;
  /** Noise & Silence: true = platform-owned / outside operator control. A locked finding carries NO fix; the renderer shows the redirect instead, and validate_findings rejects a locked finding that has a fix. */
  locked?: boolean | null;
  /** For a locked finding: the controllable equivalent (merchant-side lever) or an explicit stop-trying note shown in place of a fix. */
  redirect?: string | null;
}

export interface Deliverable {
  title: string;
  lang?: string;
  code: string;
}

export interface DoneWellItem {
  item: string;
  evidence?: string | null;
}

export interface PlanItem {
  bucket: "today" | "sprint" | "architectural";
  position: number;
  item: string;
}

/** Machine-readable twin of the audit report. Long-form arrays (metrics, history, adjudications, findings, plan) map 1:1 onto SQL tables; join runs on run.url + run.date + run.strategy, join flags across runs on adjudications[].audit_id (stable Lighthouse IDs), and join findings across runs on findings[].slug (stable problem-class ID; findings[].id is positional and re-assigned every run). */
export interface FindingsDocument {
  schema: "pagespeed-audit/findings@1";
  run: RunInfo;
  metrics: MetricRow[];
  history?: HistoryRow[];
  adjudications: Adjudication[];
  findings: Finding[];
  deliverables?: Deliverable[];
  done_well?: DoneWellItem[];
  plan?: PlanItem[];
}

C#

// pagespeed-audit findings document v1 — generated from /docs/findings.schema.json. Do not edit by hand.
// Deserialize with System.Text.Json: JsonSerializer.Deserialize<FindingsDocument>(json).
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace PageSpeedAudit.Findings;

public sealed record AdjudicationCounts
{
    [JsonPropertyName("confirmed")]
    public required int Confirmed { get; init; }
    [JsonPropertyName("false_positive")]
    public required int FalsePositive { get; init; }
    [JsonPropertyName("deprioritized")]
    public required int Deprioritized { get; init; }
    [JsonPropertyName("platform_blocked")]
    public required int PlatformBlocked { get; init; }
    [JsonPropertyName("readout")]
    public required int Readout { get; init; }
}

public sealed record RunInfo
{
    [JsonPropertyName("run_id")]
    public required string RunId { get; init; }
    [JsonPropertyName("generated_at")]
    public required string GeneratedAt { get; init; }
    [JsonPropertyName("skill_version")]
    public required string SkillVersion { get; init; }
    [JsonPropertyName("site")]
    public required string Site { get; init; }
    [JsonPropertyName("url")]
    public required string Url { get; init; }
    [JsonPropertyName("final_url")]
    public string? FinalUrl { get; init; }
    /// <remarks>One of: "mobile", "desktop".</remarks>
    [JsonPropertyName("strategy")]
    public required string Strategy { get; init; }
    [JsonPropertyName("date")]
    public required string Date { get; init; }
    [JsonPropertyName("lighthouse_version")]
    public string? LighthouseVersion { get; init; }
    [JsonPropertyName("data_sources")]
    public IReadOnlyList<string>? DataSources { get; init; }
    [JsonPropertyName("field_available")]
    public required bool FieldAvailable { get; init; }
    [JsonPropertyName("binding_constraint")]
    public required string BindingConstraint { get; init; }
    [JsonPropertyName("missing_from_psi")]
    public string? MissingFromPsi { get; init; }
    [JsonPropertyName("adjudication_counts")]
    public required AdjudicationCounts AdjudicationCounts { get; init; }
    /// <summary>Public naming layer applied to this run's report, e.g. 'noise-silence/four-verdicts@1' (Real=confirmed, Wrong=false_positive, Trivial=deprioritized, Locked=platform_blocked)</summary>
    [JsonPropertyName("framework")]
    public string? Framework { get; init; }
    /// <summary>Noise &amp; Silence framework: (false_positive + deprioritized + platform_blocked) / adjudicated flags, readout excluded</summary>
    [JsonPropertyName("noise_rate")]
    public double? NoiseRate { get; init; }
}

public sealed record MetricRow
{
    /// <remarks>One of: "LCP", "INP", "CLS", "FCP", "TTFB".</remarks>
    [JsonPropertyName("metric")]
    public required string Metric { get; init; }
    /// <remarks>One of: "field_page", "field_origin", "lab".</remarks>
    [JsonPropertyName("source")]
    public required string Source { get; init; }
    [JsonPropertyName("value")]
    public required double? Value { get; init; }
    /// <remarks>One of: "ms", "".</remarks>
    [JsonPropertyName("unit")]
    public string? Unit { get; init; }
    [JsonPropertyName("category")]
    public string? Category { get; init; }
    [JsonPropertyName("good")]
    public double? Good { get; init; }
    [JsonPropertyName("poor")]
    public double? Poor { get; init; }
}

public sealed record HistoryRow
{
    [JsonPropertyName("date")]
    public required string Date { get; init; }
    /// <remarks>One of: "LCP", "INP", "CLS", "FCP", "TTFB".</remarks>
    [JsonPropertyName("metric")]
    public required string Metric { get; init; }
    [JsonPropertyName("p75")]
    public required double? P75 { get; init; }
    /// <remarks>One of: "ms", "".</remarks>
    [JsonPropertyName("unit")]
    public string? Unit { get; init; }
}

public sealed record QuickFix
{
    [JsonPropertyName("lang")]
    public string? Lang { get; init; }
    [JsonPropertyName("code")]
    public string? Code { get; init; }
    [JsonPropertyName("note")]
    public string? Note { get; init; }
}

public sealed record Adjudication
{
    [JsonPropertyName("audit_id")]
    public required string AuditId { get; init; }
    /// <remarks>One of: "confirmed", "false_positive", "deprioritized", "platform_blocked", "readout".</remarks>
    [JsonPropertyName("disposition")]
    public required string Disposition { get; init; }
    [JsonPropertyName("claim")]
    public required string Claim { get; init; }
    [JsonPropertyName("evidence")]
    public required string Evidence { get; init; }
    [JsonPropertyName("finding_ref")]
    public string? FindingRef { get; init; }
    [JsonPropertyName("metric_savings")]
    public JsonElement? MetricSavings { get; init; }
    [JsonPropertyName("has_quick_fix")]
    public bool? HasQuickFix { get; init; }
    [JsonPropertyName("fix")]
    public QuickFix? Fix { get; init; }
}

public sealed record Coupling
{
    [JsonPropertyName("finding")]
    public required string Finding { get; init; }
    /// <remarks>One of: "invalidates", "invalidated_by", "depends_on", "required_by", "co-requisite", "interacts".</remarks>
    [JsonPropertyName("kind")]
    public required string Kind { get; init; }
    [JsonPropertyName("note")]
    public string? Note { get; init; }
    /// <summary>true = generated from the other finding's declaration, not authored here</summary>
    [JsonPropertyName("mirrored")]
    public bool? Mirrored { get; init; }
}

public sealed record FindingFix
{
    [JsonPropertyName("lang")]
    public string? Lang { get; init; }
    [JsonPropertyName("before")]
    public string? Before { get; init; }
    [JsonPropertyName("after")]
    public string? After { get; init; }
    [JsonPropertyName("note")]
    public string? Note { get; init; }
}

public sealed record Impact
{
    [JsonPropertyName("narrative")]
    public required string Narrative { get; init; }
    [JsonPropertyName("arithmetic")]
    public string? Arithmetic { get; init; }
    /// <remarks>One of: "LCP", "INP", "CLS", "FCP", "TTFB".</remarks>
    [JsonPropertyName("metric")]
    public string? Metric { get; init; }
    /// <remarks>One of: "ms", "".</remarks>
    [JsonPropertyName("unit")]
    public string? Unit { get; init; }
    [JsonPropertyName("min")]
    public double? Min { get; init; }
    [JsonPropertyName("max")]
    public double? Max { get; init; }
    /// <remarks>One of: "decrease", "increase".</remarks>
    [JsonPropertyName("direction")]
    public string? Direction { get; init; }
    /// <remarks>One of: "HIGH", "MEDIUM-HIGH", "MEDIUM", "LOW".</remarks>
    [JsonPropertyName("confidence")]
    public string? Confidence { get; init; }
}

public sealed record Finding
{
    /// <summary>Positional in-report anchor, re-assigned every run (F1, F2, …) and the target of adjudications[].finding_ref. NOT stable across runs — never join on it. Use slug for that.</summary>
    [JsonPropertyName("id")]
    public required string Id { get; init; }
    /// <summary>Stable cross-run identifier for the PROBLEM CLASS, not the wording: the same underlying problem on the same site produces the same slug in every future audit, even when title, prose, severity or measured numbers change. Never encodes run-specific data (no values, dates, run numbers, ordering, Lighthouse version). Unique within a run; a class that legitimately recurs is disambiguated with a stable discriminator derived from the resource itself, e.g. 'render-blocking-css:fonts.googleapis.com' — never a positional counter. Join findings across runs on run.url (or run.final_url) + findings[].slug. Authoring vocabulary and the fallback rule live in SKILL.md.</summary>
    [JsonPropertyName("slug")]
    public required string Slug { get; init; }
    [JsonPropertyName("title")]
    public required string Title { get; init; }
    /// <remarks>One of: "CRITICAL", "HIGH", "MEDIUM", "LOW".</remarks>
    [JsonPropertyName("severity")]
    public required string Severity { get; init; }
    /// <remarks>One of: "HIGH", "MEDIUM-HIGH", "MEDIUM", "LOW".</remarks>
    [JsonPropertyName("confidence")]
    public required string Confidence { get; init; }
    [JsonPropertyName("effort")]
    public string? Effort { get; init; }
    [JsonPropertyName("tags")]
    public IReadOnlyList<string>? Tags { get; init; }
    [JsonPropertyName("evidence")]
    public string? Evidence { get; init; }
    /// <summary>What the defect was VERIFIED to affect, in the words of what was tested: 'origin-wide (verified on / /pricing /blog)' or 'this route only (tested / only)'. Never an inference from a single route.</summary>
    [JsonPropertyName("scope")]
    public string? Scope { get; init; }
    /// <summary>Human-readable falsification note. When the graded arrays below are present this is their flattened rendering ('Measured: … | Reasoned (inference): … | Verify before shipping: …'), so a v1 consumer that only reads this field keeps working.</summary>
    [JsonPropertyName("falsification")]
    public string? Falsification { get; init; }
    /// <summary>Claims the audit OBSERVED — header, byte count, snippet, response. Optional; added additively to @1.</summary>
    [JsonPropertyName("falsification_measured")]
    public IReadOnlyList<string>? FalsificationMeasured { get; init; }
    /// <summary>Claims the audit INFERRED from those observations. Presenting an inference as a confirmed check overstates the evidence grade, so the two are carried apart. Optional; added additively to @1.</summary>
    [JsonPropertyName("falsification_reasoned")]
    public IReadOnlyList<string>? FalsificationReasoned { get; init; }
    /// <summary>The concrete test that settles a reasoned inference. REQUIRED (validate_findings) whenever falsification_reasoned is non-empty on a finding that ships a fix.</summary>
    [JsonPropertyName("verify_before_shipping")]
    public string? VerifyBeforeShipping { get; init; }
    /// <summary>Interactions with other findings in this run: one finding's fix changing a precondition another rests on, a prerequisite, or a co-requisite. Mirrored onto the other finding by the renderer and re-checked for symmetry by validate_findings — an interaction stated on only one side is an error. Optional; added additively to @1.</summary>
    [JsonPropertyName("coupling")]
    public IReadOnlyList<Coupling>? Coupling { get; init; }
    [JsonPropertyName("chain")]
    public string? Chain { get; init; }
    [JsonPropertyName("fix")]
    public FindingFix? Fix { get; init; }
    [JsonPropertyName("impact")]
    public required Impact Impact { get; init; }
    [JsonPropertyName("sequencing")]
    public string? Sequencing { get; init; }
    /// <summary>Noise &amp; Silence: true = platform-owned / outside operator control. A locked finding carries NO fix; the renderer shows the redirect instead, and validate_findings rejects a locked finding that has a fix.</summary>
    [JsonPropertyName("locked")]
    public bool? Locked { get; init; }
    /// <summary>For a locked finding: the controllable equivalent (merchant-side lever) or an explicit stop-trying note shown in place of a fix.</summary>
    [JsonPropertyName("redirect")]
    public string? Redirect { get; init; }
}

public sealed record Deliverable
{
    [JsonPropertyName("title")]
    public required string Title { get; init; }
    [JsonPropertyName("lang")]
    public string? Lang { get; init; }
    [JsonPropertyName("code")]
    public required string Code { get; init; }
}

public sealed record DoneWellItem
{
    [JsonPropertyName("item")]
    public required string Item { get; init; }
    [JsonPropertyName("evidence")]
    public string? Evidence { get; init; }
}

public sealed record PlanItem
{
    /// <remarks>One of: "today", "sprint", "architectural".</remarks>
    [JsonPropertyName("bucket")]
    public required string Bucket { get; init; }
    [JsonPropertyName("position")]
    public required int Position { get; init; }
    [JsonPropertyName("item")]
    public required string Item { get; init; }
}

/// <summary>Machine-readable twin of the audit report. Long-form arrays (metrics, history, adjudications, findings, plan) map 1:1 onto SQL tables; join runs on run.url + run.date + run.strategy, join flags across runs on adjudications[].audit_id (stable Lighthouse IDs), and join findings across runs on findings[].slug (stable problem-class ID; findings[].id is positional and re-assigned every run).</summary>
public sealed record FindingsDocument
{
    [JsonPropertyName("schema")]
    public required string Schema { get; init; }
    [JsonPropertyName("run")]
    public required RunInfo Run { get; init; }
    [JsonPropertyName("metrics")]
    public required IReadOnlyList<MetricRow> Metrics { get; init; }
    [JsonPropertyName("history")]
    public IReadOnlyList<HistoryRow>? History { get; init; }
    [JsonPropertyName("adjudications")]
    public required IReadOnlyList<Adjudication> Adjudications { get; init; }
    [JsonPropertyName("findings")]
    public required IReadOnlyList<Finding> Findings { get; init; }
    [JsonPropertyName("deliverables")]
    public IReadOnlyList<Deliverable>? Deliverables { get; init; }
    [JsonPropertyName("done_well")]
    public IReadOnlyList<DoneWellItem>? DoneWell { get; init; }
    [JsonPropertyName("plan")]
    public IReadOnlyList<PlanItem>? Plan { get; init; }
}

Python

# pagespeed-audit findings document v1 — generated from /docs/findings.schema.json. Do not edit by hand.
# Load with json.load(); the TypedDicts describe the shape for type checkers.
# Python 3.11+ (NotRequired); on older versions import NotRequired and TypedDict from typing_extensions.
from __future__ import annotations

from typing import Any, Literal, NotRequired, TypedDict

class AdjudicationCounts(TypedDict):
    confirmed: int
    false_positive: int
    deprioritized: int
    platform_blocked: int
    readout: int


class RunInfo(TypedDict):
    run_id: str
    generated_at: str
    skill_version: str
    site: str
    url: str
    final_url: NotRequired[str | None]
    strategy: Literal["mobile", "desktop"]
    date: str
    lighthouse_version: NotRequired[str | None]
    data_sources: NotRequired[list[str]]
    field_available: bool
    binding_constraint: str
    missing_from_psi: NotRequired[str | None]
    adjudication_counts: AdjudicationCounts
    # Public naming layer applied to this run's report, e.g. 'noise-silence/four-verdicts@1' (Real=confirmed, Wrong=false_positive, Trivial=deprioritized, Locked=platform_blocked)
    framework: NotRequired[str]
    # Noise & Silence framework: (false_positive + deprioritized + platform_blocked) / adjudicated flags, readout excluded
    noise_rate: NotRequired[float | None]


class MetricRow(TypedDict):
    metric: Literal["LCP", "INP", "CLS", "FCP", "TTFB"]
    source: Literal["field_page", "field_origin", "lab"]
    value: float | None
    unit: NotRequired[Literal["ms", ""]]
    category: NotRequired[str | None]
    good: NotRequired[float | None]
    poor: NotRequired[float | None]


class HistoryRow(TypedDict):
    date: str
    metric: Literal["LCP", "INP", "CLS", "FCP", "TTFB"]
    p75: float | None
    unit: NotRequired[Literal["ms", ""]]


class QuickFix(TypedDict):
    lang: NotRequired[str]
    code: NotRequired[str]
    note: NotRequired[str]


class Adjudication(TypedDict):
    audit_id: str
    disposition: Literal["confirmed", "false_positive", "deprioritized", "platform_blocked", "readout"]
    claim: str
    evidence: str
    finding_ref: NotRequired[str | None]
    metric_savings: NotRequired[dict[str, Any] | None]
    has_quick_fix: NotRequired[bool]
    fix: NotRequired[QuickFix | None]


class Coupling(TypedDict):
    finding: str
    kind: Literal["invalidates", "invalidated_by", "depends_on", "required_by", "co-requisite", "interacts"]
    note: NotRequired[str | None]
    # true = generated from the other finding's declaration, not authored here
    mirrored: NotRequired[bool]


class FindingFix(TypedDict):
    lang: NotRequired[str]
    before: NotRequired[str | None]
    after: NotRequired[str]
    note: NotRequired[str | None]


class Impact(TypedDict):
    narrative: str
    arithmetic: NotRequired[str | None]
    metric: NotRequired[Literal["LCP", "INP", "CLS", "FCP", "TTFB"] | None]
    unit: NotRequired[Literal["ms", ""] | None]
    min: NotRequired[float | None]
    max: NotRequired[float | None]
    direction: NotRequired[Literal["decrease", "increase"] | None]
    confidence: NotRequired[Literal["HIGH", "MEDIUM-HIGH", "MEDIUM", "LOW"] | None]


class Finding(TypedDict):
    # Positional in-report anchor, re-assigned every run (F1, F2, …) and the target of adjudications[].finding_ref. NOT stable across runs — never join on it. Use slug for that.
    id: str
    # Stable cross-run identifier for the PROBLEM CLASS, not the wording: the same underlying problem on the same site produces the same slug in every future audit, even when title, prose, severity or measured numbers change. Never encodes run-specific data (no values, dates, run numbers, ordering, Lighthouse version). Unique within a run; a class that legitimately recurs is disambiguated with a stable discriminator derived from the resource itself, e.g. 'render-blocking-css:fonts.googleapis.com' — never a positional counter. Join findings across runs on run.url (or run.final_url) + findings[].slug. Authoring vocabulary and the fallback rule live in SKILL.md.
    slug: str
    title: str
    severity: Literal["CRITICAL", "HIGH", "MEDIUM", "LOW"]
    confidence: Literal["HIGH", "MEDIUM-HIGH", "MEDIUM", "LOW"]
    effort: NotRequired[str | None]
    tags: NotRequired[list[str]]
    evidence: NotRequired[str]
    # What the defect was VERIFIED to affect, in the words of what was tested: 'origin-wide (verified on / /pricing /blog)' or 'this route only (tested / only)'. Never an inference from a single route.
    scope: NotRequired[str | None]
    # Human-readable falsification note. When the graded arrays below are present this is their flattened rendering ('Measured: … | Reasoned (inference): … | Verify before shipping: …'), so a v1 consumer that only reads this field keeps working.
    falsification: NotRequired[str | None]
    # Claims the audit OBSERVED — header, byte count, snippet, response. Optional; added additively to @1.
    falsification_measured: NotRequired[list[str] | None]
    # Claims the audit INFERRED from those observations. Presenting an inference as a confirmed check overstates the evidence grade, so the two are carried apart. Optional; added additively to @1.
    falsification_reasoned: NotRequired[list[str] | None]
    # The concrete test that settles a reasoned inference. REQUIRED (validate_findings) whenever falsification_reasoned is non-empty on a finding that ships a fix.
    verify_before_shipping: NotRequired[str | None]
    # Interactions with other findings in this run: one finding's fix changing a precondition another rests on, a prerequisite, or a co-requisite. Mirrored onto the other finding by the renderer and re-checked for symmetry by validate_findings — an interaction stated on only one side is an error. Optional; added additively to @1.
    coupling: NotRequired[list[Coupling] | None]
    chain: NotRequired[str | None]
    fix: NotRequired[FindingFix | None]
    impact: Impact
    sequencing: NotRequired[str | None]
    # Noise & Silence: true = platform-owned / outside operator control. A locked finding carries NO fix; the renderer shows the redirect instead, and validate_findings rejects a locked finding that has a fix.
    locked: NotRequired[bool | None]
    # For a locked finding: the controllable equivalent (merchant-side lever) or an explicit stop-trying note shown in place of a fix.
    redirect: NotRequired[str | None]


class Deliverable(TypedDict):
    title: str
    lang: NotRequired[str]
    code: str


class DoneWellItem(TypedDict):
    item: str
    evidence: NotRequired[str | None]


class PlanItem(TypedDict):
    bucket: Literal["today", "sprint", "architectural"]
    position: int
    item: str


class FindingsDocument(TypedDict):
    """Machine-readable twin of the audit report. Long-form arrays (metrics, history, adjudications, findings, plan) map 1:1 onto SQL tables; join runs on run.url + run.date + run.strategy, join flags across runs on adjudications[].audit_id (stable Lighthouse IDs), and join findings across runs on findings[].slug (stable problem-class ID; findings[].id is positional and re-assigned every run)."""

    schema: Literal["pagespeed-audit/findings@1"]
    run: RunInfo
    metrics: list[MetricRow]
    history: NotRequired[list[HistoryRow]]
    adjudications: list[Adjudication]
    findings: list[Finding]
    deliverables: NotRequired[list[Deliverable]]
    done_well: NotRequired[list[DoneWellItem]]
    plan: NotRequired[list[PlanItem]]