feat: add production capability foundations

2026-07-31 23:50:44 +09:00
parent b3add0162d
commit 567422f2e5
757 changed files with 132385 additions and 2146 deletions
@@ -433,6 +433,311 @@ metrics:
    compatibility_impact: additive
    required_test: contract-verification:metrics-cardinality

+  # source: redis-production-capability — optional bounded cache-only L1
+  - name: cache.local.requests.total
+    type: counter
+    unit: total
+    tags:
+      - name: cache_name
+        cardinality_limit: 50
+      - name: result
+        cardinality_limit: 4
+        allowed_values: [hit, miss, error, bypass]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p3: "bypass or error rate above baseline for 15m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [cache_name, result]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability — local stale-age bound
+  - name: cache.local.entry.age.seconds
+    type: timer
+    unit: seconds
+    tags:
+      - name: cache_name
+        cardinality_limit: 50
+    percentiles: [0.5, 0.9, 0.95, 0.99]
+    histogram_buckets: slo_driven
+    alert_severity_thresholds:
+      p3: "p99 approaches configured local TTL for 30m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [cache_name]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability — bounded invalidation and generation reconciliation
+  - name: cache.local.maintenance.total
+    type: counter
+    unit: total
+    tags:
+      - name: cache_name
+        cardinality_limit: 50
+      - name: event
+        cardinality_limit: 14
+        allowed_values:
+          - evict_cardinality
+          - evict_weight
+          - evict_ttl
+          - evict_invalidation
+          - flush_invalidation
+          - reconcile_generation_changed
+          - reconcile_unchanged
+          - reconcile_error
+          - subscriber_disconnected
+          - subscriber_overflow
+          - subscriber_malformed
+          - subscriber_publish_success
+          - subscriber_publish_error
+          - other
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p2: "reconcile_error, subscriber_overflow, or sustained disconnects for 5m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [cache_name, event]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — closed semantic operation outcomes
+  - name: redis.capability.operations.total
+    type: counter
+    unit: total
+    tags:
+      - name: capability
+        cardinality_limit: 6
+        allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session, runtime]
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: operation
+        cardinality_limit: 24
+        allowed_values:
+          - lookup
+          - record
+          - invalidate
+          - refresh_claim
+          - refresh_release
+          - rate_evaluate
+          - idempotency_claim
+          - idempotency_start
+          - idempotency_renew
+          - idempotency_complete
+          - idempotency_fail
+          - idempotency_release
+          - idempotency_inspect
+          - lease_acquire
+          - lease_inspect
+          - lease_renew
+          - lease_release
+          - session_create
+          - session_inspect
+          - session_save
+          - session_touch
+          - session_revoke
+          - session_rotate
+          - route_command
+      - name: redis_outcome
+        cardinality_limit: 15
+        allowed_values:
+          - success
+          - hit
+          - miss
+          - denied
+          - contended
+          - conflict
+          - incompatible
+          - unavailable
+          - overloaded
+          - closed
+          - indeterminate
+          - stale
+          - skipped
+          - tombstoned
+          - absolute_expired
+      - name: certainty
+        cardinality_limit: 3
+        allowed_values: [definite, not_applied, indeterminate]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p1: "required coordination/session unavailable or indeterminate mutation sustained for 2m"
+      p2: "optional cache unavailable or overloaded above baseline for 5m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [capability, role, operation, redis_outcome, certainty]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — monotonic semantic operation duration
+  - name: redis.capability.duration.seconds
+    type: timer
+    unit: seconds
+    tags:
+      - name: capability
+        cardinality_limit: 6
+        allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session, runtime]
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: operation
+        cardinality_limit: 24
+        allowed_values:
+          - lookup
+          - record
+          - invalidate
+          - refresh_claim
+          - refresh_release
+          - rate_evaluate
+          - idempotency_claim
+          - idempotency_start
+          - idempotency_renew
+          - idempotency_complete
+          - idempotency_fail
+          - idempotency_release
+          - idempotency_inspect
+          - lease_acquire
+          - lease_inspect
+          - lease_renew
+          - lease_release
+          - session_create
+          - session_inspect
+          - session_save
+          - session_touch
+          - session_revoke
+          - session_rotate
+          - route_command
+      - name: redis_outcome
+        cardinality_limit: 15
+        allowed_values:
+          - success
+          - hit
+          - miss
+          - denied
+          - contended
+          - conflict
+          - incompatible
+          - unavailable
+          - overloaded
+          - closed
+          - indeterminate
+          - stale
+          - skipped
+          - tombstoned
+          - absolute_expired
+    percentiles: [0.5, 0.9, 0.95, 0.99]
+    histogram_buckets: slo_driven
+    alert_severity_thresholds:
+      p2: "p99 approaches the configured command or caller deadline for 10m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [capability, role, operation, redis_outcome]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — admission rejected before command ownership
+  - name: redis.capability.admission.rejected.total
+    type: counter
+    unit: total
+    tags:
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: admission
+        cardinality_limit: 2
+        allowed_values: [rejected_saturated, rejected_closed]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p1: "required role rejection sustained above zero for 2m"
+      p2: "optional cache saturation sustained for 5m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [role, admission]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — bounded admitted command count observation
+  - name: redis.capability.inflight.total
+    type: gauge
+    unit: total
+    tags:
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: state
+        cardinality_limit: 3
+        allowed_values: [idle, active, saturated]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p2: "saturated series remains nonzero for 5m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [role, state]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — observations of exact sanitized RoleHealth
+  - name: redis.capability.readiness.total
+    type: counter
+    unit: total
+    tags:
+      - name: capability
+        cardinality_limit: 5
+        allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session]
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: state
+        cardinality_limit: 3
+        allowed_values: [available, unavailable, overloaded]
+      - name: reason
+        cardinality_limit: 11
+        allowed_values:
+          - command_unavailable
+          - route_closed
+          - semantic_probe_succeeded
+          - semantic_read_write_failed
+          - semantic_program_acl_denied
+          - semantic_program_failed
+          - server_version_unsupported
+          - semantic_probe_in_progress
+          - semantic_observation_stale
+          - command_saturated
+          - recent_command_failure
+      - name: requirement
+        cardinality_limit: 2
+        allowed_values: [optional, required]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p1: "required coordination/session unavailable for 2m"
+      p2: "optional cache unavailable or overloaded for 5m"
+    owner_branch: redis-production-capability
+    log_field_mapping: [capability, role, state, reason, requirement]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
+  # source: redis-production-capability Task 16 — bounded router shutdown drain result
+  - name: redis.capability.lifecycle.drain.total
+    type: counter
+    unit: total
+    tags:
+      - name: role
+        cardinality_limit: 3
+        allowed_values: [cache, coordination, session]
+      - name: drain_outcome
+        cardinality_limit: 3
+        allowed_values: [drained, forced_after_timeout, interrupted]
+    percentiles: null
+    histogram_buckets: null
+    alert_severity_thresholds:
+      p1: "required role forced_after_timeout or interrupted during shutdown"
+      p2: "optional cache forced close during shutdown"
+    owner_branch: redis-production-capability
+    log_field_mapping: [role, drain_outcome]
+    compatibility_impact: additive
+    required_test: contract-verification:metrics-cardinality
+
  # === Log appender ===
  # source: feature-log-management-contract — Sampling Policy (final)
  #   "async appender overflow default: drop oldest INFO/DEBUG with counter metric (log.appender.dropped.total)"
