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

Dogfood Project: Message Queue Consumer Library

Start Date: 2026-02-10 Hypothesis: Async connection patterns + resource limits from httpclient/dbpool corpora transfer to message queue consumers with 50%+ pattern reuse, demonstrating cross-domain flywheel strength.

Corpus Overlap: httpclient + dbpool → ~50% pattern reuse expected

Target Metrics:

• Time savings: ≥60% vs manual (4 hrs manual → 1.5-2 hrs with flywheel)
• Pattern reuse: ≥50% of claims (11+/22)
• Detection rate: ≥90% of violations (8/8 or 7/8)
• Naming errors: <2 (corpus conventions established)

---

Why This Domain?

Message queue consumers combine:

• Async patterns from httpclient (timeout, retry, TLS, metrics)
• Resource limits from dbpool (max connections, lifecycle, cleanup)
• New patterns unique to messaging (backpressure, ack_timeout, queue_size)

This tests whether the flywheel adapts across domains - if patterns learned in HTTP/DB contexts transfer to async messaging, the knowledge compounding mechanism is working.

---

Day 1: Claims Extraction (1-2 hours)

Goal: Author 22 claims (11 reused from corpus, 11 new) using pattern discovery

Skills:

• /aphoria-suggest --corpus httpclient,dbpool - discover reusable patterns
• /aphoria-claims - author claims with full provenance

Process:

Step 1: Pattern Discovery (30 min)

# Use skill to analyze both corpora
/aphoria-suggest --corpus httpclient,dbpool --domain msgqueue

# Expected reusable patterns:
# From httpclient: timeout, retry, tls, async, metrics
# From dbpool: max_connections, connection_lifecycle, cleanup
# New for msgqueue: backpressure, queue_size, ack_timeout

Step 2: Authority Source Curation (30 min)

Fetch and extract key sections:

1. AMQP 0-9-1 Protocol Spec (Tier 1 - Standards)
   • Connection lifecycle, acknowledgment modes, QoS
2. RabbitMQ Best Practices (Tier 2 - Vendor)
   • Consumer prefetch, heartbeat, timeout recommendations
3. lapin Library Docs (Tier 3 - Community)
   • Rust async patterns, connection pooling, error handling

Step 3: Claim Authoring (30-60 min)

Use /aphoria-claims to create 22 claims:

Reused from Corpus (11 expected):

1. msgqueue/consumer/timeout (from httpclient)
2. msgqueue/tls/certificate_validation (from httpclient)
3. msgqueue/connection/max_connections (from dbpool)
4. msgqueue/connection/lifecycle (from dbpool)
5. msgqueue/metrics/enabled (from httpclient)
6. msgqueue/retry/max_attempts (from httpclient)
7. msgqueue/retry/backoff_strategy (from httpclient)
8. msgqueue/connection/cleanup (from dbpool)
9. msgqueue/async/runtime (from httpclient)
10. msgqueue/connection/idle_timeout (from dbpool)
11. msgqueue/tls/min_version (from httpclient)

New for Message Queue (11 expected): 12. msgqueue/consumer/prefetch_count - QoS setting (1-100) 13. msgqueue/consumer/ack_mode - auto vs manual acknowledgment 14. msgqueue/consumer/ack_timeout - must ack within N seconds 15. msgqueue/queue/max_size - bounded queue prevents OOM 16. msgqueue/consumer/backpressure_strategy - pause vs drop vs error 17. msgqueue/connection/heartbeat_interval - keepalive (10-60s) 18. msgqueue/consumer/requeue_limit - max redeliveries (3-5) 19. msgqueue/queue/durable - persistence for crash recovery 20. msgqueue/consumer/exclusive - single consumer guarantee 21. msgqueue/connection/recovery_strategy - auto-reconnect logic 22. msgqueue/consumer/dead_letter_queue - failed message handling

Step 4: Batch Import (Recommended)

# Import all 22 claims at once from TOML template
aphoria claims import claims-template.toml

# Or preview first with dry-run
aphoria claims import claims-template.toml --dry-run

# Or validate format without importing
aphoria claims import claims-template.toml --validate-only

Target Output:

