stemedb/applications/aphoria/dogfood/dbpool/plan.md

# Dogfood Project: Database Connection Pool (`dbpool`)

**Status:** 🎯 ACTIVE
**Start Date:** 2026-02-09
**Target Completion:** 2026-02-14 (5 days)
**Owner:** Aphoria Development Team

---

## Executive Summary

Build a production-ready database connection pool with **intentional violations** of established best practices, then use Aphoria to detect and guide remediation. This demonstrates Aphoria's value in preventing real production incidents through code-level truth linting.

**Key Metrics:**
- **Claims to Extract:** 25-30
- **Intentional Violations:** 7-8
- **Expected Detection Rate:** 100% (all violations caught)
- **Final State:** 0 conflicts, production-ready

**Demonstration Value:**
- ✅ Safety enforcement (prevents connection exhaustion)
- ✅ Security validation (credential handling)
- ✅ Standards compliance (HikariCP, PostgreSQL best practices)
- ✅ Educational impact (each violation teaches a lesson)

---

## Product Overview

### What We're Building

**dbpool:** A safe, opinionated PostgreSQL/MySQL connection pool library for Rust.

**Why This Product:**
1. **High Stakes:** Connection pool misconfigurations cause P0 production incidents
2. **Clear Authority:** HikariCP documentation + PostgreSQL/MySQL guides provide canonical best practices
3. **Common Mistakes:** Developers frequently misconfigure max_connections, timeouts, and lifetimes
4. **Measurable ROI:** "Aphoria prevented a production outage" is a compelling story

### Scope

**Initial Implementation (v0.1.0):**
- Basic connection pool with configurable limits
- Connection validation and health checks
- Timeout management (connection, checkout, validation)
- Metrics exposure (pool size, active, idle, waiting)
- PostgreSQL support (MySQL in future iteration)

**Lines of Code:** ~600 (intentionally small for clarity)

**Dependencies:**
- `tokio-postgres` for database connections
- `tokio` for async runtime
- `serde` for configuration
- `prometheus` for metrics (optional)

---

## Authority Sources

### Primary Sources

1. **HikariCP Configuration Documentation**
   - **URL:** https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing
   - **Authority Tier:** Tier 2 (Vendor - industry standard Java connection pool)
   - **Expected Claims:** 12-15
   - **Key Topics:**
     - Pool sizing (max, min connections)
     - Connection lifecycle (max_lifetime, idle_timeout)
     - Timeout configuration (connection, validation, checkout)
     - Health checks and validation

2. **PostgreSQL Connection Pooling Guide**
   - **URL:** PostgreSQL official documentation
   - **Authority Tier:** Tier 2 (Vendor)
   - **Expected Claims:** 8-10
   - **Key Topics:**
     - max_connections calculation
     - Statement timeout
     - Idle connection handling
     - Connection validation queries

3. **OWASP Database Security**
   - **URL:** OWASP Top 10 A07:2021
   - **Authority Tier:** Tier 1 (Clinical)
   - **Expected Claims:** 3-5
   - **Key Topics:**
     - Credential handling (no plaintext passwords)
     - Connection string security
     - Certificate validation for TLS

### Extraction Strategy

**Method:** Manual extraction → CLI creation (not LLM for this dogfood)
- We'll create claims by hand from the authority sources
- This ensures we have exact claims we want to violate
- Tests the CLI workflow (`aphoria corpus create`)
- Faster for a focused dogfood (5 days)

**Alternative:** Use `extract-wiki-corpus` skill if we convert docs to markdown first.

---

## Expected Claims (25-30 total)

### Safety Claims (10)

| Subject | Predicate | Value | Authority | Tier |
|---------|-----------|-------|-----------|------|
| `dbpool/max_connections` | `required` | `true` | HikariCP | 2 |
| `dbpool/max_connections` | `bounded` | `true` | PostgreSQL | 2 |
| `dbpool/min_connections` | `minimum` | `2` | HikariCP | 2 |
| `dbpool/connection_timeout` | `maximum` | `30` (seconds) | HikariCP | 2 |
| `dbpool/idle_timeout` | `required` | `true` | HikariCP | 2 |
| `dbpool/idle_timeout` | `bounded` | `true` | PostgreSQL | 2 |
| `dbpool/max_lifetime` | `required` | `true` | HikariCP | 2 |
| `dbpool/max_lifetime` | `default` | `1800` (30 min) | HikariCP | 2 |
| `dbpool/validation_timeout` | `maximum` | `3` (seconds) | HikariCP | 2 |
| `dbpool/leak_detection_threshold` | `recommended` | `true` | HikariCP | 2 |

