wpd 2.0: planned user value

[jantimon]

Tracking issue for 2.0. 2.0 is a batch: every breaking change waits here and ships together, so users re-record baselines once. Non-breaking work keeps shipping as 1.x.

What 2.0 adds for users

1. --deep on heavy production pages (the 512MB ceiling goes away)

Today a --deep trace of a heavy page can exceed what one JSON string holds (~512MB); wpd refuses, so heavy pages are limited to one iteration. 2.0 moves the deep event log out of the recording into an indexed SQLite sidecar (Node's built-in node:sqlite, no new dependency):

• Deep logs of 4-10GB become normal, so multi-iteration --deep on real landing pages works.
• Drills (query get, query events, stored blame) become indexed lookups, not a full-file parse.
• The main recording stays digest-sized on every capture mode; agents keep reading it whole.
• JSON stays compatible where promised, at the query … --format json|toon verbs. A streaming NDJSON export covers plain-text interop.

Status: probed, design final. Measured on Node 24 / SQLite 3.50.4: RSS stays flat at 84-125MB while writing a 4-10GB index, where the current one-string format throws at ~478k events; drills drop from seconds to sub-millisecond (point lookup 0.13ms vs 2.4s, range 46ms vs 11s). Full probe: docs/dev/deep-log-storage.md; background: docs/dev/trace-buffer.md.

2. Small breaking cleanups riding the batch

• Rename the three *Provenance exported type names (GroupSpansProvenance and siblings). The word is gone from every doc and comment; the type names follow now that a breaking release ships anyway.
• Split usage errors onto exit code 2. Today exit 1 means a blown gate, a mistyped flag, and a missing file alike, so a caller gating on assert cannot tell a regression from a bad invocation. 2.0: 0 pass, 1 measured failure (gate fired, n/a FAIL, comparability refusal), 2 wrong invocation (unknown flag, missing argument, unreadable file). Contained in src/cli.ts's error paths plus commander's exitOverride.

3. Considered and declined

• Renaming routeLcp/routeCls/routeInpMs to the ecosystem's soft-nav names (web-vitals v6, Lighthouse 13.4, PSI). The route* names say what is measured, not which API measured it, so they stay; a README note mapping the two names will do. Joins the batch only if the ecosystem names harden against us. Background: docs/dev/navigation-and-lcp.md.

What 2.0 is not

No new measurement semantics: the trust tiers, refusal behavior, and comparability gates carry over unchanged. How every number is verified: docs/verification.md.

Migration (known today)

• Old recordings refuse to open with a re-record message (the schema-epoch rule, README: Stability and versioning); re-record stored baselines once after upgrading.
• CLI commands and flags: no removals planned.
• Raw-JSON consumers of the deep events[] array switch to the query verbs or the NDJSON export.
• Consumers importing the *Provenance type names update the imports; the shapes are unchanged.
• Scripts branching on exit == 1 treat exit 2 as a usage error; scripts branching on != 0 are unaffected.