Module candidate_gate 

Unified Candidate Gate Interface (Task 4)

This module defines the AllowedSet abstraction that every retrieval executor MUST accept. The gate guarantees:

1. Never return a doc outside AllowedSet - structural enforcement
2. Apply constraints during generation - no post-filtering
3. Consistent semantics across vector/BM25/hybrid/context

The Contract

Every executor receives an AllowedSet and must:

• Check membership BEFORE including any candidate
• Short-circuit if AllowedSet is empty (return empty results)
• Report selectivity for query planning

Representations

AllowedSet supports multiple representations for efficiency:

Representation	Best For	Membership	Space
Bitmap	Dense sets	O(1)	O(N/8)
SortedVec	Sparse sets	O(log n)	O(n)
HashSet	Random access	O(1) avg	O(n)
All	No constraint	O(1)	O(1)

Selectivity

Executors use selectivity |S|/N to choose execution strategy:

• High selectivity (> 0.1): Standard search with filter
• Low selectivity (< 0.01): Scan only allowed IDs
• Very low (< 0.001): Consider alternative strategy

Structs

AllowedBitmap

Simple bitmap for allowed document IDs

BitmapIter

Iterator over set bits in a bitmap

Enums

AllowedSet

The unified gate for candidate filtering

AllowedSetIter

Iterator over allowed document IDs

ExecutionStrategy

Execution strategy based on selectivity

Traits

CandidateGate

The candidate gate trait that all executors must implement