# ADR-042: Code Coverage Improvement Plan

- **Status**: Proposed
- **Date**: 2026-03-14
- **Deciders**: Project maintainers
- **Related**: ADR-033 (Modern Testing Strategy), ADR-041 (Test Health Remediation)

## Context

The project currently has a 90% code coverage target configured in `.codecov.yml`, but the actual coverage is estimated to be significantly lower. PR #363 shows the codecov/patch check as a potential blocker for new contributions.

### Current State

| Aspect | Status |
|--------|--------|
| Coverage tool | `cargo-llvm-cov` configured in CI |
| Target coverage | 90% (project), 80% (patch) |
| Estimated actual | ~55-65% (based on test module analysis) |
| Test infrastructure | `cargo-nextest`, `proptest`, `insta` available |
| CI integration | Codecov with OIDC authentication |

### Test Module Distribution

| Crate | `#[cfg(test)]` Count | Coverage Priority |
|-------|---------------------|-------------------|
| do-memory-core | 104 files | HIGH - Core business logic |
| do-memory-mcp | 52 files | HIGH - Protocol and security |
| do-memory-storage-turso | 44 files | MEDIUM - Database operations |
| do-memory-cli | 26 files | MEDIUM - User interface |
| do-memory-storage-redb | 8 files | HIGH - Cache and persistence |

### Identified Coverage Gaps

1. **do-memory-core**
   - `reward/`: Complex calculation paths (efficiency, quality, learning bonuses)
   - `spatiotemporal/`: Index operations, retrieval logic
   - `sync/`: Two-phase commit, storage synchronization
   - `reflection/`: Insight generation paths

2. **do-memory-storage-redb**
   - `persistence/`: Manager, config, types
   - `cache/adaptive/`: Adaptive TTL logic, eviction policies

3. **do-memory-storage-turso**
   - `metrics/export/`: HTTP export, Prometheus formatting
   - `transport/`: Compression, wrapper operations
   - `pool/keepalive/`: Connection lifecycle

4. **do-memory-mcp**
   - `batch/`: Dependency graph, batch execution
   - `patterns/predictive/`: Forecasting, ETS algorithms
   - `sandbox/`: Security boundaries

5. **do-memory-cli**
   - `commands/`: Episode, pattern, tag operations
   - `config/validator/rules/`: Validation logic

## Decision

Implement a phased coverage improvement plan with realistic targets:

### Target Coverage by Phase

| Phase | Target | Focus |
|-------|--------|-------|
| Phase 1 (Week 1-2) | 70% | Critical paths |
| Phase 2 (Week 3-4) | 75% | Property tests |
| Phase 3 (Week 5-6) | 80% | Integration tests |
| Ongoing | +5%/sprint | Continuous improvement |

### Target Coverage by Crate

| Crate | Phase 1 | Phase 3 | Final Target |
|-------|---------|---------|--------------|
| do-memory-core | 70% | 80% | 85% |
| do-memory-storage-redb | 60% | 75% | 80% |
| do-memory-storage-turso | 65% | 75% | 80% |
| do-memory-mcp | 55% | 70% | 75% |
| do-memory-cli | 50% | 65% | 70% |

### Implementation Strategy

#### Phase 1: Critical Path Coverage (Week 1-2)

**Goal**: Ensure all critical business logic is tested.

1. **Episode Lifecycle Tests**
   - Test create, log step, complete flow
   - Test all `TaskOutcome` variants
   - Test error handling paths

2. **Storage Consistency Tests**
   - Write/read round-trip tests
   - Concurrent access tests
   - Error recovery tests

3. **Reward Calculation Tests**
   - Boundary value tests for efficiency multiplier
   - Quality multiplier edge cases
   - Learning bonus scenarios

#### Phase 2: Property Test Expansion (Week 3-4)

**Goal**: Use property-based testing for broad coverage with minimal code.

1. **Serialization Round-trips**
   ```rust
   proptest! {
       fn episode_roundtrip(episode in any::<Episode>()) {
           let encoded = postcard::to_allocvec(&episode).unwrap();
           let decoded: Episode = postcard::from_bytes(&encoded).unwrap();
           prop_assert_eq!(episode, decoded);
       }
   }
   ```

2. **Calculator Properties**
   - RewardCalculator outputs always in bounds
   - Cache TTL calculations monotonic
   - Index operations preserve ordering