@@ -89,6 +89,18 @@ secrets:
    compatibility_impact: breaking
    required_test: secrets-contract:redis-password-no-leak

+  - name: APP_CACHE_REDIS_TRUST_PEM
+    # Public CA bundle content, but integrity-sensitive and supplied by the mounted environment.
+    classification: sensitive-config
+    source: mounted-env
+    rotation_policy: restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:redis-trust-reference-no-leak
+
  - name: APP_CACHE_REDIS_KEY_HMAC_SECRET
    # Stable cache-key HMAC material. It is distinct from the Redis authentication credential.
    classification: secret
@@ -101,6 +113,102 @@ secrets:
    compatibility_impact: breaking
    required_test: secrets-contract:redis-key-hmac-no-leak

+  - name: APP_RATE_LIMIT_REDIS_PASSWORD
+    # Dedicated coordination-role Redis credential. It is never inherited from cache Redis.
+    classification: secret
+    source: secret-manager
+    rotation_policy: restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-distributed-rate-limit
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:rate-limit-redis-password-no-leak
+
+  - name: APP_RATE_LIMIT_REDIS_TRUST_PEM
+    # Coordination-role CA bundle content; integrity-sensitive but not credential material.
+    classification: sensitive-config
+    source: mounted-env
+    rotation_policy: restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:rate-limit-redis-trust-reference-no-leak
+
+  - name: APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET
+    # Stable private-key derivation material for rate-limit subjects and policy revisions.
+    classification: secret
+    source: secret-manager
+    rotation_policy: dual-read-restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-distributed-rate-limit
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:rate-limit-redis-key-hmac-no-leak
+
+  - name: APP_SESSION_REDIS_PASSWORD
+    # Dedicated session-role ACL credential; never shared implicitly with cache or coordination.
+    classification: secret
+    source: secret-manager
+    rotation_policy: restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:session-redis-password-no-leak
+
+  - name: APP_SESSION_REDIS_TRUST_PEM
+    # Session-role CA bundle content; integrity-sensitive but not credential material.
+    classification: sensitive-config
+    source: mounted-env
+    rotation_policy: restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:session-redis-trust-reference-no-leak
+
+  - name: APP_SESSION_REDIS_KEY_HMAC_SECRET
+    # Stable private derivation material for pseudonymous Redis session keys.
+    classification: secret
+    source: secret-manager
+    rotation_policy: dual-read-restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:session-redis-key-hmac-no-leak
+
+  - name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET
+    # Owner-safe request-replay keys must not expose tenant/scope/request identifiers.
+    classification: secret
+    source: secret-manager
+    rotation_policy: cold-cutover-restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability-completion
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:idempotency-redis-key-hmac-no-leak
+
+  - name: APP_LEASE_REDIS_KEY_HMAC_SECRET
+    # Efficiency-lease resource and owner scopes use a dedicated derivation key.
+    classification: secret
+    source: secret-manager
+    rotation_policy: cold-cutover-restart-only
+    prod_default: null
+    dev_sentinel_prefix: __LOCAL_DEV_
+    owner_branch: redis-production-capability-completion
+    masking_rule: full
+    compatibility_impact: additive
+    required_test: secrets-contract:lease-redis-key-hmac-no-leak
+
  - name: APP_PRIVACY_PSEUDONYMIZATION_SALT
    # source: feature-data-retention-privacy-contract 2026-05-22
    # "pseudonymization key = HMAC-SHA-256 with rotating salt. salt rotation interval = 90일.