# 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 = "aphoria-no-unwrap-001"
concept_path = "aphoria/production/error_handling"
predicate = "unwrap_count"
value = 0.0
comparison = "equals"
provenance = "CI clippy::unwrap_used lint at deny level"
invariant = "Production code MUST NOT use unwrap() or expect()"
consequence = "Runtime panics in production"
authority_tier = "expert"
evidence = [
    "CLAUDE.md critical rules",
    "Cargo.toml clippy config",
]
category = "safety"
status = "active"
created_by = "jml"
created_at = "2026-02-08T12:00:00Z"

[[claim]]
id = "aphoria-bridge-tier-001"
concept_path = "aphoria/bridge/tier_assignment"
predicate = "default_tier"
value = "SourceClass::Community"
comparison = "present"
provenance = "Bridge module design: observations default to Community tier"
invariant = "Observation-to-assertion bridge MUST assign Community tier by default"
consequence = "Incorrect authority ranking in conflict detection"
authority_tier = "expert"
evidence = ["bridge.rs observation_to_assertion function"]
category = "architecture"
status = "active"
created_by = "jml"
created_at = "2026-02-08T12:00:00Z"

[[claim]]
id = "aphoria-lifecycle-skip-001"
concept_path = "aphoria/bridge/lifecycle"
predicate = "skips_pending"
value = true
comparison = "present"
provenance = "Bridge design: observations skip Pending and go directly to Approved"
invariant = "Observations bypass Pending lifecycle stage"
consequence = "Observations would be invisible to queries if stuck in Pending"
authority_tier = "expert"
evidence = ["bridge.rs observation_to_assertion"]
category = "architecture"
status = "active"
created_by = "jml"
created_at = "2026-02-08T12:00:00Z"

[[claim]]
id = "aphoria-tls-verify-001"
concept_path = "aphoria/tls/cert_verification"
predicate = "enabled"
value = false
comparison = "absent"
provenance = "RFC 5246 Section 7.4.2 - TLS certificate verification is mandatory"
invariant = "TLS certificate verification MUST NOT be disabled in production code"
consequence = "MITM attacks become trivial; all encrypted traffic can be intercepted"
authority_tier = "regulatory"
evidence = [
    "RFC 5246",
    "OWASP TLS Cheat Sheet",
]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-no-tokio-core-001"
concept_path = "stemedb_core/imports/tokio"
predicate = "imported"
value = true
comparison = "absent"
provenance = "Architecture decision: stemedb-core must remain runtime-agnostic"
invariant = "stemedb-core MUST NOT import tokio to prevent runtime coupling"
consequence = "Core becomes tied to a specific async runtime, preventing embedding in non-tokio contexts"
authority_tier = "expert"
evidence = [
    "CLAUDE.md architecture overview",
    "stemedb-core Cargo.toml",
]
category = "architecture"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-no-md5-001"
concept_path = "aphoria/crypto/hashing/algorithm"
predicate = "algorithm"
value = "md5"
comparison = "not_equals"
provenance = "NIST SP 800-131A Rev 2 - MD5 is not approved for any cryptographic use"
invariant = "MD5 MUST NOT be used for hashing in any security context"
consequence = "Collision attacks are practical; signatures and integrity checks become meaningless"
authority_tier = "regulatory"
evidence = [
    "NIST SP 800-131A",
    "RFC 6151",
]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-no-wildcard-cors-001"
concept_path = "aphoria/cors/allow_origin"
predicate = "config_value"
value = "*"
comparison = "absent"
provenance = "OWASP CORS Misconfiguration - Wildcard origin with credentials is a vulnerability"
invariant = "CORS MUST NOT use wildcard (*) origin in production services"
consequence = "Any origin can make credentialed cross-origin requests, bypassing same-origin policy"
authority_tier = "expert"
evidence = [
    "OWASP Testing Guide v4 - CORS",
    "CWE-942",
]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-jwt-audience-001"
concept_path = "aphoria/jwt/audience_validation"
predicate = "enabled"
value = false
comparison = "absent"
provenance = "RFC 7519 Section 4.1.3 - The aud claim MUST be validated"
invariant = "JWT audience validation MUST NOT be disabled"
consequence = "Tokens issued for one service can be replayed against another"
authority_tier = "regulatory"
evidence = ["RFC 7519 Section 4.1.3"]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-hsts-enabled-001"
concept_path = "aphoria/security_headers/hsts"
predicate = "header_status"
value = "disabled"
comparison = "absent"
provenance = "RFC 6797 - HTTP Strict Transport Security must be enabled for HTTPS services"
invariant = "HSTS header MUST NOT be disabled on HTTPS-serving endpoints"
consequence = "Users can be downgraded to HTTP via SSL stripping attacks"
authority_tier = "regulatory"
evidence = [
    "RFC 6797",
    "OWASP Secure Headers Project",
]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "aphoria-no-hardcoded-secrets-001"
concept_path = "aphoria/secrets/api_key"
predicate = "storage_method"
value = "hardcoded"
comparison = "absent"
provenance = "OWASP Top 10 2021 - A07 Identification and Authentication Failures"
invariant = "API keys MUST NOT be hardcoded in source files"
consequence = "Secrets leak through version control; credential rotation requires code changes"
authority_tier = "expert"
evidence = [
    "OWASP Top 10 A07:2021",
    "CWE-798",
]
category = "security"
status = "active"
created_by = "jml"
created_at = "2026-02-08T14:00:00Z"

