How do you merge two sorted iter.Seq[string] sequences in order using iter.Pull?

## The problem A log-shipping step reads two already-sorted streams — say two `io.Reader`s over rotated log files, each yielding lines in timestamp order as an `iter.Seq[string]` — and has to write one merged, still-sorted stream out. This is the textbook use of `iter.Pull`, and it is worth understanding why the push form cannot do it. With `for line := range a`, the loop body becomes the `yield` callback and the sequence drives: the loop runs to completion before the statement after it executes. You are never suspended in the middle of two sequences at once, so you can never compare their two current heads. `iter.Pull` inverts that: each pull gives you a cursor you advance on demand, and holding two cursors at once is exactly what a merge needs. ## The shape ``` nextA, stopA := iter.Pull(a) defer stopA() nextB, stopB := iter.Pull(b) defer stopB() ``` Two pulls, two defers, each defer on the line after its pull so no early return can skip it. Then **prime** both cursors — call each `next` once before the loop — and keep four variables: the current value and the current `ok` for each side. ``` va, okA := nextA() vb, okB := nextB() ``` The loop condition is `okA || okB`: keep going while *either* side still has something. Inside, pick the side to emit: - if only A is live, emit A; - if only B is live, emit B; - if both are live, emit whichever head sorts first. A `switch` with no expression expresses that compactly, with the two-sided comparison folded into one case: `case okA && (!okB || va <= vb):`. ## The rule that makes it correct **Advance only the cursor you emitted from.** The head you did not emit is still unconsumed and must remain available for the next comparison. Calling both `next` functions once per iteration is the most common mistake here, and it is quiet: the output is still sorted-looking, but half of one input has vanished. It is quiet in the other direction too — if you emit a head and forget to advance its cursor, you loop forever writing the same line. Priming matters for the same reason. If you call `next` inside the comparison, you consume a value in order to look at it and then have nowhere to keep it. The cursor gives you one value at a time; the merge state is the two values you are currently holding. ## Stability and ties Using `<=` rather than `<` when A and B tie makes the merge **stable** with respect to the argument order: equal elements from A come out before equal elements from B. That is a deliberate choice, and for log lines with identical timestamps it is usually the one you want, because it is deterministic. Flipping to `<` reverses tie order; both are sorted, only one is reproducible in the way readers expect. ## Errors and cleanup If the merge writes as it goes, a write error is an early `return`, and that is where the two deferred stops earn their place: they resume each suspended sequence with `yield` returning `false`, so each iterator returns and closes the reader it opened. Without the defers, a merge that returns early — on a write error, on a `break` after N lines, or simply because one side ran out and the code returned right there — leaves a suspended sequence behind on every call. If a sequence needs to report its own read error, the usual shape is `iter.Seq2[string, error]` and `iter.Pull2`, whose `next` returns `(string, error, bool)`. The merge logic is unchanged; you just carry an error alongside each head and abort when one is non-nil. ## Zipping is the same skeleton A zip — pair the nth element of A with the nth of B — is the same two-cursor structure with a simpler rule: advance **both** cursors every iteration and stop when either reports `false`. The reason both are natural here and neither is expressible with `range` is identical: you need two cursors alive at the same time. ## Cost Each `iter.Pull` sets up a coroutine and each `next` is a control switch rather than a plain call. For a merge over large streams that is entirely reasonable — the work per element dwarfs the switch. For merging two small in-memory slices, indexing them directly is simpler and faster; do not reach for pull cursors when you already have random access.