frontend-patterns/sequences/LocalFirstApplication.md

Offline local-work sequence

0.1 research preview · synthetic VC-02 guidance · all linked candidates are hypotheses. Start · Core and extensions

Starting context

People create/edit notes without connectivity, restart without losing acknowledged work, then synchronize. Multiple writers may produce incompatible changes. Notes do not make globally exclusive reservations or approvals. Access/retention policy and separate device-loss recovery must be explicit.

Offline usability, recoverability and completeness compete with freshness, storage complexity and reconciliation effort. Decide what “saved” means before choosing sync or rendering tools. An evictable cache is not automatically the required local record.

Decisions and resulting contexts

Decision	Candidate and resulting context	Alternative / boundary
Acknowledge only a recoverable local commit	CAND-0002 Local Commit Boundary: accepted local revision and pending propagation survive the specified restart	Memory-only feedback cannot satisfy restart; server-only saving cannot satisfy offline acceptance. Verify transaction and failure boundaries
Keep propagation visible and restartable	CAND-0003 Pending Synchronization: distinguish queued, sent and receiver-acknowledged	Online-only writes change the brief. Untracked upload cannot prove completion; receiver receipt does not mean every device received the change
Preserve detected competing content when permitted	CAND-0001 Conflict Copy: working version selected, divergent intent still available	Immediate comparison or justified semantic merge may be preferable; a copy cannot detect all conflicts or guarantee no loss
Make semantic resolution an explicit decision	CAND-0004 Explicit Reconciliation: comparison produces a new revision and pending work	A version store can supply alternatives without conflict files; domain-appropriate automatic merge may avoid manual review

Local projection must reconstruct required offline work from locally available inputs. Initial online server rendering may coexist with that path; it cannot be the only way to display new offline edits. Choosing a CRDT or sync transport does not by itself establish persistence, access or acceptable domain outcomes.

Follow the failure

A and B edit a common revision while disconnected. A acknowledges local save only after the specified durable transaction. Restart reconstructs that work and its pending identity. When divergence is detected, preserve alternatives subject to policy and block obsolete retry work. Selecting a working version does not settle intended content. When the user resolves it, atomically record the new revision/pending operation and supersede the old one. An already transmitted operation still needs receiver-side ancestry/precondition handling. Late receipts must not clear newer pending work.

A lost acknowledgement remains unresolved propagation, not proof of rejection. Retry only within the receiver contract; expired identity or access needs explicit handling. Backup must survive the failure you promise to recover from. Another local copy or synchronized deletion is not an independent restore path.

Change a constraint

If only A may edit and that restriction actually holds, omit the concurrent-version branch. Local commit and pending propagation remain. If another writer, external tool or restored revision violates the assumption, reassess divergence handling.

If the user instead needs offline globally exclusive checkout or approval, stop: this note-oriented configuration does not provide global exclusivity. Clarify the acceptance requirement or choose a separately justified domain protocol.

Implementation and evidence

Offline mechanism mappings locate local storage, sync metadata and documented conflict-handling options. They do not establish our atomic storage or retry contracts. The full VC-02 trace records its baseline and assumptions. M1 review remains revise/defer; crash recovery, receiver semantics, human/AT and independent usefulness evidence are still open.