Queues user mutations while offline with durable identity, ordering rules, retry and conflict policies, and user-visible queue state so reconnect does not replay or drop work unpredictably.
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
When connectivity is unavailable, persist user mutations in a durable queue with explicit state transitions rather than silently dropping work or double-applying on reconnect. Flush policies respect per-entity ordering, idempotent server acknowledgment, and user-visible queue status.
Scope
- Offline detection, enqueue rules, storage, and queue depth limits.
- Flush scheduling, retry backoff, and terminal states defined in
queue-states.yaml. - Conflict handling when server truth diverges from queued mutations.
- Integration with optimistic UI where both are adopted.
Outside this block
- Full local-first database replication.
- Background sync for read-only caches.
- Server-side queue infrastructure.
Contract
- Every enqueued mutation has a client mutation id persisted before the UI reports success offline.
- Per-entity FIFO ordering is preserved during flush unless a documented merge rule applies.
- Retry attempts increment from flushing and awaiting_ack; transient failures requeue, terminal failures move to failed or tombstoned without silent retry.
- Queued delete mutations tombstone local state and supersede pending updates for the same entity.
- Server-reported entity deletion tombstones queued updates for that entity.
- After the dedupe window expires, replay is rejected until an explicit reconcile fetch confirms server state.
- Conflict responses transition to conflict state with documented user actions; silent discard is prohibited.
- Queue depth cannot exceed the profile max without blocking new enqueues and informing the user.
- Applied mutations are removed from the active queue within the profile retention window after acknowledgment.
Implementation guidance
- Implement the state machine from
queue-states.yamlas the single authority for queue transitions. - Use durable storage surviving process restarts; verify recovery tests after simulated crash.
- Coordinate with optimistic updates so provisional UI reflects queued state honestly rather than implying server confirmation.
- Align client mutation ids with API idempotency support on the server and document queue-eligible mutation types in feature specs.
Failure handling and safeguards
- On storage corruption, quarantine the queue and offer export before reset.
- Prevent parallel flush of the same entity beyond documented parallelism rules.
- Do not auto-delete failed mutations without explicit user action.
Verification and operations
- Monitor queue depth, flush latency, retry counts, and conflict rate.
- Test offline enqueue, reconnect flush, crash recovery, and dedupe scenarios.
- Alert when failed queue entries exceed profile thresholds; link to access-controlled diagnostics by opaque correlation id instead of copying mutation payloads or user identifiers into the alert.
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
- Depth limits, backoff arrays, and storage technology in
example.yamlare profile choices for a field-notes mobile app, not universal defaults. - Teams must classify which mutations are queue-eligible versus online-only.
References
- No external normative source is required; pair with API idempotency specifications when available.