[[claim]]
id = "dbpool-max-conn-required-001"
concept_path = "dbpool/config/max_connections"
predicate = "is_option"
value = false
comparison = "equals"
provenance = "HikariCP Configuration Guide - Pool sizing"
invariant = "max_connections MUST be a required field, not Optional"
consequence = "Without max_connections limit, pool grows unbounded and exhausts database connections under load"
authority_tier = "observational"
evidence = []
category = "safety"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:39Z"

[[claim]]
id = "dbpool-plaintext-pwd-001"
concept_path = "dbpool/config/connection_string"
predicate = "contains_plaintext_password"
value = false
comparison = "equals"
provenance = "OWASP A07:2021 - Identification and Authentication Failures"
invariant = "Connection strings MUST NOT contain plaintext passwords"
consequence = "Plaintext passwords in code expose credentials in logs, configs, and version control"
authority_tier = "clinical"
evidence = []
category = "security"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "dbpool-max-lifetime-required-001"
concept_path = "dbpool/config/max_lifetime"
predicate = "is_option"
value = false
comparison = "equals"
provenance = "HikariCP Configuration Guide - Connection lifetime management"
invariant = "max_lifetime MUST be a required field, not Optional"
consequence = "Without max_lifetime, connections persist indefinitely leading to stale connections and resource leaks"
authority_tier = "observational"
evidence = []
category = "safety"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "dbpool-conn-timeout-max-001"
concept_path = "dbpool/config/connection_timeout"
predicate = "max_seconds"
value = 30.0
comparison = "equals"
provenance = "PostgreSQL Connection Pooling Guide - Timeout configuration"
invariant = "connection_timeout MUST NOT exceed 30 seconds"
consequence = "Excessive timeouts (>30s) cause thread exhaustion and cascade failures under load"
authority_tier = "observational"
evidence = []
category = "performance"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "dbpool-min-conn-minimum-001"
concept_path = "dbpool/config/min_connections"
predicate = "min_value"
value = 2.0
comparison = "equals"
provenance = "HikariCP Configuration Guide - Minimum pool size"
invariant = "min_connections MUST be at least 2"
consequence = "Single idle connection creates single point of failure; zero idle connections causes cold start latency"
authority_tier = "observational"
evidence = []
category = "performance"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "dbpool-validation-required-001"
concept_path = "dbpool/config/validate_on_checkout"
predicate = "required"
value = true
comparison = "equals"
provenance = "PostgreSQL Connection Pooling Guide - Connection validation"
invariant = "validate_on_checkout MUST be enabled"
consequence = "Without pre-checkout validation, applications receive stale/broken connections causing query failures"
authority_tier = "observational"
evidence = []
category = "safety"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "dbpool-metrics-recommended-001"
concept_path = "dbpool/config/enable_metrics"
predicate = "recommended"
value = true
comparison = "equals"
provenance = "HikariCP Configuration Guide - Observability best practices"
invariant = "Metrics collection SHOULD be enabled for production deployments"
consequence = "Without metrics, pool exhaustion and performance degradation are invisible until user-facing failures occur"
authority_tier = "observational"
evidence = []
category = "performance"
status = "active"
created_by = "dogfood-demo"
created_at = "2026-02-10T02:17:55Z"

