# STR-002: Module Hierarchy

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

---

## Summary

The module hierarchy MUST match the specification layout, providing a clear separation of concerns across store, config, types, constants, error handling, encoding, caching, canonical chain, compression, pipeline, and snapshot modules.

---

## Specification

The `src/` directory MUST contain the following module structure:

```
src/
  lib.rs                    # Crate root with re-exports
  store.rs                  # BlockStore struct and core implementation
  config.rs                 # BlockStoreConfig and configuration logic
  constants.rs              # CF_* and META_* constants
  cf_options.rs             # Per–column-family RocksDB options ([`TYP-003`](../../storage_types/specs/TYP-003.md))
  error.rs                  # BlockStoreError enum
  encoding.rs               # Key encoding functions
  compression.rs            # Zstd compression/decompression
  pipeline.rs               # Async write pipeline
  snapshot.rs               # Snapshot export/import
  wire.rs                   # L2Block Streamable wire bytes ([`SER-003`](../../serialization/specs/SER-003.md))
  types/
    mod.rs                  # Types module root
    block_record.rs         # BlockRecord struct
    stored_checkpoint.rs    # StoredCheckpoint struct
    chain_tip.rs            # ChainTip struct
    storage_stats.rs        # StorageStats struct
  cache/
    mod.rs                  # Cache module root
    sharded.rs              # Sharded LRU cache implementation
    warming.rs              # Cache warming on startup
  canonical/
    mod.rs                  # Canonical module root
    index.rs                # Canonical chain index logic
    mmap.rs                 # Memory-mapped canonical.bin file
```

Each `mod.rs` MUST declare its child modules. `lib.rs` MUST declare all top-level modules.

---

## Acceptance Criteria

- [x] `src/store.rs` exists and defines `BlockStore`
- [x] `src/config.rs` exists and defines `BlockStoreConfig`
- [x] `src/types/block_record.rs` exists and defines `BlockRecord`
- [x] `src/types/stored_checkpoint.rs` exists and defines `StoredCheckpoint`
- [x] `src/types/chain_tip.rs` exists and defines `ChainTip`
- [x] `src/types/storage_stats.rs` exists and defines `StorageStats`
- [x] `src/constants.rs` exists with CF_* and META_* constants
- [x] `src/error.rs` exists with `BlockStoreError`
- [x] `src/encoding.rs` exists with key encoding functions
- [x] `src/cache/sharded.rs` exists with sharded LRU cache
- [x] `src/cache/warming.rs` exists with cache warming logic
- [x] `src/canonical/index.rs` exists with canonical index
- [x] `src/canonical/mmap.rs` exists with mmap support
- [x] `src/compression.rs` exists with zstd compression
- [x] `src/pipeline.rs` exists with async write pipeline
- [x] `src/snapshot.rs` exists with snapshot logic
- [x] `cargo check` compiles the full module tree

---

## Implementation Notes

- The module tree mirrors the SPEC Section 16 layout. Additional private helper modules may be added as needed, but the listed modules are required.
- Each subdirectory (`types/`, `cache/`, `canonical/`) requires a `mod.rs` that declares its submodules.

---

## Test Plan

| Test Name | Type | Description |
|-----------|------|-------------|
| `test_all_modules_exist` | unit | Verify each listed source file exists on disk |
| `test_module_tree_compiles` | integration | `cargo check` succeeds with no missing-module errors |

---

## Expected Test Files

- `tests/str_002_tests.rs`
