Module push_index 

The guarded push fan-out reverse index (designs/205-GUARDED-PUSH-FANOUT-DESIGN.md): prunes a source write’s per-connection fan-out to the connections whose equality-shaped where guard could match. A conservative superset index — never under-approximates — so filter_push stays the exact gate. Guarded push fan-out: a reverse predicate index over source connections (designs/205-GUARDED-PUSH-FANOUT-DESIGN.md).

Every source write today fans out to every connection on the table and runs its full compiled predicate against the changed row(s) — O(N) predicate evaluations per write, N = connection slots, almost all concluding “drop” for the where col = ? shapes that dominate rindled. This module is the conservative index that prunes that fan-out to the connections that could actually match.

Why skipping is exact, not heuristic

The index is only ever a superset filter — it may over-approximate (visit a connection whose predicate then rejects the row), never under-approximate. Two facts (design §“safety argument”) make that sound:

1. filter_push remains the exact gate: a connection contributes nothing iff its predicate rejects both the old and the new row. So the index need only never miss a possibly-matching connection; a false positive re-runs the exact predicate, unchanged.
2. Skipping is observationally equivalent for the reentrancy machinery — a skipped connection’s stale last_pushed_epoch hides the overlay exactly as the connection’s own predicate would have narrowed that overlay to nothing.

Corollary: every approximation here errs only toward visiting. A guard-less or un-guardable connection lands in the always-visited scan list; a coarser-than-identity GuardKey bucket merely re-checks the exact predicate. The one thing that would be a bug is a finer key.

This module is intentionally standalone and free of the push orchestration: it is pure data (PushGuard), a comparator newtype (GuardKey), and the index (PushIndex). The extraction of a PushGuard from a query’s where tree lives in crate::builder; the wiring of a PushIndex into ConnTable’s push path lives in crate::source_common.

Structs

PushGuard

predicate(row) ⇒ row[col] ∈ values — a finite single-column implication of a connection’s pushed-down equality-shaped filter, extracted (in crate::builder) from the same stripped condition the connection’s RowPredicate was compiled from. Backend-neutral pure data (like SqlCondition), populated for both the memory and SQLite leaves.

PushIndex

The reverse index: guard value → connection slots, plus the always-visited scan set and a refcounted union of split-edit keys.