expose a version-fenced / atomic reclaim primitive on the sync path

[fabracht]

Summary

The MQTT sync path exposes no client-driven compare-and-set, so an atomic reclaim of an existing row (fence on an expected version/holder, then take it) cannot be expressed as a single operation. A caller must do delete(stale) → create(new), which is non-atomic and racy.

Why the create-conflict fix does not cover this

The Store::create rollback fix (stitch-sync 0.5.0) closes the fresh-claim-on-a-free-key race: two creates on a unique key → the loser now rejects with Conflict. But reclaiming a key already held by a departed/stale owner is a different problem: the client must atomically assert "the current holder is still X at version N" and replace it. There is no primitive for that.

Concrete downstream shape (ticket-live seat reclaim): acquireHold does store.delete(staleHold) then store.create(newHold) — two ops, no fence. Between them another client can claim the seat. This is the non-atomic-reclaim behavior Presence.tla breaks in a handful of steps.

What exists server-side vs. what the client can drive

• mqdb has _version optimistic concurrency, and stitch already maps update/delete CAS conflicts to Error::Conflict.
• BUT Store::update / Store::delete take no expected-version precondition from the client (update(entity, id, fields, origin) / delete(entity, id, origin)), and the agent's field-level LWW retry-on-conflict merges rather than rejects — the opposite of a fence. So the building block is present in the store but not surfaced as a client-controllable CAS.

Proposal (options to design between)

1. Conditional write: an update/delete variant that takes an expected_version (or expected field values) and returns Error::Conflict when the precondition fails, disabling the LWW auto-merge for that call.
2. Claim-transfer op: a dedicated "take ownership of id if holder == X and version == N" operation, returning Conflict otherwise — closer to a presence-lease.

Either lets a reclaim be a single fenced op instead of delete-then-create.

Notes

• Overlaps the presence-lease / reclaim work in stitch-p2p (multi-leader LWW + HLC, signed reclaim), but that's the P2P crate — this request is for the MQTT/mqdb sync path (stitch-sync).
• Architecture item, not a one-liner; worth designing deliberately (and probably a TLA+ model of the fenced reclaim before implementing).
• Surfaced while integrating the seat-claim fix from roll back optimistic create on remote conflict (0.5.0 / 0.4.0) #22.

[fabracht]

Update: mqdb owns the reclaim primitives — this issue narrows to surfacing them in stitch

Coordinated with the mqdb team. The version-fenced reclaim is being built in mqdb, not stitch, and mqdb has TLA-proven the contract (mqdb docs/design/hold-reclaim.md, specs/AbandonedHoldReclaim.tla).

The proven contract: a reap is correct iff both hold — (1) the release is a terminal compare-and-set on _version (a mismatch is non-retryable, not swallowed by the write loop), and (2) a returning holder re-asserts (a write bumping _version / refreshing a lease field) within a grace window. Presence/TTL are only detection latency — the correctness fence is reassert-write + CAS.

mqdb phasing:

• Shipped — TTL backstop fixed: mqdb-agent 0.8.25 / mqdb-cluster 0.4.11. TTL expiry now releases the row's unique guard (was: seat permanently unsellable), emits a delete change event (was: silent in cluster), and is renewal-safe (version-guarded sweep — was: a renewed hold could be deleted on a stale snapshot). This is exactly the TTL-leak reported during the investigation.
• PR2 (not yet shipped) — client CAS: expected_version: Option<u64> on Request::Update/Delete, terminal, with a new non-retryable PreconditionFailed error/code.
• PR3 (not yet shipped) — presence feed: connect/disconnect events on $DB/_presence; requires mqtt5 0.38.4 (carries user_id).

stitch's remaining scope (this issue):

1. When PR2 lands: accept + send expected_version on sync_update/sync_delete (remote_sync.rs / sync_engine.rs), and map the terminal PreconditionFailed to a typed Error variant — surfaced to JS as err.kind via wasm bindings should reject with a structured error (kind/entity/id), not a Display string #25. This is the fenced update/delete originally scoped here.
2. Reassert-on-reconnect is app-driven; stitch already exposes the reconnect_validator hook to trigger it.
3. Later (PR3): an optional $DB/_presence subscription for a janitor, and bump mqtt5 → 0.38.4.

Buildable now with no stitch change: the TTL-lease reclaim. stitch forwards ttl_secs/_expires_at unchanged (verified — only null-stripping, no schema whitelist), and delivers the sweep's delete change event through subscriptions, so an app can build the lease + heartbeat + reassert-on-reconnect janitor today against 0.8.25.

Consumption blocker: 0.8.25 isn't on crates.io (stitch pins 0.8.10). To actually run the fixed broker — and to land the PR2 surfacing — stitch needs mqdb to publish the newer versions or a git dep on the mqdb repo.