desktop: make feature parity and cross-platform agent verification first-class gates #287

Problem

Rivet's macOS implementation tends to become the de facto reference implementation, while Windows and Linux lag behind in feature completeness and refinement.

This is partly inherent to Rivet's architecture: backend/schema/RVT1 are shared, but product behavior above that boundary can still drift across SwiftUI, WinUI, and GTK. It is also amplified by agent development: an agent working on macOS can validate macOS locally, but cannot directly observe the real WinUI or Linux/GTK result.

The result is two related failure modes:

1. Feature parity drift — a feature is considered "done" after the macOS implementation works, while Windows/Linux remain incomplete or behaviorally different.
2. Local-OS verification bias — an agent treats the current OS as the effective verification scope, instead of validating all required desktop targets.

Proposal

Make desktop parity and distributed platform verification first-class Rivet contracts.

1. Classify desktop capabilities

Define three categories:

• Guaranteed — same semantics are required on Windows/macOS/Linux. Missing support is a release/acceptance failure.
• Conditional capability — same API/semantics, but runtime availability may differ (for example tray, global shortcuts, secure storage, notifications). Adapters must report supported/unavailable/permission/provider state explicitly.
• Platform-specific — intentionally native-only capabilities with no forced cross-platform abstraction.

The goal is semantic parity, not identical visual behavior.

2. Make feature parity executable

Extend the acceptance model so a cross-platform feature can declare its required platforms and suites.

Conceptually:

(feature 'export-document
  #:platforms '(windows macos linux)
  #:required? #t)

A Guaranteed desktop feature should not be considered complete until the required acceptance scenarios pass on all declared platforms.

Suggested definition of done:

• shared semantic contract
• backend/schema changes
• macOS native implementation
• Windows native implementation
• Linux native implementation
• macOS acceptance
• Windows acceptance
• Linux acceptance

This should build on the existing rivet-acceptance.rktd, native UI E2E, capability discovery, and schema gates rather than introducing another parallel test system.

3. Add cross-platform verification orchestration for agents

The local OS should be treated as an editing environment, not the boundary of verification.

A coding agent should be able to:

1. run fast local checks;
2. trigger Windows/macOS/Linux verification jobs;
3. receive structured machine-readable results;
4. inspect accessibility snapshots, screenshots, logs, and failing assertions;
5. fix the implementation and re-run only the affected platform/suite.

Each platform job should emit a normalized result artifact, for example:

{
  "platform": "windows-x64",
  "result": "failed",
  "feature": "export-document",
  "stage": "native-ui",
  "expected": "Save dialog opened",
  "actual": "No dialog appeared",
  "accessibility_snapshot": "uia.json",
  "screenshot": "failure.png"
}

Accessibility/semantic evidence should be primary; screenshots are supplemental because native SwiftUI, WinUI, and GTK UIs are expected to look different.

4. Add a verification matrix view

Consider a command such as:

raco rivet matrix
raco rivet matrix --json

It could aggregate local and remote acceptance evidence:

Desktop verification matrix

                     local   remote
Racket contract       PASS      -
macOS native UI       PASS      -
Windows build           -      PASS
Windows native UI       -      FAIL
Linux build             -      PASS
Linux native UI         -      PASS

Cross-platform status: FAIL

The exact command name is not important; the important part is one machine-readable source of truth for platform completeness.

5. Use tiered verification

Avoid making every edit wait for the full release pipeline.

• Tier 0 / local: unit, schema, codegen
• Tier 1 / remote quick: per-platform compile + targeted tests
• Tier 2 / PR: package + native UI acceptance
• Tier 3 / release: installer, signing, real-hardware/system-integration checks

This keeps agent feedback fast while still preventing parity drift.

Agent contract

Add an explicit rule to the maintainer/agent contract along these lines:

A change touching a Guaranteed desktop capability is incomplete until the required acceptance suites pass on Windows, macOS, and Linux. The local operating system determines only which checks can run locally; it does not reduce the required verification scope.

Non-goals

• Do not introduce a cross-platform UI DSL.
• Do not require pixel-identical UIs across platforms.
• Do not treat Linux desktop-service availability differences as bugs when they are explicitly modeled as capabilities.
• Do not require full release/signing validation for every edit.

Expected outcome

Rivet should move from:

shared backend + three native implementations that can drift

toward:

shared behavior contract + native platform adapters whose parity is continuously proven

This would also make Rivet substantially more agent-native: an agent could develop from one OS while still receiving actionable evidence from the other platforms instead of assuming correctness from local results alone.