### Performance Claims (8)

| Subject | Predicate | Value | Authority | Tier |
|---------|-----------|-------|-----------|------|
| `dbpool/max_connections/development` | `default_value` | `10` | HikariCP | 2 |
| `dbpool/max_connections/production` | `recommended_range` | `50-100` | HikariCP | 2 |
| `dbpool/checkout_timeout` | `default_value` | `5` (seconds) | HikariCP | 2 |
| `dbpool/validation/frequency` | `required` | `on_checkout` | PostgreSQL | 2 |
| `dbpool/connection_test_query` | `recommended` | `SELECT 1` | PostgreSQL | 2 |
| `dbpool/prefill` | `recommended` | `true` (production) | HikariCP | 2 |
| `dbpool/fair_queue` | `default_value` | `true` | HikariCP | 2 |
| `dbpool/metrics/enabled` | `recommended` | `true` | HikariCP | 2 |

### Security Claims (5)

| Subject | Predicate | Value | Authority | Tier |
|---------|-----------|-------|-----------|------|
| `dbpool/connection_string/password` | `must_not_be` | `plaintext` | OWASP A07 | 1 |
| `dbpool/connection_string/source` | `required` | `environment_variable` | OWASP A07 | 1 |
| `dbpool/tls/enabled` | `recommended` | `true` (production) | OWASP A07 | 1 |
| `dbpool/tls/certificate_validation` | `required` | `true` | OWASP A07 | 1 |
| `dbpool/credentials/rotation` | `recommended` | `true` | OWASP A07 | 1 |

### Architecture Claims (4)

| Subject | Predicate | Value | Authority | Tier |
|---------|-----------|-------|-----------|------|
| `dbpool/health_check/endpoint` | `required` | `true` | HikariCP | 2 |
| `dbpool/metrics/exposed` | `required` | `pool_size,active,idle,waiting` | HikariCP | 2 |
| `dbpool/error_handling/connection_failure` | `must` | `return_error_not_panic` | Rust Best Practices | 3 |
| `dbpool/shutdown/graceful` | `required` | `true` | HikariCP | 2 |

---

## Intentional Violations (7-8)

### Critical Violations (Will be detected as BLOCK)

1. **Unbounded max_connections**
   ```rust
   pub max_connections: Option<usize>,  // None = unbounded
   ```
   - **Claim Violated:** `dbpool/max_connections` required
   - **Consequence:** Unbounded growth exhausts database connections
   - **Severity:** CRITICAL

2. **Plaintext Password**
   ```rust
   pub connection_string: String,  // "postgres://user:password@..."
   ```
   - **Claim Violated:** `dbpool/connection_string/password` must not be plaintext
   - **Consequence:** Credential exposure in logs/configs
   - **Severity:** CRITICAL

3. **Missing max_lifetime**
   ```rust
   pub max_lifetime: Option<Duration>,  // None = connections never recycled
   ```
   - **Claim Violated:** `dbpool/max_lifetime` required
   - **Consequence:** Stale connections accumulate, intermittent errors
   - **Severity:** CRITICAL

### Error Violations (Will be detected as FLAG)

4. **Excessive connection_timeout**
   ```rust
   pub connection_timeout: Duration::from_secs(60),  // Should be <= 30s
   ```
   - **Claim Violated:** `dbpool/connection_timeout` maximum 30
   - **Consequence:** Slow failures cascade
   - **Severity:** ERROR

5. **Zero min_connections**
   ```rust
   pub min_connections: usize = 0,  // Should be >= 2
   ```
   - **Claim Violated:** `dbpool/min_connections` minimum 2
   - **Consequence:** Cold start penalty on first request
   - **Severity:** ERROR

6. **Missing Connection Validation**
   ```rust
   pub async fn get(&self) -> Result<Connection> {
       self.connections.pop()  // No validation before return
   }
   ```
   - **Claim Violated:** `dbpool/validation/frequency` required on_checkout
   - **Consequence:** Return stale/broken connections to application
   - **Severity:** ERROR

