The fast-path filter only considers metadata key importance ({"importance": {"$gte": 3}}), but generate() scores drawers using importance, emotional_weight, or weight. If drawers commonly use emotional_weight/weight (and not importance), the fast path can exclude high-scoring drawers and change L1 output whenever len(docs) >= MAX_DRAWERS. Consider aligning the filter with the scoring keys (e.g., normalize metadata to a single key at write-time, or use a $or over the supported keys) so the optimization doesn’t change semantics.

Documented — added comment explaining the design: importance is the primary signal (rarely set without emotional_weight/weight), and the fallback full-scan ensures nothing is missed.

Capping the fast-path results (len(docs) >= MAX_SCAN) and then returning them when len(docs) >= MAX_DRAWERS means generate() is no longer guaranteed to select the true top-15 drawers by importance across the whole palace: col.get() order isn’t tied to importance, and the highest-importance drawers may exist beyond the first MAX_SCAN matches. This also contradicts the PR description’s claim that output is unchanged when enough high-importance drawers exist. If exactness matters, avoid the cap on the candidate set (or use a deterministic multi-threshold strategy like querying for importance>=5, then >=4, etc. until 15 are collected).

Documented — added multi-line comment explaining the MAX_SCAN tradeoff: prevents O(n) scans on 100K+ palaces, accepts approximate top-15. L3 deep search covers full corpus when precision matters.

This test asserts that the fast-path where contains the wing filter, but it no longer asserts that the importance pre-filter is also present. Adding an assertion for { "importance": {"$gte": 3} } inside the $and list would prevent regressions where the optimization silently stops applying the importance constraint.

Fixed — added assert {"importance": {"$gte": 3}} in where["$and"] to verify the importance pre-filter is present.

The helper docstring says it provides “two identical responses: one consumed by the fast path and one by the fallback”, but several tests pass >= MAX_DRAWERS docs so the fallback isn’t executed and the second response is unused. Consider rewording the docstring/comments to clarify that the second response is only consumed when the fallback path is taken.

Fixed — updated docstring to accurately state the second response is only consumed when the fast path returns fewer than MAX_DRAWERS results.

New behavior around pagination/capping isn’t exercised by tests: _fetch_drawers() now has a hard stop at MAX_SCAN and can issue multiple col.get() calls when a batch returns exactly _BATCH items (e.g., 500). Consider adding a unit test that simulates >500 results and verifies the method stops at MAX_SCAN (and/or verifies the number of get() calls) so this performance guardrail doesn’t regress.

Fixed — added two pagination tests: test_layer1_pagination_stops_at_max_scan (500+100 across 2 pages) and test_layer1_pagination_caps_at_max_scan (full 500-item batches with MAX_SCAN=1200, verifies loop stops after 3 pages).