• 22 claims in .aphoria/claims.toml
• 11/22 (50%) reused from httpclient/dbpool
• 0 naming errors (follow corpus conventions: /{domain}/{concept}/{property})
• Daily summary: DAY1-SUMMARY.md

Success Criteria:

• ✅ All claims have: provenance, invariant, consequence, authority tier
• ✅ Reuse rate ≥ 50%
• ✅ Time ≤ 2 hours (60%+ faster than 4-5 hr baseline)

---

Day 2: Implementation (2-4 hours)

Goal: Build Rust message queue consumer library with 8 intentional violations

Tech Stack:

• lapin (AMQP client for RabbitMQ)
• tokio (async runtime)
• thiserror (error handling)

Violations (Intentional):

1. Zero Timeout → Indefinite Blocking

// @aphoria:claim[safety] Consumer timeout MUST be >0 -- timeout=0 causes indefinite blocking under connection loss
pub timeout: Duration = Duration::from_secs(0); // ❌ VIOLATION

Consequence: Consumer hangs forever if broker is unresponsive Location: src/config.rs:15

2. Missing Backpressure → OOM Under Load

// @aphoria:claim[safety] Consumer MUST implement backpressure -- unbounded queue causes OOM under sustained load
pub max_queue_size: Option<usize> = None; // ❌ VIOLATION (unbounded)

Consequence: Memory exhaustion when broker sends faster than consumer processes Location: src/config.rs:23

3. Unbounded Prefetch → Resource Exhaustion

// @aphoria:claim[safety] Prefetch count MUST be bounded (1-100) -- unbounded prefetch exhausts memory
pub prefetch_count: u16 = u16::MAX; // ❌ VIOLATION

Consequence: Broker sends all messages at once, overwhelming consumer Location: src/config.rs:31

4. Auto-Ack Without Processing → Data Loss

// @aphoria:claim[safety] Auto-ack MUST only be used with guaranteed processing -- auto-ack before processing causes data loss
pub ack_mode: AckMode = AckMode::AutoAck; // ❌ VIOLATION (no processing guarantee)

Consequence: Message acknowledged before processing → lost on crash Location: src/consumer.rs:45

5. No Requeue Limit → Infinite Retry Loops

// @aphoria:claim[safety] Requeue limit MUST be set (3-5) -- infinite requeues create poison message loops
pub max_requeues: Option<u32> = None; // ❌ VIOLATION (infinite)

Consequence: Failed messages requeue forever, blocking queue Location: src/consumer.rs:67

6. Missing TLS Validation → MITM Attacks

// @aphoria:claim[security] TLS certificate validation MUST be enabled -- disabled validation allows MITM
pub verify_tls: bool = false; // ❌ VIOLATION

Consequence: Attacker intercepts message queue traffic Location: src/connection.rs:89

7. No Connection Pooling → Resource Exhaustion

// @aphoria:claim[performance] Connection pool MUST be bounded (1-10) -- unbounded connections exhaust broker resources
pub max_connections: Option<usize> = None; // ❌ VIOLATION

Consequence: Spawns unlimited connections, DoS on broker Location: src/connection.rs:102

8. Synchronous Processing → Throughput Collapse

// @aphoria:claim[performance] Message processing MUST be async -- synchronous processing blocks event loop
pub async fn process_message(&self, msg: Message) {
    std::thread::sleep(Duration::from_secs(1)); // ❌ VIOLATION (blocking in async)
}

Consequence: Blocks tokio runtime, throughput drops to 1 msg/sec Location: src/processor.rs:34

Process:

1. Create src/ files: config.rs, consumer.rs, connection.rs, processor.rs, lib.rs
2. Implement happy path: connect → subscribe → consume → ack
3. Embed 8 violations with inline markers
4. Add unit tests for non-violating code paths
5. Keep code realistic (not toy example)

Target Output:

• Working consumer library (basic pub/sub functionality)
• 8 embedded violations with inline markers
• Daily summary: DAY2-SUMMARY.md

Success Criteria:

• ✅ All violations have inline markers
• ✅ Code compiles and runs
• ✅ Time ≤ 4 hours

---

Day 3: Scanning (1-2 hours)