[[claim]]
id = "httpclient-connect-timeout-001"
concept_path = "httpclient/connect_timeout"
predicate = "max_value"
value = 10.0
comparison = "equals"
provenance = "Mozilla HTTP docs + Requests library (10s connect timeout)"
invariant = "TCP connection timeout MUST NOT exceed 10 seconds"
consequence = "Unresponsive endpoints block connection establishment"
authority_tier = "expert"
evidence = ["Mozilla HTTP guidelines, Requests library default"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-request-timeout-001"
concept_path = "httpclient/request_timeout"
predicate = "max_value"
value = 30.0
comparison = "equals"
provenance = "Mozilla HTTP docs (30s recommended), aligned with dbpool timeout pattern"
invariant = "HTTP request timeout MUST NOT exceed 30 seconds"
consequence = "Slow external services block thread pool, cascade failures"
authority_tier = "expert"
evidence = ["Mozilla HTTP guidelines, RFC 7230"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-read-timeout-001"
concept_path = "httpclient/read_timeout"
predicate = "max_value"
value = 30.0
comparison = "equals"
provenance = "Mozilla HTTP docs (15-30s for response body reading)"
invariant = "Response body read timeout MUST NOT exceed 30 seconds"
consequence = "Slow streaming responses block thread pool"
authority_tier = "expert"
evidence = ["Mozilla HTTP guidelines"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-idle-timeout-001"
concept_path = "httpclient/idle_timeout"
predicate = "required"
value = true
comparison = "equals"
provenance = "RFC 7230 Section 6.3 (persistent connections), reused from dbpool/idle_timeout pattern"
invariant = "Idle connection timeout MUST be configured"
consequence = "Stale connections accumulate, waste resources"
authority_tier = "expert"
evidence = ["RFC 7230 Section 6.3, dbpool pattern alignment"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-idle-timeout-default-001"
concept_path = "httpclient/idle_timeout"
predicate = "default_value"
value = 60.0
comparison = "equals"
provenance = "Mozilla HTTP docs + RFC 7230 (60s aligns with server keep-alive)"
invariant = "Idle timeout default SHOULD be 60 seconds"
consequence = "Too short closes connections prematurely, too long wastes resources"
authority_tier = "community"
evidence = ["Mozilla HTTP guidelines, RFC 7230"]
category = "constants"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-tls-cert-validation-001"
concept_path = "httpclient/tls/certificate_validation"
predicate = "required"
value = true
comparison = "equals"
provenance = "OWASP A07:2021 + Mozilla Security Guidelines, reused from dbpool pattern"
invariant = "HTTPS connections MUST validate server certificates"
consequence = "Man-in-the-middle attacks, credential exposure"
authority_tier = "expert"
evidence = ["OWASP A07:2021, Mozilla HTTPS guidelines, Requests library default"]
category = "security"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-tls-enabled-001"
concept_path = "httpclient/tls/enabled"
predicate = "recommended"
value = true
comparison = "equals"
provenance = "Security best practice, reused from dbpool pattern"
invariant = "HTTPS SHOULD be enabled by default for all connections"
consequence = "Unencrypted traffic exposes sensitive data (credentials, PII)"
authority_tier = "community"
evidence = ["Mozilla Security Guidelines, OWASP"]
category = "security"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-tls-min-version-001"
concept_path = "httpclient/tls/min_version"
predicate = "min_value"
value = 1.2
comparison = "equals"
provenance = "OWASP + Mozilla Security Guidelines (TLS 1.2 minimum as of 2023)"
invariant = "TLS version MUST be >= 1.2 (TLS 1.0/1.1 deprecated)"
consequence = "Vulnerable to protocol downgrade attacks (BEAST, POODLE)"
authority_tier = "expert"
evidence = ["OWASP TLS cheat sheet, Mozilla guidelines"]
category = "security"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-tls-ciphers-001"
concept_path = "httpclient/tls/cipher_suites"
predicate = "recommended"
value = "modern_only"
comparison = "equals"
provenance = "Mozilla Security Guidelines (ECDHE, AES-GCM preferred)"
invariant = "TLS cipher suites SHOULD use modern ciphers only"
consequence = "Weak ciphers (RC4, 3DES, MD5) enable decryption attacks"
authority_tier = "community"
evidence = ["Mozilla Security Guidelines"]
category = "security"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-max-redirects-001"
concept_path = "httpclient/max_redirects"
predicate = "max_value"
value = 10.0
comparison = "equals"
provenance = "RFC 7231 Section 6.4 (10 redirects recommended), pattern from dbpool/max_connections"
invariant = "HTTP redirect limit MUST NOT exceed 10"
consequence = "Infinite redirect loops exhaust client resources"
authority_tier = "expert"
evidence = ["RFC 7231 Section 6.4"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-redirect-loop-001"
concept_path = "httpclient/redirects/loop_detection"
predicate = "required"
value = true
comparison = "equals"
provenance = "Requests library pattern (TooManyRedirects exception)"
invariant = "Redirect loop detection MUST be implemented"
consequence = "Without detection, infinite loops exhaust resources"
authority_tier = "expert"
evidence = ["Requests library implementation, RFC 7231"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-retry-max-001"
concept_path = "httpclient/retry/max_attempts"
predicate = "max_value"
value = 3.0
comparison = "equals"
provenance = "Requests library default + Mozilla guidelines (3 retries max)"
invariant = "Retry attempts MUST NOT exceed 3"
consequence = "Unlimited retries cause retry storms, amplify cascading failures"
authority_tier = "expert"
evidence = ["Requests library default, Mozilla HTTP guidelines"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-retry-backoff-001"
concept_path = "httpclient/retry/backoff"
predicate = "required"
value = "exponential"
comparison = "equals"
provenance = "Requests library pattern (exponential backoff 1s, 2s, 4s)"
invariant = "Retry backoff MUST use exponential strategy"
consequence = "Fixed-interval retries amplify load spikes during outages"
authority_tier = "expert"
evidence = ["Requests library urllib3.util.retry"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-retry-idempotent-001"
concept_path = "httpclient/retry/idempotent_only"
predicate = "required"
value = true
comparison = "equals"
provenance = "Mozilla HTTP docs + Requests library (only retry GET/PUT/DELETE)"
invariant = "Retries MUST only apply to idempotent methods"
consequence = "Retrying POST requests may cause duplicate operations (charges, bookings)"
authority_tier = "expert"
evidence = ["Mozilla HTTP guidelines, Requests library default"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-retry-post-excluded-001"
concept_path = "httpclient/retry/post_excluded"
predicate = "required"
value = true
comparison = "equals"
provenance = "Requests library default (never retry POST by default)"
invariant = "POST requests MUST be excluded from automatic retries"
consequence = "Retrying POST can cause duplicate charges, bookings, state mutations"
authority_tier = "expert"
evidence = ["Requests library implementation"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-metrics-enabled-001"
concept_path = "httpclient/metrics/enabled"
predicate = "recommended"
value = true
comparison = "equals"
provenance = "Observability best practice, reused from dbpool pattern"
invariant = "Metrics collection SHOULD be enabled for production HTTP clients"
consequence = "Cannot monitor client health, debug production issues, or detect cascades"
authority_tier = "community"
evidence = ["Prometheus best practices, SRE handbook, dbpool pattern"]
category = "observability"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-metrics-exposed-001"
concept_path = "httpclient/metrics/exposed"
predicate = "required"
value = "request_count,active_connections,latency_p99,error_rate"
comparison = "equals"
provenance = "RED method (Rate, Errors, Duration), adapted from dbpool/metrics/exposed"
invariant = "Core HTTP metrics MUST be exposed: request_count, active_connections, latency_p99, error_rate"
consequence = "Incomplete observability prevents production debugging and SLO tracking"
authority_tier = "community"
evidence = ["RED method (Prometheus), dbpool pattern alignment"]
category = "observability"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-pool-size-001"
concept_path = "httpclient/pool_size"
predicate = "recommended_range"
value = "50-100"
comparison = "equals"
provenance = "Mozilla HTTP docs (50-100 connections per host for production)"
invariant = "Connection pool size SHOULD be 50-100 per host in production"
consequence = "Too few limits throughput, too many causes resource exhaustion"
authority_tier = "community"
evidence = ["Mozilla HTTP guidelines"]
category = "constants"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-pool-default-size-001"
concept_path = "httpclient/pool/default_size"
predicate = "default_value"
value = 10.0
comparison = "equals"
provenance = "Requests library default (10 connections via urllib3)"
invariant = "Default pool size SHOULD be 10 connections per host"
consequence = "Default works for most cases, high-concurrency apps need tuning"
authority_tier = "community"
evidence = ["Requests library urllib3.poolmanager default"]
category = "constants"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-connection-pooling-001"
concept_path = "httpclient/sessions/connection_pooling"
predicate = "recommended"
value = true
comparison = "equals"
provenance = "Requests library best practice (use Session() for connection reuse)"
invariant = "Connection pooling SHOULD be enabled for multi-request scenarios"
consequence = "Without pooling, every request pays TCP + TLS handshake cost"
authority_tier = "community"
evidence = ["Requests library Session documentation"]
category = "architecture"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-user-agent-001"
concept_path = "httpclient/headers/user_agent"
predicate = "required"
value = true
comparison = "equals"
provenance = "Mozilla HTTP docs (always send User-Agent header)"
invariant = "User-Agent header MUST be sent with all requests"
consequence = "Servers may block or rate-limit requests without User-Agent"
authority_tier = "community"
evidence = ["Mozilla HTTP guidelines"]
category = "architecture"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"

[[claim]]
id = "httpclient-error-handling-001"
concept_path = "httpclient/error_handling/request_failure"
predicate = "must"
value = "return_error_not_panic"
comparison = "equals"
provenance = "Robustness pattern, reused from dbpool/error_handling/connection_failure"
invariant = "HTTP request failures MUST return Result, NEVER panic"
consequence = "Unhandled panics crash the application"
authority_tier = "expert"
evidence = ["Rust error handling best practices, dbpool pattern"]
category = "safety"
status = "active"
created_by = "aphoria-suggest"
created_at = "2026-02-10T04:09:22Z"