fix: Resolve pending shapes in FlushTracker when consumer process receives commit fragment with no relevant changes

[alco]

Summary

Fix #4063

When a {Storage, :flushed, offset} message arrives at a Consumer process while it's in the middle of processing a multi-fragment transaction, the flush notification could be lost. This caused the FlushTracker in ShapeLogCollector to get stuck waiting for a flush that was already completed.

Changes

Consumer (consumer.ex, consumer/state.ex):

• Defer flush notifications that arrive during a pending transaction by storing the max flushed offset in pending_flush_offset
• Process deferred flush notifications when the pending transaction completes (commit, skip, or no relevant changes)

FlushTracker (flush_tracker.ex):

• Simplify to commit-only tracking: remove non-commit fragment handling since Consumer now defers flush notifications during pending transactions
• Remove shapes_with_changes parameter from handle_txn_fragment/3 — all affected shapes are tracked uniformly at commit time

ShapeLogCollector (shape_log_collector.ex):

• Only call FlushTracker.handle_txn_fragment/3 on commit fragments
• Remove shapes_with_changes computation that is no longer needed

Test plan

• New regression test for stuck flush tracker scenario
• Stricter assertions in EventRouterTest for txn fragment reslicing
• Updated Consumer tests for deferred flush notification behavior
• Existing test suite passes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.67%. Comparing base (0af96e9) to head (b76d0d3).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4064   +/-   ##
=======================================
  Coverage   88.67%   88.67%           
=======================================
  Files          25       25           
  Lines        2438     2438           
  Branches      615      611    -4     
=======================================
  Hits         2162     2162           
  Misses        274      274           
  Partials        2        2           

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.81% <ø> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	88.67% <ø> (ø)
unit-tests	88.67% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[claude]

Claude Code Review

Summary

Fixes a real production bug (#4063) where the FlushTracker could get permanently stuck when a storage buffer-size flush fires during multi-fragment transaction processing. The approach of deferring flush notifications at the Consumer level and simplifying FlushTracker to commit-only tracking is clean and well-tested.

What's Working Well

• Root cause analysis is excellent: the issue writeup precisely identifies the race sequence with production state dumps and proposed fix directions
• Simplification is a net win: removing FlushTracker non-commit pre-registration complexity makes both components easier to reason about independently
• Deferred flush notification covers all three terminal paths of a pending transaction cleanly
• Double-notification in the no-changes path is correctly benign (second call is a safe no-op)
• Regression test faithfully reproduces the production scenario
• Changeset included

Issues Found

Critical (Must Fix)

None.

Important (Should Fix)

None.

Suggestions (Nice to Have)

is_write_unit_txn_fragment guard defined but unused
File: packages/sync-service/lib/electric/shapes/consumer/state.ex:401
The guard was added but is not referenced anywhere in consumer.ex or the broader codebase. The @write_unit_txn_fragment module attribute is still matched directly via pattern matching at line 271. Either replace that pattern match with the guard or remove it to avoid confusion for future readers.

handle_txn_fragment/3 is now load-bearing for commit-only callers
File: packages/sync-service/lib/electric/replication/shape_log_collector/flush_tracker.ex:98
The function will crash with FunctionClauseError if a non-commit fragment is passed (old non-commit clause removed). Since the only callsite already guards with when not is_nil(commit), this is safe today. A short @doc note stating only commit fragments are accepted would protect future callers from discovering this at runtime.

Issue Conformance

Issue #4063 is well-specified with a precise root-cause analysis, exact race sequence, production state dumps, and three proposed fix directions. The PR implements Option 1 (deferred flush notification), the cleanest approach. Implementation fully addresses the race condition. No scope creep.

Previous Review Status

• Fixed: Typo in consumer/state.ex comment (ultiple -> Multiple) — addressed in commit b76d0d3.
• Open: is_write_unit_txn_fragment guard unused — not yet addressed.
• Open: handle_txn_fragment/3 missing @doc note for commit-only contract — not yet addressed.

---

Review iteration: 2 | 2026-03-26