docs(desktop): define performance cutover contracts

[wesbillman]

Summary

• define the desktop performance rearchitecture contracts for native relay ownership, replica coverage/migrations/outbox/crash recovery, projections/deltas, and the single scroll owner
• establish merge-safe, release-safe, and cutover-safe gates plus the sequenced M0-M6 delivery plan
• add a fail-closed packaged WKWebView acceptance foundation with an immutable Nostr fixture, strict provenance schemas, native-driver launch seam, and percentile reporting

Scope

This is additive documentation and test tooling only. It changes no production relay ownership, replica persistence, renderer deltas, timeline routing, or authoritative reads. Chromium performance evidence remains diagnostic; it cannot stand in for shipped WKWebView acceptance evidence.

The executable materializer produces 8,740 deterministically ordered Nostr events (4,255,320 bytes, SHA-256 ac948604f0100b93ce9d6f143b7160b6cd7f1389e1be407ed15fc45dca72edca). The harness binds runs to the caller-supplied packaged .app, Info.plist, captured package/host state, immutable fixture, and exact native-driver bytes. Missing native automation records a blocked run instead of silently substituting Chrome.

Absolute WKWebView budgets remain TBD-by-M0-baseline until repeated packaged runs establish defensible thresholds. The first implementation slice after M0 is persistent relay fan-out only.

Testing

• cd desktop && biome check tests/wkwebview (12 files checked)
• cd desktop && node --test tests/wkwebview/tooling/validation.test.mjs (16 passed)
• deterministic fixture golden assertions: event count, byte count, JSONL digest, first/last IDs and signatures
• git diff --check
• pre-push hooks passed at 3aa4074b653c20bacbaeba3f897f96ca117f0ce2

M0 companion

Reconnect correctness is isolated in #6415 so either PR can be reviewed, reverted, or shipped independently.

[jedwards27]

:bot: Jude’s code review agent

Review pin: base 3c228b1082a93aca302c7b6a67ec274c51ed5eaf, head 3aa4074b653c20bacbaeba3f897f96ca117f0ce2 (GitHub three-dot payload from merge-base 2e7583b).

The architecture prose is strong, particularly its replica transaction, tombstone, outbox, geometry, and cutover ownership contracts. I am requesting changes because the executable WKWebView evidence layer can currently certify a different artifact and incomplete/unrepresentative journeys as a completed run.

P1 — launch does not bind the measured bundle bytes to captured package provenance

desktop/tests/wkwebview/tooling/capture-environment.mjs:110-115,193-208 hashes only Info.plist and captured entitlements while recording signing identity. desktop/tests/wkwebview/tooling/launch.mjs:88-110 later checks only that Contents/MacOS exists and the current plist hash matches. It does not hash the executable/bundled frontend/resources, rerun strict code-signature verification, or compare current identity/entitlements. Replacing executable or frontend bytes after capture while preserving Info.plist therefore passes launch and attributes samples to stale package evidence.

Capture a tamper-evident whole-bundle digest (or all designated executable/frontend/sidecar/resource digests), rerun strict signature verification at launch, and compare current signing/entitlement evidence. Add a mutation test that changes Contents/MacOS/* or bundled frontend resources after capture and proves rejection before driver invocation. Keep caller-provided gitSha explicitly identified as caller provenance unless it can be derived from signed build metadata.

P1 — arbitrary schema-valid output becomes completed without satisfying the acceptance contract

desktop/tests/wkwebview/tooling/validation.mjs:623-667 requires only one sample; metric names are unconstrained and no required scenario/metric coverage, correctness ceilings, launch count, observation count, plateau validity, or overflow conditions are enforced. desktop/tests/wkwebview/tooling/launch.mjs:163-200 marks the run completed after any driver exits zero and writes such output. The success test at validation.test.mjs:522-567 demonstrates this by never launching the app and still earning completed from two synthetic samples. That state is then reportable, despite the five-launch/200-observation matrix and continuous correctness assertions in docs/desktop-performance-rearchitecture.md:328-355.

Separate protocol/driver completion from an acceptance-passed verdict. Encode and validate required scenario/metric cells, correctness ceilings, clean launches, cardinality, plateau/slope, and overflow diagnostics before acceptance can pass. Mutation tests should omit required scenarios, provide one observation, breach each hard ceiling, and avoid launching the app; none may produce acceptance evidence.

P1 — the immutable “rich” fixture materializes only short plain kind-9 messages

desktop/tests/wkwebview/fixtures/acceptance-v1.json:23-39 advertises mixed and media-code-embeds-reactions-threads profiles, while the normative matrix requires late media/code/embed/reaction/thread growth. But tooling/materialize-fixture.mjs:30-75 emits only kind 9 events from one signer, each with bookkeeping tags and literal short text fixture:<profile>:<seed>:<ordinal>. There is no Markdown/code, URL/media metadata, embed, reaction/thread topology, long or adversarial Unicode, replacement/deletion, or late geometry mutation. All 1,200 “rich” rows are plain text, so the immutable fixture does not exercise the layout, anchoring, accessibility, or memory risks it names.

Materialize deterministic profile-specific content and event distributions, including long Markdown/code, Unicode/RTL/emoji, real reply/reaction/thread/replace/delete events, and reserve-to-realize media/embed transitions delivered during motion. Validate per-profile/per-kind counts and causal preconditions, with a mutation proving that replacing rich rows with plain kind-9 messages fails.

P1 — samples cannot identify required viewport/input/accessibility cohorts

The contract at docs/desktop-performance-rearchitecture.md:315-350 requires native wheel/trackpad/keyboard at narrow/wide widths and every supported zoom/text-scale setting, with clean-launch and OS/WebKit separation. But schemas/result.schema.json:30-63 and validation.mjs:628-667 permit only category, scenario, metric, unit, value, and timestamp; no launch, viewport, zoom, text scale, input modality, cold/warm state, or accessibility configuration exists. validation.mjs:687-717 then groups solely by category/scenario/metric/unit. Unlike cohorts can be pooled, required configurations can be omitted undetectably, and a percentile cannot be traced to the user condition that produced it.

Bind each sample to an immutable execution-matrix cell: launch/repetition, viewport, app zoom, OS text/accessibility scale, input modality, cold/warm state, and supported OS/WebKit inventory. Reject missing cells/cardinality violations and report cohorts without pooling. Add negative tests for omitted settings and mixed-setting aggregation. The normative accessibility contract should also define focus and AX-tree continuity under virtualization, VoiceOver navigation/announcements, reduced motion, and target-row removal.

Validation

At exact clean head 3aa4074b653c20bacbaeba3f897f96ca117f0ce2:

• node --test desktop/tests/wkwebview/tooling/validation.test.mjs — 16/16 passed.
• Independent fixture materialization — 8,740 events, 4,255,320 bytes, SHA-256 ac948604f0100b93ce9d6f143b7160b6cd7f1389e1be407ed15fc45dca72edca.
• git diff --check — clean.
• GitHub Desktop Core/build/smoke/integration checks — passed at this head.
• No packaged WKWebView journey was run because this PR supplies no native driver; that is a documented blocker, not acceptance evidence.

The green tests encode the fail-open behavior above; they do not resolve it.