e758f2ebfb
Completes Task #3 of httpclient dogfooding with 100% detection rate (7/7 violations). ## New Extractors - **OptionBoundsExtractor**: Detects Option<T> fields set to None (unbounded) - **OptionValueExtractor**: Extracts values from Some(n) for threshold checks Both extractors use context-aware pattern matching to understand Rust Option<T> semantics, which declarative extractors cannot handle. ## Implementation **Files Created**: - applications/aphoria/src/extractors/option_bounds.rs (257 lines) - applications/aphoria/src/extractors/option_value.rs (277 lines) - applications/aphoria/docs/examples/extractors/programmatic-option-semantics.md **Files Modified**: - applications/aphoria/src/extractors/mod.rs - Added module declarations - applications/aphoria/src/extractors/registry.rs - Registered extractors - applications/aphoria/dogfood/httpclient/.aphoria/claims.toml - Added 4 claims - applications/aphoria/dogfood/httpclient/TASK-1-SUMMARY.md - Task #3 completion ## Results | Metric | Value | |--------|-------| | Detection Rate | 100% (7/7 violations) | | Improvement | +29 percentage points (from 71%) | | New Violations | 2 (max_redirects, max_retries unbounded) | | Unit Tests | 13 (all passing) | ## Two-Claim Strategy For each bounded Option<T> field: 1. **configured** claim - Detects None (unbounded) 2. **max_value** claim - Validates Some(n) threshold Example: - `max_redirects: None` → CONFLICT (not configured) - `max_redirects: Some(20)` → CONFLICT (exceeds 10) - `max_redirects: Some(5)` → PASS ## Enterprise Quality ✓ Proper error handling (no unwrap/expect) ✓ Comprehensive tests (6+7 unit tests) ✓ Full documentation with examples ✓ Reusable for 10+ similar patterns ✓ Screening patterns for performance ## Cachewrap Dogfood Also includes complete cachewrap dogfood exercise: - 10 claims for Redis cache wrapper - Day 1-5 summaries - Full retrospective and evaluation - Declarative extractors for all patterns Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
327 lines
11 KiB
TOML
327 lines
11 KiB
TOML
# Aphoria Claims - version controlled
|
|
#
|
|
# Human-authored claims with provenance, invariants, and consequences.
|
|
# Each claim represents a deliberate architectural decision or safety invariant.
|
|
#
|
|
# Manage with: aphoria claims create|list|explain|update|supersede|deprecate
|
|
|
|
[[claim]]
|
|
id = "cache-timeout-001"
|
|
concept_path = "cache/timeout"
|
|
predicate = "max_value"
|
|
value = 5.0
|
|
comparison = "equals"
|
|
provenance = "Redis best practices + httpclient/dbpool pattern alignment"
|
|
invariant = "Cache operation timeout MUST NOT exceed 5 seconds"
|
|
consequence = "Slow cache operations block application threads, cascade failures"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:09Z"
|
|
|
|
[[claim]]
|
|
id = "cache-tls-validation-001"
|
|
concept_path = "cache/tls/certificate_validation"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "OWASP A07:2021 + AWS ElastiCache Security Guide, aligned with httpclient/msgqueue pattern"
|
|
invariant = "TLS certificate validation MUST be enabled for Redis connections"
|
|
consequence = "Disabled validation allows MITM attacks, credential theft"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "security"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:09Z"
|
|
|
|
[[claim]]
|
|
id = "cache-retry-max-001"
|
|
concept_path = "cache/retry/max_attempts"
|
|
predicate = "max_value"
|
|
value = 3.0
|
|
comparison = "equals"
|
|
provenance = "Redis retry best practices, aligned with httpclient pattern"
|
|
invariant = "Cache command retry attempts MUST NOT exceed 3"
|
|
consequence = "Unlimited retries create retry storms, amplify cascading failures"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:09Z"
|
|
|
|
[[claim]]
|
|
id = "cache-async-blocking-001"
|
|
concept_path = "cache/async/blocking_forbidden"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "redis-rs async API requirements, aligned with msgqueue async pattern"
|
|
invariant = "Async cache operations MUST NOT use blocking calls"
|
|
consequence = "Blocking in async context degrades throughput to <10 ops/sec"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "performance"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:12Z"
|
|
|
|
[[claim]]
|
|
id = "cache-max-connections-001"
|
|
concept_path = "cache/connection/max_connections"
|
|
predicate = "bounded"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis connection pooling guide, aligned with dbpool pattern"
|
|
invariant = "Cache connection pool MUST have bounded max_connections (10-50 recommended)"
|
|
consequence = "Unbounded connections exhaust Redis file descriptors, cause cascading failures"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:15Z"
|
|
|
|
[[claim]]
|
|
id = "cache-connection-lifecycle-001"
|
|
concept_path = "cache/connection/lifecycle"
|
|
predicate = "validation_required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis PING command spec, aligned with dbpool/msgqueue lifecycle patterns"
|
|
invariant = "Cache connections MUST be validated (PING) before use"
|
|
consequence = "Stale connections cause command failures, timeouts"
|
|
authority_tier = "expert"
|
|
evidence = []
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:17Z"
|
|
|
|
[[claim]]
|
|
id = "cache-metrics-enabled-001"
|
|
concept_path = "cache/metrics/enabled"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Observability best practices, aligned with httpclient/dbpool/msgqueue patterns"
|
|
invariant = "Metrics MUST be enabled for production cache clients (hit_rate, miss_rate, latency)"
|
|
consequence = "Cannot debug cache effectiveness, performance regressions invisible"
|
|
authority_tier = "community"
|
|
evidence = []
|
|
category = "observability"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:19Z"
|
|
|
|
[[claim]]
|
|
id = "cache-ttl-required-001"
|
|
concept_path = "cache/ttl"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis SETEX/EXPIRE command spec (docs/sources/redis-spec.md)"
|
|
invariant = "TTL (Time To Live) MUST be set for all cached values"
|
|
consequence = "Missing TTL causes memory leak - unbounded cache growth leads to OOM"
|
|
authority_tier = "expert"
|
|
evidence = ["Redis SETEX spec, AWS ElastiCache best practices"]
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:34Z"
|
|
|
|
[[claim]]
|
|
id = "cache-key-validation-001"
|
|
concept_path = "cache/key_validation"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "OWASP Injection Prevention (CWE-943), AWS ElastiCache security"
|
|
invariant = "Cache keys MUST be validated for control characters and length"
|
|
consequence = "Unvalidated keys enable injection attacks, cache poisoning, data breaches"
|
|
authority_tier = "expert"
|
|
evidence = ["OWASP Injection Cheat Sheet, AWS ElastiCache Security Guide"]
|
|
category = "security"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:37Z"
|
|
|
|
[[claim]]
|
|
id = "cache-max-size-001"
|
|
concept_path = "cache/max_size"
|
|
predicate = "bounded"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis maxmemory config, AWS ElastiCache sizing guide"
|
|
invariant = "Cache MUST have bounded max_size to prevent OOM"
|
|
consequence = "Unbounded cache size causes out-of-memory under sustained load"
|
|
authority_tier = "expert"
|
|
evidence = ["Redis maxmemory docs, AWS ElastiCache configuration"]
|
|
category = "safety"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:39Z"
|
|
|
|
[[claim]]
|
|
id = "cache-eviction-policy-001"
|
|
concept_path = "cache/eviction_policy"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis maxmemory-policy config (LRU/LFU/TTL), AWS ElastiCache guide"
|
|
invariant = "Eviction policy MUST be configured (LRU, LFU, or TTL-based)"
|
|
consequence = "Missing eviction policy causes unpredictable behavior when cache is full"
|
|
authority_tier = "expert"
|
|
evidence = ["Redis eviction policies doc, AWS ElastiCache best practices"]
|
|
category = "correctness"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:56:42Z"
|
|
|
|
[[claim]]
|
|
id = "cache-hardcoded-password-001"
|
|
concept_path = "cache/credentials/password"
|
|
predicate = "hardcoded"
|
|
value = false
|
|
comparison = "equals"
|
|
provenance = "OWASP A07:2021 - Identification and Authentication Failures"
|
|
invariant = "Redis passwords MUST NOT be hardcoded in source code"
|
|
consequence = "Hardcoded credentials leak via version control, cannot rotate without code changes"
|
|
authority_tier = "expert"
|
|
evidence = ["OWASP Top 10 A07:2021, CWE-798"]
|
|
category = "security"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:15Z"
|
|
|
|
[[claim]]
|
|
id = "cache-key-prefix-001"
|
|
concept_path = "cache/key_prefix"
|
|
predicate = "recommended"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis key naming best practices, multi-tenant pattern"
|
|
invariant = "Cache keys SHOULD use consistent prefixes for namespacing"
|
|
consequence = "No key prefixes cause key collisions in multi-tenant or multi-app scenarios"
|
|
authority_tier = "community"
|
|
evidence = ["Redis key design patterns, AWS ElastiCache multi-tenancy guide"]
|
|
category = "architecture"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:18Z"
|
|
|
|
[[claim]]
|
|
id = "cache-serialization-001"
|
|
concept_path = "cache/serialization"
|
|
predicate = "format"
|
|
value = "json_or_msgpack"
|
|
comparison = "equals"
|
|
provenance = "redis-rs library serialization patterns (docs/sources/redis-rs-lib.md)"
|
|
invariant = "Cache values SHOULD use structured serialization (JSON, MessagePack, bincode)"
|
|
consequence = "Ad-hoc string serialization causes parsing errors, data corruption"
|
|
authority_tier = "community"
|
|
evidence = ["redis-rs ToRedisArgs/FromRedisValue traits"]
|
|
category = "correctness"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:22Z"
|
|
|
|
[[claim]]
|
|
id = "cache-compression-001"
|
|
concept_path = "cache/compression"
|
|
predicate = "recommended_for_large_values"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "AWS ElastiCache performance optimization guide"
|
|
invariant = "Compression SHOULD be enabled for values >1KB"
|
|
consequence = "Uncompressed large values waste network bandwidth and memory"
|
|
authority_tier = "community"
|
|
evidence = ["AWS ElastiCache best practices"]
|
|
category = "performance"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:24Z"
|
|
|
|
[[claim]]
|
|
id = "cache-consistency-mode-001"
|
|
concept_path = "cache/consistency_mode"
|
|
predicate = "configured"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Redis Cluster consistency semantics, AWS ElastiCache replication guide"
|
|
invariant = "Consistency mode MUST be configured (strong, eventual, client-side)"
|
|
consequence = "Undefined consistency causes data anomalies (stale reads, lost writes)"
|
|
authority_tier = "expert"
|
|
evidence = ["Redis Cluster spec, AWS ElastiCache replication docs"]
|
|
category = "correctness"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:27Z"
|
|
|
|
[[claim]]
|
|
id = "cache-sharding-strategy-001"
|
|
concept_path = "cache/sharding_strategy"
|
|
predicate = "recommended"
|
|
value = "consistent_hashing"
|
|
comparison = "equals"
|
|
provenance = "Redis Cluster hash slot algorithm, consistent hashing best practice"
|
|
invariant = "Sharding SHOULD use consistent hashing for multi-node deployments"
|
|
consequence = "Naive sharding (modulo) causes massive reshuffling on node changes"
|
|
authority_tier = "community"
|
|
evidence = ["Redis Cluster spec, AWS ElastiCache sharding guide"]
|
|
category = "architecture"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:31Z"
|
|
|
|
[[claim]]
|
|
id = "cache-read-through-001"
|
|
concept_path = "cache/read_through"
|
|
predicate = "recommended"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Caching patterns guide, AWS ElastiCache DAX pattern"
|
|
invariant = "Read-through pattern SHOULD be used for cache-aside workloads"
|
|
consequence = "Manual cache population creates race conditions and inconsistencies"
|
|
authority_tier = "community"
|
|
evidence = ["AWS ElastiCache DAX, cache design patterns"]
|
|
category = "architecture"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:33Z"
|
|
|
|
[[claim]]
|
|
id = "cache-write-through-001"
|
|
concept_path = "cache/write_through"
|
|
predicate = "recommended_for_critical_data"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Caching patterns guide, write-through vs write-behind trade-offs"
|
|
invariant = "Write-through SHOULD be used for critical data requiring strong consistency"
|
|
consequence = "Write-behind patterns risk data loss on cache failure"
|
|
authority_tier = "community"
|
|
evidence = ["Cache design patterns, AWS ElastiCache write strategies"]
|
|
category = "correctness"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:35Z"
|
|
|
|
[[claim]]
|
|
id = "cache-stampede-prevention-001"
|
|
concept_path = "cache/stampede_prevention"
|
|
predicate = "required"
|
|
value = true
|
|
comparison = "equals"
|
|
provenance = "Cache stampede mitigation patterns (probabilistic early expiration, locking)"
|
|
invariant = "Cache stampede prevention MUST be implemented (locks, PER, or jitter)"
|
|
consequence = "Stampede on popular key expiration causes thundering herd, DB overload"
|
|
authority_tier = "expert"
|
|
evidence = ["redis-rs lua script patterns, probabilistic early recomputation"]
|
|
category = "performance"
|
|
status = "active"
|
|
created_by = "aphoria-suggest"
|
|
created_at = "2026-02-11T03:57:38Z"
|