3. **Fuzz Testing**
   - MCP JSON-RPC message parsing
   - CLI argument parsing
   - Configuration deserialization

#### Phase 3: Integration Coverage (Week 5-6)

**Goal**: Test complete workflows and edge cases.

1. **CLI Integration Tests**
   - Episode CRUD workflows
   - Pattern analysis workflows
   - Error message formatting

2. **MCP Server Tests**
   - Tool invocation sequences
   - Batch operation handling
   - Rate limiting behavior

3. **Storage Integration Tests**
   - Cache eviction under pressure
   - Connection pool behavior
   - Compression/decompression

## Consequences

### Positive

- **Higher confidence** in code correctness
- **Fewer production bugs** in edge cases
- **Better refactoring support** with test safety net
- **PR codecov/patch check passes** consistently
- **Mutation testing** validates test effectiveness

### Negative

- **Engineering time**: ~2-3 weeks for full implementation
- **Maintenance cost**: Tests need updates when code changes
- **CI time**: More tests = longer CI runs
- **False sense of security**: Coverage does not guarantee correctness

### Risks

- **Flaky tests** if not carefully written
- **Test brittleness** if too coupled to implementation
- **Maintenance burden** if tests are hard to understand

## Quality Gates

### Per-Phase Gates

**Phase 1 Gate:**
- [ ] All critical modules have basic tests
- [ ] No module below 50% coverage
- [ ] `cargo llvm-cov --workspace --lcov` shows 70%+ overall

**Phase 2 Gate:**
- [ ] Property tests for all serializable types
- [ ] Calculator properties validated
- [ ] Fuzz tests pass with 10,000 iterations

**Phase 3 Gate:**
- [ ] CLI integration tests cover all commands
- [ ] MCP tool tests cover all tools
- [ ] Storage tests cover error paths

### Continuous Gates

- [ ] `codecov/patch` passes on all PRs
- [ ] Coverage never decreases by more than 1%
- [ ] Mutation testing shows <20% missed mutants

## Monitoring Plan

### Weekly Reports

1. Coverage percentage by crate
2. Coverage trend (increasing/decreasing)
3. Files with coverage below 50%

### CI Integration

1. PR coverage diff in comments
2. Coverage badge in README
3. Alert on coverage decrease >2%

### Monthly Mutation Testing

```bash
cargo mutants --timeout 120 --jobs 4 -- --lib
```

## References

- ADR-033: Modern Testing Strategy
- ADR-041: Test Health Remediation
- [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov)
- [Codecov Documentation](https://docs.codecov.com/)
- [proptest Book](https://proptest-rs.github.io/proptest/)

## Implementation Progress

### Phase 1 Progress (2026-03-14)

| Action | Status | Details |
|--------|--------|---------|
| ACT-026 | ✅ Complete | Episode lifecycle tests in do-memory-core |
| ACT-027 | ✅ Complete | Reward calculation property tests |
| ACT-028 | ✅ Complete | Storage consistency tests |
| ACT-029 | ✅ Complete | Error handling tests |

### Phase 2 Progress (2026-03-14)

| Action | Status | Details |
|--------|--------|---------|
| ACT-030 | ✅ Complete | Serialization round-trip tests (proptest) |
| ACT-031 | ✅ Complete | Calculator property tests (bounds validation) |
| ACT-032 | ⏳ Pending | MCP JSON-RPC fuzz tests |

### Phase 3 Progress

| Action | Status | Details |
|--------|--------|---------|
| ACT-033 | ⏳ Pending | CLI integration tests |
| ACT-034 | ⏳ Pending | MCP tool integration tests |
| ACT-035 | ⏳ Pending | Cache eviction tests |

### Coverage Fix (2026-03-14)

**Issue**: Coverage workflow failed due to `test_server_creation` test race condition.

**Root Cause**: `is_wasm_sandbox_available()` environment variable timing varies between tool registration and test assertion in parallel test execution.

**Resolution**:
- Removed conditional assertion for `execute_agent_code` tool
- Test now asserts only core tools that are always available (`query_memory`, `analyze_patterns`, `health_check`)
- Updated snapshot tests for v0.1.19

**Files Changed**:
- `do-memory-mcp/src/server/tests.rs` - Fixed test assertion
- `do-memory-cli/tests/snapshots/*` - Updated version snapshots