### Warning Violations

7. **No Metrics Exposed**
   ```rust
   // No metrics struct, no instrumentation
   ```
   - **Claim Violated:** `dbpool/metrics/enabled` recommended
   - **Consequence:** No observability into pool health
   - **Severity:** WARNING

8. **Missing Leak Detection** (Optional)
   ```rust
   // No leak detection threshold configured
   ```
   - **Claim Violated:** `dbpool/leak_detection_threshold` recommended
   - **Consequence:** Connection leaks go undetected
   - **Severity:** WARNING

---

## Implementation Plan (5 Days)

### Day 1: Preparation & Corpus Building

**Goal:** Extract claims and populate corpus database

**Tasks:**
1. ✅ Create project structure
   ```bash
   mkdir -p applications/aphoria/dogfood/dbpool/{src,docs}
   touch applications/aphoria/dogfood/dbpool/plan.md
   ```

2. ✅ Fetch authority source documents
   - Download HikariCP configuration wiki page
   - Save PostgreSQL connection pooling guide
   - Extract OWASP A07 credential guidance
   - Store in `applications/aphoria/dogfood/dbpool/docs/sources/`

3. ⏳ Create claims manually (or via skill)
   ```bash
   # Create each claim via CLI
   aphoria corpus create \
     --subject "dbpool/max_connections" \
     --predicate "required" \
     --value "true" \
     --explanation "Connection pools MUST have max_connections set to prevent unbounded growth that exhausts database connections" \
     --authority "HikariCP Configuration Guide" \
     --category "safety" \
     --tier 2

   # Repeat for all 25-30 claims
   ```

4. ⏳ Verify corpus storage
   ```bash
   # Query via API
   curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor&limit=100' | \
     jq '.items | map(select(.subject | startswith("dbpool"))) | length'

   # Expected: 25-30 items
   ```

**Deliverables:**
- [ ] `docs/sources/hikaricp-config.md` - HikariCP documentation
- [ ] `docs/sources/postgresql-pooling.md` - PostgreSQL guide
- [ ] `docs/sources/owasp-credentials.md` - OWASP A07 excerpts
- [ ] 25-30 claims in corpus database
- [ ] Verification report showing all claims queryable

**Time:** 4-6 hours

---

### Day 2: Initial Implementation (With Violations)

**Goal:** Write working code that compiles but violates best practices

**Tasks:**
1. ⏳ Create Cargo project
   ```bash
   cd applications/aphoria/dogfood/dbpool
   cargo init --lib
   ```

2. ⏳ Add dependencies
   ```toml
   [dependencies]
   tokio = { version = "1", features = ["full"] }
   tokio-postgres = "0.7"
   serde = { version = "1", features = ["derive"] }
   thiserror = "1"
   ```

3. ⏳ Implement `PoolConfig` with violations
   ```rust
   // src/config.rs
   pub struct PoolConfig {
       pub max_connections: Option<usize>,           // VIOLATION 1: unbounded
       pub min_connections: usize,                   // VIOLATION 5: zero default
       pub connection_timeout: Duration,             // VIOLATION 4: 60s
       pub max_lifetime: Option<Duration>,           // VIOLATION 3: missing
       pub connection_string: String,                // VIOLATION 2: plaintext password
       pub idle_timeout: Option<Duration>,
       pub validation_timeout: Duration,
   }
   ```

4. ⏳ Implement `ConnectionPool` with violations
   ```rust
   // src/pool.rs
   pub struct ConnectionPool {
       config: PoolConfig,
       connections: Arc<Mutex<Vec<Connection>>>,
       metrics: Option<PoolMetrics>,               // VIOLATION 7: None default
   }

   impl ConnectionPool {
       pub async fn get(&self) -> Result<Connection> {
           let mut conns = self.connections.lock().await;

           if let Some(conn) = conns.pop() {
               return Ok(conn);                     // VIOLATION 6: no validation
           }

           self.create_connection().await
       }
   }
   ```

5. ⏳ Add basic tests (that pass despite violations)
   ```rust
   #[tokio::test]
   async fn test_pool_creation() {
       let config = PoolConfig::default();
       let pool = ConnectionPool::new(config);
       assert!(pool.is_ok());
   }
   ```

