# Hierarchical Summary Storage (E11.2)
## Overview
The Peat storage layer supports storage and retrieval of hierarchical
aggregation summaries (SquadSummary, PlatoonSummary) to enable Mode 3 (CAP
Differential) testing. The examples below use the current Automerge + Iroh
backed `PeatStore`; an earlier revision exposed the same API as `DittoStore`
against the now-removed Ditto backend.
## API
### Squad Summaries
```rust
use peat_protocol::storage::PeatStore;
use peat_schema::hierarchy::v1::SquadSummary;
// Store a squad summary
let summary: SquadSummary = /* ... */;
store.upsert_squad_summary("squad-alpha", &summary).await?;
// Retrieve a squad summary
let retrieved = store.get_squad_summary("squad-alpha").await?;
match retrieved {
Some(summary) => println!("Found: {}", summary.squad_id),
None => println!("Not found"),
}
```
### Platoon Summaries
```rust
use peat_schema::hierarchy::v1::PlatoonSummary;
// Store a platoon summary
let summary: PlatoonSummary = /* ... */;
store.upsert_platoon_summary("platoon-1", &summary).await?;
// Retrieve a platoon summary
let retrieved = store.get_platoon_summary("platoon-1").await?;
```
## Storage Details
- **Encoding**: Protobuf messages are encoded to bytes, then base64-encoded for JSON storage
- **Collections**:
- `squad_summaries` - SquadSummary documents
- `platoon_summaries` - PlatoonSummary documents
- **Document Structure**:
```json
{
"_id": "squad-alpha",
"squad_id": "squad-alpha",
"leader_id": "node-1",
"member_count": 8,
"data": "base64-encoded-protobuf-bytes",
"type": "squad_summary"
}
```
## Integration with StateAggregator
For Mode 3 testing, use StateAggregator to create summaries, then store them:
```rust
use peat_protocol::hierarchy::StateAggregator;
use peat_protocol::storage::PeatStore;
// 1. Aggregate squad state from member NodeStates
let squad_summary = StateAggregator::aggregate_squad(
"squad-alpha",
"node-1", // leader_id
members, // Vec<(NodeConfig, NodeState)>
)?;
// 2. Store the aggregated summary
store.upsert_squad_summary("squad-alpha", &squad_summary).await?;
// 3. Leader publishes summary (via CRDT sync)
// Platoon leader can now query squad_summaries collection
// 4. Platoon leader retrieves squad summaries
let squad_alpha = store.get_squad_summary("squad-alpha").await?;
let squad_bravo = store.get_squad_summary("squad-bravo").await?;
// 5. Aggregate platoon from squad summaries
let platoon_summary = StateAggregator::aggregate_platoon(
"platoon-1",
"node-1",
vec![squad_alpha.unwrap(), squad_bravo.unwrap()],
)?;
// 6. Store platoon summary
store.upsert_platoon_summary("platoon-1", &platoon_summary).await?;
```
## Testing
See the storage module tests in `peat-protocol/src/storage/`:
- `test_squad_summary_storage()` - Example squad summary test
- `test_platoon_summary_storage()` - Example platoon summary test
## Next Steps for Experiments Team
To implement Mode 3 (CAP Differential) in your framework:
1. **Baseline (Mode 1)**: Full NodeState replication (no filtering)
2. **Mode 2 (CAP Full)**: CRDT-enabled NodeState replication (no aggregation)
3. **Mode 3 (CAP Differential)**:
- Squad members → Squad leader (full NodeState)
- Squad leaders → Platoon leader (SquadSummary only)
- Platoon leaders → Company leader (PlatoonSummary only)
This achieves O(log n) message complexity vs O(n²) in Mode 1/2.
## References
- [ADR-015](../../../docs/adr/015-experimental-validation-hierarchical-aggregation.md) - Experimental validation plan
- [hierarchy.proto](../../../peat-schema/proto/hierarchy.proto) - Schema definitions
- [state_aggregation.rs](../../hierarchy/state_aggregation.rs) - Aggregation logic