Optimistic updates: User behavior specification

Specifies how the UI applies provisional state, reconciles server truth, rolls back on conflict or failure, and surfaces durable evidence so users never trust stale optimistic data silently.

Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.

Decision

Apply optimistic UI updates for responsive mutations while treating server responses as authoritative. Every optimistic change carries a client mutation identity, preserves a restorable snapshot, and reconciles to success, rollback, conflict, or uncertain timeout states with explicit user feedback.

Scope

• Provisional apply rules, pending indicators, and snapshot storage.
• Reconciliation on success, failure, conflict, and timeout.
• Idempotent retries using client mutation identifiers aligned with server idempotency.
• Telemetry for apply, success, rollback, and conflict rates.

Outside this block

• Offline queue persistence (see offline mutation queue block).
• Server-side optimistic locking schema (see optimistic locking block).
• General form validation UX.

Contract

• Optimistic apply occurs only for mutations explicitly marked optimistic in the client contract; read paths are never optimistically fabricated.
• Each mutation generates a stable client mutation id sent on every retry until terminal reconciliation.
• UI stores a rollback snapshot before apply; failed reconciliation restores snapshot fields exactly.
• Server conflicts (profile choice: HTTP 409) trigger a conflict UX path that does not silently overwrite concurrent local edits.
• Reconciliation exceeding the profile timeout enters uncertain state and resolves via fetch-by-id or polling, not indefinite pending.
• Successful reconciliation clears pending state and replaces displayed fields with server values including entity version metadata.

Implementation guidance

• Centralize optimistic mutation middleware so all features share reconciliation semantics.
• Align client mutation ids with API idempotency keys where the server supports them.
• Use subtle pending affordances rather than blocking entire views unless policy requires.
• Emit telemetry events listed in example.yaml for operations review.

Failure handling and safeguards

• Duplicate success responses must not double-apply side effects in UI state machines.
• Do not chain optimistic mutations that depend on unresolved provisional ids; dependent mutations wait for predecessor reconciliation or reference stable server identity.
• On conflict, prefer showing server diff over blind retry to prevent edit loss.

Verification and operations

• Monitor rollback rate, conflict rate, and uncertain-timeout rate per mutation type.
• Automated tests cover success, failure, conflict, timeout, and idempotent retry paths.
• Review mutations with high rollback rates for server or validation issues.

The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Timeout, status codes, and header names in example.yaml are profile choices for a task board SPA, not universal defaults.
• Teams must map entity version fields to their API schemas.

References

• No external normative source is required; align idempotency behavior with your API idempotency block when adopted.