**Deliverables:**
- [ ] `src/lib.rs` - Library root
- [ ] `src/config.rs` - PoolConfig with 5 violations
- [ ] `src/pool.rs` - ConnectionPool with 2 violations
- [ ] `src/connection.rs` - Connection wrapper
- [ ] `tests/basic.rs` - Basic functionality tests (passing)
- [ ] `Cargo.toml` - Dependencies configured
- [ ] Compiles successfully: `cargo build`

**Time:** 4-6 hours

---

### Day 3: First Scan & Verification

**Goal:** Run Aphoria scan and verify all violations detected

**Tasks:**
1. ⏳ Create Aphoria config
   ```toml
   # applications/aphoria/dogfood/dbpool/.aphoria/config.toml
   [project]
   name = "dbpool"

   [scan]
   include = ["src/**/*.rs"]
   exclude = ["tests/**"]

   [episteme]
   corpus_db = "/home/jml/.aphoria/corpus-db"
   ```

2. ⏳ Run initial scan
   ```bash
   cd applications/aphoria/dogfood/dbpool
   aphoria scan --format json > scan-results-v1.json
   ```

3. ⏳ Analyze results
   ```bash
   # Count violations by severity
   jq '.findings | group_by(.verdict) | map({verdict: .[0].verdict, count: length})' \
     scan-results-v1.json

   # Expected:
   # - BLOCK: 3 (unbounded, plaintext, missing lifetime)
   # - FLAG: 3 (timeout, min_conns, validation)
   # - WARNING: 2 (metrics, leak detection)
   ```

4. ⏳ Create verification report
   ```bash
   # Generate markdown report
   aphoria scan --format markdown > SCAN-REPORT-v1.md
   ```

5. ⏳ Take screenshots for demo
   - Terminal output showing 8 conflicts
   - JSON report with detailed explanations
   - Markdown report for documentation

**Deliverables:**
- [ ] `.aphoria/config.toml` - Aphoria configuration
- [ ] `scan-results-v1.json` - Initial scan results
- [ ] `SCAN-REPORT-v1.md` - Human-readable report
- [ ] `screenshots/violations-detected.png` - Visual proof
- [ ] Verification that all 7-8 violations detected

**Time:** 3-4 hours

---

### Day 4: Remediation & Re-verification

**Goal:** Fix violations one by one, re-scan after each fix

**Tasks:**
1. ⏳ Fix CRITICAL violations (one at a time)

   **Fix 1: Set max_connections**
   ```rust
   pub max_connections: usize,  // Changed from Option<usize>

   impl Default for PoolConfig {
       fn default() -> Self {
           Self {
               max_connections: 10,  // Development default
               // ...
           }
       }
   }
   ```
   - Re-scan: `aphoria scan --format json > scan-v2.json`
   - Verify: BLOCK violations: 3 → 2

   **Fix 2: Use environment variable for password**
   ```rust
   pub fn from_env() -> Result<Self> {
       let connection_string = std::env::var("DATABASE_URL")
           .map_err(|_| PoolError::MissingConnectionString)?;

       // Validate no plaintext password in code
       if connection_string.contains("password=") {
           return Err(PoolError::PlaintextPassword);
       }

       Ok(Self {
           connection_string,
           // ...
       })
   }
   ```
   - Re-scan: `aphoria scan --format json > scan-v3.json`
   - Verify: BLOCK violations: 2 → 1

   **Fix 3: Set max_lifetime**
   ```rust
   pub max_lifetime: Duration,  // Required, not Optional

   impl Default for PoolConfig {
       fn default() -> Self {
           Self {
               max_lifetime: Duration::from_secs(1800),  // 30 minutes
               // ...
           }
       }
   }
   ```
   - Re-scan: `aphoria scan --format json > scan-v4.json`
   - Verify: BLOCK violations: 1 → 0 ✅

2. ⏳ Fix ERROR violations

   **Fix 4: Reduce connection_timeout**
   ```rust
   connection_timeout: Duration::from_secs(30),  // Was 60
   ```

   **Fix 5: Set min_connections**
   ```rust
   min_connections: 2,  // Was 0
   ```

   **Fix 6: Add connection validation**
   ```rust
   pub async fn get(&self) -> Result<Connection> {
       let mut conns = self.connections.lock().await;

       if let Some(mut conn) = conns.pop() {
           // Validate before returning
           if conn.is_valid().await? {
               return Ok(conn);
           } else {
               // Discard stale connection, create new
               drop(conn);
           }
       }

       self.create_connection().await
   }
   ```

   - Re-scan: `aphoria scan --format json > scan-v5.json`
   - Verify: FLAG violations: 3 → 0 ✅

