feat(sources): B2.2 — keyset merge-join

[thiagoluga]

The second multi-source strategy — the keyset merge-join.

Join.MergeJoin merges two sources ordered by the same key into an IStreamingSource<TResult>. For each left row it emits the contiguous group of right rows sharing its key. Inner drops unmatched left rows; LeftOuter keeps them with an empty group.

.From(Join.MergeJoin(
    left:     Source.Sql(conn, sqlCustomers).Keyset<Customer, long>(c => c.Id),
    keyLeft:  c => c.Id,
    right:    Source.Sql(conn, sqlOrders).Keyset<Order, long>(o => o.CustomerId),
    keyRight: o => o.CustomerId,
    map:      (c, orders) => new CustomerOrders(c, orders),
    kind:     JoinKind.LeftOuter))

Design

• Streams the merge, buffering one right key-group at a time → constant memory as long as a single key's right multiplicity is bounded (both sources must be ordered by their key, same as the v1 keyset rule). The pipeline slices the stream into batches.
• DelegatingStreamingSource<TResult> keeps the class type params low; the four-type ergonomic API lives on Join.MergeJoin (S2436 suppressed with a justification — a join needs 4 types, exactly like BCL Enumerable.GroupJoin).
• An internal Paginate<T> reads a batch source page by page as a flat async sequence.

Tests (4 green Join total)

• Inner emits only matched left rows with their group — right rows spanning a page boundary are gathered in order.
• Left-outer keeps unmatched left rows with an empty group.

Epic B2 status

B2.1 (enrichment) ✅ + B2.2 (merge-join) ✅ — both strategies done. Remaining: B2.3 (packaging + sample, needs your Pro-vs-free call) and B2.4 (dynamic config, optional).

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud