jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0fa7cfdf9b
stemedb/applications/aphoria/dogfood/msgqueue/claims-template.toml
jml 3dac3dc914 feat(aphoria): implement Day 3 debugging features and comprehensive documentation 
Implements all product gaps identified in msgqueue Day 3 evaluation (VG-DAY3-001/003/004)
and adds comprehensive documentation to prevent dogfooding failures.

## Product Features (VG-DAY3-XXX)

### VG-DAY3-001: --show-observations flag (P0)
- Shows all observations with concept paths for debugging extractor alignment
- Includes claim matching analysis (✅/❌ visual feedback)
- Explains tail-path matching and why observations don't match claims
- 8 unit tests in src/report/observations.rs
- 5 integration tests in src/tests/day3_debugging.rs

### VG-DAY3-003: aphoria extractors validate (P2)
- Validates extractor subject fields match claim concept_paths
- Smart fuzzy matching suggests corrections for typos
- Clear error messages with actionable hints
- Proper exit codes (0=success, 1=validation failed)

### VG-DAY3-004: aphoria extractors test NAME --file (P2)
- Tests single extractor pattern against one file (no full scan needed)
- Shows line numbers and matched text
- Previews what observation would be created
- Helpful troubleshooting when pattern doesn't match

## Documentation (P0-P1)

### New Docs Created
- docs/extractors/declarative-extractors.md (800 lines)
  - Complete field reference with emphasis on subject field format
  - 3 worked examples (timeout=0, unbounded queue, TLS disabled)
  - Common mistakes with fixes
  - Validation workflow
  - Debugging 0% detection rate

- docs/examples/extractors/timeout-zero-example.md (500 lines)
  - End-to-end flow: code → extractor → claim → conflict → fix
  - Visual diagrams showing path alignment
  - Troubleshooting guide
  - Validation checklist

- docs/dogfooding-common-mistakes.md (560 lines)
  - Mistake #1: Skipping Day 3 extractor creation (CRITICAL)
  - Mistake #2: Creating extractors with wrong subject format (NEW)
  - Evidence from msgqueue failures
  - Recovery procedures

### Docs Updated
- dogfood/msgqueue/plan.md (Day 3 Steps 3-4)
  - Added complete manual declarative extractor TOML format
  - Added validation workflow BEFORE scanning
  - Added debug workflow for 0% detection after creating extractors

- dogfood/msgqueue/eval/ (evaluation artifacts)
  - EVALUATION-REPORT-2026-02-10.md (600 lines)
  - DOC-FIXES-2026-02-10.md (summary of fixes)
  - IMPLEMENTATION-REVIEW-2026-02-10.md (feature review)

## New Extractors
- src/extractors/ack_mode_config.rs - Detects AckMode::AutoAck violations
- src/extractors/async_blocking.rs - Detects blocking calls in async functions
- src/extractors/unbounded_resources.rs - Detects unbounded queues/connections

## Code Changes
- src/cli/mod.rs: Add --show-observations flag to scan command
- src/cli/extractors.rs: Add Validate and Test subcommands
- src/handlers/scan.rs: Call format_observations when flag enabled
- src/handlers/extractors.rs: Implement handle_validate() and handle_test()
- src/report/observations.rs: Observation formatting with claim matching analysis
- src/tests/day3_debugging.rs: Integration tests for new features

## Dogfood Artifacts
- dogfood/msgqueue/ - Complete msgqueue Day 3 evaluation with findings
- dogfood/dbpool/ - Database pool dogfooding exercise

## Impact
- Time savings: 30 min per Day 3 debugging (67% faster)
- User experience: Transparent debugging (no blind trial-and-error)
- Documentation: 1,860 new lines covering all P0-P1 gaps

## Related Issues
- Closes VG-DAY3-001 (--show-observations)
- Closes VG-DAY3-002 (concept path alignment docs)
- Closes VG-DAY3-003 (extractors validate)
- Closes VG-DAY3-004 (extractors test)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-11 03:31:06 +00:00

400 lines
12 KiB
TOML
Raw Blame History

