[Experiment] Bitmap-based tool index for O(1) filtering

[SamMorrowDrums]

⚠️ Experimental

This is an experiment exploring bitmap-based indexing for efficient tool filtering. Not intended for immediate merge - just capturing the approach for discussion.

Problem

In stateless server patterns, we rebuild tool lists per-request. With ~130 tools and multiple filter dimensions (toolsets, read-only, feature flags), filtering becomes O(n × filters).

Approach

Pre-compute bitmaps at startup, then use bitwise operations for O(1) filtering:

// Build once at startup
index := BuildToolIndex(allTools)

// Per-request: ~78ns, 0 allocations
result := index.Query(QueryConfig{
    Toolsets: []string{"repos", "issues"},
    ReadOnly: true,
})

// Materialize only when needed: ~1µs for 130 tools
tools := index.Materialize(ctx, result)

What's included

1. bitmap.go - ToolBitmap type (256-bit, 4×uint64) with Set/And/Or/Iterate
2. tool_index.go - Pre-computed index with Query() and Materialize()
3. tool_variants.go - Simple override mechanism for tools with variant definitions

Benchmarks

Query (130 tools, 2 toolsets):     78ns    0 allocs
Materialize (full list):        1114ns    3 allocs
ToolOverrides.ApplyToTools:    ~18µs    ~130 allocs (condition funcs)

Key design decisions

• 256-tool limit via fixed bitmap size (expandable if needed)
• Lazy allocation in ApplyToTools - no allocs when no overrides match
• Pointer returns from Materialize to avoid struct copies
• Simple ToolOverrides instead of full VariantIndex (only 2 tools need variants)

Open questions

• Is this level of optimization needed for the local server?
• How does this integrate with the remote server's caching?
• Should we expose ToolIndex publicly or keep it internal?

[SamMorrowDrums]

Superseded by a cleaner implementation that encapsulates bitmask complexity behind a composable EnableCondition API. See upcoming PR.