fix(common): gracefully drain leader pushes on shutdown

[schickling]

Problem

Orderly Store.shutdown() can interrupt an in-flight client-to-leader push and abandon additional queued events. PR #1405 fixed that loss, but its handling of scope-finalizer order, rebase ownership, rejection recovery, and terminal failures grew too complex for this core sync path and was auto-merged before explicit human sign-off.

PR #1439 reverts that implementation while retaining its stronger tests as skipped specifications. GitHub cannot literally reopen a merged PR, so this stacked draft recreates #1405 as the active design and review surface.

Goal

Keep the original problem, implementation, review history, and test discoveries available while we replace the implementation quickly with a smaller explicit pre-scope shutdown boundary tracked by #1437.

This draft is not proposed for merge in its current form.

Decisions

• Reapply fix(common): gracefully drain leader pushes on shutdown #1405 exactly on top of the revert branch; the resulting tree matches current main byte-for-byte.
• Preserve the original implementation here for comparison and review rather than editing history or hiding the rejected approach.
• Use Prevent client event loss during orderly Store shutdown #1437 as the acceptance and redesign authority.
• Prefer an explicit processor shutdown operation before lifetime-scope teardown. Initially fail shutdown-time rejection rather than modeling rebase recovery inside finalizers.

Verification

• git diff origin/main HEAD is empty: this draft exactly recreates the currently merged fix(common): gracefully drain leader pushes on shutdown #1405 tree.
• Original fix(common): gracefully drain leader pushes on shutdown #1405 CI was green across unit, type, lint, integration, performance, examples, and docs.
• PR Revert complex leader-push shutdown drain while retaining specifications #1439 proves the primary retained regression is red after revert and keeps 12 shutdown specifications skipped and linked to Prevent client event loss during orderly Store shutdown #1437.

Complexity

The current implementation adds 108 net production lines to ClientSessionSyncProcessor and introduces rejection revision/prefix tracking, drain-failure side channels, finalizer-order coupling, and uninterruptible rebase transitions. Reducing that state and interaction budget is the purpose of reopening the design.

Concerns

• Do not merge this draft as-is after Revert complex leader-push shutdown drain while retaining specifications #1439; it would simply restore the disputed implementation.
• Several tests encode scheduler/virtual-clock coordination that should be replaced with explicit lifecycle handshakes when re-enabled.
• The replacement remains urgent because Revert complex leader-push shutdown drain while retaining specifications #1439 intentionally restores known event loss.

Friction & bottlenecks

• A merged GitHub PR cannot be reopened, requiring this stacked recreation.
• No product-performance bottleneck was introduced or measured.

Follow-ups

• Implement the narrower lifecycle boundary and re-enable Prevent client event loss during orderly Store shutdown #1437's skipped specifications incrementally.
• Reassess and close or reshape broader lifecycle draft Harden sync durability across rebase, RPC, and shutdown #1426 after the narrow fix is agreed.

References

• Recreates fix(common): gracefully drain leader pushes on shutdown #1405
• Stacked on revert Revert complex leader-push shutdown drain while retaining specifications #1439
• Fix design and tests: Prevent client event loss during orderly Store shutdown #1437
• Broader exploration: Harden sync durability across rebase, RPC, and shutdown #1426

[github-actions]

PR preview

Subject	Status	Report	Details	Updated
LiveStore docs preview	success	Docs preview deployed (livestore-docs-dev)	PR aliases: pr-1440-dd19312, pr-1440	2026-07-18 09:20 UTC
web-linearlite	success	web-linearlite deployed (preview)	Worker: example-web-linearlite-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc	success	web-todomvc deployed (preview)	Worker: example-web-todomvc-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc-script	success	web-todomvc-script deployed (preview)	Worker: example-web-todomvc-script-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc-sync-cf	success	web-todomvc-sync-cf deployed (preview)	Worker: example-web-todomvc-sync-cf-preview.livestore.workers.dev	2026-07-18 09:02 UTC

Report history

PR 1440 · 2026-07-18 09:26 UTC

Subject	Status	Report	Details	Updated
LiveStore docs preview	success	Docs preview deployed (livestore-docs-dev)	PR aliases: pr-1440-dd19312, pr-1440	2026-07-18 09:20 UTC
web-linearlite	success	web-linearlite deployed (preview)	Worker: example-web-linearlite-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc	success	web-todomvc deployed (preview)	Worker: example-web-todomvc-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc-script	success	web-todomvc-script deployed (preview)	Worker: example-web-todomvc-script-preview.livestore.workers.dev	2026-07-18 09:02 UTC
web-todomvc-sync-cf	success	web-todomvc-sync-cf deployed (preview)	Worker: example-web-todomvc-sync-cf-preview.livestore.workers.dev	2026-07-18 09:02 UTC

[IGassmann]

This PR contains no changes.