docs: clarify BloomFilter contract after invert

[Renkai]

This closes #194

Summary

Documentation-only clarification of the BloomFilter contract around invert(), addressing #194:

• qualify the module-level guarantees as holding before invert() only (mod.rs#L31-L33)
• same qualification at the type level (sketch.rs#L41-L42)
• state in invert()'s documentation that after inversion neither the no-false-negative nor the false-positive guarantee holds, and that is_empty()/bits_used()/load_factor() then describe the raw bit state rather than insertion history (sketch.rs#L241-L245)
• document is_empty() in terms of bit state (num_bits_set == 0), which is what the implementation actually observes (sketch.rs#L265-L268)
• remove the unreachable BloomFilterBuilder::build panic documentation: the builder has no public default constructor, and both public entry points always produce a valid configuration (builder.rs#L157)

Design questions from #194

This PR makes the current semantics honest without committing to the open API decisions:

1. invert placement: unchanged (stays on the public API, aligned with the C++/Java implementations, where it serves as an intermediate in boolean composition with union()/intersect()). Whether to move it to a raw/diagnostic API remains open in Clarify BloomFilter semantics after invert and correct builder documentation #194; the documentation added here is accurate under either outcome.
2. is_empty semantics: documented as bit state, with the normal-operation meaning noted. Renaming would be a breaking change and is not proposed here.
3. post-invert qualification of guarantees: done at module, type, and method level, which is the substance of this patch.
4. build panic documentation: removed as directed. No further code change is needed for "encode the configured state more directly": the builder fields are already non-optional, and both constructors always produce a valid configuration.

Validation

• cargo x check
• cargo x test
• cargo x lint

[tisonkun]

LGTM.

[tisonkun]

cc @leerho I wonder if a BloomFilter gets invert-ed, is its state still valid? Not sure if we should call other methods of an inverted BloomFilter and what is the proper semantic there.

[tisonkun]

Thanks for your contribution @Renkai!

[leerho]

@tisonkun,
The person you want to ask is the expert on Stochastic Filters, Niv Dayan, Prof of C.S. at Univ of Toronto. A really nice guy and has done extensive R &D on Filters and has contributed a lot of material to us for use in DataSketches. Including the BloomFilter, QuotientFilter and InfiniFilter. We almost completed work on the QuotientFilter when Yahoo laid off our little R&D sketching group.

Much of the work on our end was done by Jan Malkin, who is at Apple now and is not allowed to contribute to Open Source :( !

If you write to him, thank him for work he contributed to us, and ask if you could have a few minutes to discuss this problem with him. Or describe it in the letter if it is not too complex.