Clarify QueryCollection clearError() timing semantics

Relates to: PR #441 ("add error tracking and retry methods to query collection utils")
Scope: DX / reliability / timing behavior
Breaking changes: Potentially (if we change default behavior)

Summary

clearError() currently resets error state before refetch (optimistic behavior), creating a transient window where isError() returns false during a failing retry. This can cause UI flickering and confusion.

Current Behavior (Optimistic)

clearError: () => {
  lastError = undefined      // Reset immediately
  errorCount = 0            // Reset immediately  
  lastErrorUpdatedAt = 0    // Reset immediately
  return refetch({ throwOnError: true }) // May fail and set error again
}

Problem: Between clearError() call and observer result, isError() briefly returns false even if the retry fails.

Proposed Options

Option A: Keep optimistic + add isRecovering()

// Add recovery tracking
let isRecovering = false

clearError: async () => {
  isRecovering = true
  lastError = undefined
  errorCount = 0
  try {
    await refetch({ throwOnError: true })
  } finally {
    isRecovering = false
  }
}

isRecovering: () => isRecovering

Option B: Reset-on-success with opt-in optimistic

clearError: async (opts = { optimistic: false }) => {
  if (opts.optimistic) {
    lastError = undefined
    errorCount = 0
  }
  
  try {
    await refetch({ throwOnError: true })
    if (!opts.optimistic) {
      lastError = undefined
      errorCount = 0
    }
  } catch (e) {
    if (opts.optimistic) {
      // Restore error state since optimistic clear failed
      lastError = e
      errorCount++
    }
    throw e
  }
}

Acceptance Criteria

• Behavior is documented with timeline diagram or bullet sequence
• If isRecovering() is added, include tests and docs
• Choose default behavior that minimizes UI flickering
• Ensure error state consistency during recovery attempts
• Consider impact on existing users

Open Questions

1. Should we default to optimistic (current) or reset-on-success?
2. Is isRecovering() worth the API complexity?
3. Should this be configurable per collection or global?

Start by reviewing PR #441 and the QueryCollection clearError() and refetch() behavior described here. Compare the optimistic and reset-on-success options, including the effects on isError() during a failed retry and existing users. Done means the behavior is decided, documented with a timeline or bullet sequence, and covered by tests and docs if isRecovering() is added.