3. ⏳ Fix WARNING violations

   **Fix 7: Add metrics**
   ```rust
   pub struct PoolMetrics {
       pub total_connections: AtomicUsize,
       pub active_connections: AtomicUsize,
       pub idle_connections: AtomicUsize,
       pub waiting_requests: AtomicUsize,
   }

   impl ConnectionPool {
       pub fn metrics(&self) -> &PoolMetrics {
           &self.metrics
       }
   }
   ```

   **Fix 8: Add leak detection**
   ```rust
   pub leak_detection_threshold: Option<Duration>,

   impl Default for PoolConfig {
       fn default() -> Self {
           Self {
               leak_detection_threshold: Some(Duration::from_secs(60)),
               // ...
           }
       }
   }
   ```

   - Re-scan: `aphoria scan --format json > scan-v6.json`
   - Verify: WARNING violations: 2 → 0 ✅

4. ⏳ Final verification
   ```bash
   aphoria scan --format markdown > SCAN-REPORT-FINAL.md

   # Expected output:
   # ✅ All checks passed
   # 0 conflicts detected
   # Production ready
   ```

**Deliverables:**
- [ ] Updated `src/config.rs` - All violations fixed
- [ ] Updated `src/pool.rs` - Validation added, metrics exposed
- [ ] `src/metrics.rs` - Metrics implementation
- [ ] `scan-v2.json` through `scan-v6.json` - Progressive improvement
- [ ] `SCAN-REPORT-FINAL.md` - Clean scan report
- [ ] Git commits showing incremental fixes

**Time:** 6-8 hours

---

### Day 5: Documentation & Demo Preparation

**Goal:** Create compelling documentation and demo materials

**Tasks:**
1. ⏳ Write success story document
   ```markdown
   # Aphoria Success Story: dbpool

   ## The Challenge
   Building a database connection pool without introducing
   production incidents...

   ## Violations Detected
   - Critical: Unbounded connections (would have caused P0)
   - Critical: Plaintext credentials (security incident)
   - Critical: Missing max_lifetime (intermittent errors)
   ...

   ## Before/After Comparison
   [Screenshots showing violations → clean scan]

   ## Prevented Incidents
   - Connection exhaustion outage (estimated cost: $50K)
   - Security audit finding (compliance risk)
   - Production debugging hours (estimated: 20 engineer-hours)

   ## Conclusion
   Aphoria caught 8 violations before the first deployment.
   ```

2. ⏳ Create demo script
   ```bash
   #!/bin/bash
   # demo.sh - Live demonstration script

   echo "=== Aphoria Dogfood Demo: dbpool ==="
   echo
   echo "Step 1: Show initial violations"
   git checkout v0.1.0-violations
   aphoria scan --format table
   echo
   read -p "Press enter to fix critical violations..."

   echo "Step 2: Fix unbounded connections"
   git checkout v0.2.0-fix-unbounded
   aphoria scan --format table
   echo
   read -p "Press enter to continue..."

   # ... etc for each fix
   ```

3. ⏳ Record metrics
   ```bash
   # Scan performance
   time aphoria scan  # Should be ~0.25s (ephemeral)

   # Violation detection accuracy
   # Expected: 8/8 detected (100%)

   # False positive rate
   # Expected: 0/8 (0%)
   ```

4. ⏳ Create visual materials
   - Before/after comparison chart
   - Violation severity breakdown
   - Progressive fix timeline
   - Cost of prevented incidents

5. ⏳ Update roadmap
   - Mark dogfood project as complete
   - Document lessons learned
   - Identify improvements for next dogfood

**Deliverables:**
- [ ] `docs/SUCCESS-STORY.md` - Comprehensive case study
- [ ] `docs/DEMO-SCRIPT.md` - Step-by-step demo guide
- [ ] `demo.sh` - Automated demo script
- [ ] `docs/metrics.md` - Performance and accuracy metrics
- [ ] `docs/before-after.png` - Visual comparison
- [ ] Updated `applications/aphoria/roadmap.md`

