Define reproducible scenario-based sync verification

[slashv]

Review target

Please review RFC 0003: Scenario-Based Sync Verification.

Problem

Improving LiveStore stability requires reproducible, system-wide correctness evidence under sustained and adverse conditions. Existing focused verification remains necessary, but it does not provide one shared way to encode, stress, reproduce, verify, and visualize scenarios spanning multiple clients and sessions, real or shallow runtime and backend profiles, faults, and recovery.

The architecture needs to be agreed before implementation and then consolidated into the canonical intent hierarchy. This proposal remains in contributor documentation while it is reviewed; after acceptance, its durable contracts are intended to fold into context/02-system/09-verification/06-scenarios/ in a separate intent-layer PR before implementation begins.

Solution

Add RFC 0003, Scenario-Based Sync Verification, defining:

• a typed TypeScript authoring API built from Effect Schema-backed declarative constructors and normalized into a versioned, serializable scenario AST;
• application definitions that wrap the real LiveStoreSchema, infer event and Store types, reuse normal materializers, and expose optional named actions and normalized state inspectors;
• a typed plan model for participant and Leader-role lifecycle, connectivity faults, workloads, scheduling, settlement, and correctness oracles;
• Clients and Client sessions as scenario participants, with the Leader as a role within a Client and the sync backend as a separate topology component;
• a transport-neutral participant-host contract supporting dynamic Clients and Client sessions;
• a production-shaped in-process profile using real Stores, sync processors, materializers, and SQLite, with every result scoped to its selected execution profile;
• participant execution profiles and sync-backend realizations as separate choices without requiring every profile/backend combination or one-to-one cross-profile outcomes;
• shared host conformance for implemented profiles, with cross-profile comparison optional and scenario-specific;
• seeded reproduction for every profile and controlled boundary record/replay for in-process correctness runs;
• contract-level settlement barriers, explicit convergence groups, and bounded correctness oracles;
• a versioned semantic scenario-trace core with namespaced implementation diagnostics;
• one private tests/scenarios/ workspace boundary for the authoring model, runner, hosts, backend realizations, trace, oracles, artifacts, corpus, and visualizer, with no reverse dependency from product packages; and
• canonical intent ownership under context/02-system/09-verification/06-scenarios/ using LS.SYS.VER.SCEN-*, including a node-owned acceptance decision and an initial umbrella delta for the absent subsystem.

YAML and JSON are not primary authoring formats. JSON may encode the normalized AST in artifacts or across transports, while contributors and agents author typed scenario modules. Version one exercises the application’s actual SQLite materializers without making SQLite part of scenario-level sync semantics.

Remaining choices—such as the exact constructor ergonomics, fault-injection mechanisms, trace retention, adversarial inputs, failure minimization, and performance evidence—remain explicit design questions for the scenarios intent node.

This RFC changes no runtime behavior. Once accepted, the durable contracts, terminology, acceptance decision, and implementation delta will be folded into context/; implementation will follow in separate PRs against those requirements.

Visualisation mock-up

The mock-up below illustrates an initial direction for the eventual visualisation. It separates the current system state—covering the backend, Clients, Leader roles, Client sessions, and their sync status—from the scenario timeline that explains how the system reached that state. This is an exploratory visual aid rather than a committed interface design.

Validation

• git diff --check upstream/main...HEAD
• Verified that the RFC’s relative intent-layer link resolves locally and that fenced code blocks are balanced.
• Not run: dt lint:full:fix, dt ts:check, or dt test:run. Neither devenv nor dt is available in the current shell, and this is a documentation-only draft with no executable changes.
• No changelog entry: this RFC proposes future architecture and does not change shipped behavior or package APIs.

Demo (optional)

TypeScript scenario source
          |
          v
Effect Schema validation ----> versioned scenario AST
                                      |
                                      v
                                    runner
                                      |
                                      v
scenario trace ----> correctness oracles / artifacts / visualizer

Related issues

• Replaces the automatically closed stacked draft Design scenario-based sync verification for reproducible convergence testing #1438