docs(memory-bank): record relay hardening policy baseline and operating knobs

memory-bank/decisions.md

@@ -45,3 +45,38 @@ Related:
 
 - `context/project-overview.md`
 - `memory-bank/README.md`
+
+---
+
+### D-002: Relay forwarding hardening policy baseline (P2-S3)
+
+date: 2026-03-24  
+author: Cline  
+scope: `pages/api/middleware/relayForwarding.js`, relay-backed endpoint handlers  
+type: decision  
+rationale: Consolidate relay reliability behavior into one shared policy so retries, timeouts, and logging are predictable and safe across all migrated GET flows.  
+impact: Improves resilience and observability while reducing risk of accidental overload, noisy duplicate logs, and inconsistent retry behavior per endpoint.  
+status: accepted
+
+Decision:
+
+- Shared relay defaults and bounds are centrally enforced in middleware:
+    - timeout default `8000ms`, clamped to `100..30000ms`
+    - retries default `2`, clamped to `0..4`
+    - retry delays clamped to `0..5000ms`
+- Retry classification is explicit:
+    - retryable: `408`, `429`, `5xx`, selected network/transient transport error codes
+    - non-retryable: deterministic client/auth statuses (`400`, `401`, `403`, `404`, `422`) and other explicit non-retryable HTTP statuses
+- Structured relay logs are redacted and emitted once per failure path:
+    - relay layer emits retry/failure structured events
+    - endpoint catch logging avoids duplicate emission when relay layer already logged terminal failure
+
+Consequences:
+
+- Endpoint contracts remain unchanged while reliability behavior is normalized.
+- Future relay policy changes should be made in one location and validated via phase21 hardening tests.
+
+Related:
+
+- `memory-bank/change-log.md` (CL-030, CL-031)
+- `tests/phase21/relay-forwarding-hardening.test.cjs`

memory-bank/patterns.md

@@ -64,3 +64,28 @@ Example paths:
 
 - `locales/en/**`, `locales/cy/**`
 - `next.config.js`, `i18n.js`
+
+### P-003: Shared Relay Policy via Middleware (No Endpoint Drift)
+
+date: 2026-03-24  
+author: Cline  
+scope: `pages/api/middleware/relayForwarding.js`, `pages/api/endpoint/*_api.js` relay GET handlers  
+type: pattern  
+rationale: Keep reliability and logging policy centralized so endpoint handlers remain thin and behavior stays consistent as relay surface evolves.  
+impact: Reduces duplication/drift in timeout/retry/error behavior and supports safer incremental endpoint migration/hardening.  
+status: accepted
+
+Pattern:
+Implement retry/timeout/redacted structured logging in shared relay middleware and keep endpoint handlers focused on validation, transform, and route-level response contracts.
+
+When to use:
+
+- Any new or migrated relay-backed endpoint
+- Any relay reliability/logging policy update
+
+Example paths:
+
+- `pages/api/middleware/relayForwarding.js`
+- `pages/api/endpoint/getadvancedsearch_api.js`
+- `pages/api/endpoint/getdnscoords_api.js`
+- `tests/phase21/relay-forwarding-hardening.test.cjs`

memory-bank/techContext.md

@@ -22,6 +22,21 @@
 - Additional custom server entries exist (`server.js`, `server/server.js`) but are currently treated as non-active for the refactor baseline unless deployment evidence indicates otherwise.
 - Environment-driven config for auth, relay/API roots, hash key, notify key, and database URL.
 
+### Relay forwarding hardening policy knobs (P2-S3)
+
+- Shared relay middleware now enforces centralized timeout/retry behavior for relay-backed GET flows.
+- Supported env knobs:
+    - `RELAY_TIMEOUT_MS` (default `8000`, clamped `100..30000`)
+    - `RELAY_RETRY_MAX` (default `2`, clamped `0..4`)
+    - `RELAY_RETRY_BASE_DELAY_MS` (default `200`, clamped `0..5000`)
+    - `RELAY_RETRY_MAX_DELAY_MS` (default `1200`, clamped `0..5000`)
+- Retry classification:
+    - retryable: `408`, `429`, `5xx`, selected transient transport errors
+    - non-retryable: deterministic client/auth statuses (`400`, `401`, `403`, `404`, `422`) and other explicit non-retryable HTTP statuses
+- Logging behavior:
+    - structured redacted relay events emitted for retry/failure
+    - duplicate endpoint-layer error logging suppressed when relay layer already emitted terminal failure log
+
 ## Tooling and quality gates
 
 - Linting: `npm run lint` (`next lint`).