design: peer-mode §12 invariants and reactive scope-open

[fabracht]

Summary

Two design-doc updates bundled together. Both stem from the same review pass that started as a follow-up to PR #11.

1. docs/design/reactive-peer-mode.md — §12 additions

Spells out how MQDB and peer modes coexist, and what happens if a client tries to switch between them. The original draft underspecified this; sanity-checking surfaced three invariants worth locking in before any Phase 1 code lands.

Three load-bearing invariants:

1. §12.1 — syncMode is per-store, boot-time, immutable. Persisted in store metadata; mismatch on subsequent boot throws ModeMismatchError with a clearLocalData() recovery path. Both have explicit contracts in the doc (error fields, clearLocalData side effects).
2. §12.2 — Versioning fields are mode-segregated: _version: number for MQDB, _hlc: { ts: number; counter: number; nodeId: string } for peer. Independent fields, no runtime polymorphism. Supersedes the earlier "HLC replaces _version" wording in §5.3 / §5.4.
3. §12.3 — A scope is single-mode. Enforced mechanically by giving peer mode a distinct default syncTopicPrefix (stitch/peer) so cross-mode topic collisions are impossible at the broker.

Plus failure-mode table (§12.4), offline-queue interaction (§12.5), and explicit out-of-scope items (§12.6 — no MQDB→peer data migration, no per-scope mode, no CRDT yet).

Consistency fixes in §5.3, §5.4, §6.1, and §11 Phase 1 description bring older sections in line with §12.

2. docs/design/reactive-scope-open.md — new doc

Reviewing §12 surfaced a sequencing question: stitch's existing server-backed replaceScope blocks on N parallel request/reply round-trips inside openScope (each capped at 10s). Peer mode designs around that by removing the server entirely, but the underlying client architecture would benefit from being reactive end-to-end first.

The new doc proposes:

• Replace Promise.all([fetchOne, fetchList × N]) in openScope with a client-published hello and server-emitted per-record events on the existing scope events topic.
• replaceScope returns immediately; UI populates as records stream in.
• bumpScopeVersion becomes a server-emitted event instead of a per-mutation round-trip (cuts awaited-mutation latency in half).
• Mutations stay request/reply — write validation still needs synchronous server feedback. Out of scope here.
• Backwards compat via MQTT 5 User Property capability negotiation. Old servers fall back to fetchList.

§9 of the new doc lays out the relationship to peer mode: both designs converge on the same client shape (one events topic, hello-driven manifest diff, no client-side deadlines). Doing scope-open first means peer mode reuses the streaming infrastructure rather than building a parallel reactive stack.

This is the design-doc landing only. Implementation is gated on agreement with whoever owns the MQDB server.

Supporting material — docs/design/MQDB-AGENT-BRIEF.md: self-contained brief for whoever picks up the server-side work. Inlines the wire format (topics, ChangeEvent schema, MQTT user properties, request/reply envelope, the new hello and scope-open-error payloads), the consolidated server-side checklist from reactive-scope-open.md §4.4.1, pseudo-code for the hello handler, and a server-side phasing plan. Designed so the MQDB agent can work straight from this one document without reading stitch's source tree.

Test plan

• No code changes; nothing to type-check or test.
• node scripts/verify-changelog.mjs not relevant (doc-only, no behavior change).
• Review the three invariants in §12.1–12.3 — these gate peer-mode Phase 1.
• Review reactive-scope-open.md (and the supporting MQDB-AGENT-BRIEF.md) — gates server-protocol negotiation.