Goal: Detect 8/8 violations via aphoria scan AND create extractors for gaps

⚠️ THIS IS THE CORE FLYWHEEL STEP - Day 3 validates autonomous learning. Do NOT skip extractor creation.

Prerequisites (Pre-Flight Check):

# 1. Verify skill availability
/help | grep aphoria-custom-extractor-creator
# Expected: Skill should be listed

# 2. Verify inline markers present
grep -r "@aphoria:claim" src/ | wc -l
# Expected: 8 markers (one per violation)

# 3. Verify code compiles
cargo check
# Expected: Success

If any check fails, STOP and fix before proceeding.

---

Process:

Step 1: Baseline Scan (15 min)

cd /path/to/dogfood/msgqueue
aphoria scan --format json > scan-results-v1.json
aphoria scan --format markdown > SCAN-REPORT-v1.md

Expected on FIRST scan: Low detection rate (0-20%) is NORMAL for new domains because extractors don't exist yet.

This is NOT a failure - it's the signal that Step 3 (extractor creation) is needed.

---

Step 2: Gap Analysis (15 min) [REQUIRED]

Analyze scan-results-v1.json:

• Which claims show "MISSING" verdict? (no observations found)
• Which violations have inline markers but weren't detected?
• What patterns need extractors?

Create gap analysis table:

| Violation | Location | Marker Present? | Observation Found? | Action |
|-----------|----------|----------------|-------------------|--------|
| timeout=0 | config.rs:20 | ✅ | ❌ | Create extractor |
| prefetch=MAX | config.rs:33 | ✅ | ❌ | Create extractor |
... (8 total)

---

Step 3: Extractor Creation (30 min) [REQUIRED - DO NOT SKIP]

⚠️ CRITICAL: This step is REQUIRED. Skipping this breaks the autonomous learning flywheel.

For EACH missed violation (8 total), use skill to create extractor:

# Load skill if not already loaded:
/aphoria-custom-extractor-creator

# Create extractors for each violation:
/aphoria-custom-extractor-creator --violation "timeout=0" --claim msgqueue-001
/aphoria-custom-extractor-creator --violation "prefetch_count=u16::MAX" --claim msgqueue-012
/aphoria-custom-extractor-creator --violation "verify_certificates=false" --claim msgqueue-002
/aphoria-custom-extractor-creator --violation "blocking in async fn" --claim msgqueue-009
/aphoria-custom-extractor-creator --violation "max_queue_size=None" --claim msgqueue-015
/aphoria-custom-extractor-creator --violation "ack_mode=AutoAck" --claim msgqueue-013
/aphoria-custom-extractor-creator --violation "max_requeue_count=None" --claim msgqueue-018
/aphoria-custom-extractor-creator --violation "max_connections=None" --claim msgqueue-003

# The skill will automatically:
# 1. Analyze the violation pattern
# 2. Generate regex extractor
# 3. Map to correct concept_path
# 4. Save to .aphoria/extractors/{name}.toml
# 5. Verify extractor loads correctly

Verification:

