mobile-debug-mcp 0.25.1 → 0.26.0

package/docs/rfcs/003-wait-and-synchronization-reliability

@@ -1,232 +0,0 @@
-
-
-# RFC-003: Wait and Synchronization Reliability
-
-Priority: 3  
-Depends on: RFC-001 (Stronger State Verification), RFC-002 (Platform-Native Element Metadata and Resolution Hints)
-
----
-
-# 1. Problem
-
-Agents can often identify the right element (RFC-002) and verify the right state (RFC-001), but still fail because they act before the UI has reached the intended post-action state.
-
-This causes:
-
-- retries caused by racing the UI
-- false failures from stale snapshots
-- overuse of network/log verification when UI evidence should suffice
-- flakiness in asynchronous and in-place update flows
-- unreliable behaviour in Compose-heavy or thin accessibility trees
-
-Current system limitations:
-
-- wait_for_ui is underused after actions involving async state changes
-- current waits focus on expected elements appearing, not general UI transition detection
-- snapshot staleness is not explicitly surfaced
-- loading state transitions are inconsistently observable
-
----
-
-# 2. Goals
-
-This RFC introduces:
-
-1. UI-first synchronization policy after actions
-2. Snapshot staleness and revision metadata
-3. UI-change based waiting for in-place updates
-4. Structured loading-state detection
-5. Compose-aware synchronization hints
-
-Success goals:
-
-- reduce retries caused by premature actions
-- increase successful post-action verification
-- reduce unnecessary fallbacks to logs/network checks
-- improve reliability in asynchronous UI flows
-
----
-
-# 3. Non-Goals
-
-This RFC does not:
-
-- redefine state verification semantics (RFC-001)
-- redefine element identity contracts (RFC-002)
-- add new interaction primitives (long press, pinch, etc.)
-- replace network or log verification where no UI outcome exists
-
----
-
-# 4. Proposed Model
-
-## 4.1 UI-First Synchronization Policy
-
-Default post-action flow SHOULD be:
-
-```text
-action
-→ wait_for_ui(expected outcome)
-→ verify state
-→ only fall back to network/logs when no UI outcome exists or wait fails
-```
-
-Rules:
-
-- UI evidence MUST be preferred over network or log evidence when a UI outcome is expected.
-- Actions that trigger navigation, async mutation, or visible state changes SHOULD be followed by a wait.
-- Network/log checks are fallback signals, not primary synchronization mechanisms.
-
----
-
-## 4.2 Snapshot Revision / Staleness Metadata
-
-Snapshot responses MUST expose revision metadata.
-
-Preferred shape:
-
-```json
-{
-  "snapshot_revision": 184,
-  "captured_at_ms": 1714452012301
-}
-```
-
-Rules:
-
-- snapshot_revision MUST increment when hierarchy meaningfully changes.
-- captured_at_ms MUST reflect snapshot capture time.
-- Agents SHOULD use revision changes as synchronization signals.
-- Agents SHOULD treat stale revisions as suspect for verification.
-
----
-
-## 4.3 wait_for_ui_change Primitive
-
-A UI-diff based wait primitive SHOULD support waiting on hierarchy changes, not only explicit expected elements.
-
-Conceptual contract:
-
-```ts
-wait_for_ui_change({
-  expected_change?: "hierarchy_diff" | "text_change" | "state_change",
-  timeout_ms?: number
-})
-```
-
-Use cases:
-
-- in-place content refresh
-- async partial rerender
-- list mutations
-- Compose recomposition-driven updates
-
-Rules:
-
-- wait_for_ui_change SHOULD detect meaningful UI deltas, not cosmetic noise.
-- It MAY use snapshot revisions as one signal.
-- It complements wait_for_ui; it does not replace it.
-
----
-
-## 4.4 Structured Loading-State Detection
-
-Systems SHOULD surface structured loading signals when detectable.
-
-Examples:
-
-- progress indicator present/absent
-- disabled submit button becomes enabled
-- loading spinner removed
-
-Preferred model:
-
-```json
-{
-  "loading_state": {
-    "active": true,
-    "signal": "progress_indicator"
-  }
-}
-```
-
-Rules:
-
-- loading start and loading completion SHOULD be detectable when possible.
-- Loading signals MAY be used as synchronization hints, not sole success criteria.
-
----
-
-## 4.5 Compose-Aware Synchronization Hints
-
-For Compose or thin accessibility structures:
-
-Systems SHOULD support:
-
-- merged semantic node changes as wait signals
-- text mutations within existing nodes
-- in-place recomposition awareness
-
-These are synchronization hints layered on top of standard wait behaviour.
-
----
-
-# 5. Failure Modes
-
-## 5.1 Premature Action Progression
-
-If an action is followed immediately by verification without waiting:
-
-- system SHOULD bias toward suggesting wait_for_ui
-- retries SHOULD prefer synchronization correction before repeated action execution
-
----
-
-## 5.2 Stale Snapshot Reads
-
-If verification uses an old snapshot:
-
-- revision metadata SHOULD expose staleness
-- agents SHOULD reacquire snapshot before retrying verification
-
----
-
-## 5.3 No Visible UI Outcome
-
-If no UI outcome is expected:
-
-- network/log verification MAY be primary evidence
-- UI-first policy does not apply rigidly
-
----
-
-# 6. Acceptance Criteria
-
-RFC-003 is complete when:
-
-- UI-first synchronization policy is enforced in agent guidance
-- snapshot revision metadata is exposed in snapshot responses
-- wait_for_ui_change contract is implemented or stubbed
-- structured loading-state hints are surfaced where detectable
-- retries caused by premature action progression are reduced
-
----
-
-# 7. Success Metrics
-
-- Fewer retries caused by timing/synchronization errors
-- Higher post-action verification success rate
-- Reduced unnecessary fallback to network/log evidence
-- Improved stability in asynchronous and Compose-heavy flows
-
----
-
-# 8. Deferred To Later RFCs
-
-- Advanced subscriptions / notify-when-element-appears APIs
-- Full action-to-ui trace correlation (Priority 7)
-- Gesture-trigger-specific synchronization logic
-
----
-
-This RFC standardises temporal reliability and synchronization signals layered on top of state verification and element identity guarantees from RFC-001 and RFC-002.