**Time:** 4-6 hours

---

## Success Criteria

### Objective Metrics

| Metric | Target | How to Measure |
|--------|--------|----------------|
| **Claims Extracted** | 25-30 | `curl corpus API \| jq '.total_matching'` |
| **Violations Detected** | 7-8 | `jq '.findings \| length' scan-results-v1.json` |
| **Detection Accuracy** | 100% | All intentional violations found |
| **False Positives** | 0 | No spurious conflicts |
| **Scan Performance** | ≤0.3s | `time aphoria scan` (ephemeral mode) |
| **Final Scan Result** | 0 conflicts | `scan-v6.json` shows PASS |

### Qualitative Outcomes

- [ ] **Compelling Story:** "Aphoria prevented 3 potential P0 incidents"
- [ ] **Educational Value:** Each violation teaches a lesson (documented in explanations)
- [ ] **Production Ready:** Final code is genuinely production-worthy
- [ ] **Reusable:** Can be extracted as a real library
- [ ] **Demonstrable:** 5-minute demo shows clear value

### Documentation Completeness

- [ ] Plan document (this file)
- [ ] Success story with before/after
- [ ] Demo script for live presentations
- [ ] Metrics report showing accuracy
- [ ] Screenshots of violations and fixes
- [ ] Updated roadmap with completion

---

## Risks & Mitigations

### Risk 1: Claims Don't Match Code Patterns

**Scenario:** Extractors don't detect violations because concept paths don't align.

**Likelihood:** Medium
**Impact:** High (entire dogfood fails)

**Mitigation:**
1. Design concept paths BEFORE writing code
2. Verify extractors can detect patterns via unit tests
3. Use simple, regex-friendly patterns (avoid AST complexity)
4. Fallback: Write custom extractor for dbpool if needed

### Risk 2: Too Many False Positives

**Scenario:** Aphoria flags legitimate code as violations.

**Likelihood:** Low (we control both corpus and code)
**Impact:** Medium (undermines demo)

**Mitigation:**
1. Intentionally violate only clear, unambiguous rules
2. Use high-confidence claims (0.9+)
3. Test extractors on sample code before full implementation
4. Acknowledge false positives as known limitations

### Risk 3: Scan Performance Degrades

**Scenario:** Scan takes >0.5s, breaking fast scan promise.

**Likelihood:** Low (small codebase ~600 lines)
**Impact:** Low (still usable, just not impressive)

**Mitigation:**
1. Profile scan with `RUST_LOG=debug`
2. Use ephemeral mode (no persistence overhead)
3. Optimize hot paths if needed
4. Document actual performance in metrics report

### Risk 4: Time Overrun

**Scenario:** 5 days not enough to complete plan.

**Likelihood:** Medium
**Impact:** Low (can reduce scope)

**Mitigation:**
1. Prioritize critical path: claims → code → scan → fix
2. Defer nice-to-haves (leak detection, advanced metrics)
3. Reduce claim count to 20 if extraction takes too long
4. Extend to 6-7 days if needed (still within sprint)

---

## Follow-Up Opportunities

### Immediate (Week 2)

1. **Extract as Real Library**
   - Publish to crates.io as `aphoria-dbpool`
   - Add "Aphoria-verified" badge to README
   - Becomes reference implementation

2. **Add to Aphoria Examples**
   - Move to `applications/aphoria/examples/dbpool/`
   - Include in documentation as case study
   - Use in onboarding: "Try Aphoria on dbpool"

### Short-Term (Month 1)

3. **Extend to MySQL**
   - Add MySQL-specific claims
   - Test cross-database compatibility
   - Demonstrates corpus extensibility

4. **Add Advanced Features**
   - Connection retry logic
   - Dynamic pool sizing
   - Load-based auto-scaling
   - Each feature = new claims to validate

### Long-Term (Quarter 1)

5. **Production Deployment**
   - Use in a real service
   - Monitor for drift
   - Collect real-world violation examples
   - "We use Aphoria in production" credibility

6. **Community Contribution**
   - Open-source the library
   - Invite community to add claims
   - Demonstrate community corpus building

---

## Appendix A: Claim Templates

