Add BlockCursor (postings a block at a time, with block-max bounds) and optional mergeable/releasable interfaces

[capemox]

Draft, do not merge. This is one layer of a stacked checkpoint (scorch_segment_api → freeway → zapx → vellum → bleve). The branches carry local replace directives in go.mod that point at sibling checkouts, so they only build with those checkouts side by side. Opened for review of the design and the code, not for merging as is.

What

Two additions to scorch_segment_api, both optional capabilities so existing implementations keep compiling:

• BlockPostingsIterator (block_iterator.go): a variant of PostingsIterator that yields postings a block at a time, for consumers that want only the scalars a scorer needs (doc number, term frequency, norm) and want to pay for an interface call once per batch instead of once per posting.
  • BlockPostingsList (optional, on a PostingsList) has BlockIterator, the counterpart of Iterator, which returns a BlockPostingsIterator.
  • BlockPostingsIterator fills a PostingsBlock of up to 128 docs, freqs and norms with NextBlock / SeekBlock; deleted docs never appear. Count and LiveCount give the number of postings, the latter exactly and without moving the iterator.
  • BlockMaxPostingsIterator (optional, on a BlockPostingsIterator) bounds the scores of a list: the bounds of the block holding a target without decoding or moving anything (BoundsAt), of the block last decoded, and of the whole list. This is what block-max pruning (WAND / MAXSCORE) is made of.
• MergeablePostingsList / MergeablePostingsIterator and Releasable (segment.go): lets an implementation opt into segment-merge support and pooled reuse without changing the base PostingsList / PostingsIterator contract.

New dependency (read this before merging)

PostingsBlockLen is bitpack.BlockLen from blevesearch/freeway instead of a second 128: the block length is a property of the codec, and it is now defined once and handed on from here (zapx and bleve use segment.PostingsBlockLen).

• This module now requires github.com/blevesearch/freeway, which has no dependencies of its own.
• freeway's go directive is 1.25.0, so this module's go line moves from 1.24.0 to 1.25.0 (bleve and zapx v17 / v18 are already on 1.25.0).
• freeway is currently a private repository. This module is public, so freeway has to be public (or otherwise resolvable by everyone who builds with this module) before this can merge.

Why

The bleve per segment search path (blevesearch/bleve, perseg/term-path) reads postings through these interfaces instead of one Next per posting.

Testing

go build ./... and go vet ./.... The package has no tests of its own; the interfaces are exercised by the zapx implementation and bleve's tests in the PRs above and below this one.

Stack (review order)

#	PR	what
1	freeway#1	float32 TF-IDF / BM25 SIMD kernels (bitpack.BlockLen is the block length everything else uses)
2	this PR scorch_segment_api#87	BlockPostingsIterator interfaces; PostingsBlockLen from freeway
3	zapx#451	BlockPostingsIterator over bit-packed postings (base bitpack-simd)
4	vellum#30	FST traversal performance work (independent)
5	bleve#2404	the per segment search path

Only the last one is the design under review. freeway, scorch_segment_api and zapx are the pieces it reads postings and scores through (the block length is defined once, in freeway, and handed on by scorch_segment_api), and vellum is independent FST work that bleve builds against.

🤖 Generated with Claude Code