Sync State Invariants

Sync State Invariants

Required Context

Read packages/ui/src/sync/DOCUMENTATION.md and the nearest owning module documentation before editing. Context gathering is complete when every changed state has an identified owner, authority, scope, and lifecycle.

Before editing behavior a user can reach, write the surface list from ui-api-decoupling, Name The Surfaces Before Editing: one line per runtime, including the ones this change appears to leave alone. State that reconciles differently per runtime is a parity decision, not an implementation detail.

Sources Of Truth

Classify every input before deriving state:

Prefer deterministic authoritative records over heuristics. Derive live behavior from live channels, not historical anomalies.

Give each state and its invariants one owner. Callers request domain transitions from that owner; they do not inspect one field, mutate another collection, and repair status externally. Split ownership only when the states have genuinely independent lifecycles.

Represent mutually exclusive lifecycle states with discriminated unions or equally precise contracts. Avoid boolean/nullable field combinations that permit impossible states. Reject invalid transitions at the owning boundary so downstream reducers and effects receive trusted state.

Failure Is Not Empty

Any authoritative loader whose result can replace, delete, or clear state must distinguish failure from successful empty data.

Use an existing pattern:

• Throw when an outer logical block can catch and preserve prior state.
• Return T | null when follow-up work must continue and null exclusively means fetch failure.

Never swallow an SDK/API error into [], {}, or another valid empty success. Verify that callers skip destructive replacement after failure.

Track completeness at the smallest entity/scope. One failed project or directory blocks destructive work for itself, not for unrelated complete scopes.

Inferring destructive cleanup from disappearance between snapshots requires an established authoritative baseline. This is separate from applying a complete snapshot whose contract explicitly authorizes first-load replacement.

• Never infer a disappearance event from the first snapshot, startup-empty state, filtered/visible subsets, or partially loaded scopes.
• Compare two complete authoritative snapshots from the same runtime and logical scope before treating disappearance as removal.
• Key disappearance by stable entity identity. Owner, directory, grouping, category, or presentation moves are not deletion unless the authoritative contract says so.
• Reset the baseline when runtime identity or authoritative scope changes.
• Prefer explicit deletion events; snapshot-difference cleanup is a fallback that requires completeness guarantees.

Live And Historical State

• Use historical state to restore context, not to infer ongoing execution.
• Scope delayed-live fallbacks to the active entity and clear them when authoritative state arrives.
• Do not let stale persisted data keep a fallback active indefinitely.
• Define field precedence when global and local/live snapshots feed the same view.
• Use one ordering/rank source for all views of the same entities.

Event Reducers

• Make the valid transition path explicit and flat. Return early for irrelevant entities and semantic no-ops; assert or reject transitions that violate an established invariant.
• Clone only fields the event mutates; preserve every unrelated reference.
• Return no change for semantically identical events.
• Gate scans behind cheap event/entity checks.
• Coalesce repeated same-entity events without violating ordering.
• Reject stale async/event completions using generation or authoritative timestamps.
• Do not widen a narrow fallback to arbitrary historical records.

For streaming-frequency work, also load performance-engineering.

Polling And Bootstrap

• Preserve rich fields when lightweight polling omits them.
• Use cheap change detection before heavy per-directory fetches.
• Refresh only directories already running: the selected one and those an event names. Every OpenCode read of a directory starts it with its MCP servers (opencode-v2), so a refresh over every store is a fan-out.
• Treat startup 502/503 as transient with bounded retry/recovery.
• A retry loop requires a real failure signal; swallowed errors disable retries.
• Preserve previous authoritative state during transient bootstrap/reconnect failures.
• Distinguish stale-scope rejection from same-scope mutation reconciliation. A generation token rejects obsolete owners but does not protect mutations made while a still-valid request is in flight.
• Capture a mutation revision when an authoritative load starts. At commit time, read current state and preserve or overlay entity mutations newer than that revision.
• Record removals as mutations even when the entity is already absent, so an in-flight response cannot resurrect it.
• Return committed reconciled state, not the raw fetched snapshot, when callers depend on the result.

Optimistic Updates

• Keep optimistic promotion, reconciliation, and rollback behavior behind the store/module that owns both visible and shadow state; do not expose collections for callers to mutate independently.
• Insert optimistic data into the visible store and a separate shadow tracker.
• Use client-generated IDs accepted and echoed by the server to reconcile in place.
• Remove optimistic data from both visible and shadow state on failure.
• Reconcile deterministically on authoritative fetch/event; do not guess from unrelated events.
• Stabilize callbacks stored in module-level refs to avoid effect loops.

Session And Queue Consistency

• Capture provider, model, agent, variant, and other send configuration when queueing.
• Do not re-resolve queued configuration from mutable current state at send time.
• Preserve server-backed attachments and convert paths at the transport boundary.
• Pass a directory hint when a newly created session is not indexed yet.
• Read mutable current directory at call time; never cache it in a long-lived closure.