miroir/notes/miroir-cdo.4.md

# P1.4 Result Merger - Verification Summary

## Status: ✅ COMPLETE

The result merger implementation in `crates/miroir-core/src/merger.rs` is fully implemented and tested.

## Acceptance Criteria Verification

All acceptance criteria from plan §8 "Result merger" are met:

### ✅ Global sort by `_rankingScore` descending across shards
- Implementation: Lines 82-166 in merger.rs
- Test: `test_global_sort_by_ranking_score`
- Uses binary min-heap optimization for large result sets

### ✅ `offset + limit` applied **after** merge (not per-shard)
- Implementation: Lines 170-191 in merger.rs
- Tests: `test_offset_and_limit_applied_after_merge`, `test_offset_limit_pagination_reconstruction`
- Includes pagination reconstruction test (50 docs with known scores)

### ✅ `_rankingScore` stripped when `client_requested_score=false`
- Implementation: Lines 183-187 in merger.rs
- Tests: `test_ranking_score_stripped_when_not_requested`, `test_ranking_score_included_when_requested`

### ✅ `_miroir_shard` always stripped
- Implementation: Lines 178-180 in merger.rs
- Test: `test_miroir_shard_always_stripped`, `test_strip_all_miroir_reserved_fields`
- Strips **all** `_miroir_*` prefix fields (not just `_miroir_shard`)

### ✅ Facet counts sum correctly including keys unique to one shard
- Implementation: Lines 364-406 in merger.rs
- Tests: `test_facet_counts_summed_across_shards`, `test_facet_keys_unique_to_one_shard_preserved`
- Uses `BTreeMap` for stable, deterministic serialization

### ✅ `estimatedTotalHits` summed across shards
- Implementation: Lines 197-200 in merger.rs
- Test: `test_estimated_total_hits_summed`

### ✅ `processingTimeMs` = max across covering set
- Implementation: Lines 203-207 in merger.rs
- Test: `test_processing_time_max_across_shards`

### ✅ Stable serialization: `merge` on same input produces byte-identical JSON
- Test: `test_stable_serialization_same_input_same_json`
- Achieved via `BTreeMap` for facet aggregation

## Additional Features Implemented

### Binary Min-Heap Optimization
- Implementation: Lines 109-162 in merger.rs
- Test: `test_binary_heap_efficiency_large_fan_out`
- Avoids keeping all hits in RAM when fan-out is large
- Activates when `all_hits.len() > heap_size * 2`

### Tie-Breaking by Primary Key
- Implementation: Lines 241-252 in merger.rs
- Test: `test_tie_breaking_by_primary_key`
- On equal `_rankingScore`, falls back to lexicographic `primary_key` for deterministic ordering

### Degraded Mode
- Implementation: Lines 72-79 in merger.rs
- Tests: `test_degraded_flag_when_shard_fails`, `test_not_degraded_when_all_succeed`
- Sets `degraded: true` when some shards fail

### Facet Filtering
- Implementation: Lines 374-379 in merger.rs
- Test: `test_facet_filter_only_merges_requested_facets`
- Supports optional facet filter to only merge requested facets

## Test Results

All 21 tests pass:
```
running 21 tests
test merger::tests::test_binary_heap_efficiency_large_fan_out ... ok
test merger::tests::test_facet_keys_unique_to_one_shard_preserved ... ok
test merger::tests::test_limit_exceeds_available_hits ... ok
test merger::tests::test_degraded_flag_when_shard_fails ... ok
test merger::tests::test_empty_shards_returns_empty_result ... ok
test merger::tests::test_estimated_total_hits_summed ... ok
test merger::tests::test_facet_filter_only_merges_requested_facets ... ok
test merger::tests::test_global_sort_by_ranking_score ... ok
test merger::tests::test_facet_counts_summed_across_shards ... ok
test merger::tests::test_offset_and_limit_applied_after_merge ... ok
test merger::tests::test_ranking_score_stripped_when_not_requested ... ok
test merger::tests::test_offset_exceeds_total_hits ... ok
test merger::tests::test_miroir_shard_always_stripped ... ok
test merger::tests::test_missing_facet_distribution_handled_gracefully ... ok
test merger::tests::test_not_degraded_when_all_succeed ... ok
test merger::tests::test_stable_serialization_same_input_same_json ... ok
test merger::tests::test_strip_all_miroir_reserved_fields ... ok
test merger::tests::test_processing_time_max_across_shards ... ok
test merger::tests::test_ranking_score_included_when_requested ... ok
test merger::tests::test_tie_breaking_by_primary_key ... ok
test merger::tests::test_offset_limit_pagination_reconstruction ... ok

test result: ok. 21 passed; 0 failed; 0 ignored; 0 measured
```

## Code Quality

- **Pure function**: The `merge()` function is deterministic and testable without network
- **Memory efficient**: Binary heap optimization for large result sets
- **Stable serialization**: BTreeMap ensures deterministic JSON output
- **Well-documented**: Comprehensive inline comments and docstrings
- **Tested**: 21 tests covering all acceptance criteria and edge cases

## Conclusion

The result merger implementation is complete, correct, and production-ready. No changes are required.