ls .aphoria/extractors/*.toml | wc -l
# Expected: 8 extractor files

# Verify directory was created:
ls .aphoria/extractors/
# Expected: timeout_zero.toml, prefetch_unbounded.toml, tls_disabled.toml, etc.

If skill is unavailable: You can manually create declarative extractors. Follow the format below:

Manual Fallback (Declarative Extractor):

Add to .aphoria/config.toml for EACH violation:

[[extractors.declarative]]
name = "descriptive_name"
pattern = 'regex_pattern_matching_code'
languages = ["rust"]

[extractors.declarative.claim]
subject = "FULL_CLAIM_CONCEPT_PATH"  # ← Copy from claim's concept_path EXACTLY
predicate = "claim_predicate"
value = inverted_value  # false if claim expects true, 0 if claim expects > 0
confidence = 0.95

⚠️ CRITICAL: subject must EXACTLY match your claim's concept_path.

Example: If claim has concept_path = "msgqueue/queue/max_size", Then extractor needs subject = "msgqueue/queue/max_size" (not just "queue/max_size")

Complete Example (timeout=0):

[[extractors.declarative]]
name = "timeout_zero_detector"
pattern = 'timeout:\s*Duration::from_secs\(0\)'
languages = ["rust"]

[extractors.declarative.claim]
subject = "msgqueue/config/timeout"  # ← Matches claim concept_path exactly
predicate = "zero"
value = 0
confidence = 0.95

Validation Before Scanning:

# 1. Check subject matches claim concept_path
grep "subject =" .aphoria/config.toml
grep "concept_path =" .aphoria/claims.toml
# Subjects should match concept_paths EXACTLY

# 2. Test regex pattern matches code
grep -rE 'timeout:\s*Duration::from_secs\(0\)' src/
# Should find the violation line

# 3. Verify TOML syntax
cargo install taplo-cli
taplo fmt --check .aphoria/config.toml

See also: docs/extractors/declarative-extractors.md for complete reference.

---

Step 4: Verification Scan (15 min) [REQUIRED]

aphoria scan --format json > scan-results-v2.json
aphoria scan --format markdown > SCAN-REPORT-v2.md

Expected: Detection rate ≥90% (8/8 or 7/8 violations detected)

Compare v1 vs v2:

• v1: 0/8 detected (0%) - before extractors
• v2: 8/8 detected (100%) - after extractors
• Improvement: +100 percentage points

If detection rate is still 0% (extractors don't match claims):

This means extractors ran but observations didn't align with claims. Debug:

# Step 1: Verify observations were created
jq '.observations | length' scan-results-v2.json
# Expected: > 0 (if 0, patterns don't match code)

# Step 2: Compare observation paths vs claim paths
jq '.observations[].concept_path' scan-results-v2.json | sort -u
grep "concept_path =" .aphoria/claims.toml | sort -u
# Observation paths should END with same tail as claim paths

# Step 3: Check for tail-path mismatch
# Example mismatch:
# - Observation: queue/max_size (extractor subject too short)
# - Claim: msgqueue/queue/max_size (needs full path)
# - Fix: Update extractor subject = "msgqueue/queue/max_size"

# Step 4: Verify predicate alignment
jq '.observations[].predicate' scan-results-v2.json | sort -u
grep "predicate =" .aphoria/claims.toml | sort -u
# Must match exactly

Common Issue: Extractor subject doesn't match claim concept_path. Fix: Update extractor subject to use full path matching claim.

Example Fix:

# Before (WRONG):
[extractors.declarative.claim]
subject = "queue/max_size"  # ❌ Missing "msgqueue/" prefix

# After (CORRECT):
[extractors.declarative.claim]
subject = "msgqueue/queue/max_size"  # ✅ Matches claim exactly

Re-scan after fixing:

aphoria scan --format json > scan-results-v3.json
# Should now show 8/8 conflicts

---

Step 5: Documentation (15 min) [REQUIRED]

Create DAY3-SUMMARY.md with:

## Metrics

| Metric | Target | Actual | Delta |
|--------|--------|--------|-------|
| Detection (v1) | N/A | 0/8 (0%) | Baseline |
| Extractors created | 8 | 8 | ✅ |
| Detection (v2) | ≥90% | 8/8 (100%) | ✅ +100% |
| Time spent | ≤2 hrs | {actual} | {+/-} |

## Extractors Created

1. timeout_zero.toml - Detects Duration::from_secs(0)
2. prefetch_unbounded.toml - Detects u16::MAX prefetch
3. tls_disabled.toml - Detects verify_certificates=false
4. blocking_in_async.toml - Detects std::thread::sleep in async fn
5. unbounded_queue.toml - Detects max_queue_size=None
6. auto_ack.toml - Detects AckMode::AutoAck
7. infinite_requeue.toml - Detects max_requeue_count=None
8. unbounded_connections.toml - Detects max_connections=None

## Learning Captured

### Patterns Identified:
- Rust Option<T> = None → "unbounded" pattern (5 violations)
- std::thread::sleep in async fn → "blocking-in-async" anti-pattern
- u16::MAX → "unbounded integer" pattern

### Corpus Growth:
- 8 new extractors applicable to all future Rust msgqueue projects
- 3 extractors (timeout, TLS, blocking-in-async) reusable across HTTP/DB/msgqueue domains

**Target Output:**
- Scan v1 report (baseline)
- **8 extractor files** in `.aphoria/extractors/`
- Scan v2 report (**8/8 violations detected**)
- Daily summary: `DAY3-SUMMARY.md`

**Success Criteria:**
- ✅ Pre-flight checks pass (skill available, markers present, code compiles)
- ✅ Gap analysis completed (table of missed violations)
- ✅ **8 extractors created** (one per violation) - **CRITICAL**
- ✅ Detection rate ≥ 90% in v2 scan (8/8 or 7/8)
- ✅ Detection rate improvement documented (v1 → v2)
- ✅ Zero false positives
- ✅ Time ≤ 2 hours

**Evidence of Correct Execution:**
```bash
# These MUST exist after Day 3:
ls .aphoria/extractors/*.toml | wc -l  # Should be: 8
ls scan-results-v2.json                # Should exist
ls DAY3-SUMMARY.md                     # Should exist

If ANY of these are missing, Day 3 was not completed correctly. Redo Steps 3-5.

---

Day 4: Remediation (2-4 hours)

Goal: Progressive fixes - remove violations one by one, verify after each

Process:

Fix 1: Zero Timeout (15 min)

- pub timeout: Duration = Duration::from_secs(0);
+ pub timeout: Duration = Duration::from_secs(30);

aphoria scan --format json > scan-v1.json  # Should show 7 conflicts

Fix 2: Missing Backpressure (20 min)

- pub max_queue_size: Option<usize> = None;
+ pub max_queue_size: Option<usize> = Some(1000);

aphoria scan --format json > scan-v2.json  # Should show 6 conflicts

Fix 3: Unbounded Prefetch (15 min)

- pub prefetch_count: u16 = u16::MAX;
+ pub prefetch_count: u16 = 10;

aphoria scan --format json > scan-v3.json  # Should show 5 conflicts

Fix 4: Auto-Ack Without Processing (30 min)

- pub ack_mode: AckMode = AckMode::AutoAck;
+ pub ack_mode: AckMode = AckMode::ManualAck;
+ // Add proper ack after processing

Fix 5: No Requeue Limit (20 min)

- pub max_requeues: Option<u32> = None;
+ pub max_requeues: Option<u32> = Some(3);

Fix 6: Missing TLS Validation (15 min)

- pub verify_tls: bool = false;
+ pub verify_tls: bool = true;

Fix 7: No Connection Pooling (30 min)

- pub max_connections: Option<usize> = None;
+ pub max_connections: Option<usize> = Some(5);

Fix 8: Synchronous Processing (30 min)

- std::thread::sleep(Duration::from_secs(1));
+ tokio::time::sleep(Duration::from_secs(1)).await;

Final Verification (15 min)

aphoria scan --format json > scan-final.json
# Expected: 0 conflicts

Target Output:

• All 8 violations fixed
• Progressive scan results: 8 → 7 → 6 → ... → 0
• Daily summary: DAY4-SUMMARY.md

Success Criteria:

• ✅ Final scan: 0 conflicts
• ✅ Each fix verified independently
• ✅ Time ≤ 4 hours

---

Day 5: Documentation (2-3 hours)

Goal: Comprehensive report with metrics, findings, product gaps

Process:

Step 1: Calculate Final Metrics (30 min)

| Metric | Target | Actual | Delta | Analysis |
|--------|--------|--------|-------|----------|
| Total time | ≤10 hrs | {actual} | {+/-} | {Why different?} |
| Pattern reuse | ≥50% | {actual}% | {+/-} | {Which 11 patterns?} |
| Detection rate | ≥90% | {actual}% | {+/-} | {What missed?} |
| Naming errors | <2 | {actual} | {+/-} | {Examples if any} |
| Time savings | ≥60% | {actual}% | {+/-} | {vs 4hr baseline} |

Step 2: Write DAY5-DOGFOODING-REPORT.md (90 min)

Use dogfood/httpclient/DAY5-DOGFOODING-REPORT.md as template.

Required Sections:

1. Executive Summary (3 paragraphs)

   • Hypothesis tested
   • Key finding (flywheel works/breaks at which step?)
   • Critical gaps discovered

2. What We Built (detailed per-day breakdown)

   • Day 1: Claims extraction results
   • Day 2: Implementation with violations
   • Day 3: Scanning results
   • Day 4: Remediation progression
   • Day 5: This document

3. What Worked (Flywheel Successes)

   • Pattern reuse examples (httpclient → msgqueue, dbpool → msgqueue)
   • Time savings calculation
   • Zero naming errors (corpus conventions)

4. What Broke (Product Gaps)

   • Priority 1 (Blockers)
   • Priority 2 (Major)
   • Priority 3 (Minor)

5. Product Gap Analysis (table with VG-XXX IDs, severity, effort, ROI)

6. Recommendations

   • Immediate (this sprint)
   • Short-term (next 2 sprints)
   • Long-term (roadmap)

7. Appendices

   • Daily summaries
   • Claims created (list all 22)
   • Violations embedded (list all 8)

Step 3: Update README (15 min)

Add links to:

• Final report
• Daily summaries
• Key findings

Step 4: Archive & Review (15 min)

# Verify all files present
ls -la dogfood/msgqueue/
# Expected: plan.md, README.md, DAY1-5-SUMMARY.md, DAY5-DOGFOODING-REPORT.md

Target Output:

• DAY5-DOGFOODING-REPORT.md (500-800 lines)
• Updated README with report link
• All metrics quantified

Success Criteria:

• ✅ All metrics quantified
• ✅ Product gaps prioritized (P1/P2/P3)
• ✅ Recommendations actionable
• ✅ Time ≤ 3 hours

---

Success Metrics (Summary)

Metric	Target	Notes
Total Time	≤10 hours	Compressed from 5 days to validate efficiency
Pattern Reuse	≥50%	11/22 claims from httpclient + dbpool
Detection Rate	≥90%	8/8 or 7/8 violations caught
Naming Errors	<2	Corpus conventions prevent mistakes
Time Savings	≥60%	Day 1 claims in 1.5-2 hrs vs 4 hrs manual

---

Authority Sources

AMQP 0-9-1 Protocol Specification (Tier 1 - Standards)

• URL: https://www.rabbitmq.com/amqp-0-9-1-reference.html
• Relevance: Defines connection lifecycle, acknowledgment modes, QoS prefetch
• Covered Claims: connection/lifecycle, consumer/ack_mode, consumer/prefetch_count

RabbitMQ Best Practices (Tier 2 - Vendor)

• URL: https://www.rabbitmq.com/best-practices.html
• Relevance: Official guidance on consumer timeouts, heartbeat intervals, connection pooling
• Covered Claims: consumer/timeout, connection/heartbeat_interval, connection/max_connections

lapin Library Documentation (Tier 3 - Community)

• URL: https://docs.rs/lapin/latest/lapin/
• Relevance: Rust async patterns, error handling, connection management
• Covered Claims: async/runtime, connection/recovery_strategy, consumer/backpressure_strategy

---

References

• httpclient dogfood: dogfood/httpclient/ (gold standard)
• dbpool dogfood: dogfood/dbpool/ (connection management patterns)
• Claims authoring: /aphoria-claims skill
• Pattern discovery: /aphoria-suggest skill
• Extractor creation: /aphoria-custom-extractor-creator skill

---

Daily Checklist

Day 1: Claims ✅

• Run /aphoria-suggest --corpus httpclient,dbpool
• Create 22 claims (11 reused, 11 new)
• Write DAY1-SUMMARY.md

Day 2: Implementation ✅

• Build Rust consumer library
• Embed 8 violations with inline markers
• Write DAY2-SUMMARY.md

Day 3: Scanning ✅

• Run aphoria scan
• Generate missing extractors if needed
• Write DAY3-SUMMARY.md

Day 4: Remediation ✅

• Fix violations progressively (8 → 0)
• Verify after each fix
• Write DAY4-SUMMARY.md

Day 5: Documentation ✅

• Calculate final metrics
• Write DAY5-DOGFOODING-REPORT.md
• Update README
• Archive summaries

---

Ready to start Day 1! Use /aphoria-suggest and /aphoria-claims to author 22 claims with 50%+ corpus reuse.