### Safety Claim Template
```bash
aphoria corpus create \
  --subject "dbpool/{component}/{property}" \
  --predicate "{required|recommended|must_be}" \
  --value "{value}" \
  --explanation "{What} MUST {do what} because {why}. If {violation}, then {consequence}." \
  --authority "{HikariCP|PostgreSQL|OWASP} {document name}" \
  --category "safety" \
  --tier 2 \
  --confidence 0.95
```

### Security Claim Template
```bash
aphoria corpus create \
  --subject "dbpool/{component}/{property}" \
  --predicate "{must_not_be|required}" \
  --value "{value}" \
  --explanation "{What} MUST NOT {do what} per {standard}. Violation exposes {threat}." \
  --authority "OWASP A07:2021" \
  --category "security" \
  --tier 1 \
  --confidence 0.98
```

### Performance Claim Template
```bash
aphoria corpus create \
  --subject "dbpool/{component}/{property}" \
  --predicate "{default_value|recommended_range}" \
  --value "{value}" \
  --explanation "{Property} SHOULD be {value} for {environment} to {achieve outcome}." \
  --authority "HikariCP Configuration Guide" \
  --category "performance" \
  --tier 2 \
  --confidence 0.90
```

---

## Appendix B: File Structure

```
applications/aphoria/dogfood/dbpool/
├── plan.md                          # This file
├── Cargo.toml                       # Rust project manifest
├── .aphoria/
│   └── config.toml                  # Aphoria scan configuration
├── src/
│   ├── lib.rs                       # Library root
│   ├── config.rs                    # PoolConfig (with violations → fixed)
│   ├── pool.rs                      # ConnectionPool (with violations → fixed)
│   ├── connection.rs                # Connection wrapper
│   ├── metrics.rs                   # Metrics implementation
│   └── error.rs                     # Error types
├── tests/
│   ├── basic.rs                     # Basic functionality tests
│   └── compliance.rs                # Aphoria compliance tests
├── docs/
│   ├── sources/
│   │   ├── hikaricp-config.md       # HikariCP documentation excerpts
│   │   ├── postgresql-pooling.md    # PostgreSQL guide excerpts
│   │   └── owasp-credentials.md     # OWASP A07 excerpts
│   ├── SUCCESS-STORY.md             # Case study document
│   ├── DEMO-SCRIPT.md               # Live demo guide
│   ├── metrics.md                   # Performance and accuracy metrics
│   └── before-after.png             # Visual comparison
├── screenshots/
│   ├── violations-detected.png      # Initial scan results
│   ├── fix-progression.png          # Progressive fixes
│   └── final-clean-scan.png         # Clean scan result
├── scan-results-v1.json             # Initial scan (8 violations)
├── scan-results-v2.json             # After fix 1 (7 violations)
├── ...                              # Progressive scans
├── scan-results-v6.json             # Final scan (0 violations)
├── SCAN-REPORT-v1.md                # Initial markdown report
├── SCAN-REPORT-FINAL.md             # Final markdown report
└── demo.sh                          # Automated demo script
```

---

## Appendix C: Git Commit Strategy

Tag each major milestone for easy demo navigation:

```bash
# Initial state
git tag v0.1.0-violations "Initial implementation with 8 violations"

# Fix critical violations
git tag v0.2.0-fix-unbounded "Fix unbounded max_connections"
git tag v0.3.0-fix-credentials "Fix plaintext password"
git tag v0.4.0-fix-lifetime "Fix missing max_lifetime"

# Fix error violations
git tag v0.5.0-fix-timeouts "Fix excessive timeouts and min_connections"
git tag v0.6.0-fix-validation "Add connection validation"

# Fix warning violations
git tag v0.7.0-fix-observability "Add metrics and leak detection"

# Final state
git tag v1.0.0-production-ready "All violations fixed, production ready"
```

---

## Status Tracking

| Phase | Status | Completed | Notes |
|-------|--------|-----------|-------|
| Day 1: Preparation | 🔄 IN PROGRESS | 2026-02-09 | Corpus building |
| Day 2: Implementation | ⏳ PENDING | - | - |
| Day 3: First Scan | ⏳ PENDING | - | - |
| Day 4: Remediation | ⏳ PENDING | - | - |
| Day 5: Documentation | ⏳ PENDING | - | - |

**Last Updated:** 2026-02-09
**Next Review:** 2026-02-10 (daily standup)