# Batch Claim Import Template for Message Queue Dogfood
#
# Import with: aphoria claims import claims-template.toml
#
# Options:
# --dry-run Preview without writing
# --validate-only Check format without importing
# --format json JSON output for scripting
#
# This template includes 22 claims:
# - 11 reused from httpclient/dbpool corpus (50% reuse)
# - 11 new for message queue domain
#
# IMPORTANT: ComparisonMode only supports:
# equals, not_equals, present, absent, contains, not_contains
#
# For numeric constraints, encode in predicate or use not_equals for "must not be X"
# =============================================================================
# REUSED FROM CORPUS (11 claims)
# =============================================================================
# 1. Consumer timeout (from httpclient) - must not be zero
[[claim]]
id = "msgqueue-001"
concept_path = "msgqueue/consumer/timeout"
predicate = "zero"
value = 0
comparison = "not_equals"
provenance = "AMQP 0-9-1 spec - Connection lifecycle"
invariant = "Consumer timeout MUST NOT be zero"
consequence = "timeout=0 causes indefinite blocking under connection loss"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 2. TLS certificate validation (from httpclient) - must be enabled
[[claim]]
id = "msgqueue-002"
concept_path = "msgqueue/tls/certificate_validation"
predicate = "required"
value = true
comparison = "equals"
provenance = "RabbitMQ Best Practices - Security"
invariant = "TLS certificate validation MUST be enabled in production"
consequence = "Disabled validation allows MITM attacks"
authority_tier = "expert"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "security"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 3. Max connections (from dbpool) - must be bounded
[[claim]]
id = "msgqueue-003"
concept_path = "msgqueue/connection/max_connections"
predicate = "bounded"
value = true
comparison = "equals"
provenance = "RabbitMQ Best Practices - Connection pooling"
invariant = "Max connections MUST be bounded (1-10 recommended)"
consequence = "Unbounded connections exhaust broker file descriptors"
authority_tier = "expert"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 4. Connection lifecycle (from dbpool)
[[claim]]
id = "msgqueue-004"
concept_path = "msgqueue/connection/lifecycle"
predicate = "handshake_required"
value = true
comparison = "equals"
provenance = "AMQP 0-9-1 spec - Connection handshake"
invariant = "Connection MUST complete full handshake (Start, Tune, Open)"
consequence = "Skipped handshake results in protocol violation"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "correctness"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 5. Metrics enabled (from httpclient)
[[claim]]
id = "msgqueue-005"
concept_path = "msgqueue/metrics/enabled"
predicate = "required"
value = true
comparison = "equals"
provenance = "Observability best practices"
invariant = "Metrics MUST be enabled for production monitoring"
consequence = "No metrics blinds operators to performance issues"
authority_tier = "community"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "observability"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 6. Retry max attempts (from httpclient) - must be bounded
[[claim]]
id = "msgqueue-006"
concept_path = "msgqueue/retry/max_attempts"
predicate = "bounded"
value = true
comparison = "equals"
provenance = "RabbitMQ redelivery semantics"
invariant = "Retry attempts MUST be bounded (1-5 recommended)"
consequence = "Unbounded retries create infinite loops"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 7. Retry backoff strategy (from httpclient)
[[claim]]
id = "msgqueue-007"
concept_path = "msgqueue/retry/backoff_strategy"
predicate = "exponential_required"
value = true
comparison = "equals"
provenance = "Exponential backoff best practices"
invariant = "Retry backoff MUST be exponential with jitter"
consequence = "Constant backoff amplifies load spikes"
authority_tier = "community"
evidence = ["docs/sources/lapin-library.md"]
category = "performance"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 8. Connection cleanup (from dbpool)
[[claim]]
id = "msgqueue-008"
concept_path = "msgqueue/connection/cleanup"
predicate = "required"
value = true
comparison = "equals"
provenance = "AMQP connection closure semantics"
invariant = "Connections MUST be closed on drop"
consequence = "Missing cleanup leaks broker resources"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 9. Async runtime (from httpclient)
[[claim]]
id = "msgqueue-009"
concept_path = "msgqueue/async/runtime"
predicate = "blocking_forbidden"
value = true
comparison = "equals"
provenance = "lapin tokio requirements"
invariant = "Async functions MUST NOT use blocking operations"
consequence = "Blocking in async degrades throughput to <10 msg/sec"
authority_tier = "expert"
evidence = ["docs/sources/lapin-library.md"]
category = "performance"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 10. Connection idle timeout (from dbpool) - must be present
[[claim]]
id = "msgqueue-010"
concept_path = "msgqueue/connection/idle_timeout"
predicate = "configured"
value = true
comparison = "equals"
provenance = "RabbitMQ heartbeat recommendations"
invariant = "Idle timeout MUST be configured (30-60s recommended)"
consequence = "No timeout fails to detect dead connections"
authority_tier = "community"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 11. TLS min version (from httpclient)
[[claim]]
id = "msgqueue-011"
concept_path = "msgqueue/tls/min_version"
predicate = "version"
value = "1.2"
comparison = "equals"
provenance = "TLS security best practices"
invariant = "TLS version MUST be >= 1.2"
consequence = "TLS 1.0/1.1 vulnerable to POODLE, BEAST attacks"
authority_tier = "expert"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "security"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# =============================================================================
# NEW FOR MESSAGE QUEUE (11 claims)
# =============================================================================
# 12. Prefetch count - must be bounded
[[claim]]
id = "msgqueue-012"
concept_path = "msgqueue/consumer/prefetch_count"
predicate = "bounded"
value = true
comparison = "equals"
provenance = "AMQP QoS prefetch specification"
invariant = "Prefetch count MUST be bounded (1-100 recommended)"
consequence = "prefetch=0 causes OOM; prefetch>100 exhausts broker"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 13. Ack mode - manual recommended
[[claim]]
id = "msgqueue-013"
concept_path = "msgqueue/consumer/ack_mode"
predicate = "manual_recommended"
value = true
comparison = "equals"
provenance = "AMQP acknowledgment modes"
invariant = "Manual ack SHOULD be used for reliable processing"
consequence = "Auto-ack before processing causes data loss on crash"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 14. Ack timeout - must not be zero
[[claim]]
id = "msgqueue-014"
concept_path = "msgqueue/consumer/ack_timeout"
predicate = "zero"
value = 0
comparison = "not_equals"
provenance = "RabbitMQ consumer timeout"
invariant = "Ack timeout MUST NOT be zero (30-120s recommended)"
consequence = "No timeout allows infinite processing, blocking queue"
authority_tier = "community"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 15. Queue max size - must be bounded
[[claim]]
id = "msgqueue-015"
concept_path = "msgqueue/queue/max_size"
predicate = "bounded"
value = true
comparison = "equals"
provenance = "lapin backpressure patterns"
invariant = "In-memory queue MUST be bounded (100-10000 recommended)"
consequence = "Unbounded queue causes OOM under sustained load"
authority_tier = "expert"
evidence = ["docs/sources/lapin-library.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 16. Backpressure strategy
[[claim]]
id = "msgqueue-016"
concept_path = "msgqueue/consumer/backpressure_strategy"
predicate = "required"
value = true
comparison = "equals"
provenance = "RabbitMQ backpressure best practices"
invariant = "Backpressure strategy MUST be implemented (pause/drop/error)"
consequence = "No backpressure causes OOM when producer > consumer rate"
authority_tier = "expert"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 17. Heartbeat interval - must be configured
[[claim]]
id = "msgqueue-017"
concept_path = "msgqueue/connection/heartbeat_interval"
predicate = "configured"
value = true
comparison = "equals"
provenance = "AMQP heartbeat negotiation"
invariant = "Heartbeat interval MUST be configured (10-60s recommended)"
consequence = "No heartbeat fails to detect dead connections"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 18. Requeue limit - must be bounded
[[claim]]
id = "msgqueue-018"
concept_path = "msgqueue/consumer/requeue_limit"
predicate = "bounded"
value = true
comparison = "equals"
provenance = "RabbitMQ redelivery semantics"
invariant = "Requeue attempts MUST be bounded (3-5 recommended)"
consequence = "Unlimited requeues create poison message loops"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 19. Queue durable
[[claim]]
id = "msgqueue-019"
concept_path = "msgqueue/queue/durable"
predicate = "production_required"
value = true
comparison = "equals"
provenance = "AMQP queue persistence"
invariant = "Production queues MUST be durable"
consequence = "Non-durable queues lose all messages on broker restart"
authority_tier = "expert"
evidence = ["docs/sources/amqp-spec.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 20. Consumer exclusive
[[claim]]
id = "msgqueue-020"
concept_path = "msgqueue/consumer/exclusive"
predicate = "required_for_ordering"
value = true
comparison = "equals"
provenance = "AMQP exclusive consumer semantics"
invariant = "Exclusive mode MUST be set when ordering is required"
consequence = "Non-exclusive consumers race, breaking message order"
authority_tier = "community"
evidence = ["docs/sources/lapin-library.md"]
category = "correctness"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 21. Recovery strategy
[[claim]]
id = "msgqueue-021"
concept_path = "msgqueue/connection/recovery_strategy"
predicate = "auto_reconnect_required"
value = true
comparison = "equals"
provenance = "lapin connection recovery"
invariant = "Auto-reconnect MUST be enabled for resilience"
consequence = "No auto-reconnect means transient failures are permanent"
authority_tier = "expert"
evidence = ["docs/sources/lapin-library.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
# 22. Dead letter queue
[[claim]]
id = "msgqueue-022"
concept_path = "msgqueue/consumer/dead_letter_queue"
predicate = "required"
value = true
comparison = "equals"
provenance = "RabbitMQ DLX best practices"
invariant = "Dead letter exchange MUST be configured"
consequence = "No DLX means poison messages block queue forever"
authority_tier = "expert"
evidence = ["docs/sources/rabbitmq-docs.md"]
category = "safety"
status = "active"
created_by = "dogfood-exercise"
created_at = "2026-02-10T00:00:00Z"
Reference in New Issue View Git Blame Copy Permalink