# BLK-015: Get Records in Range (`get_records_in_range`)

| Link | Path |
|------|------|
| **Normative** | [NORMATIVE.md](../NORMATIVE.md) |
| **Verification** | [VERIFICATION.md](../VERIFICATION.md) |
| **Tracking** | [TRACKING.yaml](../TRACKING.yaml) |
| **Spec** | [SPEC.md](../../../../resources/SPEC.md) Section 5.3, 15.3 |

---

## Summary

`get_records_in_range(&self, start_height: u64, end_height: u64) -> Result<Vec<BlockRecord>>` retrieves canonical block records in a height range with inclusive bounds. Lighter than `get_blocks_in_range` because it only needs header deserialization (no full block decompression).

---

## Specification

```rust
/// Retrieves canonical block records in a height range [start, end] inclusive.
/// Lighter than get_blocks_in_range -- no full block deserialization.
pub fn get_records_in_range(
    &self,
    start_height: u64,
    end_height: u64,
) -> Result<Vec<BlockRecord>> {
    if start_height > end_height {
        return Ok(Vec::new());
    }

    let mut records = Vec::with_capacity((end_height - start_height + 1) as usize);
    for height in start_height..=end_height {
        if let Some(record) = self.get_record_by_height(height)? {
            records.push(record);
        }
    }
    Ok(records)
}
```

### Semantics

- **Inclusive range**: Both `start_height` and `end_height` are included.
- **Empty range**: If `start_height > end_height`, returns an empty `Vec`.
- **Missing heights**: Heights with no canonical entry are silently skipped.
- **Lightweight**: Records are derived from headers via `from_header()`, avoiding full block decompression.
- **Order**: Records are returned in ascending height order.

---

## Acceptance Criteria

- [ ] Returns records in `[start_height, end_height]` inclusive
- [ ] Returns records in ascending height order
- [ ] Returns empty vec when `start_height > end_height`
- [ ] Skips heights with no canonical entry
- [ ] Does not decompress full blocks (uses header-only path)
- [ ] Records are derived from headers on cache miss

---

## Test Plan

| Test Name | Type | Description |
|-----------|------|-------------|
| `test_records_in_range_basic` | unit | Store blocks 0-9, request range 3-7, verify 5 records returned in order |
| `test_records_in_range_empty` | unit | Request range 7-3 (inverted), verify empty vec |
| `test_records_in_range_fields` | unit | Verify records contain correct height, hash, epoch for each entry |
| `test_records_in_range_lightweight` | benchmark | Compare timing vs get_blocks_in_range for same range; records should be faster |

---

## Expected Test Files

- `tests/blk_015_tests.rs`
