@precepts/standards 0.1.0

package/standards/integration/standards/observability/integration-observability.md

@@ -0,0 +1,226 @@
+---
+identifier: "INTG-STD-029"
+name: "Integration Observability"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "observability"
+appliesTo: ["api", "events", "a2a", "files", "mcp", "webhooks", "grpc", "graphql", "batch", "streaming"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: []
+  w3c: ["Trace-Context"]
+  other: ["OpenTelemetry-Specification", "OWASP-Logging-Cheat-Sheet"]
+
+taxonomy:
+  capability: "observability"
+  subCapability: "logging-tracing-metrics"
+  layer: "infrastructure"
+
+enforcement:
+  method: "hybrid"
+  validationRules:
+    traceContextHeader: "traceparent"
+    logFormat: "JSON"
+    requiredLogFields: ["timestamp", "level", "trace_id", "service", "message"]
+  rejectionCriteria:
+    - "Missing traceparent header propagation"
+    - "Unstructured (non-JSON) log output"
+    - "PII or secrets in log entries"
+    - "Missing correlation ID in API responses"
+
+dependsOn: ["INTG-STD-004"]
+supersedes: ""
+---
+
+# Observability
+
+## Purpose
+
+Every integration action - API call, event, file transfer, or agent handshake - **MUST** be traceable from origin to destination. This standard establishes mandatory requirements for distributed tracing (W3C Trace Context), structured logging (JSON), and metrics collection (OpenTelemetry) across all integration touchpoints. It also codifies what **MUST NOT** appear in logs to prevent data leakage per the OWASP Logging Cheat Sheet.
+
+## Rules
+
+### R-1: W3C Trace Context Propagation
+
+All integration endpoints **MUST** propagate the `traceparent` HTTP header per the W3C Trace Context specification:
+
+```
+traceparent: {version}-{trace-id}-{parent-id}-{trace-flags}
+Example:     00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
+```
+
+Services **MUST NOT** generate all-zero `trace-id` or `parent-id` values. If a request arrives without `traceparent`, the receiving service **MUST** generate a new trace context.
+
+Services **SHOULD** propagate the `tracestate` header alongside `traceparent` and **MUST NOT** modify or strip `tracestate` entries they do not own.
+
+For non-HTTP transports, trace context **MUST** be propagated via the protocol's native metadata mechanism (gRPC metadata keys, Kafka message headers, AMQP application properties, batch file manifest metadata).
+
+### R-2: Correlation IDs
+
+All API responses **MUST** include an `X-Request-ID` header containing a UUID v4 or ULID. If the incoming request includes `X-Request-ID`, the service **MUST** echo that value; otherwise it **MUST** generate one.
+
+The `X-Request-ID` **MUST** be included in all log entries for that request via the `request_id` field. The `X-Request-ID` is distinct from `trace-id` - it is a business-level identifier that **MAY** be shared with API consumers for support purposes.
+
+### R-3: Structured Logging Format
+
+All integration components **MUST** emit logs in JSON format. Unstructured log output **MUST NOT** be used beyond local development.
+
+**Required fields:**
+
+| Field | Type | Description | Example |
+| ----- | ---- | ----------- | ------- |
+| `timestamp` | string | ISO 8601 with UTC (`Z`), microsecond precision | `"2026-03-28T14:32:01.482319Z"` |
+| `level` | string | Log severity (uppercase) | `"INFO"` |
+| `trace_id` | string | W3C trace identifier (32 hex chars) | `"0af7651916cd43dd8448eb211c80319c"` |
+| `span_id` | string | Current span identifier (16 hex chars) | `"b9c7c989f97918e1"` |
+| `service` | string | Service name (lowercase, hyphenated) | `"order-service"` |
+| `message` | string | Human-readable event description | `"Payment authorization completed"` |
+
+Optional fields **SHOULD** be included when applicable: `request_id`, `environment`, `version`, `operation`, `duration_ms`, `http.method`, `http.status_code`, `http.url` (sensitive parameters redacted), `error.type`, `error.message`.
+
+The `service` field **MUST** match the OpenTelemetry `service.name` resource attribute.
+
+### R-4: Prohibited Log Content
+
+Log entries **MUST NOT** contain:
+
+| Category | Examples |
+| -------- | -------- |
+| PII | Names, emails, phone numbers, government IDs, dates of birth |
+| Authentication credentials | Passwords, API keys, bearer tokens, JWTs, session IDs |
+| Cryptographic material | Private keys, certificates, encryption keys |
+| Financial data | Full card numbers, bank account numbers, CVV codes |
+| Health data | Medical records, diagnoses, treatment information |
+| Full request/response bodies | Use truncated or summarized representations instead |
+
+If debugging requires logging intersecting data, it **MUST** be masked before writing (e.g., `"d***@example.com"`, `"****-****-****-4242"`, `"sk-prod-****"`, or log schema shape only: `"body_keys: [\"name\", \"address\"]"`).
+
+Log entries **MUST** be sanitized against log injection - newlines, control characters, and ANSI escape sequences **MUST** be escaped or stripped from user-supplied values (ref: OWASP CWE-117). Stack traces **SHOULD** only appear at `ERROR` or `FATAL` level and **MUST** be reviewed for leaked secrets.
+
+### R-5: Log Levels
+
+Services **MUST** use the following log levels consistently:
+
+| Level | When to Use |
+| ----- | ----------- |
+| `FATAL` | Unrecoverable failure; service cannot continue |
+| `ERROR` | Operation failed; requires attention but service continues |
+| `WARN` | Unexpected condition that does not prevent operation |
+| `INFO` | Normal operational events worth recording |
+| `DEBUG` | Diagnostic detail for troubleshooting |
+| `TRACE` | Protocol-level verbosity |
+
+Production environments **MUST** default to `INFO`. `DEBUG` and `TRACE` **MUST** be activatable at runtime without redeployment. `ERROR` **MUST** be reserved for conditions requiring investigation - client 4xx errors **SHOULD** be logged at `WARN`, not `ERROR`.
+
+### R-6: Metrics
+
+All custom integration metrics **MUST** follow OpenTelemetry semantic naming conventions: dot-separated namespaces, lowercase, no units in names.
+
+**Required metrics for every integration endpoint:**
+
+| Metric Name | Type | Unit | Description |
+| ----------- | ---- | ---- | ----------- |
+| `integration.request.duration` | Histogram | `s` | Request-to-response time |
+| `integration.request.count` | Counter | `{request}` | Total requests |
+| `integration.request.error.count` | Counter | `{request}` | Failed requests |
+| `integration.request.active` | UpDownCounter | `{request}` | In-flight requests |
+
+**Additional metrics for event-driven integrations:**
+
+| Metric Name | Type | Unit | Description |
+| ----------- | ---- | ---- | ----------- |
+| `integration.event.publish.count` | Counter | `{event}` | Events published |
+| `integration.event.consume.count` | Counter | `{event}` | Events consumed |
+| `integration.event.consume.duration` | Histogram | `s` | Event processing time |
+| `integration.event.consume.lag` | Gauge | `{event}` | Consumer lag |
+| `integration.event.dlq.count` | Counter | `{event}` | Dead-letter queue events |
+
+All metrics **MUST** include resource attributes `service.name`, `service.version`, and `deployment.environment.name`. Common attributes **MUST** include `integration.type`, `integration.target`, `network.protocol.name`, and `error.type` where applicable.
+
+### R-7: Span Attributes
+
+All integration operations **MUST** be instrumented as OpenTelemetry spans. Span names **MUST** follow protocol conventions (e.g., `GET /api/v2/orders` for HTTP, `orders.created publish` for messaging).
+
+HTTP spans **MUST** include: `http.request.method`, `http.response.status_code`, `url.path`, `server.address`. Messaging spans **MUST** include: `messaging.system`, `messaging.destination.name`, `messaging.operation.type`.
+
+Spans **MUST** set appropriate `SpanKind`: `SERVER`/`CLIENT` for HTTP/gRPC, `PRODUCER`/`CONSUMER` for messaging, `INTERNAL` for local processing. Span status **MUST** be set to `ERROR` on failure; HTTP 5xx **MUST** set span error status, 4xx **SHOULD NOT**.
+
+### R-8: Audit Traceability
+
+Every state-changing integration operation **MUST** produce an `INFO` log entry including at minimum: `trace_id`, `span_id`, `request_id`, `operation`, `service`, and outcome. It **MUST** be possible to reconstruct the complete execution path of any transaction using `trace_id` across all participating services. Audit-relevant entries **MUST** be retained per the organization's data retention policy.
+
+## Examples
+
+### Structured Log Entry
+
+```json
+{
+  "timestamp": "2026-03-28T14:32:01.482319Z",
+  "level": "INFO",
+  "trace_id": "0af7651916cd43dd8448eb211c80319c",
+  "span_id": "b9c7c989f97918e1",
+  "service": "order-service",
+  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "operation": "createOrder",
+  "http.method": "POST",
+  "http.status_code": 201,
+  "duration_ms": 142.7,
+  "message": "Order created successfully"
+}
+```
+
+### Trace Context Headers
+
+```http
+GET /api/v2/orders/12345 HTTP/1.1
+Host: order-service.internal
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
+tracestate: vendorA=eyJhbGciOiJIUzI,vendorB=abc123
+X-Request-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
+```
+
+## Enforcement Rules
+
+- **Gateway enforcement**: API gateways **MUST** generate `traceparent` and `X-Request-ID` for incoming external requests that lack them. Internal service-to-service requests missing `traceparent` **SHOULD** be flagged.
+- **Build-time enforcement**: CI/CD pipelines **MUST** validate that all log output is valid JSON with required fields (`timestamp`, `level`, `trace_id`, `span_id`, `service`, `message`), ISO 8601 timestamps, and valid log levels. Non-JSON log output **MUST** fail validation.
+- **Runtime enforcement**: Log aggregation systems **SHOULD** reject or quarantine entries missing required fields.
+- **Security enforcement**: Log pipelines **SHOULD** include automated PII/credential pattern detection. Matches **MUST** trigger security team alerts. Repeated violations **MAY** result in deployment blocks.
+- **Correlation ID check**: API gateways or integration test suites **MUST** verify all responses include `X-Request-ID`.
+
+**Validation patterns:**
+
+- traceparent: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`
+- X-Request-ID (UUID v4): `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
+- X-Request-ID (ULID): `^[0-9A-HJKMNP-TV-Z]{26}$`
+- Timestamp (ISO 8601 UTC): `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$`
+
+## References
+
+- [W3C Trace Context Specification](https://www.w3.org/TR/trace-context/)
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
+- [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
+
+## Rationale
+
+**W3C Trace Context over proprietary headers** - Vendor-neutral W3C Recommendation supported by all major observability platforms, preventing lock-in and ensuring partner interoperability.
+
+**JSON structured logging** - Machine-parseable without custom grammars, natively supported by all major log aggregation platforms, and enables field-level indexing for correlation across services.
+
+**Separate X-Request-ID from trace-id** - The trace-id is an internal tracing concern that may be regenerated at trust boundaries; X-Request-ID is a business-facing identifier consumers can reference in support tickets.
+
+**Prohibit PII in logs** - Logs are stored with broader access controls than production databases, making aggregated log stores high-value targets (ref: OWASP CWE-532). Prevention is far more effective than post-hoc redaction.
+
+**OpenTelemetry naming conventions** - CNCF-backed industry standard ensuring metrics and spans from different teams, languages, and frameworks are consistent and correlatable without manual mapping.
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/resilience/_category_.json

@@ -0,0 +1 @@
+{"label": "Resilience", "position": 5}

package/standards/integration/standards/resilience/integration-resilience-patterns.md

@@ -0,0 +1,291 @@
+---
+identifier: "INTG-STD-033"
+name: "Integration Resilience Patterns"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "reliability"
+appliesTo: ["api", "events", "a2a", "mcp", "webhooks", "grpc", "graphql", "batch"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: []
+  w3c: []
+  other: ["Microsoft-Resilience-Patterns", "Resilience4j", "Release-It-Nygard"]
+
+taxonomy:
+  capability: "reliability"
+  subCapability: "resilience-patterns"
+  layer: "infrastructure"
+
+enforcement:
+  method: "review-based"
+  reviewChecklist:
+    - "Circuit breaker configured for all external dependencies"
+    - "Bulkhead isolation between independent dependency pools"
+    - "Fallback strategy defined for critical paths"
+    - "Health check endpoints implemented"
+    - "Resilience metrics exposed to monitoring"
+
+dependsOn: ["INTG-STD-029", "INTG-STD-034", "INTG-STD-035"]
+supersedes: ""
+---
+
+# Resilience Patterns
+
+## Purpose
+
+This standard defines **MANDATORY** resilience patterns for all integration points to ensure graceful degradation, automatic recovery, and full observability under failure. It covers circuit breaking, bulkhead isolation, fallback strategies, health checking, load shedding, pattern composition, and observability.
+
+This standard works with INTG-STD-034 (Retry Policies) and INTG-STD-035 (Timeout Standards) to form a complete reliability framework. Retry and timeout behaviors are governed by those companion standards; this document governs the structural patterns that contain, isolate, and recover from failures.
+
+## Rules
+
+### R-1: Circuit Breaker Pattern
+
+Every outbound integration call to an external dependency **MUST** be protected by a circuit breaker implementing three states:
+
+```
+               failure threshold
+                  reached
+  [CLOSED] -----------------> [OPEN]
+     ^                           |
+     |  all probes     timeout   |
+     |  succeed        expires   v
+     +---------- [HALF-OPEN] ---+
+                     |
+                  probe fails -> back to OPEN
+```
+
+**State definitions:**
+
+- **CLOSED** - Normal operation. Requests pass through. When failure rate in the sliding window exceeds the threshold, transitions to OPEN.
+- **OPEN** - Fail-fast mode. All requests rejected immediately. After the wait duration, transitions to HALF-OPEN.
+- **HALF-OPEN** - A limited number of trial requests are permitted. If all succeed, transitions to CLOSED. If any fail, transitions back to OPEN.
+
+**Configuration parameters** - all circuit breakers **MUST** be configurable with:
+
+| Parameter | Description | Required Default |
+|---|---|---|
+| `failureRateThreshold` | Percentage of failures that triggers OPEN state | 50% |
+| `slowCallRateThreshold` | Percentage of slow calls that triggers OPEN state | 80% |
+| `slowCallDurationThreshold` | Duration above which a call is considered slow | Per INTG-STD-035 |
+| `slidingWindowType` | COUNT_BASED or TIME_BASED | COUNT_BASED |
+| `slidingWindowSize` | Number of calls (count) or seconds (time) in the window | 100 calls or 60s |
+| `minimumNumberOfCalls` | Minimum calls before failure rate is calculated | 20 |
+| `waitDurationInOpenState` | Time in OPEN before transitioning to HALF-OPEN | 30s |
+| `permittedNumberOfCallsInHalfOpen` | Trial calls allowed in HALF-OPEN state | 5 |
+| `automaticTransitionEnabled` | Whether to auto-transition from OPEN to HALF-OPEN | true |
+
+Teams **MAY** override defaults per dependency based on documented SLA characteristics, but **MUST NOT** set `failureRateThreshold` below 25% or `waitDurationInOpenState` below 5 seconds to prevent flapping.
+
+**Failure classification:**
+
+- HTTP 5xx and 429 responses **MUST** be counted as failures
+- Connection timeouts and read timeouts **MUST** be counted as failures
+- HTTP 4xx responses (except 429) **MUST NOT** be counted as failures (client errors, not dependency failures)
+- Responses exceeding `slowCallDurationThreshold` **MUST** be counted as slow calls
+
+**Security constraints:**
+
+- Circuit breakers **MUST NOT** cache or replay authentication tokens when probing in HALF-OPEN state. Each probe **MUST** carry fresh credentials.
+- Circuit breaker state **MUST NOT** be externally modifiable without administrative authorization. Manual override endpoints **MUST** require RBAC permissions and **MUST** log every override with actor identity.
+
+**Observability:**
+
+- Every state transition **MUST** be logged at WARN level with: timestamp, dependency name, previous state, new state, failure rate, and sliding window statistics.
+- **MUST** expose metrics: `circuit_breaker_state` (gauge), `circuit_breaker_failure_rate` (gauge), `circuit_breaker_calls_total` (counter by outcome), `circuit_breaker_state_transitions_total` (counter by from/to state).
+- Teams **MUST** alert on: any transition to OPEN, OPEN state lasting longer than 5 minutes, and flapping (>3 transitions in 5 minutes).
+
+### R-2: Bulkhead Isolation
+
+Every integration point **MUST** be isolated using bulkhead patterns so that resource exhaustion in one dependency does not starve others. Teams **MUST** implement at least one strategy per dependency:
+
+- **Thread pool isolation** - dedicated thread pool per dependency. **SHOULD** be used when the dependency has unpredictable latency or full isolation is required.
+- **Semaphore isolation** - counting semaphore limiting concurrent calls. **SHOULD** be used for predictable-latency dependencies or single-threaded/async runtimes.
+- **Connection pool isolation** - separate connection pools per dependency. **MUST** be used for all database and persistent-connection dependencies regardless of other strategies.
+
+**Sizing** - bulkhead sizes **MUST** be calculated from measured dependency characteristics:
+
+```
+maxConcurrent = (peakRPS * p99LatencySeconds) * safetyFactor(1.5-2.0)
+```
+
+Example: Payment API at 200 RPS, 150ms p99 - maxConcurrent = (200 * 0.15) * 1.5 = 45 slots. Teams **MUST** review sizes quarterly or after significant traffic changes.
+
+**Rejection handling** - when a bulkhead rejects a request, the system **MUST**: return immediately (fail-fast), count the rejection as a circuit breaker signal, log at WARN level, route to the fallback handler, and increment `bulkhead_rejections_total`.
+
+### R-3: Fallback Strategies
+
+Every integration point on a critical user-facing path **MUST** define a fallback strategy. Background processes **SHOULD** define fallbacks where feasible. A fallback is invoked when the circuit breaker is OPEN, the bulkhead rejects, retries are exhausted, or the timeout is exceeded.
+
+Teams **MUST** select and document one or more strategies per dependency:
+
+| Strategy | Description | When to Use |
+|---|---|---|
+| **Static Default** | Predefined hardcoded response | When a reasonable default exists |
+| **Cache Fallback** | Last known good response from cache | When stale data is acceptable for a bounded period |
+| **Graceful Degradation** | Reduced functionality, service stays operational | When partial results beat no results |
+| **Alternative Service** | Route to a backup service | When a redundant provider exists |
+| **Queued Retry** | Accept and process asynchronously later | When eventual consistency is acceptable |
+| **Fail with Context** | Structured error with degradation info | When the caller must know and adapt |
+
+**Security constraints** - fallback strategies **MUST NOT** bypass authentication or authorization. Cache fallbacks **MUST** be keyed to include the caller's authorization context (tenant, role, scope). If a fallback returns stale data, the response **MUST** include staleness metadata (e.g., `X-Fallback-Active: true` header and a `data-age` field).
+
+### R-4: Health Check Patterns
+
+Every service exposing integration endpoints **MUST** implement health check endpoints. Every service consuming external dependencies **MUST** perform dependency health checks. Services **MUST** implement at least two levels:
+
+**Shallow health check (liveness)** - `GET /health/live`
+- Verifies the process is running and can accept requests
+- **MUST NOT** call external dependencies
+- **MUST** respond within 100ms
+- **MUST** return HTTP 200 if alive, 503 if not
+
+**Deep health check (readiness)** - `GET /health/ready`
+- Verifies all critical dependencies are operational
+- **MUST** check connectivity to each critical dependency
+- **MUST** respect a 5-second total timeout for all checks combined
+- **MUST** return HTTP 200 if ready, 503 if any critical dependency is unhealthy
+- **MUST** return structured health status in the response body
+
+Circuit breakers **MAY** use dedicated health check endpoints to probe recovery in HALF-OPEN state. Health check probes **MUST NOT** be counted in circuit breaker failure statistics. Health check endpoints **MUST NOT** expose sensitive information. Deep health checks **SHOULD** require authentication when they expose dependency topology.
+
+### R-5: Load Shedding
+
+Services on critical paths **MUST** implement load shedding to maintain quality for high-priority traffic under pressure.
+
+All inbound requests **MUST** be classifiable into at least three priority tiers:
+
+| Priority | Shedding Behavior |
+|---|---|
+| **CRITICAL** (revenue/safety-impacting) | Shed last - only under catastrophic load |
+| **NORMAL** (standard business operations) | Shed when utilization exceeds 85% |
+| **LOW** (deferrable operations) | Shed first when utilization exceeds 70% |
+
+Shedding decisions **MUST** be based on measurable signals: bulkhead utilization, queue depth, p99 latency relative to SLA, CPU/memory utilization, or upstream circuit breaker states.
+
+When shedding, the service **MUST**: return HTTP 503 with a `Retry-After` header, include a structured body indicating load shedding, log at INFO level (shedding is a designed behavior), and increment `load_shedding_total{priority="<tier>"}`.
+
+### R-6: Pattern Composition
+
+Resilience patterns **MUST** be composed in the following order (outermost to innermost):
+
+```
+Load Shedder -> Bulkhead -> Circuit Breaker -> Retry(STD-034) -> Timeout(STD-035) -> Call
+```
+
+This means:
+- Retry wraps the timeout-bounded call. A single retry attempt **MUST NOT** exceed the per-call timeout.
+- Circuit breaker wraps retry. If the circuit is OPEN, retries do not execute.
+- Bulkhead wraps circuit breaker. A rejected bulkhead request does not consume circuit breaker capacity.
+- Load shedder wraps bulkhead. Shed requests never reach the resource pool.
+
+**Timeout budget coordination** - the total timeout **MUST** satisfy:
+
+```
+totalOperationTimeout >= retryAttempts * perCallTimeout + retryDelayBudget
+
+Example: perCallTimeout=2s, retries=3, backoff=[0.5s,1.0s] -> 3*2s + 1.5s = 7.5s -> set totalTimeout=8s
+```
+
+If the circuit breaker transitions to OPEN during a retry sequence, remaining retries **MUST** be abandoned immediately. Circuit breaker rejections are non-retryable.
+
+**Anti-patterns that MUST be avoided:**
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Retry outside circuit breaker without coordination | Retry inside circuit breaker; CB rejection is non-retryable |
+| Timeout longer than CB wait duration | Per-call timeout **MUST** be shorter than `waitDurationInOpenState` |
+| Bulkhead inside circuit breaker | Bulkhead outside circuit breaker |
+| Retry on circuit-breaker-rejected calls | Treat CB rejection as non-retryable |
+| Per-call timeout exceeding total operation timeout | `perCallTimeout < totalOperationTimeout / retryAttempts` |
+
+### R-7: Observability
+
+Every service **MUST** expose a resilience dashboard covering: circuit breaker state, bulkhead utilization, fallback activation rate, load shedding rate by tier, and health check status for all dependencies.
+
+**Required metrics** (Prometheus, OpenTelemetry, or equivalent):
+
+| Metric | Type | Labels |
+|---|---|---|
+| `circuit_breaker_state` | Gauge | `dependency` |
+| `circuit_breaker_failure_rate` | Gauge | `dependency` |
+| `circuit_breaker_calls_total` | Counter | `dependency`, `outcome` |
+| `circuit_breaker_state_transitions_total` | Counter | `dependency`, `from`, `to` |
+| `bulkhead_available_concurrent_calls` | Gauge | `dependency` |
+| `bulkhead_max_concurrent_calls` | Gauge | `dependency` |
+| `bulkhead_rejections_total` | Counter | `dependency` |
+| `fallback_activations_total` | Counter | `dependency`, `strategy` |
+| `load_shedding_total` | Counter | `priority` |
+| `health_check_status` | Gauge | `dependency`, `level` |
+| `health_check_duration_seconds` | Histogram | `dependency`, `level` |
+
+**Structured logging** - all resilience events **MUST** be logged as structured JSON with: `timestamp` (ISO-8601), `level`, `dependency`, `pattern`, `event`, and `correlationId`.
+
+**Alerting** - teams **MUST** configure alerts for:
+
+| Condition | Severity |
+|---|---|
+| Circuit breaker transitions to OPEN | Warning - ack within 15 min |
+| Circuit breaker OPEN > 5 minutes | High - ack within 5 min |
+| Circuit breaker flapping (>3 transitions in 5 min) | High - ack within 5 min |
+| Bulkhead utilization > 90% sustained 2 min | Warning - ack within 15 min |
+| Fallback activation rate > 10% over 5 min | Warning - ack within 15 min |
+| Load shedding CRITICAL tier requests | Critical - ack within 2 min |
+| Deep health check failing > 2 min | High - ack within 5 min |
+
+## Examples
+
+### Circuit breaker composition ordering
+
+```
+Inbound Request
+  -> Load Shedder (reject low-priority if overloaded)
+    -> Bulkhead (limit concurrency per dependency)
+      -> Circuit Breaker (fail-fast if dependency down)
+        -> Retry (recover from transient failures, per INTG-STD-034)
+          -> Timeout (bound call duration, per INTG-STD-035)
+            -> External Call
+```
+
+If the circuit is OPEN, the request skips retry and timeout, goes directly to the fallback handler.
+
+## Enforcement Rules
+
+- Every service exposing or consuming integration points **MUST** implement these resilience patterns before production deployment.
+- Architecture reviews **MUST** verify implementation against the following checklist: circuit breaker configured per dependency, bulkhead isolation with measured sizing, fallback strategy documented and authZ-compliant, liveness/readiness endpoints implemented, patterns composed in correct order, timeout budgets consistent, all metrics exposed and alerts configured, and RBAC on circuit breaker overrides.
+- Services without circuit breakers for external dependencies **MUST NOT** be approved for production.
+- Fallback strategies **MUST** be tested via resilience testing (chaos engineering, dependency failure injection).
+- Non-compliance discovered post-deployment **MUST** be remediated within one sprint or documented with an accepted risk exception signed by the service owner and integration architecture lead.
+- Where tooling permits, CI/CD **SHOULD** validate: resilience config parsing, timeout budget consistency, HTTP client references to circuit breaker/bulkhead config, and health check endpoint definitions.
+
+## References
+
+- [Microsoft Azure - Circuit Breaker Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
+- [Resilience4j - CircuitBreaker](https://resilience4j.readme.io/docs/circuitbreaker)
+- [Release It! Second Edition](https://pragprog.com/titles/mnee2/release-it-second-edition/) - Michael Nygard's stability patterns
+- [AWS - Advanced Multi-AZ Resilience Patterns](https://docs.aws.amazon.com/whitepapers/latest/advanced-multi-az-resilience-patterns/pattern-1-health-check-circuit-breaker.html)
+
+## Rationale
+
+**Why these specific patterns?** The six patterns represent the minimum viable resilience set validated by over a decade of production experience at Netflix, Amazon, Google, and Microsoft, codified in Nygard's "Release It!" and implemented in Hystrix, Resilience4j, and Polly.
+
+**Why mandate composition order?** Incorrect composition is a common, subtle failure source - e.g., retry outside circuit breaker causes retries to fight the breaker, delaying fail-fast and wasting resources.
+
+**Why include security constraints?** Resilience patterns introduce alternative code paths that can inadvertently bypass security controls - cache fallbacks can leak data across authorization boundaries, and HALF-OPEN probes can replay stale tokens.
+
+**Why detailed observability?** Without mandatory metrics and logging, teams cannot distinguish "breaker correctly protecting from failure" from "breaker incorrectly blocking all traffic due to misconfigured threshold."
+
+**Why not mandate specific libraries?** This standard specifies behavior and configuration, not implementations. Resilience4j, Polly, and custom implementations all satisfy these requirements without limiting technology choice.
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |