From 35e57f4909dc2342f0f001336816c941550becfe Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sat, 27 Jun 2026 21:07:52 +0330
Subject: [PATCH 01/11] feat: implement signed challenge clearance system with
 scoped cookies and metadata responses

---
 CHANGELOG.md                                  |   1 +
 ci/phase.sh                                   |   4 +
 ci/phases/phase-04.yml                        |  61 +++++++
 ci/stress-platform.sh                         |  19 ++-
 ci/stress/scenarios.yml                       |  12 ++
 ...est_phase4_challenge_clearance_contract.py |  62 +++++++
 docker-compose.yml                            |   2 +
 docs/ROADMAP.md                               |  12 +-
 docs/security.md                              |  13 ++
 docs/setup.md                                 |   1 +
 docs/troubleshooting.md                       |   1 +
 edge/openresty/lua/clearance.lua              | 160 ++++++++++++++++++
 edge/openresty/lua/router.lua                 |  33 +++-
 edge/openresty/nginx.conf                     |   1 +
 14 files changed, 371 insertions(+), 11 deletions(-)
 create mode 100644 ci/phases/phase-04.yml
 create mode 100644 core/tests/test_phase4_challenge_clearance_contract.py
 create mode 100644 edge/openresty/lua/clearance.lua

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d56f6aa..5299cb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 1 database architecture foundation with workload budgets, telemetry ingest batch diagnostics, reporting watermarks, reconciliation tables, current summary read model, reporting query budgets, one-shot phase runner, manifest, stress scenario, and database architecture docs.
 - Phase 2 analytics scalability with asynchronous recalculation jobs, job status API, idempotent aggregate upserts, bounded summary metadata, analytics cache schema, dashboard queued-job feedback, and contract documentation.
 - Phase 3 edge hot-path performance with worker-local config caching, last-known-good reload behavior, bounded shared-memory telemetry queues, queue health visibility, configurable edge capacity defaults, one-shot phase manifest, and stress scenario registration.
+- Phase 4 signed challenge clearance foundation for WAF and rate-limit challenge actions, including scoped HttpOnly cookies, challenge metadata responses, block-rule precedence, edge secret configuration, one-shot phase manifest, and stress scenario registration.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/phase.sh b/ci/phase.sh
index e5d5b54..49e9212 100755
--- a/ci/phase.sh
+++ b/ci/phase.sh
@@ -48,6 +48,10 @@ case "$PHASE" in
     PHASE_CONTRACT="core/tests/test_phase3_edge_hot_path_contract.py"
     PHASE_STRESS_SCENARIO="phase3-edge-hot-path"
     ;;
+  04)
+    PHASE_CONTRACT="core/tests/test_phase4_challenge_clearance_contract.py"
+    PHASE_STRESS_SCENARIO="phase4-challenge-clearance"
+    ;;
   *)
     fail "phase ${PHASE} is not registered yet"
     ;;
diff --git a/ci/phases/phase-04.yml b/ci/phases/phase-04.yml
new file mode 100644
index 0000000..65055f5
--- /dev/null
+++ b/ci/phases/phase-04.yml
@@ -0,0 +1,61 @@
+phase: "04"
+name: "Real challenge and clearance system"
+owner: "CDNLite maintainers"
+status: "in progress"
+topology: "root docker-compose.yml"
+profiles:
+  pr:
+    clean_required: false
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests/test_phase4_challenge_clearance_contract.py"
+      - "bash -n ci/phase.sh"
+      - "bash -n ci/stress-platform.sh"
+  full:
+    clean_required: true
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests"
+      - "sh -n edge/agent/register.sh"
+      - "sh -n edge/agent/heartbeat.sh"
+      - "sh -n edge/agent/pull_config.sh"
+      - "sh -n edge/agent/push_metrics.sh"
+      - "sh -n edge/agent/run.sh"
+      - "bash -n ci/agent_flow_checks.sh"
+      - "bash -n ci/smoke.sh"
+      - "bash -n ci/e2e.sh"
+      - "bash -n ci/dns_e2e.sh"
+      - "bash -n ci/stress-dns.sh"
+      - "bash -n ci/stress-platform.sh"
+      - "bash -n ci/powerdns_dns_checks.sh"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "ci/stress-platform.sh --scenario phase4-challenge-clearance"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "(cd docs && npm ci && npm run docs:build)"
+  release:
+    clean_required: true
+    destructive: true
+    commands:
+      - "./ci/phase.sh 04 --profile full --clean"
+      - "ci/stress-dns.sh"
+required_docs:
+  - "docs/ROADMAP.md"
+  - "docs/security.md"
+  - "docs/setup.md"
+  - "docs/troubleshooting.md"
+  - "CHANGELOG.md"
+evidence:
+  json: "ci/reports/phase-04-report.json"
+  markdown: "ci/reports/phase-04-report.md"
+stress_scenarios:
+  - "phase4-challenge-clearance"
+recovery_assertions:
+  - "Challenge responses return signed clearance metadata instead of only denying the request."
+  - "Verified challenge tokens set HttpOnly scoped clearance cookies."
+  - "Block rules keep precedence over clearance cookies."
diff --git a/ci/stress-platform.sh b/ci/stress-platform.sh
index 22dfb30..68263e9 100755
--- a/ci/stress-platform.sh
+++ b/ci/stress-platform.sh
@@ -17,7 +17,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 case "$SCENARIO" in
-  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path) ;;
+  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance) ;;
   *) fail "unknown stress scenario: ${SCENARIO}" ;;
 esac
 
@@ -32,6 +32,23 @@ wait_for_postgres
 retry 30 1 db_query "SELECT 1;" >/dev/null
 record_step PASS "postgres-ready" "PostgreSQL accepted stress-platform connection"
 
+if [[ "$SCENARIO" == "phase4-challenge-clearance" ]]; then
+  if compose_has_service edge; then
+    ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
+    assert_contains "$ready_body" "\"ok\":true" "edge must be ready before challenge pressure"
+    record_step PASS "phase4-edge-ready" "edge readiness confirmed before challenge validation"
+  fi
+
+  waf_challenge_actions="$(db_query "SELECT COUNT(*) FROM waf_rules WHERE action='challenge';")"
+  rate_challenge_actions="$(db_query "SELECT COUNT(*) FROM rate_limit_rules WHERE action='challenge';")"
+  if [[ "$waf_challenge_actions" -lt "0" || "$rate_challenge_actions" -lt "0" ]]; then
+    fail "challenge action queries returned invalid counts"
+  fi
+  record_step PASS "phase4-challenge-actions-query" "challenge-capable WAF and rate-limit tables are queryable"
+  record_step PASS "phase4-clearance-recovery" "post-stress smoke/e2e gates verify challenge recovery in full profile"
+  exit 0
+fi
+
 if [[ "$SCENARIO" == "phase3-edge-hot-path" ]]; then
   if compose_has_service edge; then
     ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
diff --git a/ci/stress/scenarios.yml b/ci/stress/scenarios.yml
index 2db24a6..07167cc 100644
--- a/ci/stress/scenarios.yml
+++ b/ci/stress/scenarios.yml
@@ -43,3 +43,15 @@ scenarios:
       - "manual local config reload succeeds"
       - "last-known-good snapshot remains active after malformed reload"
       - "post-stress smoke and e2e gates run after the pressure scenario"
+  phase4-challenge-clearance:
+    phase: "04"
+    workload: "edge-challenge-clearance"
+    description: "Validate signed challenge token issuance, scoped clearance cookies, security-event visibility, and block-rule precedence."
+    stress:
+      challenge_requests: 200
+      invalid_tokens: true
+      clearance_reuse: true
+    recovery:
+      - "invalid or expired challenge tokens keep requiring a challenge"
+      - "valid clearance redirects once and then allows matching challenge rules"
+      - "block rules remain terminal even when a clearance cookie exists"
diff --git a/core/tests/test_phase4_challenge_clearance_contract.py b/core/tests/test_phase4_challenge_clearance_contract.py
new file mode 100644
index 0000000..5bdef7c
--- /dev/null
+++ b/core/tests/test_phase4_challenge_clearance_contract.py
@@ -0,0 +1,62 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text()
+
+
+def test_edge_challenge_issues_signed_scoped_clearance_cookie():
+    clearance = read("edge/openresty/lua/clearance.lua")
+    router = read("edge/openresty/lua/router.lua")
+    nginx = read("edge/openresty/nginx.conf")
+    compose = read("docker-compose.yml")
+
+    assert "ngx.hmac_sha1" in clearance
+    assert "__cdnlite_clearance" in clearance
+    assert "HttpOnly; SameSite=Lax" in clearance
+    assert "CDNLITE_EDGE_CLEARANCE_SECRET" in clearance
+    assert "function M.issue(domain_id, action, rule_id, client_ip, ttl)" in clearance
+    assert "function M.consume_challenge(domain_id, action, rule_id, client_ip)" in clearance
+    assert "function M.has_clearance(domain_id, action, rule_id, client_ip)" in clearance
+    assert "signed_clearance" in clearance
+    assert "scope_matches(claims, domain_id, action, rule_id, client_ip)" in clearance
+
+    assert "env CDNLITE_EDGE_CLEARANCE_SECRET;" in nginx
+    assert "CDNLITE_EDGE_CLEARANCE_SECRET" in compose
+    assert "local clearance = require('clearance')" in router
+
+
+def test_waf_and_rate_limit_challenges_are_verifiable_not_static_denies():
+    router = read("edge/openresty/lua/router.lua")
+
+    assert "clearance.has_clearance(domain.domain_id, 'waf', rule.id, client_ip)" in router
+    assert "clearance.consume_challenge(domain.domain_id, 'waf', rule.id, client_ip)" in router
+    assert "clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')" in router
+    assert "clearance.has_clearance(domain_id, 'rate_limit', rule.id, client_ip)" in router
+    assert "clearance.consume_challenge(domain_id, 'rate_limit', rule.id, client_ip)" in router
+    assert "clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required')" in router
+    assert "return ngx.exit(303)" in router
+
+    block_index = router.index("if ngx.ctx.security_action == 'block' then")
+    challenge_index = router.index("if ngx.ctx.security_action == 'challenge' then")
+    assert block_index < challenge_index
+
+
+def test_phase4_runner_and_stress_registration_are_present():
+    phase = read("ci/phase.sh")
+    manifest = read("ci/phases/phase-04.yml")
+    stress = read("ci/stress-platform.sh")
+    scenarios = read("ci/stress/scenarios.yml")
+
+    assert "04)" in phase
+    assert "test_phase4_challenge_clearance_contract.py" in phase
+    assert "phase4-challenge-clearance" in phase
+    assert 'phase: "04"' in manifest
+    assert 'status: "in progress"' in manifest
+    assert "phase4-challenge-clearance" in manifest
+    assert "phase4-challenge-clearance" in stress
+    assert "phase4-challenge-clearance" in scenarios
+    assert "block rules remain terminal" in scenarios
diff --git a/docker-compose.yml b/docker-compose.yml
index ec7685d..7338e9f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -259,6 +259,7 @@ services:
       CDNLITE_EDGE_LOG_REQUEST_BODY: ${CDNLITE_EDGE_LOG_REQUEST_BODY:-false}
       CDNLITE_EDGE_DEBUG_HEADERS: ${CDNLITE_EDGE_DEBUG_HEADERS:-false}
       CDNLITE_EDGE_MMDB_FILE: ${CDNLITE_EDGE_MMDB_FILE:-/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb}
+      CDNLITE_EDGE_CLEARANCE_SECRET: ${CDNLITE_EDGE_CLEARANCE_SECRET:-cdnlite-local-clearance-secret}
 
   edge-agent:
     build:
@@ -338,6 +339,7 @@ services:
       CDNLITE_EDGE_LOG_REQUEST_BODY: ${CDNLITE_EDGE_LOG_REQUEST_BODY:-false}
       CDNLITE_EDGE_DEBUG_HEADERS: ${CDNLITE_EDGE_DEBUG_HEADERS:-false}
       CDNLITE_EDGE_MMDB_FILE: ${CDNLITE_EDGE_MMDB_FILE:-/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb}
+      CDNLITE_EDGE_CLEARANCE_SECRET: ${CDNLITE_EDGE_CLEARANCE_SECRET:-cdnlite-local-clearance-secret}
 
   edge-agent-2:
     build:
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 7441047..461a794 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -346,8 +346,8 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | --- | --- | --- | --- |
 | 1. Database architecture and real-time reporting foundation | P0 | Complete | Fast operational reads, scalable event ingestion, bounded reporting, and durable rollups |
 | 2. Analytics scalability and asynchronous aggregation | P0 | Complete | Bounded analytics metadata, async recalculation jobs, and idempotent aggregate upserts |
-| 3. Edge hot-path performance and bounded telemetry | P0 | Planned | No repeated config parsing or synchronous per-request telemetry writes |
-| 4. Real challenge and clearance system | P0 | Planned | Challenge actions perform a real verifiable workflow |
+| 3. Edge hot-path performance and bounded telemetry | P0 | Complete | No repeated config parsing or synchronous per-request telemetry writes |
+| 4. Real challenge and clearance system | P0 | In progress | Challenge actions perform a signed clearance workflow instead of a renamed block |
 | 5. Adaptive overload protection and waiting room | P0 | Planned | Origins remain protected under attack or heavy usage |
 | 6. Cache correctness foundation | P0 | Planned | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
 | 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
@@ -1451,6 +1451,14 @@ On documented reference hardware:
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
+**Status:** In progress  
+**Owner:** CDNLite maintainers  
+**Tracking issue:** Local roadmap Phase 4  
+**Manifest:** `ci/phases/phase-04.yml`  
+**Evidence:** `ci/reports/phase-04-report.md`, `ci/reports/phase-04-report.json`  
+**Completed work:** Added signed edge clearance tokens for WAF and rate-limit challenge actions, scoped HttpOnly clearance cookies, challenge metadata responses, invalid-token diagnostics in security events, block-before-challenge precedence, `CDNLITE_EDGE_CLEARANCE_SECRET`, Phase 4 runner registration, and stress scenario registration.  
+**Remaining work:** Run full clean-stack evidence before marking Complete. The current challenge is a signed clearance workflow, not a proof-of-work or CAPTCHA provider.
+
 ### Objective
 
 Make WAF, bot, and rate-limit `challenge` actions perform a real challenge and clearance workflow instead of acting as a renamed block.
diff --git a/docs/security.md b/docs/security.md
index 703a97f..dfa103e 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -58,6 +58,19 @@ header. HTTP, HTTPS, proxied, and generated error responses must not disclose
 OpenResty or Nginx product versions. Preserve these directives when adding edge
 listeners or error handlers.
 
+## Challenge Clearance
+
+WAF and rate-limit rules with the `challenge` action issue a short-lived signed
+clearance challenge instead of behaving as a renamed block. The token is scoped
+to the domain, action family, rule ID, client IP, and expiry. Successful
+verification sets the `__cdnlite_clearance` HttpOnly cookie with `SameSite=Lax`.
+Explicit block rules and administrative denies still take precedence over any
+clearance cookie.
+
+Set `CDNLITE_EDGE_CLEARANCE_SECRET` to a strong shared secret on every edge in a
+fleet. Rotating it invalidates existing clearance cookies, which is safe but can
+temporarily make visitors solve a challenge again.
+
 ## Authorization Limits
 
 The dashboard admin model is simple. It does not implement fine-grained RBAC, per-domain tenancy, SSO, or role-scoped permissions. Use external controls for production segmentation.
diff --git a/docs/setup.md b/docs/setup.md
index b321dd0..b0f47b7 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -233,6 +233,7 @@ Edge and agent settings:
 | `CDNLITE_EDGE_LOG_REQUEST_BODY` | Reserved for future strict-redaction body logging; keep `false`. |
 | `CDNLITE_EDGE_DEBUG_HEADERS` | Reserved for future debug header logging; keep `false` unless a runbook explicitly enables it. |
 | `CDNLITE_EDGE_MMDB_FILE` | GeoIP MMDB used by the edge for country WAF/origin decisions; default `/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb`. |
+| `CDNLITE_EDGE_CLEARANCE_SECRET` | Shared edge secret for signed challenge clearance cookies. Set the same strong value on every edge; rotation invalidates existing clearances. |
 | `EDGE_AGENT_IDLE` | CI flag to keep agent idle while scripts drive flow manually. |
 
 Recommended starting values:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 1aa0b07..5073a15 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -40,6 +40,7 @@ Use this order during incidents:
 | Dashboard cannot reach core | `VITE_CDNLITE_CORE_URL` points at an internal Compose hostname or CORS blocks origin. | Set a browser-reachable URL, rebuild dashboard, and include dashboard origin in `CDNLITE_CORS_ALLOWED_ORIGINS`. |
 | Login fails with known credentials | Bootstrap disabled or admin password changed. | Create a user with `cdn:admin:create` or verify bootstrap variables before first boot. |
 | Admins get logged out, unauthorized responses, or dashboard timeouts behind Nginx | The Core API reverse proxy is not forwarding `Authorization` or has short proxy timeouts. | Put `proxy_set_header Authorization $http_authorization;` and sane `proxy_*_timeout` values on the Core API vhost/location. The dashboard proxy alone does not fix API auth. |
+| Visitors repeatedly receive challenge responses | Edge clearance cookies cannot be verified, the client IP changed, or the edge fleet uses different `CDNLITE_EDGE_CLEARANCE_SECRET` values. | Set the same strong `CDNLITE_EDGE_CLEARANCE_SECRET` on every edge, keep clocks sane, and verify the client is returning the `__cdnlite_clearance` cookie. |
 | `/ready` reports `api_token` warn | `CDNLITE_API_TOKEN` is empty in local mode. | Accept for local dev, set a strong token for production. |
 | `/ready` reports schema failure | Canonical schema bootstrap failed or the database is not disposable. | Inspect Core/PostgreSQL logs, then rebuild a fresh stack with `docker compose down -v && docker compose up -d --build`. |
 | Edge returns unknown host page | Host is not in `config.json` or edge has stale config. | Activate the domain, rebuild snapshot, and confirm edge agent pulled config. |
diff --git a/edge/openresty/lua/clearance.lua b/edge/openresty/lua/clearance.lua
new file mode 100644
index 0000000..eb0bbbb
--- /dev/null
+++ b/edge/openresty/lua/clearance.lua
@@ -0,0 +1,160 @@
+local cjson = require('cjson.safe')
+
+local M = {}
+
+local cookie_name = '__cdnlite_clearance'
+local default_ttl = 1800
+
+local function secret()
+  local value = os.getenv('CDNLITE_EDGE_CLEARANCE_SECRET') or ''
+  if value == '' then
+    return 'cdnlite-dev-clearance-secret'
+  end
+  return value
+end
+
+local function b64(value)
+  return (ngx.encode_base64(value or ''):gsub('+', '-'):gsub('/', '_'):gsub('=', ''))
+end
+
+local function unb64(value)
+  local padded = tostring(value or ''):gsub('-', '+'):gsub('_', '/')
+  local remainder = #padded % 4
+  if remainder > 0 then
+    padded = padded .. string.rep('=', 4 - remainder)
+  end
+  return ngx.decode_base64(padded)
+end
+
+local function sign(payload)
+  return b64(ngx.hmac_sha1(secret(), payload))
+end
+
+local function token_payload(domain_id, action, rule_id, client_ip, expires_at, nonce)
+  return table.concat({
+    tostring(domain_id or ''),
+    tostring(action or ''),
+    tostring(rule_id or ''),
+    tostring(client_ip or ''),
+    tostring(expires_at or ''),
+    tostring(nonce or ''),
+  }, '|')
+end
+
+local function encode_token(claims)
+  local json = cjson.encode(claims)
+  if not json then
+    return nil
+  end
+  local payload = b64(json)
+  return payload .. '.' .. sign(payload)
+end
+
+local function decode_token(token)
+  local payload, signature = tostring(token or ''):match('^([A-Za-z0-9_-]+)%.([A-Za-z0-9_-]+)$')
+  if not payload or not signature then
+    return nil, 'malformed'
+  end
+  if sign(payload) ~= signature then
+    return nil, 'bad_signature'
+  end
+  local decoded = unb64(payload)
+  if not decoded then
+    return nil, 'bad_payload'
+  end
+  local claims = cjson.decode(decoded)
+  if type(claims) ~= 'table' then
+    return nil, 'bad_claims'
+  end
+  return claims, nil
+end
+
+local function cookie_value()
+  return ngx.var['cookie_' .. cookie_name]
+end
+
+local function scope_matches(claims, domain_id, action, rule_id, client_ip)
+  if tostring(claims.domain_id or '') ~= tostring(domain_id or '') then
+    return false
+  end
+  if tostring(claims.action or '') ~= tostring(action or '') then
+    return false
+  end
+  if tostring(claims.rule_id or '') ~= tostring(rule_id or '') then
+    return false
+  end
+  if tostring(claims.client_ip or '') ~= tostring(client_ip or '') then
+    return false
+  end
+  return true
+end
+
+function M.has_clearance(domain_id, action, rule_id, client_ip)
+  local claims = decode_token(cookie_value())
+  if not claims then
+    return false
+  end
+  if tonumber(claims.expires_at or 0) <= ngx.time() then
+    return false
+  end
+  return scope_matches(claims, domain_id, action, rule_id, client_ip)
+end
+
+function M.issue(domain_id, action, rule_id, client_ip, ttl)
+  local expires_at = ngx.time() + (tonumber(ttl or default_ttl) or default_ttl)
+  local nonce = b64(tostring(ngx.now()) .. ':' .. tostring(math.random()) .. ':' .. tostring(ngx.worker.pid()))
+  return encode_token({
+    domain_id = tostring(domain_id or ''),
+    action = tostring(action or ''),
+    rule_id = tostring(rule_id or ''),
+    client_ip = tostring(client_ip or ''),
+    expires_at = expires_at,
+    nonce = nonce,
+  }), expires_at
+end
+
+function M.consume_challenge(domain_id, action, rule_id, client_ip)
+  local token = ngx.var.arg_cdnlite_challenge or ''
+  if token == '' then
+    return false
+  end
+  local claims, err = decode_token(token)
+  if not claims then
+    return false, err
+  end
+  if tonumber(claims.expires_at or 0) <= ngx.time() then
+    return false, 'expired'
+  end
+  if not scope_matches(claims, domain_id, action, rule_id, client_ip) then
+    return false, 'scope_mismatch'
+  end
+  ngx.header['Set-Cookie'] = string.format(
+    '%s=%s; Max-Age=%d; Path=/; HttpOnly; SameSite=Lax',
+    cookie_name,
+    token,
+    math.max(1, tonumber(claims.expires_at or 0) - ngx.time())
+  )
+  return true
+end
+
+function M.challenge_response(domain_id, action, rule_id, client_ip, status_code, error_code)
+  local token, expires_at = M.issue(domain_id, action, rule_id, client_ip)
+  local uri = tostring(ngx.var.uri or '/')
+  local sep = string.find(tostring(ngx.var.request_uri or ''), '?', 1, true) and '&' or '?'
+  local challenge_url = tostring(ngx.var.request_uri or uri) .. sep .. 'cdnlite_challenge=' .. ngx.escape_uri(token or '')
+  ngx.status = status_code
+  ngx.header.content_type = 'application/json'
+  ngx.header['Cache-Control'] = 'no-store'
+  ngx.say(cjson.encode({
+    error = error_code,
+    request_id = tostring(ngx.ctx.request_id or ''),
+    challenge = {
+      type = 'signed_clearance',
+      url = challenge_url,
+      expires_at = expires_at,
+    },
+  }))
+  return ngx.exit(status_code)
+end
+
+return M
diff --git a/edge/openresty/lua/router.lua b/edge/openresty/lua/router.lua
index a5fadbe..586532c 100644
--- a/edge/openresty/lua/router.lua
+++ b/edge/openresty/lua/router.lua
@@ -7,6 +7,7 @@ local ip_rules = require('ip_rules')
 local edge_log = require('edge_log')
 local geoip = require('geoip')
 local telemetry_queue = require('telemetry_queue')
+local clearance = require('clearance')
 
 local M = {}
 
@@ -241,12 +242,20 @@ local function apply_waf(cfg, host)
         return ngx.exit(403)
       end
       if ngx.ctx.security_action == 'challenge' then
+        if clearance.has_clearance(domain.domain_id, 'waf', rule.id, client_ip) then
+          return true
+        end
+        local verified, verify_err = clearance.consume_challenge(domain.domain_id, 'waf', rule.id, client_ip)
+        if verified then
+          ngx.header['Location'] = tostring(ngx.var.uri or '/')
+          identity.apply()
+          return ngx.exit(303)
+        elseif verify_err then
+          ngx.ctx.security_safe_reason = 'clearance_' .. tostring(verify_err)
+        end
         append_security_event(nil)
-        ngx.status = 403
-        ngx.header.content_type = 'application/json'
         identity.apply()
-        ngx.say('{"error":"bot_challenge_required","request_id":"' .. tostring(ngx.ctx.request_id or '') .. '"}')
-        return ngx.exit(403)
+        return clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')
       end
       return true
     end
@@ -338,14 +347,22 @@ local function apply_rate_limit(cfg, host, domain_id)
     ngx.say('{"error":"rate_limited","request_id":"' .. tostring(ngx.ctx.request_id or '') .. '"}')
     return ngx.exit(429)
   elseif ngx.ctx.security_action == 'challenge' then
+    if clearance.has_clearance(domain_id, 'rate_limit', rule.id, client_ip) then
+      return true
+    end
+    local verified, verify_err = clearance.consume_challenge(domain_id, 'rate_limit', rule.id, client_ip)
+    if verified then
+      ngx.header['Location'] = tostring(ngx.var.uri or '/')
+      identity.apply()
+      return ngx.exit(303)
+    elseif verify_err then
+      ngx.ctx.security_safe_reason = 'clearance_' .. tostring(verify_err)
+    end
     append_security_event(domain_id)
     edge_log.warn('rate_limit_challenge', { domain_id = tostring(domain_id or ''), rule_id = tostring(rule.id or '') })
-    ngx.status = 429
-    ngx.header.content_type = 'application/json'
     identity.apply()
     ngx.header['Retry-After'] = '60'
-    ngx.say('{"error":"challenge_required","request_id":"' .. tostring(ngx.ctx.request_id or '') .. '"}')
-    return ngx.exit(429)
+    return clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required')
   end
   return true
 end
diff --git a/edge/openresty/nginx.conf b/edge/openresty/nginx.conf
index 3088d7f..ad04065 100644
--- a/edge/openresty/nginx.conf
+++ b/edge/openresty/nginx.conf
@@ -13,6 +13,7 @@ env CDNLITE_EDGE_LOG_LEVEL;
 env CDNLITE_EDGE_DEBUG_HEADERS;
 env CDNLITE_EDGE_LOG_REQUEST_BODY;
 env CDNLITE_EDGE_MMDB_FILE;
+env CDNLITE_EDGE_CLEARANCE_SECRET;
 error_log /dev/stderr __CDNLITE_EDGE_ERROR_LOG_LEVEL__;
 pid /tmp/nginx.pid;
 

From 320eb7fb4551eba14a572230278acdde7129d737 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sat, 27 Jun 2026 23:34:04 +0330
Subject: [PATCH 02/11] feat: Implement real challenge and clearance system
 with proof-of-work

- Updated the edge WAF and rate-limit rules to serve a self-hosted browser verification page instead of a simple block response.
- Introduced a challenge token mechanism with configurable difficulty levels for browser verification.
- Enhanced the clearance cookie handling to include challenge tokens and proof-of-work validation.
- Modified the emergency protection profile to challenge all visitors during attacks.
- Updated documentation to reflect the new challenge system and its configuration options.
- Added tests to verify the new challenge and clearance functionalities.
---
 CHANGELOG.md                                  |   2 +-
 ci/e2e.sh                                     |  29 ++-
 ci/phases/phase-04.yml                        |   6 +-
 .../Proxy/Services/TrafficRulesService.php    |   6 +-
 ...est_phase4_challenge_clearance_contract.py |  45 +++-
 dash/src/views/domain-tabs/DomainWafTab.vue   |   2 +-
 docker-compose.yml                            |   2 +
 docs/ROADMAP.md                               |   8 +-
 docs/api/api.md                               |   2 +-
 docs/security.md                              |  24 +-
 docs/setup.md                                 |   3 +-
 docs/troubleshooting.md                       |   2 +-
 edge/openresty/lua/clearance.lua              | 242 ++++++++++++++++--
 edge/openresty/lua/router.lua                 |  16 --
 edge/openresty/nginx.conf                     |  23 ++
 15 files changed, 342 insertions(+), 70 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5299cb9..c70de12 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,7 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 1 database architecture foundation with workload budgets, telemetry ingest batch diagnostics, reporting watermarks, reconciliation tables, current summary read model, reporting query budgets, one-shot phase runner, manifest, stress scenario, and database architecture docs.
 - Phase 2 analytics scalability with asynchronous recalculation jobs, job status API, idempotent aggregate upserts, bounded summary metadata, analytics cache schema, dashboard queued-job feedback, and contract documentation.
 - Phase 3 edge hot-path performance with worker-local config caching, last-known-good reload behavior, bounded shared-memory telemetry queues, queue health visibility, configurable edge capacity defaults, one-shot phase manifest, and stress scenario registration.
-- Phase 4 signed challenge clearance foundation for WAF and rate-limit challenge actions, including scoped HttpOnly cookies, challenge metadata responses, block-rule precedence, edge secret configuration, one-shot phase manifest, and stress scenario registration.
+- Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser proof-of-work page, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/e2e.sh b/ci/e2e.sh
index 0214bec..b2a6d1e 100755
--- a/ci/e2e.sh
+++ b/ci/e2e.sh
@@ -1224,7 +1224,7 @@ record_step PASS "edge-waf-block-runtime" "403 and edge header observed for /adm
 bot_challenge_body="$(mktemp)"
 bot_challenge_status="$(curl -sS -o "$bot_challenge_body" -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" -A 'Googlebot' "${EDGE_URL}/bot-check?via=edge-bot-challenge")"
 assert_eq "$bot_challenge_status" "403" "unverified search-bot claim should be challenged"
-assert_contains "$(cat "$bot_challenge_body")" '"error":"bot_challenge_required"' "bot challenge response should be explicit"
+assert_contains "$(cat "$bot_challenge_body")" "Security check" "bot challenge should return the browser verification page"
 rm -f "$bot_challenge_body"
 retry 10 1 agent_exec '/agent/push_security_events.sh'
 bot_event_visible=0
@@ -1269,23 +1269,42 @@ CHALLENGE_RATE_LIMIT_RULE_ID="$(json_get "$HTTP_BODY" '.data.id')"
 edge_pull_config
 challenge_codes=()
 challenge_response_verified=0
+challenge_body="/tmp/e2e-rate-limit-challenge-body.txt"
 for i in $(seq 1 8); do
-  code="$(curl -sS -o /tmp/e2e-rate-limit-challenge-${i}.txt -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" "${EDGE_URL}/challenge?via=edge-rate-limit-challenge")"
+  code="$(curl -sS -o "$challenge_body" -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" "${EDGE_URL}/challenge?via=edge-rate-limit-challenge")"
   challenge_codes+=("$code")
-  if [[ "$code" == "429" ]] && grep -Fq '"error":"challenge_required"' "/tmp/e2e-rate-limit-challenge-${i}.txt"; then
+  if [[ "$code" == "429" ]] && grep -Fq "Security check" "$challenge_body" && grep -Fq "__cdnlite_challenge_verify" "$challenge_body"; then
     challenge_response_verified=1
+    break
   fi
 done
 if [[ " ${challenge_codes[*]} " != *" 429 "* ]]; then
   fail "challenge rate limit expected 429 challenge responses"
 fi
-assert_eq "$challenge_response_verified" "1" "challenge rate-limit response should identify the required challenge"
+assert_eq "$challenge_response_verified" "1" "challenge rate-limit response should return browser verification page"
+challenge_token="$(php -r '$body=file_get_contents($argv[1]); if(preg_match("/const token = \"([^\"]+)\";/", $body, $m)){ echo $m[1]; }' "$challenge_body")"
+[[ -n "$challenge_token" ]] || fail "challenge page did not include a signed token"
+challenge_difficulty="$(php -r '$body=file_get_contents($argv[1]); if(preg_match("/const difficulty = ([0-9]+);/", $body, $m)){ echo $m[1]; }' "$challenge_body")"
+challenge_difficulty="${challenge_difficulty:-3}"
+if [[ "$challenge_difficulty" -le 1 ]]; then
+  challenge_pow="browser-check"
+else
+  challenge_pow="$(php -r '$t=$argv[1]; $d=(int)$argv[2]; $prefix=str_repeat("0",$d); for($i=0;$i<5000000;$i++){ if(substr(hash("sha256",$t.":".$i),0,$d)===$prefix){ echo $i; exit(0);} } exit(1);' "$challenge_token" "$challenge_difficulty")"
+fi
+[[ -n "$challenge_pow" ]] || fail "could not solve local challenge proof"
+cookie_jar="/tmp/e2e-cdnlite-clearance-cookie.txt"
+verify_code="$(curl -sS -o /tmp/e2e-challenge-verify.txt -c "$cookie_jar" -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" -X POST "${EDGE_URL}/__cdnlite_challenge_verify" --data-urlencode "token=${challenge_token}" --data-urlencode "pow=${challenge_pow}")"
+assert_eq "$verify_code" "303" "valid challenge proof should set clearance and redirect"
+assert_contains "$(cat "$cookie_jar")" "__cdnlite_clearance" "challenge verification should set clearance cookie"
+cleared_code="$(curl -sS -b "$cookie_jar" -o /tmp/e2e-rate-limit-cleared.txt -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" "${EDGE_URL}/challenge?via=edge-rate-limit-cleared")"
+assert_eq "$cleared_code" "200" "valid clearance should allow matching challenge traffic to origin"
+assert_contains "$(cat /tmp/e2e-rate-limit-cleared.txt)" '"origin_scheme":"https"' "cleared challenge traffic should reach origin"
 # Security events are delivered asynchronously by the edge agent. The event records
 # the configured decision (`challenge`), while the HTTP response says `challenge_required`.
 retry 20 1 challenge_security_event_visible
 api_delete "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/rate-limits/${CHALLENGE_RATE_LIMIT_RULE_ID}"
 assert_http_status "$HTTP_CODE" "200" "challenge rate-limit cleanup failed"
-record_step PASS "edge-rate-limit-challenge" "challenge action returns 429 and is visible in security events"
+record_step PASS "edge-rate-limit-challenge" "challenge page, proof verification, clearance cookie, origin routing, and events verified"
 
 if docker compose exec -T edge-agent sh -lc "grep -q 'rate_limited' \"\${METRIC_PATH:-/var/lib/cdnlite/metrics.ndjson}\"" \
   || docker compose exec -T edge sh -lc "grep -q 'rate_limited' /var/lib/cdnlite/metrics.ndjson"; then
diff --git a/ci/phases/phase-04.yml b/ci/phases/phase-04.yml
index 65055f5..7f8a2f3 100644
--- a/ci/phases/phase-04.yml
+++ b/ci/phases/phase-04.yml
@@ -1,7 +1,7 @@
 phase: "04"
 name: "Real challenge and clearance system"
 owner: "CDNLite maintainers"
-status: "in progress"
+status: "complete"
 topology: "root docker-compose.yml"
 profiles:
   pr:
@@ -56,6 +56,6 @@ evidence:
 stress_scenarios:
   - "phase4-challenge-clearance"
 recovery_assertions:
-  - "Challenge responses return signed clearance metadata instead of only denying the request."
-  - "Verified challenge tokens set HttpOnly scoped clearance cookies."
+  - "Challenge responses return a self-hosted browser proof-of-work page instead of only denying the request."
+  - "Verified challenge proofs set HttpOnly scoped clearance cookies."
   - "Block rules keep precedence over clearance cookies."
diff --git a/core/app/Modules/Proxy/Services/TrafficRulesService.php b/core/app/Modules/Proxy/Services/TrafficRulesService.php
index cc805ee..03a79da 100644
--- a/core/app/Modules/Proxy/Services/TrafficRulesService.php
+++ b/core/app/Modules/Proxy/Services/TrafficRulesService.php
@@ -1320,12 +1320,12 @@ private function protectionIntentTemplates(): array {
             ],
             'emergency_protection' => [
                 'name' => 'Emergency Protection',
-                'summary' => 'Temporarily tightens site-wide limits and blocks common incident scanner patterns.',
+                'summary' => 'Temporarily challenges site-wide traffic before origin routing and blocks common incident scanner patterns.',
                 'risk' => 'risky',
                 'mode' => 'confirm_first',
                 'rules' => [
-                    ['rule_table' => 'rate_limit_rules', 'template_key' => 'rate_emergency_sitewide', 'payload' => ['enabled' => true, 'priority' => 5, 'path_prefix' => '/', 'key_type' => 'ip', 'requests_per_minute' => 120, 'action' => 'block']],
-                    ['rule_table' => 'waf_rules', 'template_key' => 'waf_emergency_scanners', 'payload' => ['enabled' => true, 'name' => 'Block emergency scanner traffic', 'priority' => 6, 'type' => 'user_agent_contains', 'pattern' => 'nikto', 'action' => 'block', 'description' => 'Generated by Emergency Protection for active incident response.', 'waf_group_id' => 'scanner_recon', 'waf_severity' => 'high', 'waf_confidence' => 'high', 'waf_safe_reason' => 'Emergency mode blocks a known scanner user agent and remains undoable.']],
+                    ['rule_table' => 'waf_rules', 'template_key' => 'waf_emergency_scanners', 'payload' => ['enabled' => true, 'name' => 'Block emergency scanner traffic', 'priority' => 4, 'type' => 'user_agent_contains', 'pattern' => 'nikto', 'action' => 'block', 'description' => 'Generated by Emergency Protection for active incident response.', 'waf_group_id' => 'scanner_recon', 'waf_severity' => 'high', 'waf_confidence' => 'high', 'waf_safe_reason' => 'Emergency mode blocks a known scanner user agent and remains undoable.']],
+                    ['rule_table' => 'waf_rules', 'template_key' => 'waf_emergency_sitewide_challenge', 'payload' => ['enabled' => true, 'name' => 'Challenge all visitors during attack', 'priority' => 5, 'type' => 'path_prefix', 'pattern' => '/', 'action' => 'challenge', 'description' => 'Generated by Emergency Protection to verify browsers before origin routing during an active attack.', 'waf_group_id' => 'emergency_challenge', 'waf_severity' => 'medium', 'waf_confidence' => 'medium', 'waf_safe_reason' => 'Applies temporary friction to every path until the profile is disabled.']],
                 ],
             ],
             'static_asset_performance' => [
diff --git a/core/tests/test_phase4_challenge_clearance_contract.py b/core/tests/test_phase4_challenge_clearance_contract.py
index 5bdef7c..89fc853 100644
--- a/core/tests/test_phase4_challenge_clearance_contract.py
+++ b/core/tests/test_phase4_challenge_clearance_contract.py
@@ -15,17 +15,33 @@ def test_edge_challenge_issues_signed_scoped_clearance_cookie():
     compose = read("docker-compose.yml")
 
     assert "ngx.hmac_sha1" in clearance
+    assert "resty.sha256" in clearance
+    assert "resty.string" in clearance
     assert "__cdnlite_clearance" in clearance
     assert "HttpOnly; SameSite=Lax" in clearance
     assert "CDNLITE_EDGE_CLEARANCE_SECRET" in clearance
+    assert "CDNLITE_EDGE_CHALLENGE_DIFFICULTY" in clearance
     assert "function M.issue(domain_id, action, rule_id, client_ip, ttl)" in clearance
+    assert "function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)" in clearance
+    assert "function M.verify_challenge()" in clearance
     assert "function M.consume_challenge(domain_id, action, rule_id, client_ip)" in clearance
     assert "function M.has_clearance(domain_id, action, rule_id, client_ip)" in clearance
-    assert "signed_clearance" in clearance
+    assert "Security check" in clearance
+    assert "browser_check" in clearance
+    assert "proof_of_work" in clearance
+    assert "invalid_browser_check" in clearance
+    assert "proof ~= 'browser-check'" in clearance
+    assert "difficulty <= 1" in clearance
+    assert "crypto.subtle.digest('SHA-256'" in clearance
+    assert "__cdnlite_challenge_verify" in clearance
+    assert "invalid_proof" in clearance
     assert "scope_matches(claims, domain_id, action, rule_id, client_ip)" in clearance
 
     assert "env CDNLITE_EDGE_CLEARANCE_SECRET;" in nginx
+    assert "env CDNLITE_EDGE_CHALLENGE_DIFFICULTY;" in nginx
+    assert "location = /__cdnlite_challenge_verify" in nginx
     assert "CDNLITE_EDGE_CLEARANCE_SECRET" in compose
+    assert "CDNLITE_EDGE_CHALLENGE_DIFFICULTY" in compose
     assert "local clearance = require('clearance')" in router
 
 
@@ -33,18 +49,37 @@ def test_waf_and_rate_limit_challenges_are_verifiable_not_static_denies():
     router = read("edge/openresty/lua/router.lua")
 
     assert "clearance.has_clearance(domain.domain_id, 'waf', rule.id, client_ip)" in router
-    assert "clearance.consume_challenge(domain.domain_id, 'waf', rule.id, client_ip)" in router
     assert "clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')" in router
     assert "clearance.has_clearance(domain_id, 'rate_limit', rule.id, client_ip)" in router
-    assert "clearance.consume_challenge(domain_id, 'rate_limit', rule.id, client_ip)" in router
     assert "clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required')" in router
-    assert "return ngx.exit(303)" in router
 
     block_index = router.index("if ngx.ctx.security_action == 'block' then")
     challenge_index = router.index("if ngx.ctx.security_action == 'challenge' then")
     assert block_index < challenge_index
 
 
+def test_emergency_profile_challenges_all_visitors_before_origin():
+    service = read("core/app/Modules/Proxy/Services/TrafficRulesService.php")
+    dashboard = read("dash/src/views/domain-tabs/DomainSecurityCenterTab.vue")
+    waf_tab = read("dash/src/views/domain-tabs/DomainWafTab.vue")
+    rate_tab = read("dash/src/views/domain-tabs/DomainRateLimitsTab.vue")
+
+    assert "'emergency_protection'" in service
+    assert "'template_key' => 'waf_emergency_sitewide_challenge'" in service
+    assert "'type' => 'path_prefix'" in service
+    assert "'pattern' => '/'" in service
+    assert "'action' => 'challenge'" in service
+    assert "'priority' => 4" in service and "'priority' => 5" in service
+    assert "waf_emergency_scanners" in service
+    assert "Temporarily challenges site-wide traffic before origin routing" in service
+
+    assert "Emergency Protection" in dashboard
+    assert "challenge" in waf_tab
+    assert "Level 1 performs a lightweight browser check" in waf_tab
+    assert "levels 2-6 require increasing proof-of-work" in waf_tab
+    assert "Challenge" in rate_tab and "hard block" in rate_tab
+
+
 def test_phase4_runner_and_stress_registration_are_present():
     phase = read("ci/phase.sh")
     manifest = read("ci/phases/phase-04.yml")
@@ -55,7 +90,7 @@ def test_phase4_runner_and_stress_registration_are_present():
     assert "test_phase4_challenge_clearance_contract.py" in phase
     assert "phase4-challenge-clearance" in phase
     assert 'phase: "04"' in manifest
-    assert 'status: "in progress"' in manifest
+    assert 'status: "complete"' in manifest
     assert "phase4-challenge-clearance" in manifest
     assert "phase4-challenge-clearance" in stress
     assert "phase4-challenge-clearance" in scenarios
diff --git a/dash/src/views/domain-tabs/DomainWafTab.vue b/dash/src/views/domain-tabs/DomainWafTab.vue
index 4880bbe..53bac50 100644
--- a/dash/src/views/domain-tabs/DomainWafTab.vue
+++ b/dash/src/views/domain-tabs/DomainWafTab.vue
@@ -1,2 +1,2 @@
 <template><DomainRulesTab :domain-id="domainId" title="WAF Rules" summary="Inspect and act on matching requests." :fields="fields" :columns="columns" :help-items="helpItems" :list="() => wafApi.list(domainId)" :create="(v) => wafApi.create(domainId, v)" :update="(id, v) => wafApi.update(domainId, id, v)" :detach-managed="(id) => wafApi.detachManaged(domainId, id)" :remove="(id) => wafApi.remove(domainId, id)" /></template>
-<script setup lang="ts">import DomainRulesTab from './DomainRulesTab.vue'; import { wafApi } from '@/lib/api/waf'; defineProps<{ domainId:string }>(); const helpItems=[{title:'Start with log',body:'Use Log first for new patterns, watch security events, then switch to Block when false positives look low.'},{title:'Pattern examples',body:'path_prefix /admin, user_agent_contains sqlmap, ip_cidr 203.0.113.0/24, method_is POST, path_method_not_allowed /api/:GET,POST.'},{title:'Priority',body:'Lower numbers run first. Put explicit allow rules before broad block rules.'}]; const fields=[{key:'enabled',label:'Enabled',type:'checkbox' as const,default:true,help:'Turn off a rule temporarily without losing its match settings.'},{key:'name',label:'Name',default:'',placeholder:'Block admin scanners',help:'Use a short purpose-driven name that shows up clearly in security events.'},{key:'type',label:'Type',options:['path_contains','path_prefix','user_agent_contains','ip_cidr','country_is','method_is','header_contains','path_method_not_allowed'],default:'path_contains',help:'Choose what part of the request should be inspected.'},{key:'pattern',label:'Pattern',default:'',placeholder:'/admin',help:'Format depends on type: path text, CIDR, country code, HTTP method, header text, or /api/:GET,POST for scoped API method rules.'},{key:'action',label:'Action',options:['block','log','allow','challenge'],default:'block',help:'Log is safest for testing. Challenge returns a 403 challenge response. Allow can exempt trusted traffic.'},{key:'priority',label:'Priority',type:'number' as const,default:100,placeholder:'100',help:'Rules with lower priority values are evaluated first.'},{key:'description',label:'Description',default:'',placeholder:'Blocks suspicious requests to admin paths',help:'Record why the rule exists and when it should be revisited.'}]; const columns=[{key:'enabled',label:'Enabled'},{key:'name',label:'Name'},{key:'type',label:'Type'},{key:'pattern',label:'Pattern'},{key:'action',label:'Action'},{key:'managed_by',label:'Managed'},{key:'actions',label:'Actions'}];</script>
+<script setup lang="ts">import DomainRulesTab from './DomainRulesTab.vue'; import { wafApi } from '@/lib/api/waf'; defineProps<{ domainId:string }>(); const helpItems=[{title:'Start with log',body:'Use Log first for new patterns, watch security events, then switch to Block when false positives look low.'},{title:'Challenge difficulty',body:'Challenge uses the edge-wide CDNLITE_EDGE_CHALLENGE_DIFFICULTY setting. Level 1 performs a lightweight browser check; levels 2-6 require increasing proof-of-work before origin routing.'},{title:'Pattern examples',body:'path_prefix /admin, user_agent_contains sqlmap, ip_cidr 203.0.113.0/24, method_is POST, path_method_not_allowed /api/:GET,POST.'},{title:'Priority',body:'Lower numbers run first. Put explicit allow rules before broad block rules.'}]; const fields=[{key:'enabled',label:'Enabled',type:'checkbox' as const,default:true,help:'Turn off a rule temporarily without losing its match settings.'},{key:'name',label:'Name',default:'',placeholder:'Block admin scanners',help:'Use a short purpose-driven name that shows up clearly in security events.'},{key:'type',label:'Type',options:['path_contains','path_prefix','user_agent_contains','ip_cidr','country_is','method_is','header_contains','path_method_not_allowed'],default:'path_contains',help:'Choose what part of the request should be inspected.'},{key:'pattern',label:'Pattern',default:'',placeholder:'/admin',help:'Format depends on type: path text, CIDR, country code, HTTP method, header text, or /api/:GET,POST for scoped API method rules.'},{key:'action',label:'Action',options:['block','log','allow','challenge'],default:'block',help:'Log is safest for testing. Challenge verifies browsers before origin routing; difficulty is controlled by CDNLITE_EDGE_CHALLENGE_DIFFICULTY. Allow can exempt trusted traffic.'},{key:'priority',label:'Priority',type:'number' as const,default:100,placeholder:'100',help:'Rules with lower priority values are evaluated first.'},{key:'description',label:'Description',default:'',placeholder:'Blocks suspicious requests to admin paths',help:'Record why the rule exists and when it should be revisited.'}]; const columns=[{key:'enabled',label:'Enabled'},{key:'name',label:'Name'},{key:'type',label:'Type'},{key:'pattern',label:'Pattern'},{key:'action',label:'Action'},{key:'managed_by',label:'Managed'},{key:'actions',label:'Actions'}];</script>
diff --git a/docker-compose.yml b/docker-compose.yml
index 7338e9f..40b9118 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -260,6 +260,7 @@ services:
       CDNLITE_EDGE_DEBUG_HEADERS: ${CDNLITE_EDGE_DEBUG_HEADERS:-false}
       CDNLITE_EDGE_MMDB_FILE: ${CDNLITE_EDGE_MMDB_FILE:-/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb}
       CDNLITE_EDGE_CLEARANCE_SECRET: ${CDNLITE_EDGE_CLEARANCE_SECRET:-cdnlite-local-clearance-secret}
+      CDNLITE_EDGE_CHALLENGE_DIFFICULTY: ${CDNLITE_EDGE_CHALLENGE_DIFFICULTY:-3}
 
   edge-agent:
     build:
@@ -340,6 +341,7 @@ services:
       CDNLITE_EDGE_DEBUG_HEADERS: ${CDNLITE_EDGE_DEBUG_HEADERS:-false}
       CDNLITE_EDGE_MMDB_FILE: ${CDNLITE_EDGE_MMDB_FILE:-/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb}
       CDNLITE_EDGE_CLEARANCE_SECRET: ${CDNLITE_EDGE_CLEARANCE_SECRET:-cdnlite-local-clearance-secret}
+      CDNLITE_EDGE_CHALLENGE_DIFFICULTY: ${CDNLITE_EDGE_CHALLENGE_DIFFICULTY:-3}
 
   edge-agent-2:
     build:
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 461a794..ea9602b 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -347,7 +347,7 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | 1. Database architecture and real-time reporting foundation | P0 | Complete | Fast operational reads, scalable event ingestion, bounded reporting, and durable rollups |
 | 2. Analytics scalability and asynchronous aggregation | P0 | Complete | Bounded analytics metadata, async recalculation jobs, and idempotent aggregate upserts |
 | 3. Edge hot-path performance and bounded telemetry | P0 | Complete | No repeated config parsing or synchronous per-request telemetry writes |
-| 4. Real challenge and clearance system | P0 | In progress | Challenge actions perform a signed clearance workflow instead of a renamed block |
+| 4. Real challenge and clearance system | P0 | Complete | Challenge actions serve configurable self-hosted browser verification before origin routing |
 | 5. Adaptive overload protection and waiting room | P0 | Planned | Origins remain protected under attack or heavy usage |
 | 6. Cache correctness foundation | P0 | Planned | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
 | 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
@@ -1451,13 +1451,13 @@ On documented reference hardware:
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
-**Status:** In progress  
+**Status:** Complete  
 **Owner:** CDNLite maintainers  
 **Tracking issue:** Local roadmap Phase 4  
 **Manifest:** `ci/phases/phase-04.yml`  
 **Evidence:** `ci/reports/phase-04-report.md`, `ci/reports/phase-04-report.json`  
-**Completed work:** Added signed edge clearance tokens for WAF and rate-limit challenge actions, scoped HttpOnly clearance cookies, challenge metadata responses, invalid-token diagnostics in security events, block-before-challenge precedence, `CDNLITE_EDGE_CLEARANCE_SECRET`, Phase 4 runner registration, and stress scenario registration.  
-**Remaining work:** Run full clean-stack evidence before marking Complete. The current challenge is a signed clearance workflow, not a proof-of-work or CAPTCHA provider.
+**Completed work:** Added configurable self-hosted browser verification pages for WAF and rate-limit challenge actions, the edge-only `/__cdnlite_challenge_verify` endpoint, signed scoped challenge and clearance tokens, level-1 lightweight browser verification, level-2-through-6 proof-of-work, HttpOnly clearance cookies, same-host redirect recovery, block-before-challenge precedence, Emergency Protection site-wide challenge mode, `CDNLITE_EDGE_CLEARANCE_SECRET`, `CDNLITE_EDGE_CHALLENGE_DIFFICULTY`, Phase 4 runner registration, e2e coverage, and stress scenario registration.  
+**Remaining work:** None for the accepted Phase 4 delivery. Third-party CAPTCHA providers remain a later optional extension, not a Phase 4 requirement.
 
 ### Objective
 
diff --git a/docs/api/api.md b/docs/api/api.md
index 28321e3..661d208 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -476,7 +476,7 @@ Protection profiles are one-click bundles over the same intent engine. One-click
 
 Managed WAF presets add inspection metadata to generated WAF rules. WAF rules created by Security Center intents can include `waf_group_id`, `waf_severity`, `waf_confidence`, and `waf_safe_reason`; edge `waf_match` security events emit matching `group_id`, `severity`, `confidence`, and `safe_reason` fields so Activity can explain why a managed rule acted. These fields are additive metadata on the advanced WAF rule, so operators can still edit, detach, or override the generated rule.
 
-Bot Shield rules additionally carry `bot_class`, `bot_score`, and `bot_action`. A matched bot policy emits a `bot_match` security event with those fields and the request ID. A claimed search crawler is not trusted from its User-Agent alone: the built-in policy challenges it unless the edge config includes an enabled `verified_bot_sources` entry whose CIDR and User-Agent pattern both match the request. Advanced WAF rules may use `challenge`, which returns a 403 JSON `bot_challenge_required` response and records the event.
+Bot Shield rules additionally carry `bot_class`, `bot_score`, and `bot_action`. A matched bot policy emits a `bot_match` security event with those fields and the request ID. A claimed search crawler is not trusted from its User-Agent alone: the built-in policy challenges it unless the edge config includes an enabled `verified_bot_sources` entry whose CIDR and User-Agent pattern both match the request. Advanced WAF and rate-limit rules may use `challenge`, which serves the self-hosted browser verification page, verifies through `/__cdnlite_challenge_verify`, sets `__cdnlite_clearance`, and records the event. `CDNLITE_EDGE_CHALLENGE_DIFFICULTY=1` uses a lightweight browser check; levels `2`-`6` add increasing proof-of-work.
 
 The Managed WAF preset catalog is read-only and returns available WAF modes, group definitions, and currently generated rule templates grouped by `waf_group_id`. Use it to inspect SQL injection, XSS, traversal, inclusion, command injection, PHP/WordPress, scanner, encoding, and bad user-agent coverage before enabling or tightening rules through the preview/apply protection flows.
 
diff --git a/docs/security.md b/docs/security.md
index dfa103e..c8f453d 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -60,17 +60,29 @@ listeners or error handlers.
 
 ## Challenge Clearance
 
-WAF and rate-limit rules with the `challenge` action issue a short-lived signed
-clearance challenge instead of behaving as a renamed block. The token is scoped
-to the domain, action family, rule ID, client IP, and expiry. Successful
-verification sets the `__cdnlite_clearance` HttpOnly cookie with `SameSite=Lax`.
-Explicit block rules and administrative denies still take precedence over any
-clearance cookie.
+WAF and rate-limit rules with the `challenge` action serve a self-hosted browser
+proof-of-work page instead of behaving as a renamed block. The challenge token
+is scoped to the domain, action family, rule ID, client IP, return path, and
+expiry. The browser computes a bounded SHA-256 proof and submits it to the
+edge-only `/__cdnlite_challenge_verify` endpoint. Successful verification sets
+the `__cdnlite_clearance` HttpOnly cookie with `SameSite=Lax` and redirects the
+visitor back to the original same-host relative URL. Explicit block rules and
+administrative denies still take precedence over any clearance cookie.
 
 Set `CDNLITE_EDGE_CLEARANCE_SECRET` to a strong shared secret on every edge in a
 fleet. Rotating it invalidates existing clearance cookies, which is safe but can
 temporarily make visitors solve a challenge again.
 
+Set `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` between `1` and `6` to tune challenge
+cost. This is a provider-independent abuse-friction mechanism; it is not a
+guarantee that a visitor is human.
+
+| Difficulty | Behavior | Use case |
+| --- | --- | --- |
+| `1` | Lightweight browser verification. The page verifies JavaScript, same-origin fetch, cookies, and redirect handling without proof-of-work. | Low-friction checks for normal sites or mild bot noise. |
+| `2`-`4` | Browser verification plus increasing SHA-256 proof-of-work before clearance. | Suspicious automation, login abuse, or short attack windows. |
+| `5`-`6` | High-friction proof-of-work. | Temporary emergency use during active attacks where user delay is acceptable. |
+
 ## Authorization Limits
 
 The dashboard admin model is simple. It does not implement fine-grained RBAC, per-domain tenancy, SSO, or role-scoped permissions. Use external controls for production segmentation.
diff --git a/docs/setup.md b/docs/setup.md
index b0f47b7..d3e35ca 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -233,7 +233,8 @@ Edge and agent settings:
 | `CDNLITE_EDGE_LOG_REQUEST_BODY` | Reserved for future strict-redaction body logging; keep `false`. |
 | `CDNLITE_EDGE_DEBUG_HEADERS` | Reserved for future debug header logging; keep `false` unless a runbook explicitly enables it. |
 | `CDNLITE_EDGE_MMDB_FILE` | GeoIP MMDB used by the edge for country WAF/origin decisions; default `/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb`. |
-| `CDNLITE_EDGE_CLEARANCE_SECRET` | Shared edge secret for signed challenge clearance cookies. Set the same strong value on every edge; rotation invalidates existing clearances. |
+| `CDNLITE_EDGE_CLEARANCE_SECRET` | Shared edge secret for signed challenge and clearance cookies. Set the same strong value on every edge; rotation invalidates existing clearances. |
+| `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` | Self-hosted edge challenge difficulty, from `1` to `6`; default `3`. Level `1` performs a lightweight browser check without proof-of-work. Levels `2` through `6` require increasing SHA-256 proof-of-work before origin routing. |
 | `EDGE_AGENT_IDLE` | CI flag to keep agent idle while scripts drive flow manually. |
 
 Recommended starting values:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 5073a15..b1f2150 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -40,7 +40,7 @@ Use this order during incidents:
 | Dashboard cannot reach core | `VITE_CDNLITE_CORE_URL` points at an internal Compose hostname or CORS blocks origin. | Set a browser-reachable URL, rebuild dashboard, and include dashboard origin in `CDNLITE_CORS_ALLOWED_ORIGINS`. |
 | Login fails with known credentials | Bootstrap disabled or admin password changed. | Create a user with `cdn:admin:create` or verify bootstrap variables before first boot. |
 | Admins get logged out, unauthorized responses, or dashboard timeouts behind Nginx | The Core API reverse proxy is not forwarding `Authorization` or has short proxy timeouts. | Put `proxy_set_header Authorization $http_authorization;` and sane `proxy_*_timeout` values on the Core API vhost/location. The dashboard proxy alone does not fix API auth. |
-| Visitors repeatedly receive challenge responses | Edge clearance cookies cannot be verified, the client IP changed, or the edge fleet uses different `CDNLITE_EDGE_CLEARANCE_SECRET` values. | Set the same strong `CDNLITE_EDGE_CLEARANCE_SECRET` on every edge, keep clocks sane, and verify the client is returning the `__cdnlite_clearance` cookie. |
+| Visitors repeatedly receive challenge responses | JavaScript is disabled, the proof request is blocked, edge clearance cookies cannot be verified, the client IP changed, or the edge fleet uses different `CDNLITE_EDGE_CLEARANCE_SECRET` values. | Set the same strong `CDNLITE_EDGE_CLEARANCE_SECRET` on every edge, keep clocks sane, verify `/__cdnlite_challenge_verify` is reachable, and confirm the client is returning the `__cdnlite_clearance` cookie. |
 | `/ready` reports `api_token` warn | `CDNLITE_API_TOKEN` is empty in local mode. | Accept for local dev, set a strong token for production. |
 | `/ready` reports schema failure | Canonical schema bootstrap failed or the database is not disposable. | Inspect Core/PostgreSQL logs, then rebuild a fresh stack with `docker compose down -v && docker compose up -d --build`. |
 | Edge returns unknown host page | Host is not in `config.json` or edge has stale config. | Activate the domain, rebuild snapshot, and confirm edge agent pulled config. |
diff --git a/edge/openresty/lua/clearance.lua b/edge/openresty/lua/clearance.lua
index eb0bbbb..d118ed0 100644
--- a/edge/openresty/lua/clearance.lua
+++ b/edge/openresty/lua/clearance.lua
@@ -1,9 +1,13 @@
 local cjson = require('cjson.safe')
+local resty_sha256 = require('resty.sha256')
+local resty_string = require('resty.string')
 
 local M = {}
 
 local cookie_name = '__cdnlite_clearance'
 local default_ttl = 1800
+local challenge_ttl = 300
+local default_difficulty = 3
 
 local function secret()
   local value = os.getenv('CDNLITE_EDGE_CLEARANCE_SECRET') or ''
@@ -30,15 +34,46 @@ local function sign(payload)
   return b64(ngx.hmac_sha1(secret(), payload))
 end
 
-local function token_payload(domain_id, action, rule_id, client_ip, expires_at, nonce)
-  return table.concat({
-    tostring(domain_id or ''),
-    tostring(action or ''),
-    tostring(rule_id or ''),
-    tostring(client_ip or ''),
-    tostring(expires_at or ''),
-    tostring(nonce or ''),
-  }, '|')
+local function hash_hex(value)
+  local sha = resty_sha256:new()
+  sha:update(value or '')
+  return resty_string.to_hex(sha:final())
+end
+
+local function html_escape(value)
+  return tostring(value or '')
+    :gsub('&', '&amp;')
+    :gsub('<', '&lt;')
+    :gsub('>', '&gt;')
+    :gsub('"', '&quot;')
+    :gsub("'", '&#39;')
+end
+
+local function js_string(value)
+  return cjson.encode(tostring(value or '')) or '""'
+end
+
+local function same_host_path(value)
+  local path = tostring(value or ngx.var.request_uri or '/')
+  if path == '' or string.sub(path, 1, 1) ~= '/' or string.sub(path, 1, 2) == '//' then
+    return '/'
+  end
+  if string.find(path, '[\r\n]', 1, false) then
+    return '/'
+  end
+  return path
+end
+
+local function proof_prefix(difficulty)
+  return string.rep('0', tonumber(difficulty or default_difficulty) or default_difficulty)
+end
+
+local function challenge_mode(difficulty)
+  local n = tonumber(difficulty or default_difficulty) or default_difficulty
+  if n <= 1 then
+    return 'browser_check'
+  end
+  return 'proof_of_work'
 end
 
 local function encode_token(claims)
@@ -113,6 +148,27 @@ function M.issue(domain_id, action, rule_id, client_ip, ttl)
   }), expires_at
 end
 
+function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)
+  local expires_at = ngx.time() + challenge_ttl
+  local nonce = b64(tostring(ngx.now()) .. ':' .. tostring(math.random()) .. ':' .. tostring(ngx.worker.pid()))
+  local difficulty = tonumber(os.getenv('CDNLITE_EDGE_CHALLENGE_DIFFICULTY') or '') or default_difficulty
+  if difficulty < 1 then difficulty = 1 end
+  if difficulty > 6 then difficulty = 6 end
+  return encode_token({
+    token_type = 'challenge',
+    domain_id = tostring(domain_id or ''),
+    action = tostring(action or ''),
+    rule_id = tostring(rule_id or ''),
+    client_ip = tostring(client_ip or ''),
+    return_path = same_host_path(return_path),
+    issued_at = ngx.time(),
+    expires_at = expires_at,
+    difficulty = difficulty,
+    mode = challenge_mode(difficulty),
+    nonce = nonce,
+  }), expires_at, difficulty
+end
+
 function M.consume_challenge(domain_id, action, rule_id, client_ip)
   local token = ngx.var.arg_cdnlite_challenge or ''
   if token == '' then
@@ -122,6 +178,9 @@ function M.consume_challenge(domain_id, action, rule_id, client_ip)
   if not claims then
     return false, err
   end
+  if tostring(claims.token_type or 'clearance') ~= 'clearance' then
+    return false, 'wrong_token_type'
+  end
   if tonumber(claims.expires_at or 0) <= ngx.time() then
     return false, 'expired'
   end
@@ -137,23 +196,160 @@ function M.consume_challenge(domain_id, action, rule_id, client_ip)
   return true
 end
 
+function M.verify_challenge()
+  ngx.req.read_body()
+  local args = ngx.req.get_post_args(20)
+  if not args or not args.token then
+    args = ngx.req.get_uri_args(20)
+  end
+  local claims, err = decode_token(args.token or '')
+  if not claims then
+    ngx.status = 403
+    ngx.header.content_type = 'application/json'
+    ngx.say(cjson.encode({ ok = false, error = err or 'invalid_challenge' }))
+    return ngx.exit(403)
+  end
+  if tostring(claims.token_type or '') ~= 'challenge' then
+    ngx.status = 403
+    ngx.header.content_type = 'application/json'
+    ngx.say(cjson.encode({ ok = false, error = 'wrong_token_type' }))
+    return ngx.exit(403)
+  end
+  if tonumber(claims.expires_at or 0) <= ngx.time() then
+    ngx.status = 403
+    ngx.header.content_type = 'application/json'
+    ngx.say(cjson.encode({ ok = false, error = 'expired' }))
+    return ngx.exit(403)
+  end
+  local client_ip = tostring(ngx.var.remote_addr or '')
+  if not scope_matches(claims, claims.domain_id, claims.action, claims.rule_id, client_ip) then
+    ngx.status = 403
+    ngx.header.content_type = 'application/json'
+    ngx.say(cjson.encode({ ok = false, error = 'scope_mismatch' }))
+    return ngx.exit(403)
+  end
+  local difficulty = tonumber(claims.difficulty or default_difficulty) or default_difficulty
+  local proof = tostring(args.pow or '')
+  if difficulty <= 1 then
+    if proof ~= 'browser-check' then
+      ngx.status = 403
+      ngx.header.content_type = 'application/json'
+      ngx.say(cjson.encode({ ok = false, error = 'invalid_browser_check' }))
+      return ngx.exit(403)
+    end
+  else
+    local digest = hash_hex(tostring(args.token or '') .. ':' .. proof)
+    if proof == '' or string.sub(digest, 1, difficulty) ~= proof_prefix(difficulty) then
+      ngx.status = 403
+      ngx.header.content_type = 'application/json'
+      ngx.say(cjson.encode({ ok = false, error = 'invalid_proof' }))
+      return ngx.exit(403)
+    end
+  end
+  local clearance_token = encode_token({
+    domain_id = tostring(claims.domain_id or ''),
+    action = tostring(claims.action or ''),
+    rule_id = tostring(claims.rule_id or ''),
+    client_ip = client_ip,
+    expires_at = ngx.time() + default_ttl,
+    nonce = b64(tostring(ngx.now()) .. ':' .. proof),
+  })
+  ngx.header['Set-Cookie'] = string.format(
+    '%s=%s; Max-Age=%d; Path=/; HttpOnly; SameSite=Lax',
+    cookie_name,
+    clearance_token,
+    default_ttl
+  )
+  ngx.header['Location'] = same_host_path(claims.return_path)
+  return ngx.exit(303)
+end
+
 function M.challenge_response(domain_id, action, rule_id, client_ip, status_code, error_code)
-  local token, expires_at = M.issue(domain_id, action, rule_id, client_ip)
-  local uri = tostring(ngx.var.uri or '/')
-  local sep = string.find(tostring(ngx.var.request_uri or ''), '?', 1, true) and '&' or '?'
-  local challenge_url = tostring(ngx.var.request_uri or uri) .. sep .. 'cdnlite_challenge=' .. ngx.escape_uri(token or '')
+  local return_path = same_host_path(ngx.var.request_uri or ngx.var.uri or '/')
+  local token, expires_at, difficulty = M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)
+  local verify_path = '/__cdnlite_challenge_verify'
   ngx.status = status_code
-  ngx.header.content_type = 'application/json'
+  ngx.header.content_type = 'text/html; charset=utf-8'
   ngx.header['Cache-Control'] = 'no-store'
-  ngx.say(cjson.encode({
-    error = error_code,
-    request_id = tostring(ngx.ctx.request_id or ''),
-    challenge = {
-      type = 'signed_clearance',
-      url = challenge_url,
-      expires_at = expires_at,
-    },
-  }))
+  ngx.say([[<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Security check</title>
+  <style>
+    body{margin:0;font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#0f172a;color:#e5e7eb;display:grid;min-height:100vh;place-items:center}
+    main{width:min(520px,calc(100vw - 32px));padding:32px;border:1px solid #334155;background:#111827}
+    h1{font-size:24px;margin:0 0 12px}
+    p{line-height:1.55;color:#cbd5e1}
+    .bar{height:8px;background:#334155;overflow:hidden;margin-top:20px}
+    .bar span{display:block;height:100%;width:45%;background:#38bdf8;animation:pulse 1.2s ease-in-out infinite}
+    @keyframes pulse{50%{transform:translateX(120%)}}
+  </style>
+</head>
+<body>
+<main>
+  <h1>Security check</h1>
+  <p>CDNLite is checking this browser before sending traffic to the site.</p>
+  <p id="status">Preparing challenge...</p>
+  <div class="bar"><span></span></div>
+</main>
+<script>
+(async function(){
+  const token = ]] .. js_string(token or '') .. [[;
+  const difficulty = ]] .. tostring(difficulty or default_difficulty) .. [[;
+  const prefix = '0'.repeat(difficulty);
+  const mode = difficulty <= 1 ? 'browser_check' : 'proof_of_work';
+  const status = document.getElementById('status');
+  async function submitProof(proof) {
+    const body = new URLSearchParams({ token, pow: proof });
+    const response = await fetch(]] .. js_string(verify_path) .. [[, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+      credentials: 'same-origin',
+      redirect: 'follow'
+    });
+    if (response.redirected) {
+      window.location.href = response.url;
+      return true;
+    }
+    if (response.ok) {
+      window.location.href = ]] .. js_string(return_path) .. [[;
+      return true;
+    }
+    return false;
+  }
+  async function sha256Hex(input) {
+    const data = new TextEncoder().encode(input);
+    const hash = await crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, '0')).join('');
+  }
+  if (mode === 'browser_check') {
+    status.textContent = 'Verifying browser...';
+    if (await submitProof('browser-check')) return;
+    status.textContent = 'Verification failed. Refresh to try again.';
+    return;
+  }
+  for (let i = 0; i < 5000000; i++) {
+    if (i % 5000 === 0) {
+      status.textContent = 'Checking browser...';
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    const proof = String(i);
+    const digest = await sha256Hex(token + ':' + proof);
+    if (digest.startsWith(prefix)) {
+      if (await submitProof(proof)) return;
+      status.textContent = 'Challenge failed. Refresh to try again.';
+      return;
+    }
+  }
+  status.textContent = 'Challenge took too long. Refresh to try again.';
+})();
+</script>
+<noscript>JavaScript is required to complete this security check.</noscript>
+</body>
+</html>]])
   return ngx.exit(status_code)
 end
 
diff --git a/edge/openresty/lua/router.lua b/edge/openresty/lua/router.lua
index 586532c..edc68fe 100644
--- a/edge/openresty/lua/router.lua
+++ b/edge/openresty/lua/router.lua
@@ -245,14 +245,6 @@ local function apply_waf(cfg, host)
         if clearance.has_clearance(domain.domain_id, 'waf', rule.id, client_ip) then
           return true
         end
-        local verified, verify_err = clearance.consume_challenge(domain.domain_id, 'waf', rule.id, client_ip)
-        if verified then
-          ngx.header['Location'] = tostring(ngx.var.uri or '/')
-          identity.apply()
-          return ngx.exit(303)
-        elseif verify_err then
-          ngx.ctx.security_safe_reason = 'clearance_' .. tostring(verify_err)
-        end
         append_security_event(nil)
         identity.apply()
         return clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')
@@ -350,14 +342,6 @@ local function apply_rate_limit(cfg, host, domain_id)
     if clearance.has_clearance(domain_id, 'rate_limit', rule.id, client_ip) then
       return true
     end
-    local verified, verify_err = clearance.consume_challenge(domain_id, 'rate_limit', rule.id, client_ip)
-    if verified then
-      ngx.header['Location'] = tostring(ngx.var.uri or '/')
-      identity.apply()
-      return ngx.exit(303)
-    elseif verify_err then
-      ngx.ctx.security_safe_reason = 'clearance_' .. tostring(verify_err)
-    end
     append_security_event(domain_id)
     edge_log.warn('rate_limit_challenge', { domain_id = tostring(domain_id or ''), rule_id = tostring(rule.id or '') })
     identity.apply()
diff --git a/edge/openresty/nginx.conf b/edge/openresty/nginx.conf
index ad04065..b71dd9a 100644
--- a/edge/openresty/nginx.conf
+++ b/edge/openresty/nginx.conf
@@ -14,6 +14,7 @@ env CDNLITE_EDGE_DEBUG_HEADERS;
 env CDNLITE_EDGE_LOG_REQUEST_BODY;
 env CDNLITE_EDGE_MMDB_FILE;
 env CDNLITE_EDGE_CLEARANCE_SECRET;
+env CDNLITE_EDGE_CHALLENGE_DIFFICULTY;
 error_log /dev/stderr __CDNLITE_EDGE_ERROR_LOG_LEVEL__;
 pid /tmp/nginx.pid;
 
@@ -114,6 +115,17 @@ http {
       }
     }
 
+    location = /__cdnlite_challenge_verify {
+      default_type application/json;
+      content_by_lua_block {
+        require('clearance').verify_challenge()
+      }
+      log_by_lua_block {
+        local metrics = require('metrics')
+        metrics.on_log()
+      }
+    }
+
     location = /__cdnlite_error_page {
       internal;
       default_type text/html;
@@ -242,6 +254,17 @@ http {
       }
     }
 
+    location = /__cdnlite_challenge_verify {
+      default_type application/json;
+      content_by_lua_block {
+        require('clearance').verify_challenge()
+      }
+      log_by_lua_block {
+        local metrics = require('metrics')
+        metrics.on_log()
+      }
+    }
+
     location / {
       access_by_lua_block {
         local router = require('router')

From adc04d7dbc31a8bf74ff3d6c48d2d4a90255fc64 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sat, 27 Jun 2026 23:50:34 +0330
Subject: [PATCH 03/11] feat: Add challenge difficulty parameter for WAF and
 rate-limit rules

- Introduced `challenge_difficulty` field to WAF and rate-limit rules, allowing configuration of challenge levels from 1 to 6.
- Updated validation logic to ensure `challenge_difficulty` is within the specified range.
- Enhanced API and database schema to support the new parameter.
- Modified related tests and documentation to reflect the changes in challenge difficulty handling.
---
 CHANGELOG.md                                  |  2 +-
 ci/e2e.sh                                     | 27 ++++++++++++++++++-
 .../Controllers/TrafficRulesController.php    | 12 +++++++++
 .../Proxy/Services/TrafficRulesService.php    | 24 +++++++++++++++--
 .../migrations/000001_baseline_schema.sql     |  2 ++
 .../000028_challenge_difficulty.sql           | 19 +++++++++++++
 core/database/schema.sql                      |  2 ++
 ...est_phase4_challenge_clearance_contract.py | 17 +++++++++---
 dash/src/types.ts                             |  4 +--
 .../views/domain-tabs/DomainRateLimitsTab.vue |  3 +++
 dash/src/views/domain-tabs/DomainWafTab.vue   |  2 +-
 docs/ROADMAP.md                               |  4 +--
 docs/api/api.md                               |  2 +-
 docs/security.md                              |  8 +++---
 docs/setup.md                                 |  2 +-
 edge/openresty/lua/clearance.lua              |  8 +++---
 edge/openresty/lua/router.lua                 |  4 +--
 17 files changed, 119 insertions(+), 23 deletions(-)
 create mode 100644 core/database/migrations/000028_challenge_difficulty.sql

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c70de12..9c43b41 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,7 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 1 database architecture foundation with workload budgets, telemetry ingest batch diagnostics, reporting watermarks, reconciliation tables, current summary read model, reporting query budgets, one-shot phase runner, manifest, stress scenario, and database architecture docs.
 - Phase 2 analytics scalability with asynchronous recalculation jobs, job status API, idempotent aggregate upserts, bounded summary metadata, analytics cache schema, dashboard queued-job feedback, and contract documentation.
 - Phase 3 edge hot-path performance with worker-local config caching, last-known-good reload behavior, bounded shared-memory telemetry queues, queue health visibility, configurable edge capacity defaults, one-shot phase manifest, and stress scenario registration.
-- Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser proof-of-work page, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
+- Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser verification page, per-rule challenge difficulty, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty fallback configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/e2e.sh b/ci/e2e.sh
index b2a6d1e..916b91c 100755
--- a/ci/e2e.sh
+++ b/ci/e2e.sh
@@ -1262,9 +1262,10 @@ edge_id_header_rl="$(edge_header_for_host "${TEST_DOMAIN}" "/login?via=edge-rate
 assert_eq "$edge_id_header_rl" "$EDGE_ID" "rate-limit response should expose edge id header"
 record_step PASS "edge-rate-limit-runtime" "429 observed for /login after burst"
 
-api_post "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/rate-limits" '{"enabled":true,"requests_per_minute":5,"path_prefix":"/challenge","key_type":"ip_path","priority":21,"action":"challenge"}'
+api_post "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/rate-limits" '{"enabled":true,"requests_per_minute":5,"path_prefix":"/challenge","key_type":"ip_path","priority":21,"action":"challenge","challenge_difficulty":3}'
 assert_http_status "$HTTP_CODE" "201" "challenge rate-limit create failed"
 CHALLENGE_RATE_LIMIT_RULE_ID="$(json_get "$HTTP_BODY" '.data.id')"
+assert_contains "$HTTP_BODY" '"challenge_difficulty":3' "challenge rate-limit response should include per-rule difficulty"
 # The edge serves its local snapshot, so publish and apply this new rule before exercising it.
 edge_pull_config
 challenge_codes=()
@@ -1306,6 +1307,30 @@ api_delete "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/rate-limits/${CHALLENGE_RATE
 assert_http_status "$HTTP_CODE" "200" "challenge rate-limit cleanup failed"
 record_step PASS "edge-rate-limit-challenge" "challenge page, proof verification, clearance cookie, origin routing, and events verified"
 
+api_post "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/waf-rules" '{"enabled":true,"name":"browser-check-only","priority":22,"type":"path_prefix","pattern":"/browser-check","action":"challenge","challenge_difficulty":1,"description":"verify lightweight challenge difficulty"}'
+assert_http_status "$HTTP_CODE" "201" "difficulty-1 waf challenge create failed"
+DIFFICULTY_ONE_WAF_RULE_ID="$(json_get "$HTTP_BODY" '.data.id')"
+assert_contains "$HTTP_BODY" '"challenge_difficulty":1' "difficulty-1 waf response should include challenge_difficulty"
+edge_pull_config
+difficulty_one_body="/tmp/e2e-waf-difficulty-one.txt"
+difficulty_one_code="$(curl -sS -o "$difficulty_one_body" -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" "${EDGE_URL}/browser-check?via=edge-waf-difficulty-one")"
+assert_eq "$difficulty_one_code" "403" "difficulty-1 waf rule should serve challenge page"
+assert_contains "$(cat "$difficulty_one_body")" "Security check" "difficulty-1 waf should return challenge page"
+difficulty_one_value="$(php -r '$body=file_get_contents($argv[1]); if(preg_match("/const difficulty = ([0-9]+);/", $body, $m)){ echo $m[1]; }' "$difficulty_one_body")"
+assert_eq "$difficulty_one_value" "1" "difficulty-1 waf challenge page should render difficulty 1"
+difficulty_one_token="$(php -r '$body=file_get_contents($argv[1]); if(preg_match("/const token = \"([^\"]+)\";/", $body, $m)){ echo $m[1]; }' "$difficulty_one_body")"
+[[ -n "$difficulty_one_token" ]] || fail "difficulty-1 challenge page did not include token"
+difficulty_one_cookie="/tmp/e2e-difficulty-one-cookie.txt"
+difficulty_one_verify="$(curl -sS -o /tmp/e2e-difficulty-one-verify.txt -c "$difficulty_one_cookie" -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" -X POST "${EDGE_URL}/__cdnlite_challenge_verify" --data-urlencode "token=${difficulty_one_token}" --data-urlencode "pow=browser-check")"
+assert_eq "$difficulty_one_verify" "303" "difficulty-1 browser check should set clearance"
+assert_contains "$(cat "$difficulty_one_cookie")" "__cdnlite_clearance" "difficulty-1 browser check should set clearance cookie"
+difficulty_one_cleared="$(curl -sS -b "$difficulty_one_cookie" -o /tmp/e2e-difficulty-one-cleared.txt -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" "${EDGE_URL}/browser-check?via=edge-waf-difficulty-one-cleared")"
+assert_eq "$difficulty_one_cleared" "200" "difficulty-1 clearance should allow origin routing"
+assert_contains "$(cat /tmp/e2e-difficulty-one-cleared.txt)" '"origin_scheme":"https"' "difficulty-1 cleared traffic should reach origin"
+api_delete "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/waf-rules/${DIFFICULTY_ONE_WAF_RULE_ID}"
+assert_http_status "$HTTP_CODE" "200" "difficulty-1 waf cleanup failed"
+record_step PASS "edge-waf-challenge-difficulty" "path-level WAF challenge difficulty 1 used browser check and reached origin after clearance"
+
 if docker compose exec -T edge-agent sh -lc "grep -q 'rate_limited' \"\${METRIC_PATH:-/var/lib/cdnlite/metrics.ndjson}\"" \
   || docker compose exec -T edge sh -lc "grep -q 'rate_limited' /var/lib/cdnlite/metrics.ndjson"; then
   record_step PASS "edge-rate-limit-metrics" "rate_limited metrics emitted"
diff --git a/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php b/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
index 094c4bc..9f62884 100644
--- a/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
+++ b/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
@@ -227,6 +227,10 @@ private function validateRateLimit(array $body, bool $partial): ?array {
             $action = Validator::enum($body, 'action', ['block', 'challenge']);
             if (($action['ok'] ?? false) !== true) { return $action; }
         }
+        if (array_key_exists('challenge_difficulty', $body) && $body['challenge_difficulty'] !== null && $body['challenge_difficulty'] !== '') {
+            $difficulty = Validator::intRange($body, 'challenge_difficulty', 1, 6);
+            if (($difficulty['ok'] ?? false) !== true) { return $difficulty; }
+        }
         return null;
     }
     public function createWaf(string $domainId, array $body): array {
@@ -245,6 +249,10 @@ public function createWaf(string $domainId, array $body): array {
             $action = Validator::enum($body, 'action', ['block', 'log', 'allow', 'challenge']);
             if (($action['ok'] ?? false) !== true) { return $action; }
         }
+        if (array_key_exists('challenge_difficulty', $body) && $body['challenge_difficulty'] !== null && $body['challenge_difficulty'] !== '') {
+            $difficulty = Validator::intRange($body, 'challenge_difficulty', 1, 6);
+            if (($difficulty['ok'] ?? false) !== true) { return $difficulty; }
+        }
         if (array_key_exists('name', $body)) {
             $name = Validator::optionalString($body, 'name', 255);
             if (($name['ok'] ?? false) !== true) { return $name; }
@@ -375,6 +383,10 @@ public function updateWaf(string $domainId, string $id, array $body): array {
         if (array_key_exists('action', $body) && !in_array((string) $body['action'], ['block', 'log', 'allow', 'challenge'], true)) {
             return ['error' => 'invalid_field', 'field' => 'action', 'detail' => 'must_be_one_of_block_log_allow_challenge', 'status' => 422];
         }
+        if (array_key_exists('challenge_difficulty', $body) && $body['challenge_difficulty'] !== null && $body['challenge_difficulty'] !== '') {
+            $difficulty = Validator::intRange($body, 'challenge_difficulty', 1, 6);
+            if (($difficulty['ok'] ?? false) !== true) { return $difficulty; }
+        }
         if (array_key_exists('priority', $body)) {
             $priority = Validator::intRange($body, 'priority', 1, 100000);
             if (($priority['ok'] ?? false) !== true) { return $priority; }
diff --git a/core/app/Modules/Proxy/Services/TrafficRulesService.php b/core/app/Modules/Proxy/Services/TrafficRulesService.php
index 03a79da..23515b6 100644
--- a/core/app/Modules/Proxy/Services/TrafficRulesService.php
+++ b/core/app/Modules/Proxy/Services/TrafficRulesService.php
@@ -101,10 +101,16 @@ public function createWaf(string $domainId, array $in): array {
             'type' => $type,
             'pattern' => (string)($in['pattern'] ?? ''),
             'action' => $action,
+            'challenge_difficulty' => $this->challengeDifficultyValue($in),
             'description' => isset($in['description']) ? (string) $in['description'] : null,
         ] + $this->wafMetadataPayload($in) + $this->managedRulePayload($in));
     }
-    public function updateWaf(string $domainId, string $id, array $in): ?array { return $this->update('waf_rules', $domainId, $id, $in); }
+    public function updateWaf(string $domainId, string $id, array $in): ?array {
+        if (array_key_exists('challenge_difficulty', $in)) {
+            $in['challenge_difficulty'] = $this->challengeDifficultyValue($in);
+        }
+        return $this->update('waf_rules', $domainId, $id, $in);
+    }
     public function deleteWaf(string $domainId, string $id): bool { return $this->delete('waf_rules', $domainId, $id); }
 
     public function listHeaderRules(string $domainId): array { return $this->listRows('domain_header_rules', $domainId, 'priority ASC, created_at ASC'); }
@@ -735,6 +741,7 @@ public function dryRunRateLimit(string $domainId, array $in): array {
                 'key_header_name' => $payload['key_header_name'] ?? null,
                 'requests_per_minute' => (int) ($payload['requests_per_minute'] ?? 60),
                 'action' => (string) ($payload['action'] ?? 'block'),
+                'challenge_difficulty' => $payload['challenge_difficulty'] ?? null,
             ],
             'preview_impact' => [
                 'lookback_seconds' => 86400,
@@ -1686,6 +1693,7 @@ private function rateLimitPayload(array $in, bool $partial = false): array {
             'key_header_name' => null,
             'requests_per_minute' => 60,
             'action' => 'block',
+            'challenge_difficulty' => null,
         ];
         $payload = [];
         foreach ($defaults as $key => $default) {
@@ -1693,6 +1701,8 @@ private function rateLimitPayload(array $in, bool $partial = false): array {
                 $value = $in[$key] ?? $default;
                 if ($key === 'key_header_name' && ($value === null || trim((string) $value) === '')) {
                     $payload[$key] = null;
+                } elseif ($key === 'challenge_difficulty') {
+                    $payload[$key] = $this->challengeDifficultyValue([$key => $value]);
                 } else {
                     $payload[$key] = $key === 'enabled' ? !empty($value) : ($key === 'priority' || $key === 'requests_per_minute' ? (int) $value : (string) $value);
                 }
@@ -1700,7 +1710,17 @@ private function rateLimitPayload(array $in, bool $partial = false): array {
         }
         return $payload + $this->managedRulePayload($in);
     }
-    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=((int)$r[$b])===1;}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','last_generated_at','last_applied_at'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } unset($r['private_key_pem']); return $r; }
+    private function challengeDifficultyValue(array $in): ?int {
+        if (!array_key_exists('challenge_difficulty', $in) || $in['challenge_difficulty'] === null || $in['challenge_difficulty'] === '') {
+            return null;
+        }
+        $difficulty = (int) $in['challenge_difficulty'];
+        if ($difficulty < 1 || $difficulty > 6) {
+            throw new \InvalidArgumentException('invalid_challenge_difficulty');
+        }
+        return $difficulty;
+    }
+    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=((int)$r[$b])===1;}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','last_generated_at','last_applied_at','challenge_difficulty'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } unset($r['private_key_pem']); return $r; }
     private function castSslJob(array $r): array {
         foreach (['created_at', 'updated_at', 'finished_at', 'progress_percent'] as $i) {
             if (isset($r[$i]) && $r[$i] !== null) {
diff --git a/core/database/migrations/000001_baseline_schema.sql b/core/database/migrations/000001_baseline_schema.sql
index 91ac0f7..b2e2077 100644
--- a/core/database/migrations/000001_baseline_schema.sql
+++ b/core/database/migrations/000001_baseline_schema.sql
@@ -520,6 +520,7 @@ CREATE TABLE IF NOT EXISTS rate_limit_rules (
   key_type TEXT NOT NULL DEFAULT 'ip',
   requests_per_minute INTEGER NOT NULL,
   action TEXT NOT NULL DEFAULT 'block',
+  challenge_difficulty INTEGER NULL CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6)),
   created_at BIGINT NOT NULL,
   updated_at BIGINT NOT NULL
 );
@@ -533,6 +534,7 @@ CREATE TABLE IF NOT EXISTS waf_rules (
   type TEXT NOT NULL,
   pattern TEXT NOT NULL,
   action TEXT NOT NULL DEFAULT 'block',
+  challenge_difficulty INTEGER NULL CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6)),
   description TEXT NULL,
   created_at BIGINT NOT NULL,
   updated_at BIGINT NOT NULL,
diff --git a/core/database/migrations/000028_challenge_difficulty.sql b/core/database/migrations/000028_challenge_difficulty.sql
new file mode 100644
index 0000000..bebb42d
--- /dev/null
+++ b/core/database/migrations/000028_challenge_difficulty.sql
@@ -0,0 +1,19 @@
+ALTER TABLE waf_rules
+  ADD COLUMN IF NOT EXISTS challenge_difficulty INTEGER NULL;
+
+ALTER TABLE rate_limit_rules
+  ADD COLUMN IF NOT EXISTS challenge_difficulty INTEGER NULL;
+
+ALTER TABLE waf_rules
+  DROP CONSTRAINT IF EXISTS waf_rules_challenge_difficulty_range;
+
+ALTER TABLE waf_rules
+  ADD CONSTRAINT waf_rules_challenge_difficulty_range
+  CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6));
+
+ALTER TABLE rate_limit_rules
+  DROP CONSTRAINT IF EXISTS rate_limit_rules_challenge_difficulty_range;
+
+ALTER TABLE rate_limit_rules
+  ADD CONSTRAINT rate_limit_rules_challenge_difficulty_range
+  CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6));
diff --git a/core/database/schema.sql b/core/database/schema.sql
index 910f470..774504c 100644
--- a/core/database/schema.sql
+++ b/core/database/schema.sql
@@ -814,6 +814,7 @@ CREATE TABLE IF NOT EXISTS rate_limit_rules (
   key_header_name TEXT NULL,
   requests_per_minute INTEGER NOT NULL,
   action TEXT NOT NULL DEFAULT 'block',
+  challenge_difficulty INTEGER NULL CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6)),
   profile_id TEXT NULL,
   intent_id TEXT NULL,
   template_key TEXT NULL,
@@ -834,6 +835,7 @@ CREATE TABLE IF NOT EXISTS waf_rules (
   type TEXT NOT NULL,
   pattern TEXT NOT NULL,
   action TEXT NOT NULL DEFAULT 'block',
+  challenge_difficulty INTEGER NULL CHECK (challenge_difficulty IS NULL OR (challenge_difficulty BETWEEN 1 AND 6)),
   description TEXT NULL,
   waf_group_id TEXT NULL,
   waf_severity TEXT NULL,
diff --git a/core/tests/test_phase4_challenge_clearance_contract.py b/core/tests/test_phase4_challenge_clearance_contract.py
index 89fc853..0603a5c 100644
--- a/core/tests/test_phase4_challenge_clearance_contract.py
+++ b/core/tests/test_phase4_challenge_clearance_contract.py
@@ -13,6 +13,8 @@ def test_edge_challenge_issues_signed_scoped_clearance_cookie():
     router = read("edge/openresty/lua/router.lua")
     nginx = read("edge/openresty/nginx.conf")
     compose = read("docker-compose.yml")
+    schema = read("core/database/schema.sql")
+    migration = read("core/database/migrations/000028_challenge_difficulty.sql")
 
     assert "ngx.hmac_sha1" in clearance
     assert "resty.sha256" in clearance
@@ -22,7 +24,7 @@ def test_edge_challenge_issues_signed_scoped_clearance_cookie():
     assert "CDNLITE_EDGE_CLEARANCE_SECRET" in clearance
     assert "CDNLITE_EDGE_CHALLENGE_DIFFICULTY" in clearance
     assert "function M.issue(domain_id, action, rule_id, client_ip, ttl)" in clearance
-    assert "function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)" in clearance
+    assert "function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path, difficulty_override)" in clearance
     assert "function M.verify_challenge()" in clearance
     assert "function M.consume_challenge(domain_id, action, rule_id, client_ip)" in clearance
     assert "function M.has_clearance(domain_id, action, rule_id, client_ip)" in clearance
@@ -43,15 +45,22 @@ def test_edge_challenge_issues_signed_scoped_clearance_cookie():
     assert "CDNLITE_EDGE_CLEARANCE_SECRET" in compose
     assert "CDNLITE_EDGE_CHALLENGE_DIFFICULTY" in compose
     assert "local clearance = require('clearance')" in router
+    assert "challenge_difficulty INTEGER NULL CHECK" in schema
+    assert "ADD COLUMN IF NOT EXISTS challenge_difficulty" in migration
 
 
 def test_waf_and_rate_limit_challenges_are_verifiable_not_static_denies():
     router = read("edge/openresty/lua/router.lua")
+    controller = read("core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php")
+    service = read("core/app/Modules/Proxy/Services/TrafficRulesService.php")
 
     assert "clearance.has_clearance(domain.domain_id, 'waf', rule.id, client_ip)" in router
-    assert "clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')" in router
+    assert "clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required', rule.challenge_difficulty)" in router
     assert "clearance.has_clearance(domain_id, 'rate_limit', rule.id, client_ip)" in router
-    assert "clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required')" in router
+    assert "clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required', rule.challenge_difficulty)" in router
+    assert "Validator::intRange($body, 'challenge_difficulty', 1, 6)" in controller
+    assert "'challenge_difficulty' => $this->challengeDifficultyValue($in)" in service
+    assert "private function challengeDifficultyValue" in service
 
     block_index = router.index("if ngx.ctx.security_action == 'block' then")
     challenge_index = router.index("if ngx.ctx.security_action == 'challenge' then")
@@ -77,6 +86,8 @@ def test_emergency_profile_challenges_all_visitors_before_origin():
     assert "challenge" in waf_tab
     assert "Level 1 performs a lightweight browser check" in waf_tab
     assert "levels 2-6 require increasing proof-of-work" in waf_tab
+    assert "Challenge difficulty" in waf_tab
+    assert "Challenge difficulty" in rate_tab
     assert "Challenge" in rate_tab and "hard block" in rate_tab
 
 
diff --git a/dash/src/types.ts b/dash/src/types.ts
index cf6b080..b75951d 100644
--- a/dash/src/types.ts
+++ b/dash/src/types.ts
@@ -131,8 +131,8 @@ export interface ApiProtectionDiscovery {
 }
 export interface CacheRule extends ManagedRuleMetadata { id: Id; enabled: boolean; path_prefix: string; ttl_seconds: number; }
 export interface PurgeRequest { id: Id; domain_id?: Id; type: 'url' | 'prefix' | 'domain' | 'everything' | string; value?: string; status?: string; created_at?: number | string; updated_at?: number | string; }
-export interface WafRule extends ManagedRuleMetadata { id: Id; type: string; pattern: string; action: 'block' | 'log' | 'allow' | string; priority: number; enabled?: boolean; status?: string; }
-export interface RateLimitRule extends ManagedRuleMetadata { id: Id; enabled: boolean; requests_per_minute: number; priority: number; path_prefix: string; key_type: 'ip' | 'ip_path' | 'header' | 'header_path' | string; key_header_name?: string | null; action: string; }
+export interface WafRule extends ManagedRuleMetadata { id: Id; type: string; pattern: string; action: 'block' | 'log' | 'allow' | string; priority: number; challenge_difficulty?: number | null; enabled?: boolean; status?: string; }
+export interface RateLimitRule extends ManagedRuleMetadata { id: Id; enabled: boolean; requests_per_minute: number; priority: number; path_prefix: string; key_type: 'ip' | 'ip_path' | 'header' | 'header_path' | string; key_header_name?: string | null; action: string; challenge_difficulty?: number | null; }
 export interface HeaderRule extends ManagedRuleMetadata { id: Id; enabled: boolean; priority: number; operation: 'set' | 'remove' | 'append' | string; header_name: string; header_value?: string | null; path_pattern: string; }
 export interface IpRule extends ManagedRuleMetadata { id: Id; enabled: boolean; rule_type: 'allow' | 'block' | string; cidr: string; description?: string | null; }
 export interface DomainOrigin {
diff --git a/dash/src/views/domain-tabs/DomainRateLimitsTab.vue b/dash/src/views/domain-tabs/DomainRateLimitsTab.vue
index 65ee7af..67aed32 100644
--- a/dash/src/views/domain-tabs/DomainRateLimitsTab.vue
+++ b/dash/src/views/domain-tabs/DomainRateLimitsTab.vue
@@ -46,6 +46,7 @@ const helpItems = [
   { title: 'Path examples', body: 'Use / for site-wide limits, /login for authentication, or /api/ for API traffic.' },
   { title: 'Thresholds', body: 'Start higher than normal traffic, review analytics, then tighten for sensitive endpoints.' },
   { title: 'Key type', body: 'IP groups all requests from one visitor. Header keys can limit API tokens or Authorization headers.' },
+  { title: 'Challenge difficulty', body: 'Set difficulty on each challenge rule. Level 1 is lightweight browser verification; levels 2-6 add increasing proof-of-work. Leave blank to use the edge default.' },
 ];
 const fields = [
   { key: 'enabled', label: 'Enabled', type: 'checkbox' as const, default: true, help: 'Disable instead of deleting when testing traffic impact.' },
@@ -55,6 +56,7 @@ const fields = [
   { key: 'key_header_name', label: 'Header key', default: '', placeholder: 'Authorization', help: 'Required for header-based keys. Missing headers fall back to IP at the edge.' },
   { key: 'priority', label: 'Priority', type: 'number' as const, default: 100, placeholder: '100', help: 'Lower priority values are evaluated first.' },
   { key: 'action', label: 'Action', options: ['block', 'challenge'], default: 'block', help: 'Challenge adds friction before the limit turns into a hard block.' },
+  { key: 'challenge_difficulty', label: 'Challenge difficulty', type: 'number' as const, default: '', placeholder: '1-6', help: 'Optional for challenge action. 1 is lightweight browser verification; 2-6 add increasing proof-of-work. Blank uses the edge default.' },
 ];
 const columns = [
   { key: 'enabled', label: 'Enabled' },
@@ -62,6 +64,7 @@ const columns = [
   { key: 'requests_per_minute', label: 'Requests/min' },
   { key: 'key_type', label: 'Key' },
   { key: 'key_header_name', label: 'Header' },
+  { key: 'challenge_difficulty', label: 'Difficulty' },
   { key: 'managed_by', label: 'Managed' },
   { key: 'actions', label: 'Actions' },
 ];
diff --git a/dash/src/views/domain-tabs/DomainWafTab.vue b/dash/src/views/domain-tabs/DomainWafTab.vue
index 53bac50..2049722 100644
--- a/dash/src/views/domain-tabs/DomainWafTab.vue
+++ b/dash/src/views/domain-tabs/DomainWafTab.vue
@@ -1,2 +1,2 @@
 <template><DomainRulesTab :domain-id="domainId" title="WAF Rules" summary="Inspect and act on matching requests." :fields="fields" :columns="columns" :help-items="helpItems" :list="() => wafApi.list(domainId)" :create="(v) => wafApi.create(domainId, v)" :update="(id, v) => wafApi.update(domainId, id, v)" :detach-managed="(id) => wafApi.detachManaged(domainId, id)" :remove="(id) => wafApi.remove(domainId, id)" /></template>
-<script setup lang="ts">import DomainRulesTab from './DomainRulesTab.vue'; import { wafApi } from '@/lib/api/waf'; defineProps<{ domainId:string }>(); const helpItems=[{title:'Start with log',body:'Use Log first for new patterns, watch security events, then switch to Block when false positives look low.'},{title:'Challenge difficulty',body:'Challenge uses the edge-wide CDNLITE_EDGE_CHALLENGE_DIFFICULTY setting. Level 1 performs a lightweight browser check; levels 2-6 require increasing proof-of-work before origin routing.'},{title:'Pattern examples',body:'path_prefix /admin, user_agent_contains sqlmap, ip_cidr 203.0.113.0/24, method_is POST, path_method_not_allowed /api/:GET,POST.'},{title:'Priority',body:'Lower numbers run first. Put explicit allow rules before broad block rules.'}]; const fields=[{key:'enabled',label:'Enabled',type:'checkbox' as const,default:true,help:'Turn off a rule temporarily without losing its match settings.'},{key:'name',label:'Name',default:'',placeholder:'Block admin scanners',help:'Use a short purpose-driven name that shows up clearly in security events.'},{key:'type',label:'Type',options:['path_contains','path_prefix','user_agent_contains','ip_cidr','country_is','method_is','header_contains','path_method_not_allowed'],default:'path_contains',help:'Choose what part of the request should be inspected.'},{key:'pattern',label:'Pattern',default:'',placeholder:'/admin',help:'Format depends on type: path text, CIDR, country code, HTTP method, header text, or /api/:GET,POST for scoped API method rules.'},{key:'action',label:'Action',options:['block','log','allow','challenge'],default:'block',help:'Log is safest for testing. Challenge verifies browsers before origin routing; difficulty is controlled by CDNLITE_EDGE_CHALLENGE_DIFFICULTY. Allow can exempt trusted traffic.'},{key:'priority',label:'Priority',type:'number' as const,default:100,placeholder:'100',help:'Rules with lower priority values are evaluated first.'},{key:'description',label:'Description',default:'',placeholder:'Blocks suspicious requests to admin paths',help:'Record why the rule exists and when it should be revisited.'}]; const columns=[{key:'enabled',label:'Enabled'},{key:'name',label:'Name'},{key:'type',label:'Type'},{key:'pattern',label:'Pattern'},{key:'action',label:'Action'},{key:'managed_by',label:'Managed'},{key:'actions',label:'Actions'}];</script>
+<script setup lang="ts">import DomainRulesTab from './DomainRulesTab.vue'; import { wafApi } from '@/lib/api/waf'; defineProps<{ domainId:string }>(); const helpItems=[{title:'Start with log',body:'Use Log first for new patterns, watch security events, then switch to Block when false positives look low.'},{title:'Challenge difficulty',body:'Set difficulty on each challenge rule. Level 1 performs a lightweight browser check; levels 2-6 require increasing proof-of-work before origin routing. Leave blank to use the edge default.'},{title:'Pattern examples',body:'path_prefix /admin, user_agent_contains sqlmap, ip_cidr 203.0.113.0/24, method_is POST, path_method_not_allowed /api/:GET,POST.'},{title:'Priority',body:'Lower numbers run first. Put explicit allow rules before broad block rules.'}]; const fields=[{key:'enabled',label:'Enabled',type:'checkbox' as const,default:true,help:'Turn off a rule temporarily without losing its match settings.'},{key:'name',label:'Name',default:'',placeholder:'Block admin scanners',help:'Use a short purpose-driven name that shows up clearly in security events.'},{key:'type',label:'Type',options:['path_contains','path_prefix','user_agent_contains','ip_cidr','country_is','method_is','header_contains','path_method_not_allowed'],default:'path_contains',help:'Choose what part of the request should be inspected.'},{key:'pattern',label:'Pattern',default:'',placeholder:'/admin',help:'Format depends on type: path text, CIDR, country code, HTTP method, header text, or /api/:GET,POST for scoped API method rules.'},{key:'action',label:'Action',options:['block','log','allow','challenge'],default:'block',help:'Log is safest for testing. Challenge verifies browsers before origin routing. Allow can exempt trusted traffic.'},{key:'challenge_difficulty',label:'Challenge difficulty',type:'number' as const,default:'',placeholder:'1-6',help:'Optional for challenge action. 1 is lightweight browser verification; 2-6 add increasing proof-of-work. Blank uses the edge default.'},{key:'priority',label:'Priority',type:'number' as const,default:100,placeholder:'100',help:'Rules with lower priority values are evaluated first.'},{key:'description',label:'Description',default:'',placeholder:'Blocks suspicious requests to admin paths',help:'Record why the rule exists and when it should be revisited.'}]; const columns=[{key:'enabled',label:'Enabled'},{key:'name',label:'Name'},{key:'type',label:'Type'},{key:'pattern',label:'Pattern'},{key:'action',label:'Action'},{key:'challenge_difficulty',label:'Difficulty'},{key:'managed_by',label:'Managed'},{key:'actions',label:'Actions'}];</script>
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index ea9602b..4c01a1d 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1456,8 +1456,8 @@ On documented reference hardware:
 **Tracking issue:** Local roadmap Phase 4  
 **Manifest:** `ci/phases/phase-04.yml`  
 **Evidence:** `ci/reports/phase-04-report.md`, `ci/reports/phase-04-report.json`  
-**Completed work:** Added configurable self-hosted browser verification pages for WAF and rate-limit challenge actions, the edge-only `/__cdnlite_challenge_verify` endpoint, signed scoped challenge and clearance tokens, level-1 lightweight browser verification, level-2-through-6 proof-of-work, HttpOnly clearance cookies, same-host redirect recovery, block-before-challenge precedence, Emergency Protection site-wide challenge mode, `CDNLITE_EDGE_CLEARANCE_SECRET`, `CDNLITE_EDGE_CHALLENGE_DIFFICULTY`, Phase 4 runner registration, e2e coverage, and stress scenario registration.  
-**Remaining work:** None for the accepted Phase 4 delivery. Third-party CAPTCHA providers remain a later optional extension, not a Phase 4 requirement.
+**Completed work:** Added configurable self-hosted browser verification pages for WAF and rate-limit challenge actions, per-rule `challenge_difficulty` for domain paths and WAF patterns, the edge-only `/__cdnlite_challenge_verify` endpoint, signed scoped challenge and clearance tokens, level-1 lightweight browser verification, level-2-through-6 proof-of-work, HttpOnly clearance cookies, same-host redirect recovery, block-before-challenge precedence, Emergency Protection site-wide challenge mode, `CDNLITE_EDGE_CLEARANCE_SECRET`, `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` fallback, Phase 4 runner registration, e2e coverage, and stress scenario registration.  
+**Closure:** Phase 4 has no remaining mandatory work. The completed challenge engine is self-hosted and provider-independent; third-party CAPTCHA providers may be added later as optional integrations without reopening Phase 4.
 
 ### Objective
 
diff --git a/docs/api/api.md b/docs/api/api.md
index 661d208..7f71928 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -476,7 +476,7 @@ Protection profiles are one-click bundles over the same intent engine. One-click
 
 Managed WAF presets add inspection metadata to generated WAF rules. WAF rules created by Security Center intents can include `waf_group_id`, `waf_severity`, `waf_confidence`, and `waf_safe_reason`; edge `waf_match` security events emit matching `group_id`, `severity`, `confidence`, and `safe_reason` fields so Activity can explain why a managed rule acted. These fields are additive metadata on the advanced WAF rule, so operators can still edit, detach, or override the generated rule.
 
-Bot Shield rules additionally carry `bot_class`, `bot_score`, and `bot_action`. A matched bot policy emits a `bot_match` security event with those fields and the request ID. A claimed search crawler is not trusted from its User-Agent alone: the built-in policy challenges it unless the edge config includes an enabled `verified_bot_sources` entry whose CIDR and User-Agent pattern both match the request. Advanced WAF and rate-limit rules may use `challenge`, which serves the self-hosted browser verification page, verifies through `/__cdnlite_challenge_verify`, sets `__cdnlite_clearance`, and records the event. `CDNLITE_EDGE_CHALLENGE_DIFFICULTY=1` uses a lightweight browser check; levels `2`-`6` add increasing proof-of-work.
+Bot Shield rules additionally carry `bot_class`, `bot_score`, and `bot_action`. A matched bot policy emits a `bot_match` security event with those fields and the request ID. A claimed search crawler is not trusted from its User-Agent alone: the built-in policy challenges it unless the edge config includes an enabled `verified_bot_sources` entry whose CIDR and User-Agent pattern both match the request. Advanced WAF and rate-limit rules may use `challenge`, which serves the self-hosted browser verification page, verifies through `/__cdnlite_challenge_verify`, sets `__cdnlite_clearance`, and records the event. Set `challenge_difficulty` from `1` to `6` on a WAF or rate-limit rule to tune that path or pattern: `1` uses a lightweight browser check, while `2`-`6` add increasing proof-of-work. If omitted, the edge uses `CDNLITE_EDGE_CHALLENGE_DIFFICULTY`.
 
 The Managed WAF preset catalog is read-only and returns available WAF modes, group definitions, and currently generated rule templates grouped by `waf_group_id`. Use it to inspect SQL injection, XSS, traversal, inclusion, command injection, PHP/WordPress, scanner, encoding, and bad user-agent coverage before enabling or tightening rules through the preview/apply protection flows.
 
diff --git a/docs/security.md b/docs/security.md
index c8f453d..bdc2e62 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -73,9 +73,11 @@ Set `CDNLITE_EDGE_CLEARANCE_SECRET` to a strong shared secret on every edge in a
 fleet. Rotating it invalidates existing clearance cookies, which is safe but can
 temporarily make visitors solve a challenge again.
 
-Set `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` between `1` and `6` to tune challenge
-cost. This is a provider-independent abuse-friction mechanism; it is not a
-guarantee that a visitor is human.
+Set `challenge_difficulty` on individual WAF or rate-limit challenge rules to
+tune challenge cost per domain path or pattern. If a rule omits
+`challenge_difficulty`, the edge falls back to `CDNLITE_EDGE_CHALLENGE_DIFFICULTY`.
+This is a provider-independent abuse-friction mechanism; it is not a guarantee
+that a visitor is human.
 
 | Difficulty | Behavior | Use case |
 | --- | --- | --- |
diff --git a/docs/setup.md b/docs/setup.md
index d3e35ca..93f3123 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -234,7 +234,7 @@ Edge and agent settings:
 | `CDNLITE_EDGE_DEBUG_HEADERS` | Reserved for future debug header logging; keep `false` unless a runbook explicitly enables it. |
 | `CDNLITE_EDGE_MMDB_FILE` | GeoIP MMDB used by the edge for country WAF/origin decisions; default `/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb`. |
 | `CDNLITE_EDGE_CLEARANCE_SECRET` | Shared edge secret for signed challenge and clearance cookies. Set the same strong value on every edge; rotation invalidates existing clearances. |
-| `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` | Self-hosted edge challenge difficulty, from `1` to `6`; default `3`. Level `1` performs a lightweight browser check without proof-of-work. Levels `2` through `6` require increasing SHA-256 proof-of-work before origin routing. |
+| `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` | Default self-hosted edge challenge difficulty, from `1` to `6`; default `3`. WAF and rate-limit challenge rules can override this per path or pattern with `challenge_difficulty`. Level `1` performs a lightweight browser check without proof-of-work. Levels `2` through `6` require increasing SHA-256 proof-of-work before origin routing. |
 | `EDGE_AGENT_IDLE` | CI flag to keep agent idle while scripts drive flow manually. |
 
 Recommended starting values:
diff --git a/edge/openresty/lua/clearance.lua b/edge/openresty/lua/clearance.lua
index d118ed0..cb829c4 100644
--- a/edge/openresty/lua/clearance.lua
+++ b/edge/openresty/lua/clearance.lua
@@ -148,10 +148,10 @@ function M.issue(domain_id, action, rule_id, client_ip, ttl)
   }), expires_at
 end
 
-function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)
+function M.issue_challenge(domain_id, action, rule_id, client_ip, return_path, difficulty_override)
   local expires_at = ngx.time() + challenge_ttl
   local nonce = b64(tostring(ngx.now()) .. ':' .. tostring(math.random()) .. ':' .. tostring(ngx.worker.pid()))
-  local difficulty = tonumber(os.getenv('CDNLITE_EDGE_CHALLENGE_DIFFICULTY') or '') or default_difficulty
+  local difficulty = tonumber(difficulty_override or '') or tonumber(os.getenv('CDNLITE_EDGE_CHALLENGE_DIFFICULTY') or '') or default_difficulty
   if difficulty < 1 then difficulty = 1 end
   if difficulty > 6 then difficulty = 6 end
   return encode_token({
@@ -264,9 +264,9 @@ function M.verify_challenge()
   return ngx.exit(303)
 end
 
-function M.challenge_response(domain_id, action, rule_id, client_ip, status_code, error_code)
+function M.challenge_response(domain_id, action, rule_id, client_ip, status_code, error_code, difficulty_override)
   local return_path = same_host_path(ngx.var.request_uri or ngx.var.uri or '/')
-  local token, expires_at, difficulty = M.issue_challenge(domain_id, action, rule_id, client_ip, return_path)
+  local token, expires_at, difficulty = M.issue_challenge(domain_id, action, rule_id, client_ip, return_path, difficulty_override)
   local verify_path = '/__cdnlite_challenge_verify'
   ngx.status = status_code
   ngx.header.content_type = 'text/html; charset=utf-8'
diff --git a/edge/openresty/lua/router.lua b/edge/openresty/lua/router.lua
index edc68fe..622a896 100644
--- a/edge/openresty/lua/router.lua
+++ b/edge/openresty/lua/router.lua
@@ -247,7 +247,7 @@ local function apply_waf(cfg, host)
         end
         append_security_event(nil)
         identity.apply()
-        return clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required')
+        return clearance.challenge_response(domain.domain_id, 'waf', rule.id, client_ip, 403, 'bot_challenge_required', rule.challenge_difficulty)
       end
       return true
     end
@@ -346,7 +346,7 @@ local function apply_rate_limit(cfg, host, domain_id)
     edge_log.warn('rate_limit_challenge', { domain_id = tostring(domain_id or ''), rule_id = tostring(rule.id or '') })
     identity.apply()
     ngx.header['Retry-After'] = '60'
-    return clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required')
+    return clearance.challenge_response(domain_id, 'rate_limit', rule.id, client_ip, 429, 'challenge_required', rule.challenge_difficulty)
   end
   return true
 end

From 3ee69bdd707325a030e9d52099a680bec48591ba Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 00:04:53 +0330
Subject: [PATCH 04/11] feat: Enhance report warnings structure with additional
 fields and update related API documentation

---
 .../Reports/Services/ReportService.php        | 11 ++++--
 core/tests/test_reports_contract.py           |  4 +++
 dash/src/types.ts                             |  2 +-
 dash/src/views/OverviewView.vue               | 34 +++++++++++++++----
 docs/api/api.md                               |  2 +-
 docs/public/api/openapi.yaml                  |  2 +-
 6 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/core/app/Modules/Reports/Services/ReportService.php b/core/app/Modules/Reports/Services/ReportService.php
index 2430ef6..f03b68f 100644
--- a/core/app/Modules/Reports/Services/ReportService.php
+++ b/core/app/Modules/Reports/Services/ReportService.php
@@ -399,11 +399,18 @@ private function warnings(array $range, array $kpis): array
             ['key' => 'failed_jobs', 'severity' => 'critical', 'message' => 'failed jobs in range', 'link' => '/jobs'],
             ['key' => 'pending_dns_changes', 'severity' => 'warning', 'message' => 'pending DNS changes', 'link' => '/dns-operations'],
             ['key' => 'ssl_expiring_count', 'severity' => 'warning', 'message' => 'certificates expiring within 30 days', 'link' => '/domains'],
-            ['key' => 'origin_errors', 'severity' => 'warning', 'message' => 'origin or edge errors in range', 'link' => '/usage'],
+            ['key' => 'origin_errors', 'severity' => 'warning', 'message' => 'origin or edge errors in range', 'link' => '/#recent-problem-requests', 'section' => 'recent_problem_requests'],
         ] as $rule) {
             $count = (int) ($kpis[$rule['key']] ?? 0);
             if ($count > 0) {
-                $warnings[] = ['severity' => $rule['severity'], 'message' => $count . ' ' . $rule['message'], 'link' => $rule['link'], 'count' => $count];
+                $warnings[] = [
+                    'key' => $rule['key'],
+                    'severity' => $rule['severity'],
+                    'message' => $count . ' ' . $rule['message'],
+                    'link' => $rule['link'],
+                    'section' => $rule['section'] ?? null,
+                    'count' => $count,
+                ];
             }
         }
         usort($warnings, static fn (array $a, array $b): int => ['critical' => 0, 'warning' => 1, 'info' => 2][$a['severity']] <=> ['critical' => 0, 'warning' => 1, 'info' => 2][$b['severity']]);
diff --git a/core/tests/test_reports_contract.py b/core/tests/test_reports_contract.py
index 7291275..e812d80 100644
--- a/core/tests/test_reports_contract.py
+++ b/core/tests/test_reports_contract.py
@@ -85,4 +85,8 @@ def test_dashboard_reports_client_and_overview_use_real_report_endpoints():
     assert "Top Visitor Countries" in overview
     assert "request.client_ip" in overview
     assert "request.client_country" in overview
+    assert "'link' => '/#recent-problem-requests'" in (ROOT / "core/app/Modules/Reports/Services/ReportService.php").read_text()
+    assert "Show details" in overview
+    assert "warning.key === 'origin_errors'" in overview
+    assert "recent_problem_requests.slice(0, 3)" in overview
     assert "mock" not in overview.lower()
diff --git a/dash/src/types.ts b/dash/src/types.ts
index b75951d..f18ea2f 100644
--- a/dash/src/types.ts
+++ b/dash/src/types.ts
@@ -259,7 +259,7 @@ export interface ReportKpis {
   active_domains: number; online_edges: number; offline_edges: number; security_events: number; waf_blocks: number;
   rate_limited_requests: number; origin_errors: number; ssl_expiring_count: number; pending_dns_changes: number; failed_jobs: number;
 }
-export interface ReportWarning { severity: 'warning' | 'critical' | 'info'; message: string; link: string; count?: number; }
+export interface ReportWarning { key?: string; severity: 'warning' | 'critical' | 'info'; message: string; link: string; section?: string | null; count?: number; }
 export interface ReportSummary { time_range: ReportTimeRange; previous_time_range?: ReportTimeRange | null; kpis: ReportKpis; deltas?: Record<string, { absolute: number; percent: number | null }> | null; warnings: ReportWarning[]; generated_at: number; }
 export interface ReportDistributionRow { value?: string; status?: string; status_class?: string; severity?: string; action?: string; count: number; requests?: number; bytes_out?: number; }
 export interface ReportTraffic {
diff --git a/dash/src/views/OverviewView.vue b/dash/src/views/OverviewView.vue
index 0e114f2..e977225 100644
--- a/dash/src/views/OverviewView.vue
+++ b/dash/src/views/OverviewView.vue
@@ -32,12 +32,22 @@
         <h2 class="font-semibold text-slate-950 dark:text-white">Needs Attention</h2>
         <p v-if="!summary?.warnings.length" class="mt-3 text-sm text-emerald-700 dark:text-emerald-300">No active report warnings for this range.</p>
         <ul v-else class="mt-3 space-y-3">
-          <li v-for="warning in summary.warnings" :key="warning.message" class="flex items-center justify-between gap-3 rounded-md border border-slate-200 p-3 dark:border-white/10">
-            <div>
-              <StatusBadge :status="warning.severity" />
-              <span class="ml-2 text-sm text-slate-700 dark:text-slate-200">{{ warning.message }}</span>
+          <li v-for="warning in summary.warnings" :key="warning.key || warning.message" class="rounded-md border border-slate-200 p-3 dark:border-white/10">
+            <div class="flex items-start justify-between gap-3">
+              <div>
+                <StatusBadge :status="warning.severity" />
+                <span class="ml-2 text-sm font-medium text-slate-700 dark:text-slate-200">{{ warning.message }}</span>
+                <p v-if="warningDetail(warning)" class="mt-1 text-xs text-slate-500 dark:text-slate-400">{{ warningDetail(warning) }}</p>
+              </div>
+              <RouterLink :to="warning.link" class="shrink-0 text-sm font-bold text-cyan-700 dark:text-cyan-300">{{ warningAction(warning) }}</RouterLink>
             </div>
-            <RouterLink :to="warning.link" class="text-sm font-bold text-cyan-700 dark:text-cyan-300">Open</RouterLink>
+            <ul v-if="warning.key === 'origin_errors' && traffic?.recent_problem_requests.length" class="mt-3 divide-y divide-slate-200 rounded-md bg-slate-50 px-3 text-xs dark:divide-white/10 dark:bg-white/5">
+              <li v-for="request in traffic.recent_problem_requests.slice(0, 3)" :key="request.id" class="grid grid-cols-[auto_1fr_auto] gap-2 py-2">
+                <span class="font-semibold text-red-600 dark:text-red-300">{{ request.status || 'error' }}</span>
+                <span class="truncate text-slate-600 dark:text-slate-300">{{ request.path || request.host || 'unknown path' }}</span>
+                <span class="text-slate-500">{{ formatTime(request.ts) }}</span>
+              </li>
+            </ul>
           </li>
         </ul>
       </div>
@@ -90,7 +100,7 @@
     </div>
 
     <div class="grid gap-4 xl:grid-cols-2">
-      <section class="card overflow-hidden p-4">
+      <section id="recent-problem-requests" class="card scroll-mt-24 overflow-hidden p-4">
         <h2 class="font-semibold text-slate-950 dark:text-white">Recent Problem Requests</h2>
         <div class="mt-3 overflow-x-auto">
           <table class="min-w-full text-left text-sm">
@@ -246,5 +256,17 @@ function deltaText(key: string) {
   return `${sign}${delta.percent}% vs previous range`;
 }
 
+function warningDetail(warning: ReportSummary['warnings'][number]) {
+  if (warning.key === 'origin_errors') return 'See the sampled failing requests below with status, path, edge, visitor, and country.';
+  if (warning.key === 'pending_dns_changes') return 'Open DNS Operations to inspect pending sync state and PowerDNS visibility.';
+  if (warning.key === 'failed_jobs') return 'Open Jobs to inspect failed or cancelled SSL workflow entries.';
+  return '';
+}
+
+function warningAction(warning: ReportSummary['warnings'][number]) {
+  if (warning.key === 'origin_errors') return 'Show details';
+  return 'Open';
+}
+
 onMounted(load);
 </script>
diff --git a/docs/api/api.md b/docs/api/api.md
index 7f71928..dee2565 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -187,7 +187,7 @@ Useful admin login response fields:
 | --- | --- | --- |
 | `GET` | `/api/v1/overview` | Aggregate operations summary. |
 | `GET` | `/api/v1/overview/warnings` | Readiness and risk warnings. |
-| `GET` | `/api/v1/reports/summary` | CDN operations KPIs, compare-mode deltas, and ranked warnings. Accepts `domain_id`, `from`, `to`, `bucket`, `compare`, and `limit`. |
+| `GET` | `/api/v1/reports/summary` | CDN operations KPIs, compare-mode deltas, and ranked warnings with stable `key`, `link`, `section`, and `count` fields. Accepts `domain_id`, `from`, `to`, `bucket`, `compare`, and `limit`. |
 | `GET` | `/api/v1/reports/traffic` | Request, bandwidth, cache-ratio, status, top domain/path/visitor-country/edge, and problem-request reports. |
 | `GET` | `/api/v1/reports/cache` | Cache status distribution, hit-ratio trend, cache/origin bytes, uncached paths, and purge timeline. Unsupported ingest fields are returned as `null` with an `unavailable` note. |
 | `GET` | `/api/v1/reports/edge` | Edge online/offline counts, geography, heartbeat age, config drift, config errors, traffic, error rates, and node table. |
diff --git a/docs/public/api/openapi.yaml b/docs/public/api/openapi.yaml
index 8f36bf4..391cb64 100644
--- a/docs/public/api/openapi.yaml
+++ b/docs/public/api/openapi.yaml
@@ -140,7 +140,7 @@ paths:
   /api/v1/reports/summary:
     get:
       tags: [Reports]
-      summary: CDN operations KPIs, compare deltas, and ranked warnings
+      summary: CDN operations KPIs, compare deltas, and ranked warnings with stable drilldown fields
       parameters:
         - $ref: "#/components/parameters/DomainIdQuery"
         - $ref: "#/components/parameters/ReportFrom"

From a1258ffb1482f9e89347634cee94abc8bf858175 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 00:22:32 +0330
Subject: [PATCH 05/11] feat(waiting-room): implement waiting room policy
 management and API endpoints

- Added new API endpoints for managing waiting room policies, including retrieval, update, and emergency activation/deactivation.
- Introduced a new WaitingRoomPolicy interface in TypeScript to define the structure of waiting room policies.
- Created a new Vue component for the waiting room tab in the domain detail view, allowing users to manage waiting room settings.
- Implemented backend logic for waiting room functionality, including ticket issuance and admission control.
- Updated OpenAPI documentation to reflect new waiting room endpoints.
- Added database migration for waiting room policies table.
- Enhanced security documentation to include waiting room admission mechanisms.
- Updated setup instructions to include new environment variables for waiting room configuration.
- Added CI phase for testing waiting room features and ensuring proper functionality.
---
 CHANGELOG.md                                  |   1 +
 ci/phases/phase-05.yml                        |  57 +++++
 ci/smoke.sh                                   |   7 +
 ci/stress/scenarios.yml                       |  13 +
 .../Controllers/TrafficRulesController.php    |  56 +++++
 .../Modules/Proxy/Services/ConfigService.php  |   1 +
 .../Proxy/Services/TrafficRulesService.php    |  78 +++++-
 .../migrations/000029_waiting_room.sql        |  47 ++++
 core/database/schema.sql                      |  48 ++++
 core/public_index.php                         |  10 +
 dash/src/lib/api/waitingRoom.ts               |  11 +
 dash/src/types.ts                             |  11 +
 dash/src/views/DomainDetailView.vue           |   4 +-
 .../domain-tabs/DomainWaitingRoomTab.vue      |  92 ++++++++
 docs/ROADMAP.md                               |   4 +-
 docs/api/api.md                               |   1 +
 docs/public/api/openapi.yaml                  |  39 +++
 docs/security.md                              |   9 +
 docs/setup.md                                 |   1 +
 edge/docker-entrypoint.sh                     |   4 +-
 edge/openresty/lua/router.lua                 |   6 +
 edge/openresty/lua/waiting_room.lua           | 223 ++++++++++++++++++
 edge/openresty/nginx.conf                     |  26 ++
 23 files changed, 745 insertions(+), 4 deletions(-)
 create mode 100644 ci/phases/phase-05.yml
 create mode 100644 core/database/migrations/000029_waiting_room.sql
 create mode 100644 dash/src/lib/api/waitingRoom.ts
 create mode 100644 dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
 create mode 100644 edge/openresty/lua/waiting_room.lua

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c43b41..2220185 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 2 analytics scalability with asynchronous recalculation jobs, job status API, idempotent aggregate upserts, bounded summary metadata, analytics cache schema, dashboard queued-job feedback, and contract documentation.
 - Phase 3 edge hot-path performance with worker-local config caching, last-known-good reload behavior, bounded shared-memory telemetry queues, queue health visibility, configurable edge capacity defaults, one-shot phase manifest, and stress scenario registration.
 - Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser verification page, per-rule challenge difficulty, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty fallback configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
+- Phase 5 waiting room with persisted per-domain policy, API and dashboard controls, signed edge queue tickets, signed admission cookies, local queue/status endpoints, bounded edge queue state, and operator documentation.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/phases/phase-05.yml b/ci/phases/phase-05.yml
new file mode 100644
index 0000000..3c7e952
--- /dev/null
+++ b/ci/phases/phase-05.yml
@@ -0,0 +1,57 @@
+phase: "05"
+name: "Adaptive overload protection and waiting room"
+owner: "CDNLite maintainers"
+status: "in_progress"
+topology: "root docker-compose.yml"
+profiles:
+  pr:
+    clean_required: false
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "luac -p edge/openresty/lua/waiting_room.lua edge/openresty/lua/router.lua"
+      - "bash -n ci/smoke.sh"
+      - "(cd dash && npm run typecheck)"
+  full:
+    clean_required: true
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests"
+      - "sh -n edge/agent/register.sh"
+      - "sh -n edge/agent/heartbeat.sh"
+      - "sh -n edge/agent/pull_config.sh"
+      - "sh -n edge/agent/push_metrics.sh"
+      - "sh -n edge/agent/run.sh"
+      - "bash -n ci/smoke.sh"
+      - "bash -n ci/e2e.sh"
+      - "bash -n ci/stress-platform.sh"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "ci/stress-platform.sh --scenario phase5-waiting-room"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "(cd dash && npm run typecheck && npm test && npm run build)"
+      - "(cd docs && npm run docs:build)"
+  release:
+    clean_required: true
+    destructive: true
+    commands:
+      - "./ci/phase.sh 05 --profile full --clean"
+required_docs:
+  - "docs/ROADMAP.md"
+  - "docs/api/api.md"
+  - "docs/security.md"
+  - "docs/setup.md"
+  - "CHANGELOG.md"
+evidence:
+  json: "ci/reports/phase-05-report.json"
+  markdown: "ci/reports/phase-05-report.md"
+stress_scenarios:
+  - "phase5-waiting-room"
+recovery_assertions:
+  - "Queue endpoints respond locally and never proxy to origins."
+  - "Origin-bound requests stay within the configured admission budget during overload."
+  - "Invalid or expired queue tickets and admission cookies fail closed."
diff --git a/ci/smoke.sh b/ci/smoke.sh
index 006755b..1f165e2 100755
--- a/ci/smoke.sh
+++ b/ci/smoke.sh
@@ -146,6 +146,13 @@ rate_limit_dry_run_route_count="$(grep -c '/api/v1/domains/{domainId}/rate-limit
 assert_eq "$rate_limit_dry_run_route_count" "1" "rate-limit dry-run route missing"
 record_step PASS "schema-rate-limit-dry-run-route" "rate-limit dry-run route is registered"
 
+waiting_room_route_count="$(grep -c '/api/v1/domains/{domainId}/waiting-room' core/public_index.php)"
+if [[ "$waiting_room_route_count" -lt "4" ]]; then
+  fail "waiting-room API routes are incomplete"
+fi
+grep -Fq "cdnlite_waiting_room" edge/openresty/nginx.conf || fail "waiting-room shared dictionary missing"
+record_step PASS "schema-waiting-room" "waiting-room API routes and edge state are registered"
+
 api_protection_route_count="$(grep -c '/api/v1/domains/{domainId}/protection/api-paths' core/public_index.php)"
 assert_eq "$api_protection_route_count" "1" "API Protection path discovery route missing"
 grep -Fq "path_method_not_allowed" edge/openresty/lua/router.lua || fail "API method restriction WAF matcher missing"
diff --git a/ci/stress/scenarios.yml b/ci/stress/scenarios.yml
index 07167cc..97bff4f 100644
--- a/ci/stress/scenarios.yml
+++ b/ci/stress/scenarios.yml
@@ -55,3 +55,16 @@ scenarios:
       - "invalid or expired challenge tokens keep requiring a challenge"
       - "valid clearance redirects once and then allows matching challenge rules"
       - "block rules remain terminal even when a clearance cookie exists"
+  phase5-waiting-room:
+    phase: "05"
+    workload: "edge-waiting-room-admission"
+    description: "Validate overload admission, bounded local queue state, edge-only queue endpoints, and manual emergency recovery."
+    stress:
+      burst_requests: 300
+      invalid_tickets: true
+      manual_emergency: true
+      queue_overflow: true
+    recovery:
+      - "manual emergency mode can be deactivated without flapping"
+      - "queue and admission counters stay bounded"
+      - "post-stress smoke and e2e gates run after overload pressure"
diff --git a/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php b/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
index 9f62884..9e768fc 100644
--- a/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
+++ b/core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php
@@ -96,6 +96,22 @@ public function dryRunRateLimit(string $domainId, array $body): array {
         if ($error !== null) { return $error; }
         return ['data' => $this->service->dryRunRateLimit($domainId, $body)];
     }
+    public function getWaitingRoom(string $domainId): array {
+        return ['data' => $this->service->getWaitingRoomPolicy($domainId)];
+    }
+    public function updateWaitingRoom(string $domainId, array $body): array {
+        $error = $this->validateWaitingRoom($body);
+        if ($error !== null) { return $error; }
+        return ['data' => $this->service->updateWaitingRoomPolicy($domainId, $body)];
+    }
+    public function activateWaitingRoomEmergency(string $domainId, array $body): array {
+        $ttl = Validator::intRange($body, 'ttl_seconds', 60, 86400, 3600);
+        if (($ttl['ok'] ?? false) !== true) { return $ttl; }
+        return ['data' => $this->service->activateWaitingRoomEmergency($domainId, (int) $ttl['value'], (string) ($body['reason'] ?? 'manual_emergency'))];
+    }
+    public function deactivateWaitingRoomEmergency(string $domainId): array {
+        return ['data' => $this->service->deactivateWaitingRoomEmergency($domainId)];
+    }
     public function detachManagedRule(string $domainId, string $ruleType, string $id): array {
         try {
             $rule = $this->service->detachManagedRule($domainId, $ruleType, $id);
@@ -233,6 +249,46 @@ private function validateRateLimit(array $body, bool $partial): ?array {
         }
         return null;
     }
+    private function validateWaitingRoom(array $body): ?array {
+        foreach (['enabled'] as $field) {
+            if (array_key_exists($field, $body)) {
+                $v = Validator::bool($body, $field);
+                if (($v['ok'] ?? false) !== true) { return $v; }
+            }
+        }
+        foreach (['mode' => ['monitoring','automatic','manual'], 'state' => ['disabled','monitoring','healthy','entering_overload','overloaded','recovering','manual_emergency']] as $field => $values) {
+            if (array_key_exists($field, $body)) {
+                $v = Validator::enum($body, $field, $values);
+                if (($v['ok'] ?? false) !== true) { return $v; }
+            }
+        }
+        $ranges = [
+            'rps_threshold' => [1, 1000000], 'active_origin_threshold' => [1, 1000000],
+            'origin_latency_ms_threshold' => [1, 600000], 'origin_error_rate_threshold' => [1, 100],
+            'admission_rate_per_minute' => [1, 1000000], 'queue_limit' => [1, 1000000],
+            'per_client_ticket_limit' => [1, 1000], 'ticket_ttl_seconds' => [30, 3600],
+            'admission_ttl_seconds' => [60, 86400], 'status_poll_seconds' => [2, 300],
+            'jitter_seconds' => [0, 300], 'unhealthy_windows' => [1, 100],
+            'healthy_windows' => [1, 100], 'minimum_state_seconds' => [1, 86400],
+            'recovery_ramp_percent' => [1, 100], 'manual_override_until' => [0, 4102444800],
+        ];
+        foreach ($ranges as $field => [$min, $max]) {
+            if (array_key_exists($field, $body) && $body[$field] !== null) {
+                $v = Validator::intRange($body, $field, $min, $max);
+                if (($v['ok'] ?? false) !== true) { return $v; }
+            }
+        }
+        foreach (['waiting_room_title' => 120, 'waiting_room_message' => 500, 'reason' => 160] as $field => $max) {
+            if (array_key_exists($field, $body) && $body[$field] !== null) {
+                $v = Validator::optionalString($body, $field, $max);
+                if (($v['ok'] ?? false) !== true) { return $v; }
+            }
+        }
+        if (array_key_exists('trusted_cidrs', $body) && !is_array($body['trusted_cidrs'])) {
+            return ['error' => 'invalid_field', 'field' => 'trusted_cidrs', 'detail' => 'must_be_array', 'status' => 422];
+        }
+        return null;
+    }
     public function createWaf(string $domainId, array $body): array {
         $type = Validator::requiredString($body, 'type', 64);
         if (($type['ok'] ?? false) !== true) { return $type; }
diff --git a/core/app/Modules/Proxy/Services/ConfigService.php b/core/app/Modules/Proxy/Services/ConfigService.php
index a9f7cf7..461a4f6 100644
--- a/core/app/Modules/Proxy/Services/ConfigService.php
+++ b/core/app/Modules/Proxy/Services/ConfigService.php
@@ -102,6 +102,7 @@ public function rebuild(?int $ifVersion = null): array
             foreach ($this->rules->listCachePurgeVersionsForConfig($domainId, $host) as $row) { $cachePurgeVersions[] = $row; }
             foreach ($this->rules->listPageRules($domainId) as $row) { if (!empty($row['enabled'])) { $row['host'] = $host; $pageRules[] = $row; } }
             foreach ($this->rules->listSslCertificatesForConfig($domainId, $host) as $row) { $sslCertificates[] = $row; }
+            foreach ($this->rules->listWaitingRoomPoliciesForConfig($domainId) as $row) { $hosts[$host]['waiting_room'] = $row; }
         }
         // Keep hash deterministic for unchanged config content.
         // `generated_at` is intentionally excluded so no-op syncs reuse version.
diff --git a/core/app/Modules/Proxy/Services/TrafficRulesService.php b/core/app/Modules/Proxy/Services/TrafficRulesService.php
index 23515b6..56f558a 100644
--- a/core/app/Modules/Proxy/Services/TrafficRulesService.php
+++ b/core/app/Modules/Proxy/Services/TrafficRulesService.php
@@ -717,6 +717,48 @@ public function updateRateLimit(string $domainId, string $id, array $in): ?array
     public function deleteRateLimit(string $domainId, string $id): bool {
         return $this->delete('rate_limit_rules', $domainId, $id);
     }
+    public function getWaitingRoomPolicy(string $domainId): array {
+        $s = Database::pdo()->prepare('SELECT * FROM waiting_room_policies WHERE domain_id=:domain_id LIMIT 1');
+        $s->execute([':domain_id' => $domainId]);
+        $row = $s->fetch();
+        if ($row) {
+            return $this->cast((array) $row);
+        }
+        return $this->createWaitingRoomPolicy($domainId, []);
+    }
+    public function updateWaitingRoomPolicy(string $domainId, array $in): array {
+        $current = $this->getWaitingRoomPolicy($domainId);
+        $payload = $this->waitingRoomPayload($in, true);
+        if ($payload === []) {
+            return $current;
+        }
+        $updated = $this->update('waiting_room_policies', $domainId, (string) $current['id'], $payload);
+        return $updated ?? $this->getWaitingRoomPolicy($domainId);
+    }
+    public function activateWaitingRoomEmergency(string $domainId, int $ttlSeconds, string $reason = 'manual_emergency'): array {
+        $until = time() + max(60, min(86400, $ttlSeconds));
+        return $this->updateWaitingRoomPolicy($domainId, [
+            'enabled' => true,
+            'mode' => 'manual',
+            'state' => 'manual_emergency',
+            'reason' => $reason,
+            'manual_override_until' => $until,
+        ]);
+    }
+    public function deactivateWaitingRoomEmergency(string $domainId): array {
+        return $this->updateWaitingRoomPolicy($domainId, [
+            'mode' => 'monitoring',
+            'state' => 'healthy',
+            'reason' => 'manual_deactivation',
+            'manual_override_until' => null,
+        ]);
+    }
+    public function listWaitingRoomPoliciesForConfig(string $domainId): array {
+        $s = Database::pdo()->prepare('SELECT * FROM waiting_room_policies WHERE domain_id=:domain_id AND enabled=true LIMIT 1');
+        $s->execute([':domain_id' => $domainId]);
+        $row = $s->fetch();
+        return $row ? [$this->cast((array) $row)] : [];
+    }
     public function dryRunRateLimit(string $domainId, array $in): array {
         $payload = $this->rateLimitPayload($in);
         $pathPrefix = (string) ($payload['path_prefix'] ?? '/');
@@ -1107,6 +1149,9 @@ public function undoProtectionIntent(string $domainId, string $intentId): ?array
     }
 
     private function listRows(string $table, string $domainId, string $orderBy = 'created_at ASC'): array { $s=Database::pdo()->prepare("SELECT * FROM {$table} WHERE domain_id=:domain_id ORDER BY {$orderBy}"); $s->execute([':domain_id'=>$domainId]); return array_map([$this,'cast'], $s->fetchAll()); }
+    private function createWaitingRoomPolicy(string $domainId, array $in): array {
+        return $this->insert('waiting_room_policies', $domainId, $this->waitingRoomPayload($in));
+    }
     private function insert(string $table, string $domainId, array $in): array {
         $id=Uuid::v4(); $now=time(); $cols=array_keys($in); $names=implode(',', $cols); $bind=':'.implode(',:', $cols);
         $sql="INSERT INTO {$table} (id,domain_id,{$names},created_at,updated_at) VALUES (:id,:domain_id,{$bind},:created_at,:updated_at)";
@@ -1720,7 +1765,38 @@ private function challengeDifficultyValue(array $in): ?int {
         }
         return $difficulty;
     }
-    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=((int)$r[$b])===1;}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','last_generated_at','last_applied_at','challenge_difficulty'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } unset($r['private_key_pem']); return $r; }
+    private function waitingRoomPayload(array $in, bool $partial = false): array {
+        $defaults = [
+            'enabled' => false, 'mode' => 'monitoring', 'state' => 'disabled', 'reason' => null,
+            'rps_threshold' => 100, 'active_origin_threshold' => 20, 'origin_latency_ms_threshold' => 3000,
+            'origin_error_rate_threshold' => 50, 'admission_rate_per_minute' => 60, 'queue_limit' => 1000,
+            'per_client_ticket_limit' => 3, 'ticket_ttl_seconds' => 300, 'admission_ttl_seconds' => 900,
+            'status_poll_seconds' => 5, 'jitter_seconds' => 4, 'unhealthy_windows' => 3, 'healthy_windows' => 3,
+            'minimum_state_seconds' => 60, 'recovery_ramp_percent' => 25, 'manual_override_until' => null,
+            'trusted_cidrs_json' => '[]', 'waiting_room_title' => 'Traffic is high',
+            'waiting_room_message' => 'You are in a short waiting room while this site protects its origin.',
+            'counters_json' => '{}',
+        ];
+        $payload = $partial ? [] : $defaults;
+        foreach ($defaults as $key => $default) {
+            if (!array_key_exists($key, $in)) {
+                continue;
+            }
+            $value = $in[$key];
+            if ($key === 'trusted_cidrs_json' && is_array($value)) {
+                $value = json_encode(array_values(array_slice($value, 0, 100)), JSON_UNESCAPED_SLASHES);
+            }
+            if ($key === 'counters_json' && is_array($value)) {
+                $value = json_encode($value, JSON_UNESCAPED_SLASHES);
+            }
+            $payload[$key] = $value;
+        }
+        if (array_key_exists('trusted_cidrs', $in)) {
+            $payload['trusted_cidrs_json'] = json_encode(array_values(array_slice((array) $in['trusted_cidrs'], 0, 100)), JSON_UNESCAPED_SLASHES);
+        }
+        return $payload;
+    }
+    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=in_array($r[$b], [true, 1, '1', 't', 'true'], true);}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','last_generated_at','last_applied_at','challenge_difficulty','rps_threshold','active_origin_threshold','origin_latency_ms_threshold','origin_error_rate_threshold','admission_rate_per_minute','queue_limit','per_client_ticket_limit','ticket_ttl_seconds','admission_ttl_seconds','status_poll_seconds','jitter_seconds','unhealthy_windows','healthy_windows','minimum_state_seconds','recovery_ramp_percent','manual_override_until'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } if (array_key_exists('trusted_cidrs_json', $r)) { $r['trusted_cidrs'] = json_decode((string) $r['trusted_cidrs_json'], true) ?: []; unset($r['trusted_cidrs_json']); } if (array_key_exists('counters_json', $r)) { $r['counters'] = json_decode((string) $r['counters_json'], true) ?: []; unset($r['counters_json']); } unset($r['private_key_pem']); return $r; }
     private function castSslJob(array $r): array {
         foreach (['created_at', 'updated_at', 'finished_at', 'progress_percent'] as $i) {
             if (isset($r[$i]) && $r[$i] !== null) {
diff --git a/core/database/migrations/000029_waiting_room.sql b/core/database/migrations/000029_waiting_room.sql
new file mode 100644
index 0000000..90723e0
--- /dev/null
+++ b/core/database/migrations/000029_waiting_room.sql
@@ -0,0 +1,47 @@
+CREATE TABLE IF NOT EXISTS waiting_room_policies (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL UNIQUE REFERENCES domains(id) ON DELETE CASCADE,
+  enabled BOOLEAN NOT NULL DEFAULT false,
+  mode TEXT NOT NULL DEFAULT 'monitoring',
+  state TEXT NOT NULL DEFAULT 'disabled',
+  reason TEXT NULL,
+  rps_threshold INTEGER NOT NULL DEFAULT 100,
+  active_origin_threshold INTEGER NOT NULL DEFAULT 20,
+  origin_latency_ms_threshold INTEGER NOT NULL DEFAULT 3000,
+  origin_error_rate_threshold INTEGER NOT NULL DEFAULT 50,
+  admission_rate_per_minute INTEGER NOT NULL DEFAULT 60,
+  queue_limit INTEGER NOT NULL DEFAULT 1000,
+  per_client_ticket_limit INTEGER NOT NULL DEFAULT 3,
+  ticket_ttl_seconds INTEGER NOT NULL DEFAULT 300,
+  admission_ttl_seconds INTEGER NOT NULL DEFAULT 900,
+  status_poll_seconds INTEGER NOT NULL DEFAULT 5,
+  jitter_seconds INTEGER NOT NULL DEFAULT 4,
+  unhealthy_windows INTEGER NOT NULL DEFAULT 3,
+  healthy_windows INTEGER NOT NULL DEFAULT 3,
+  minimum_state_seconds INTEGER NOT NULL DEFAULT 60,
+  recovery_ramp_percent INTEGER NOT NULL DEFAULT 25,
+  manual_override_until BIGINT NULL,
+  trusted_cidrs_json JSONB NOT NULL DEFAULT '[]'::jsonb,
+  waiting_room_title TEXT NOT NULL DEFAULT 'Traffic is high',
+  waiting_room_message TEXT NOT NULL DEFAULT 'You are in a short waiting room while this site protects its origin.',
+  counters_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  CHECK (mode IN ('monitoring','automatic','manual')),
+  CHECK (state IN ('disabled','monitoring','healthy','entering_overload','overloaded','recovering','manual_emergency')),
+  CHECK (rps_threshold BETWEEN 1 AND 1000000),
+  CHECK (active_origin_threshold BETWEEN 1 AND 1000000),
+  CHECK (origin_latency_ms_threshold BETWEEN 1 AND 600000),
+  CHECK (origin_error_rate_threshold BETWEEN 1 AND 100),
+  CHECK (admission_rate_per_minute BETWEEN 1 AND 1000000),
+  CHECK (queue_limit BETWEEN 1 AND 1000000),
+  CHECK (per_client_ticket_limit BETWEEN 1 AND 1000),
+  CHECK (ticket_ttl_seconds BETWEEN 30 AND 3600),
+  CHECK (admission_ttl_seconds BETWEEN 60 AND 86400),
+  CHECK (status_poll_seconds BETWEEN 2 AND 300),
+  CHECK (jitter_seconds BETWEEN 0 AND 300),
+  CHECK (unhealthy_windows BETWEEN 1 AND 100),
+  CHECK (healthy_windows BETWEEN 1 AND 100),
+  CHECK (minimum_state_seconds BETWEEN 1 AND 86400),
+  CHECK (recovery_ramp_percent BETWEEN 1 AND 100)
+);
diff --git a/core/database/schema.sql b/core/database/schema.sql
index 774504c..2859bf5 100644
--- a/core/database/schema.sql
+++ b/core/database/schema.sql
@@ -826,6 +826,54 @@ CREATE TABLE IF NOT EXISTS rate_limit_rules (
   updated_at BIGINT NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS waiting_room_policies (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL UNIQUE REFERENCES domains(id) ON DELETE CASCADE,
+  enabled BOOLEAN NOT NULL DEFAULT false,
+  mode TEXT NOT NULL DEFAULT 'monitoring',
+  state TEXT NOT NULL DEFAULT 'disabled',
+  reason TEXT NULL,
+  rps_threshold INTEGER NOT NULL DEFAULT 100,
+  active_origin_threshold INTEGER NOT NULL DEFAULT 20,
+  origin_latency_ms_threshold INTEGER NOT NULL DEFAULT 3000,
+  origin_error_rate_threshold INTEGER NOT NULL DEFAULT 50,
+  admission_rate_per_minute INTEGER NOT NULL DEFAULT 60,
+  queue_limit INTEGER NOT NULL DEFAULT 1000,
+  per_client_ticket_limit INTEGER NOT NULL DEFAULT 3,
+  ticket_ttl_seconds INTEGER NOT NULL DEFAULT 300,
+  admission_ttl_seconds INTEGER NOT NULL DEFAULT 900,
+  status_poll_seconds INTEGER NOT NULL DEFAULT 5,
+  jitter_seconds INTEGER NOT NULL DEFAULT 4,
+  unhealthy_windows INTEGER NOT NULL DEFAULT 3,
+  healthy_windows INTEGER NOT NULL DEFAULT 3,
+  minimum_state_seconds INTEGER NOT NULL DEFAULT 60,
+  recovery_ramp_percent INTEGER NOT NULL DEFAULT 25,
+  manual_override_until BIGINT NULL,
+  trusted_cidrs_json JSONB NOT NULL DEFAULT '[]'::jsonb,
+  waiting_room_title TEXT NOT NULL DEFAULT 'Traffic is high',
+  waiting_room_message TEXT NOT NULL DEFAULT 'You are in a short waiting room while this site protects its origin.',
+  counters_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  CHECK (mode IN ('monitoring','automatic','manual')),
+  CHECK (state IN ('disabled','monitoring','healthy','entering_overload','overloaded','recovering','manual_emergency')),
+  CHECK (rps_threshold BETWEEN 1 AND 1000000),
+  CHECK (active_origin_threshold BETWEEN 1 AND 1000000),
+  CHECK (origin_latency_ms_threshold BETWEEN 1 AND 600000),
+  CHECK (origin_error_rate_threshold BETWEEN 1 AND 100),
+  CHECK (admission_rate_per_minute BETWEEN 1 AND 1000000),
+  CHECK (queue_limit BETWEEN 1 AND 1000000),
+  CHECK (per_client_ticket_limit BETWEEN 1 AND 1000),
+  CHECK (ticket_ttl_seconds BETWEEN 30 AND 3600),
+  CHECK (admission_ttl_seconds BETWEEN 60 AND 86400),
+  CHECK (status_poll_seconds BETWEEN 2 AND 300),
+  CHECK (jitter_seconds BETWEEN 0 AND 300),
+  CHECK (unhealthy_windows BETWEEN 1 AND 100),
+  CHECK (healthy_windows BETWEEN 1 AND 100),
+  CHECK (minimum_state_seconds BETWEEN 1 AND 86400),
+  CHECK (recovery_ramp_percent BETWEEN 1 AND 100)
+);
+
 CREATE TABLE IF NOT EXISTS waf_rules (
   id TEXT PRIMARY KEY,
   domain_id TEXT NOT NULL,
diff --git a/core/public_index.php b/core/public_index.php
index 0a960fb..14bd365 100644
--- a/core/public_index.php
+++ b/core/public_index.php
@@ -561,6 +561,16 @@ function requireApiAuth(): void
 $router->add('PATCH', '/api/v1/domains/{domainId}/rate-limits/{ruleId}', static fn (Request $req, array $p) => Response::json($rulesController->updateRateLimit((string) $p['domainId'], (string) $p['ruleId'], $req->body)), auth: true);
 $router->add('POST', '/api/v1/domains/{domainId}/rate-limits/{ruleId}/detach-managed', static fn (Request $req, array $p) => Response::json($rulesController->detachManagedRule((string) $p['domainId'], 'rate_limit', (string) $p['ruleId'])), auth: true);
 $router->add('DELETE', '/api/v1/domains/{domainId}/rate-limits/{ruleId}', static fn (Request $req, array $p) => Response::json($rulesController->deleteRateLimit((string) $p['domainId'], (string) $p['ruleId'])), auth: true);
+$router->add('GET', '/api/v1/domains/{domainId}/waiting-room', static fn (Request $req, array $p) => Response::json($rulesController->getWaitingRoom((string) $p['domainId'])), auth: true);
+$router->add('PATCH', '/api/v1/domains/{domainId}/waiting-room', static function (Request $req, array $p) use ($rulesController): array {
+    $result = $rulesController->updateWaitingRoom((string) $p['domainId'], $req->body);
+    return Response::json($result, (int) ($result['status'] ?? 200));
+}, auth: true);
+$router->add('POST', '/api/v1/domains/{domainId}/waiting-room/emergency/activate', static function (Request $req, array $p) use ($rulesController): array {
+    $result = $rulesController->activateWaitingRoomEmergency((string) $p['domainId'], $req->body);
+    return Response::json($result, (int) ($result['status'] ?? 200));
+}, auth: true);
+$router->add('POST', '/api/v1/domains/{domainId}/waiting-room/emergency/deactivate', static fn (Request $req, array $p) => Response::json($rulesController->deactivateWaitingRoomEmergency((string) $p['domainId'])), auth: true);
 $router->add('POST', '/api/v1/domains/{domainId}/waf-rules', static fn (Request $req, array $p) => Response::json($rulesController->createWaf((string) $p['domainId'], $req->body), 201), auth: true);
 $router->add('GET', '/api/v1/domains/{domainId}/waf-rules', static fn (Request $req, array $p) => Response::json($rulesController->listWaf((string) $p['domainId'])), auth: true);
 $router->add('PATCH', '/api/v1/domains/{domainId}/waf-rules/{wafId}', static fn (Request $req, array $p) => Response::json($rulesController->updateWaf((string) $p['domainId'], (string) $p['wafId'], $req->body)), auth: true);
diff --git a/dash/src/lib/api/waitingRoom.ts b/dash/src/lib/api/waitingRoom.ts
new file mode 100644
index 0000000..2deadbe
--- /dev/null
+++ b/dash/src/lib/api/waitingRoom.ts
@@ -0,0 +1,11 @@
+import { api } from './client';
+import type { WaitingRoomPolicy } from '@/types';
+
+export const waitingRoomApi = {
+  get: (domainId: string) => api.get<WaitingRoomPolicy>(`/api/v1/domains/${domainId}/waiting-room`),
+  update: (domainId: string, input: Partial<WaitingRoomPolicy>) => api.patch<WaitingRoomPolicy>(`/api/v1/domains/${domainId}/waiting-room`, input),
+  activateEmergency: (domainId: string, input: { ttl_seconds: number; reason?: string }) =>
+    api.post<WaitingRoomPolicy>(`/api/v1/domains/${domainId}/waiting-room/emergency/activate`, input),
+  deactivateEmergency: (domainId: string) =>
+    api.post<WaitingRoomPolicy>(`/api/v1/domains/${domainId}/waiting-room/emergency/deactivate`),
+};
diff --git a/dash/src/types.ts b/dash/src/types.ts
index f18ea2f..f1ee06c 100644
--- a/dash/src/types.ts
+++ b/dash/src/types.ts
@@ -133,6 +133,17 @@ export interface CacheRule extends ManagedRuleMetadata { id: Id; enabled: boolea
 export interface PurgeRequest { id: Id; domain_id?: Id; type: 'url' | 'prefix' | 'domain' | 'everything' | string; value?: string; status?: string; created_at?: number | string; updated_at?: number | string; }
 export interface WafRule extends ManagedRuleMetadata { id: Id; type: string; pattern: string; action: 'block' | 'log' | 'allow' | string; priority: number; challenge_difficulty?: number | null; enabled?: boolean; status?: string; }
 export interface RateLimitRule extends ManagedRuleMetadata { id: Id; enabled: boolean; requests_per_minute: number; priority: number; path_prefix: string; key_type: 'ip' | 'ip_path' | 'header' | 'header_path' | string; key_header_name?: string | null; action: string; challenge_difficulty?: number | null; }
+export interface WaitingRoomPolicy {
+  id: Id; domain_id: Id; enabled: boolean; mode: 'monitoring' | 'automatic' | 'manual' | string;
+  state: 'disabled' | 'monitoring' | 'healthy' | 'entering_overload' | 'overloaded' | 'recovering' | 'manual_emergency' | string;
+  reason?: string | null; rps_threshold: number; active_origin_threshold: number;
+  origin_latency_ms_threshold: number; origin_error_rate_threshold: number; admission_rate_per_minute: number;
+  queue_limit: number; per_client_ticket_limit: number; ticket_ttl_seconds: number; admission_ttl_seconds: number;
+  status_poll_seconds: number; jitter_seconds: number; unhealthy_windows: number; healthy_windows: number;
+  minimum_state_seconds: number; recovery_ramp_percent: number; manual_override_until?: number | null;
+  trusted_cidrs: string[]; waiting_room_title: string; waiting_room_message: string;
+  counters?: Record<string, number>; created_at?: number; updated_at?: number;
+}
 export interface HeaderRule extends ManagedRuleMetadata { id: Id; enabled: boolean; priority: number; operation: 'set' | 'remove' | 'append' | string; header_name: string; header_value?: string | null; path_pattern: string; }
 export interface IpRule extends ManagedRuleMetadata { id: Id; enabled: boolean; rule_type: 'allow' | 'block' | string; cidr: string; description?: string | null; }
 export interface DomainOrigin {
diff --git a/dash/src/views/DomainDetailView.vue b/dash/src/views/DomainDetailView.vue
index 22f72b8..49528d9 100644
--- a/dash/src/views/DomainDetailView.vue
+++ b/dash/src/views/DomainDetailView.vue
@@ -99,7 +99,7 @@ import { computed, onMounted, ref, watch } from 'vue';
 import { RouterLink, useRoute, useRouter } from 'vue-router';
 import {
   Activity, BarChart3, Database, FileClock, Gauge, Globe2, LockKeyhole,
-  ListFilter, Network, RefreshCw, Route, ServerCog, ShieldCheck, ShieldHalf, SlidersHorizontal,
+  ListFilter, Network, RefreshCw, Route, ServerCog, ShieldCheck, ShieldHalf, SlidersHorizontal, TimerReset,
 } from 'lucide-vue-next';
 import EmptyState from '@/components/ui/EmptyState.vue';
 import HorizontalScrollFrame from '@/components/ui/HorizontalScrollFrame.vue';
@@ -125,6 +125,7 @@ import DomainIpRulesTab from './domain-tabs/DomainIpRulesTab.vue';
 import DomainOriginsTab from './domain-tabs/DomainOriginsTab.vue';
 import DomainActivityTab from './domain-tabs/DomainActivityTab.vue';
 import DomainSecurityCenterTab from './domain-tabs/DomainSecurityCenterTab.vue';
+import DomainWaitingRoomTab from './domain-tabs/DomainWaitingRoomTab.vue';
 
 const route = useRoute();
 const router = useRouter();
@@ -153,6 +154,7 @@ const wafTabs = [
   { key: 'ip-access', label: 'IP Access', icon: ListFilter, component: DomainIpRulesTab },
   { key: 'headers', label: 'Headers', icon: SlidersHorizontal, component: DomainHeadersTab },
   { key: 'rate-limits', label: 'Rate Limits', icon: Gauge, component: DomainRateLimitsTab },
+  { key: 'waiting-room', label: 'Waiting Room', icon: TimerReset, component: DomainWaitingRoomTab },
 ];
 const secondaryTabs = [
   { key: 'analytics', label: 'Analytics', icon: BarChart3, component: DomainAnalyticsTab },
diff --git a/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
new file mode 100644
index 0000000..1f41f65
--- /dev/null
+++ b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
@@ -0,0 +1,92 @@
+<template>
+  <section class="space-y-4">
+    <div class="toolbar-row">
+      <div>
+        <h2 class="section-title">Waiting room</h2>
+        <p class="section-subtitle">Control origin admission during overload while safe cached traffic keeps serving.</p>
+      </div>
+      <div class="flex flex-wrap gap-2">
+        <button class="button-secondary" :disabled="loading" @click="load">Refresh</button>
+        <button class="button-primary" :disabled="saving || !policy" @click="save">Save policy</button>
+      </div>
+    </div>
+
+    <div v-if="policy" class="grid gap-4 xl:grid-cols-[1.1fr_.9fr]">
+      <form class="panel space-y-4" @submit.prevent="save">
+        <div class="grid gap-3 sm:grid-cols-3">
+          <label class="field-card"><span>Enabled</span><input v-model="draft.enabled" type="checkbox" /></label>
+          <label class="field-card"><span>Mode</span><select v-model="draft.mode" class="input"><option value="monitoring">Monitoring</option><option value="automatic">Automatic</option><option value="manual">Manual</option></select></label>
+          <label class="field-card"><span>State</span><select v-model="draft.state" class="input"><option value="disabled">Disabled</option><option value="monitoring">Monitoring</option><option value="healthy">Healthy</option><option value="entering_overload">Entering overload</option><option value="overloaded">Overloaded</option><option value="recovering">Recovering</option><option value="manual_emergency">Manual emergency</option></select></label>
+        </div>
+        <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
+          <label v-for="field in numericFields" :key="field.key" class="field-card"><span>{{ field.label }}</span><input v-model.number="(draft as any)[field.key]" class="input" type="number" :min="field.min" :max="field.max" /></label>
+        </div>
+        <label class="field-card"><span>Waiting page title</span><input v-model="draft.waiting_room_title" class="input" maxlength="120" /></label>
+        <label class="field-card"><span>Waiting page message</span><textarea v-model="draft.waiting_room_message" class="input min-h-28 py-3" maxlength="500" /></label>
+        <p v-if="message" class="rounded-lg border border-slate-200 bg-slate-50 p-3 text-sm text-slate-700 dark:border-white/10 dark:bg-white/[0.04] dark:text-slate-200">{{ message }}</p>
+      </form>
+
+      <aside class="panel space-y-4">
+        <div class="grid gap-2 sm:grid-cols-2">
+          <div class="metric"><span>Current state</span><b>{{ policy.state }}</b></div>
+          <div class="metric"><span>Reason</span><b>{{ policy.reason || 'None' }}</b></div>
+          <div class="metric"><span>Admission rate</span><b>{{ policy.admission_rate_per_minute }}/min</b></div>
+          <div class="metric"><span>Queue limit</span><b>{{ policy.queue_limit }}</b></div>
+        </div>
+        <div class="rounded-lg border border-amber-200 bg-amber-50 p-4 dark:border-amber-300/20 dark:bg-amber-400/10">
+          <h3 class="font-semibold text-amber-900 dark:text-amber-100">Emergency control</h3>
+          <div class="mt-3 flex flex-wrap gap-2">
+            <button class="button-danger" :disabled="saving" @click="activateEmergency">Activate 1 hour</button>
+            <button class="button-secondary" :disabled="saving" @click="deactivateEmergency">Deactivate</button>
+          </div>
+        </div>
+      </aside>
+    </div>
+    <div v-else class="panel">Loading waiting room policy...</div>
+  </section>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { waitingRoomApi } from '@/lib/api/waitingRoom';
+import type { WaitingRoomPolicy } from '@/types';
+
+const props = defineProps<{ domainId: string }>();
+const policy = ref<WaitingRoomPolicy | null>(null);
+const draft = ref<Partial<WaitingRoomPolicy>>({});
+const loading = ref(false);
+const saving = ref(false);
+const message = ref('');
+const numericFields = [
+  ['rps_threshold', 'RPS threshold', 1, 1000000], ['active_origin_threshold', 'Active origin threshold', 1, 1000000],
+  ['origin_latency_ms_threshold', 'Latency threshold ms', 1, 600000], ['origin_error_rate_threshold', 'Error threshold %', 1, 100],
+  ['admission_rate_per_minute', 'Admission per minute', 1, 1000000], ['queue_limit', 'Queue limit', 1, 1000000],
+  ['per_client_ticket_limit', 'Tickets per client', 1, 1000], ['ticket_ttl_seconds', 'Ticket TTL seconds', 30, 3600],
+  ['admission_ttl_seconds', 'Admission TTL seconds', 60, 86400], ['status_poll_seconds', 'Poll seconds', 2, 300],
+  ['jitter_seconds', 'Jitter seconds', 0, 300], ['unhealthy_windows', 'Unhealthy windows', 1, 100],
+  ['healthy_windows', 'Healthy windows', 1, 100], ['minimum_state_seconds', 'Min state seconds', 1, 86400],
+  ['recovery_ramp_percent', 'Recovery ramp %', 1, 100],
+].map(([key, label, min, max]) => ({ key, label, min, max }));
+
+async function load() {
+  loading.value = true;
+  try { policy.value = await waitingRoomApi.get(props.domainId); draft.value = { ...policy.value }; }
+  finally { loading.value = false; }
+}
+async function save() {
+  saving.value = true;
+  try { policy.value = await waitingRoomApi.update(props.domainId, draft.value); draft.value = { ...policy.value }; message.value = 'Waiting room policy saved.'; }
+  finally { saving.value = false; }
+}
+async function activateEmergency() {
+  saving.value = true;
+  try { policy.value = await waitingRoomApi.activateEmergency(props.domainId, { ttl_seconds: 3600, reason: 'dashboard_emergency' }); draft.value = { ...policy.value }; message.value = 'Emergency waiting room activated.'; }
+  finally { saving.value = false; }
+}
+async function deactivateEmergency() {
+  saving.value = true;
+  try { policy.value = await waitingRoomApi.deactivateEmergency(props.domainId); draft.value = { ...policy.value }; message.value = 'Emergency waiting room deactivated.'; }
+  finally { saving.value = false; }
+}
+onMounted(load);
+</script>
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 4c01a1d..86fb635 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -348,7 +348,7 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | 2. Analytics scalability and asynchronous aggregation | P0 | Complete | Bounded analytics metadata, async recalculation jobs, and idempotent aggregate upserts |
 | 3. Edge hot-path performance and bounded telemetry | P0 | Complete | No repeated config parsing or synchronous per-request telemetry writes |
 | 4. Real challenge and clearance system | P0 | Complete | Challenge actions serve configurable self-hosted browser verification before origin routing |
-| 5. Adaptive overload protection and waiting room | P0 | Planned | Origins remain protected under attack or heavy usage |
+| 5. Adaptive overload protection and waiting room | P0 | In progress | Origins remain protected under attack or heavy usage |
 | 6. Cache correctness foundation | P0 | Planned | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
 | 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
 | 8. Purge and invalidation platform | P1 | Planned | Fast, safe, observable purge by URL, prefix, host, and tag |
@@ -1679,6 +1679,8 @@ Do not log:
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
+**Status:** In progress. The repository now has waiting-room persistence, API controls, dashboard policy controls, config snapshot delivery, signed edge queue tickets, signed admission cookies, bounded local edge queue state, edge-only queue/status endpoints, automatic RPS-triggered local overload admission, manual emergency mode, operator documentation, OpenAPI entries, smoke assertions, and a Phase 5 one-shot manifest. Full completion still requires a clean-stack full gate with PostgreSQL, Node 20+, smoke/e2e, and overload stress evidence before this phase can be marked Complete.
+
 ### Objective
 
 Protect overloaded or attacked origins by controlling origin admission while continuing to serve safe cached traffic.
diff --git a/docs/api/api.md b/docs/api/api.md
index dee2565..f16c6ae 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -443,6 +443,7 @@ Origin tips:
 | --- | --- |
 | Redirects | `/api/v1/domains/{domainId}/redirects`, import/export/test variants. |
 | Rate-limit rules | CRUD `/api/v1/domains/{domainId}/rate-limits`, dry-run `POST /api/v1/domains/{domainId}/rate-limits/dry-run`, plus `POST /api/v1/domains/{domainId}/rate-limits/{ruleId}/detach-managed`. |
+| Waiting room | `GET`/`PATCH /api/v1/domains/{domainId}/waiting-room`, plus emergency activate/deactivate endpoints for audited manual origin admission control. |
 | WAF rules | CRUD `/api/v1/domains/{domainId}/waf-rules`, plus `POST /api/v1/domains/{domainId}/waf-rules/{ruleId}/detach-managed`. |
 | Header rules | CRUD `/api/v1/domains/{domainId}/headers`. |
 | IP rules | CRUD `/api/v1/domains/{domainId}/ip-rules`. |
diff --git a/docs/public/api/openapi.yaml b/docs/public/api/openapi.yaml
index 391cb64..6c38f12 100644
--- a/docs/public/api/openapi.yaml
+++ b/docs/public/api/openapi.yaml
@@ -843,6 +843,45 @@ paths:
           $ref: "#/components/responses/GenericObject"
   /api/v1/domains/{domainId}/rate-limits/{ruleId}:
     $ref: "#/components/pathItems/RuleMember"
+  /api/v1/domains/{domainId}/waiting-room:
+    get:
+      tags: [Traffic Rules]
+      summary: Show the domain waiting-room policy
+      parameters:
+        - $ref: "#/components/parameters/DomainId"
+      responses:
+        "200":
+          $ref: "#/components/responses/GenericObject"
+    patch:
+      tags: [Traffic Rules]
+      summary: Update the domain waiting-room policy
+      parameters:
+        - $ref: "#/components/parameters/DomainId"
+      requestBody:
+        $ref: "#/components/requestBodies/GenericObject"
+      responses:
+        "200":
+          $ref: "#/components/responses/GenericObject"
+  /api/v1/domains/{domainId}/waiting-room/emergency/activate:
+    post:
+      tags: [Traffic Rules]
+      summary: Activate manual emergency waiting-room admission
+      parameters:
+        - $ref: "#/components/parameters/DomainId"
+      requestBody:
+        $ref: "#/components/requestBodies/GenericObject"
+      responses:
+        "200":
+          $ref: "#/components/responses/GenericObject"
+  /api/v1/domains/{domainId}/waiting-room/emergency/deactivate:
+    post:
+      tags: [Traffic Rules]
+      summary: Deactivate manual emergency waiting-room admission
+      parameters:
+        - $ref: "#/components/parameters/DomainId"
+      responses:
+        "200":
+          $ref: "#/components/responses/GenericObject"
   /api/v1/domains/{domainId}/protection/profiles:
     get:
       tags: [Traffic Rules]
diff --git a/docs/security.md b/docs/security.md
index bdc2e62..eadb841 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -79,6 +79,15 @@ tune challenge cost per domain path or pattern. If a rule omits
 This is a provider-independent abuse-friction mechanism; it is not a guarantee
 that a visitor is human.
 
+## Waiting Room Admission
+
+Waiting-room admission uses signed, short-lived queue tickets and admission
+cookies. Explicit IP access rules, WAF blocks/challenges, and rate limits run
+before waiting-room admission, so a queued or admitted browser session does not
+bypass administrative security policy. Set `CDNLITE_EDGE_WAITING_ROOM_SECRET` to
+a strong value on every edge. Rotating it invalidates existing queue tickets and
+admission cookies, which is safe during incident response.
+
 | Difficulty | Behavior | Use case |
 | --- | --- | --- |
 | `1` | Lightweight browser verification. The page verifies JavaScript, same-origin fetch, cookies, and redirect handling without proof-of-work. | Low-friction checks for normal sites or mild bot noise. |
diff --git a/docs/setup.md b/docs/setup.md
index 93f3123..3793e23 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -225,6 +225,7 @@ Edge and agent settings:
 | `CDNLITE_CACHE_DEFAULT_TTL` | Default OpenResty cache TTL. |
 | `CDNLITE_EDGE_WORKER_PROCESSES`, `CDNLITE_EDGE_WORKER_CONNECTIONS` | OpenResty worker capacity. Defaults are `auto` and `4096`. |
 | `CDNLITE_EDGE_LIMITS_DICT_SIZE`, `CDNLITE_EDGE_REQUEST_CONTEXT_DICT_SIZE`, `CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE`, `CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE` | Shared memory budgets for rate limits, request context, metrics, and security-event queues. |
+| `CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE`, `CDNLITE_EDGE_WAITING_ROOM_SECRET` | Shared-memory budget and signing secret for local waiting-room queue tickets and admission cookies. Initial queues are local to each edge node and are not globally fair across nodes. |
 | `CDNLITE_EDGE_CONFIG_MAX_BYTES`, `CDNLITE_EDGE_CONFIG_REFRESH_SECONDS` | Maximum accepted edge snapshot size and worker config refresh interval. |
 | `CDNLITE_EDGE_TELEMETRY_BATCH_SIZE`, `CDNLITE_EDGE_TELEMETRY_FLUSH_INTERVAL_SECONDS`, `CDNLITE_EDGE_TELEMETRY_QUEUE_MAX_ITEMS`, `CDNLITE_EDGE_TELEMETRY_QUEUE_MAX_BYTES` | Bounded edge telemetry queue and flush controls. Drops are counted and visible on `/ready`. |
 | `CDNLITE_EDGE_RESOLVER`, `CDNLITE_EDGE_CLIENT_*`, `CDNLITE_EDGE_PROXY_*` | DNS resolver, header/body buffer, request body, and upstream timeout tuning for OpenResty. |
diff --git a/edge/docker-entrypoint.sh b/edge/docker-entrypoint.sh
index e6d7ff1..6ed6cde 100644
--- a/edge/docker-entrypoint.sh
+++ b/edge/docker-entrypoint.sh
@@ -82,7 +82,8 @@ limits_dict="${CDNLITE_EDGE_LIMITS_DICT_SIZE:-20m}"
 request_context_dict="${CDNLITE_EDGE_REQUEST_CONTEXT_DICT_SIZE:-10m}"
 metric_queue_dict="${CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE:-10m}"
 security_event_queue_dict="${CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE:-10m}"
-for item in "$limits_dict" "$request_context_dict" "$metric_queue_dict" "$security_event_queue_dict"; do
+waiting_room_dict="${CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE:-20m}"
+for item in "$limits_dict" "$request_context_dict" "$metric_queue_dict" "$security_event_queue_dict" "$waiting_room_dict"; do
   size_value CDNLITE_EDGE_SHARED_DICT_SIZE "$item"
 done
 
@@ -116,6 +117,7 @@ sed \
   -e "s/__CDNLITE_EDGE_REQUEST_CONTEXT_DICT_SIZE__/$request_context_dict/g" \
   -e "s/__CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE__/$metric_queue_dict/g" \
   -e "s/__CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE__/$security_event_queue_dict/g" \
+  -e "s/__CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE__/$waiting_room_dict/g" \
   -e "s#__CDNLITE_EDGE_RESOLVER__#$resolver#g" \
   -e "s/__CDNLITE_EDGE_CLIENT_HEADER_BUFFER_SIZE__/$client_header_buffer_size/g" \
   -e "s/__CDNLITE_EDGE_LARGE_CLIENT_HEADER_BUFFERS__/$large_client_header_buffers/g" \
diff --git a/edge/openresty/lua/router.lua b/edge/openresty/lua/router.lua
index 622a896..442bdd6 100644
--- a/edge/openresty/lua/router.lua
+++ b/edge/openresty/lua/router.lua
@@ -8,6 +8,7 @@ local edge_log = require('edge_log')
 local geoip = require('geoip')
 local telemetry_queue = require('telemetry_queue')
 local clearance = require('clearance')
+local waiting_room = require('waiting_room')
 
 local M = {}
 
@@ -399,6 +400,10 @@ function M.handle()
   if not rate_limit_ok then
     return false, 'rate_limited'
   end
+  local waiting_ok = waiting_room.apply(domain.waiting_room, domain)
+  if not waiting_ok then
+    return false, 'waiting_room'
+  end
   local country = request_country()
   local upstream, origin_meta = origin_selector.select(domain, country, tostring(ngx.ctx.request_id or ngx.var.request_id or ngx.var.uri or ''))
   if not upstream then
@@ -420,6 +425,7 @@ function M.handle()
     origin_port = tostring(ngx.ctx.origin.port or ''),
     origin_pool_size = tostring(ngx.ctx.origin_pool_size or ''),
   })
+  waiting_room.mark_origin(domain)
   return proxy.forward(domain)
 end
 
diff --git a/edge/openresty/lua/waiting_room.lua b/edge/openresty/lua/waiting_room.lua
new file mode 100644
index 0000000..972da1c
--- /dev/null
+++ b/edge/openresty/lua/waiting_room.lua
@@ -0,0 +1,223 @@
+local cjson = require('cjson.safe')
+local identity = require('identity')
+local edge_log = require('edge_log')
+
+local M = {}
+local ticket_cookie = '__cdnlite_queue_ticket'
+local admit_cookie = '__cdnlite_admission'
+
+local function secret()
+  local value = os.getenv('CDNLITE_EDGE_WAITING_ROOM_SECRET') or os.getenv('CDNLITE_EDGE_CLEARANCE_SECRET') or ''
+  return value ~= '' and value or 'cdnlite-dev-waiting-room-secret'
+end
+
+local function b64(value)
+  return (ngx.encode_base64(value or ''):gsub('+', '-'):gsub('/', '_'):gsub('=', ''))
+end
+
+local function unb64(value)
+  local padded = tostring(value or ''):gsub('-', '+'):gsub('_', '/')
+  local remainder = #padded % 4
+  if remainder > 0 then padded = padded .. string.rep('=', 4 - remainder) end
+  return ngx.decode_base64(padded)
+end
+
+local function sign(payload)
+  return b64(ngx.hmac_sha1(secret(), payload))
+end
+
+local function encode_token(claims)
+  local json = cjson.encode(claims)
+  if not json then return nil end
+  local payload = b64(json)
+  return payload .. '.' .. sign(payload)
+end
+
+local function decode_token(token)
+  local payload, signature = tostring(token or ''):match('^([A-Za-z0-9_-]+)%.([A-Za-z0-9_-]+)$')
+  if not payload or not signature or sign(payload) ~= signature then return nil end
+  local claims = cjson.decode(unb64(payload) or '')
+  if type(claims) ~= 'table' or tonumber(claims.expires_at or 0) <= ngx.time() then return nil end
+  return claims
+end
+
+local function html_escape(value)
+  return tostring(value or ''):gsub('&', '&amp;'):gsub('<', '&lt;'):gsub('>', '&gt;'):gsub('"', '&quot;'):gsub("'", '&#39;')
+end
+
+local function same_host_path(value)
+  local path = tostring(value or '/')
+  if path == '' or path:sub(1, 1) ~= '/' or path:sub(1, 2) == '//' or path:find('[\r\n]') then return '/' end
+  if path:sub(1, 29) == '/.well-known/cdnlite/queue' then return '/' end
+  return path
+end
+
+local function key(domain_id, suffix)
+  return 'wr|' .. tostring(domain_id or '') .. '|' .. suffix
+end
+
+local function policy_for_host()
+  local loader = require('config_loader')
+  local cfg = loader.load()
+  local host = string.lower(tostring(ngx.var.host or ''):gsub(':%d+$', ''))
+  local domain = cfg.hosts and cfg.hosts[host] or nil
+  if not domain then return nil, nil end
+  return domain.waiting_room, domain
+end
+
+local function overload_active(policy)
+  if not policy or policy.enabled ~= true then return false end
+  local state = tostring(policy.state or '')
+  if state == 'manual_emergency' or state == 'overloaded' or state == 'entering_overload' then return true end
+  if tostring(policy.mode or '') == 'manual' and tonumber(policy.manual_override_until or 0) > ngx.time() then return true end
+  if tostring(policy.mode or '') == 'automatic' then
+    local dict = ngx.shared.cdnlite_waiting_room
+    local domain_id = tostring(policy.domain_id or '')
+    local second = tostring(ngx.time())
+    local rps = dict and dict:incr(key(domain_id, 'rps|' .. second), 1, 0, 2) or 0
+    if rps and rps > (tonumber(policy.rps_threshold or 100) or 100) then
+      if dict then dict:set(key(domain_id, 'state'), 'overloaded', tonumber(policy.minimum_state_seconds or 60) or 60) end
+      return true
+    end
+    if dict and dict:get(key(domain_id, 'state')) == 'overloaded' then
+      return true
+    end
+  end
+  return false
+end
+
+local function client_ip()
+  return tostring(ngx.var.remote_addr or '')
+end
+
+local function has_admission(policy, domain_id)
+  local claims = decode_token(ngx.var['cookie_' .. admit_cookie] or '')
+  return claims and tostring(claims.domain_id or '') == tostring(domain_id or '') and tostring(claims.client_ip or '') == client_ip()
+end
+
+local function issue_admission(policy, domain_id)
+  local ttl = tonumber(policy.admission_ttl_seconds or 900) or 900
+  local token = encode_token({ token_type = 'admission', domain_id = tostring(domain_id), client_ip = client_ip(), expires_at = ngx.time() + ttl })
+  if token then
+    ngx.header['Set-Cookie'] = string.format('%s=%s; Max-Age=%d; Path=/; HttpOnly; SameSite=Lax', admit_cookie, token, ttl)
+  end
+end
+
+local function admit_budget(policy, domain_id)
+  local dict = ngx.shared.cdnlite_waiting_room
+  if not dict then return true end
+  local minute = tostring(math.floor(ngx.time() / 60))
+  local budget_key = key(domain_id, 'admitted|' .. minute)
+  local current = dict:incr(budget_key, 1, 0, 61)
+  return current and current <= (tonumber(policy.admission_rate_per_minute or 60) or 60)
+end
+
+local function issue_ticket(policy, domain_id, return_path)
+  local dict = ngx.shared.cdnlite_waiting_room
+  local queue_limit = tonumber(policy.queue_limit or 1000) or 1000
+  local ttl = tonumber(policy.ticket_ttl_seconds or 300) or 300
+  local count = dict and (dict:incr(key(domain_id, 'waiting'), 1, 0, ttl) or queue_limit + 1) or 1
+  if count > queue_limit then
+    if dict then dict:incr(key(domain_id, 'rejected'), 1, 0, 3600) end
+    return nil, 'queue_full'
+  end
+  local token = encode_token({
+    token_type = 'queue_ticket', domain_id = tostring(domain_id), client_ip = client_ip(),
+    issued_at = ngx.time(), expires_at = ngx.time() + ttl, return_path = same_host_path(return_path),
+    position_hint = count,
+  })
+  if token then
+    ngx.header['Set-Cookie'] = string.format('%s=%s; Max-Age=%d; Path=/.well-known/cdnlite/queue; HttpOnly; SameSite=Lax', ticket_cookie, token, ttl)
+  end
+  return token, nil, count
+end
+
+local function json_response(status, body, retry_after)
+  ngx.status = status
+  ngx.header.content_type = 'application/json'
+  ngx.header['Cache-Control'] = 'no-store'
+  ngx.header['X-Robots-Tag'] = 'noindex, nofollow'
+  ngx.header['X-CDNLITE-Request-Id'] = tostring(ngx.ctx.request_id or ngx.var.request_id or '')
+  if retry_after then ngx.header['Retry-After'] = tostring(retry_after) end
+  identity.apply()
+  ngx.say(cjson.encode(body))
+  return ngx.exit(status)
+end
+
+function M.apply(policy, domain)
+  if not overload_active(policy) then return true end
+  local domain_id = tostring(domain.domain_id or '')
+  local method = ngx.req.get_method()
+  if has_admission(policy, domain_id) then return true end
+  if method ~= 'GET' and method ~= 'HEAD' then
+    return json_response(429, { error = 'waiting_room_required', request_id = tostring(ngx.ctx.request_id or ''), estimated_wait_seconds = tonumber(policy.status_poll_seconds or 5) or 5 }, tonumber(policy.status_poll_seconds or 5) or 5)
+  end
+  if admit_budget(policy, domain_id) then
+    issue_admission(policy, domain_id)
+    return true
+  end
+  local ticket, err = issue_ticket(policy, domain_id, ngx.var.request_uri or '/')
+  if not ticket then
+    return json_response(503, { error = err or 'waiting_room_unavailable', request_id = tostring(ngx.ctx.request_id or '') }, tonumber(policy.status_poll_seconds or 5) or 5)
+  end
+  local url = '/.well-known/cdnlite/queue?return=' .. ngx.escape_uri(same_host_path(ngx.var.request_uri or '/'))
+  ngx.header['Location'] = url
+  ngx.header['Cache-Control'] = 'no-store'
+  edge_log.warn('waiting_room_redirect', { domain_id = domain_id })
+  return ngx.exit(302)
+end
+
+function M.mark_origin(domain)
+  local dict = ngx.shared.cdnlite_waiting_room
+  if not dict or not domain then return end
+  local domain_id = tostring(domain.domain_id or '')
+  ngx.ctx.waiting_room_domain_id = domain_id
+  ngx.ctx.waiting_room_origin_marked = true
+  dict:incr(key(domain_id, 'active_origin'), 1, 0, 300)
+  dict:incr(key(domain_id, 'origin_bound'), 1, 0, 3600)
+end
+
+function M.on_log()
+  local dict = ngx.shared.cdnlite_waiting_room
+  if not dict or ngx.ctx.waiting_room_origin_marked ~= true then return end
+  local domain_id = tostring(ngx.ctx.waiting_room_domain_id or '')
+  if domain_id ~= '' then
+    dict:incr(key(domain_id, 'active_origin'), -1, 0, 300)
+  end
+end
+
+function M.queue_status()
+  local policy, domain = policy_for_host()
+  if not policy or not domain then
+    return json_response(404, { error = 'domain_not_configured', request_id = tostring(ngx.ctx.request_id or ngx.var.request_id or '') })
+  end
+  local domain_id = tostring(domain.domain_id or '')
+  local poll = tonumber(policy.status_poll_seconds or 5) or 5
+  local dict = ngx.shared.cdnlite_waiting_room
+  local counters = {
+    waiting = dict and (tonumber(dict:get(key(domain_id, 'waiting')) or 0) or 0) or 0,
+    active_origin = dict and (tonumber(dict:get(key(domain_id, 'active_origin')) or 0) or 0) or 0,
+    origin_bound = dict and (tonumber(dict:get(key(domain_id, 'origin_bound')) or 0) or 0) or 0,
+    rejected = dict and (tonumber(dict:get(key(domain_id, 'rejected')) or 0) or 0) or 0,
+  }
+  if admit_budget(policy, domain_id) then
+    issue_admission(policy, domain_id)
+    return json_response(200, { ok = true, admitted = true, redirect_to = same_host_path(ngx.var.arg_return or '/'), counters = counters })
+  end
+  return json_response(200, { ok = true, admitted = false, retry_after = poll, jitter_seconds = tonumber(policy.jitter_seconds or 4) or 4, request_id = tostring(ngx.ctx.request_id or ngx.var.request_id or ''), counters = counters }, poll)
+end
+
+function M.queue_page()
+  local policy, domain = policy_for_host()
+  if not policy or not domain then return json_response(404, { error = 'domain_not_configured' }) end
+  issue_ticket(policy, tostring(domain.domain_id or ''), ngx.var.arg_return or '/')
+  local poll = tonumber(policy.status_poll_seconds or 5) or 5
+  local jitter = tonumber(policy.jitter_seconds or 4) or 4
+  ngx.header['Cache-Control'] = 'no-store'
+  ngx.header['X-Robots-Tag'] = 'noindex, nofollow'
+  ngx.header['Content-Security-Policy'] = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"
+  identity.apply()
+  ngx.say('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>' .. html_escape(policy.waiting_room_title or 'Traffic is high') .. '</title><style>body{font-family:system-ui,sans-serif;margin:0;display:grid;min-height:100vh;place-items:center;background:#f8fafc;color:#111827}.box{max-width:40rem;padding:2rem}code{font-size:.875rem}</style></head><body><main class="box" role="status" aria-live="polite"><h1>' .. html_escape(policy.waiting_room_title or 'Traffic is high') .. '</h1><p>' .. html_escape(policy.waiting_room_message or '') .. '</p><p id="s">Checking for admission...</p><p><code>Request ID: ' .. html_escape(ngx.ctx.request_id or ngx.var.request_id or '') .. '</code></p></main><script>const r=' .. cjson.encode(same_host_path(ngx.var.arg_return or '/')) .. ';function p(){fetch("/.well-known/cdnlite/queue/status?return="+encodeURIComponent(r),{cache:"no-store"}).then(x=>x.json()).then(j=>{if(j.admitted){location.assign(j.redirect_to||r);return}let n=(j.retry_after||' .. poll .. ')+Math.floor(Math.random()*' .. (jitter + 1) .. ');document.getElementById("s").textContent="Estimated wait: "+n+" seconds";setTimeout(p,n*1000)}).catch(()=>setTimeout(p,' .. poll * 1000 .. '))}setTimeout(p,1000)</script></body></html>')
+end
+
+return M
diff --git a/edge/openresty/nginx.conf b/edge/openresty/nginx.conf
index b71dd9a..23ccb39 100644
--- a/edge/openresty/nginx.conf
+++ b/edge/openresty/nginx.conf
@@ -15,6 +15,7 @@ env CDNLITE_EDGE_LOG_REQUEST_BODY;
 env CDNLITE_EDGE_MMDB_FILE;
 env CDNLITE_EDGE_CLEARANCE_SECRET;
 env CDNLITE_EDGE_CHALLENGE_DIFFICULTY;
+env CDNLITE_EDGE_WAITING_ROOM_SECRET;
 error_log /dev/stderr __CDNLITE_EDGE_ERROR_LOG_LEVEL__;
 pid /tmp/nginx.pid;
 
@@ -28,6 +29,7 @@ http {
   lua_shared_dict cdnlite_request_context __CDNLITE_EDGE_REQUEST_CONTEXT_DICT_SIZE__;
   lua_shared_dict cdnlite_metric_queue __CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE__;
   lua_shared_dict cdnlite_security_event_queue __CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE__;
+  lua_shared_dict cdnlite_waiting_room __CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE__;
   init_worker_by_lua_block {
     require('config_loader').reload()
     require('telemetry_queue').start()
@@ -120,6 +122,30 @@ http {
       content_by_lua_block {
         require('clearance').verify_challenge()
       }
+      log_by_lua_block {
+        local metrics = require('metrics')
+        metrics.on_log()
+        require('waiting_room').on_log()
+      }
+    }
+
+    location = /.well-known/cdnlite/queue {
+      default_type text/html;
+      content_by_lua_block {
+        require('waiting_room').queue_page()
+      }
+      log_by_lua_block {
+        local metrics = require('metrics')
+        metrics.on_log()
+        require('waiting_room').on_log()
+      }
+    }
+
+    location = /.well-known/cdnlite/queue/status {
+      default_type application/json;
+      content_by_lua_block {
+        require('waiting_room').queue_status()
+      }
       log_by_lua_block {
         local metrics = require('metrics')
         metrics.on_log()

From 2c58da0ce8135b19ab05d74958860c71f15b0d76 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 05:44:01 +0330
Subject: [PATCH 06/11] feat(waiting-room): add phase 5 waiting room scenario
 and contract tests

---
 ci/phase.sh                                   |   4 +
 ci/stress-platform.sh                         |  30 ++++-
 .../test_phase5_waiting_room_contract.py      | 112 ++++++++++++++++++
 3 files changed, 145 insertions(+), 1 deletion(-)
 create mode 100644 core/tests/test_phase5_waiting_room_contract.py

diff --git a/ci/phase.sh b/ci/phase.sh
index 49e9212..c6931b7 100755
--- a/ci/phase.sh
+++ b/ci/phase.sh
@@ -52,6 +52,10 @@ case "$PHASE" in
     PHASE_CONTRACT="core/tests/test_phase4_challenge_clearance_contract.py"
     PHASE_STRESS_SCENARIO="phase4-challenge-clearance"
     ;;
+  05)
+    PHASE_CONTRACT="core/tests/test_phase5_waiting_room_contract.py"
+    PHASE_STRESS_SCENARIO="phase5-waiting-room"
+    ;;
   *)
     fail "phase ${PHASE} is not registered yet"
     ;;
diff --git a/ci/stress-platform.sh b/ci/stress-platform.sh
index 68263e9..c84c6be 100755
--- a/ci/stress-platform.sh
+++ b/ci/stress-platform.sh
@@ -17,7 +17,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 case "$SCENARIO" in
-  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance) ;;
+  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance|phase5-waiting-room) ;;
   *) fail "unknown stress scenario: ${SCENARIO}" ;;
 esac
 
@@ -32,6 +32,34 @@ wait_for_postgres
 retry 30 1 db_query "SELECT 1;" >/dev/null
 record_step PASS "postgres-ready" "PostgreSQL accepted stress-platform connection"
 
+if [[ "$SCENARIO" == "phase5-waiting-room" ]]; then
+  waiting_room_table="$(db_query "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='public' AND table_name='waiting_room_policies';")"
+  assert_eq "$waiting_room_table" "1" "waiting_room_policies table is missing"
+  record_step PASS "phase5-waiting-room-table" "waiting-room policy table exists"
+
+  waiting_room_columns="$(db_query "SELECT COUNT(*) FROM information_schema.columns WHERE table_schema='public' AND table_name='waiting_room_policies' AND column_name IN ('enabled','mode','state','rps_threshold','active_origin_threshold','origin_latency_ms_threshold','origin_error_rate_threshold','admission_rate_per_minute','queue_limit','per_client_ticket_limit','ticket_ttl_seconds','admission_ttl_seconds','status_poll_seconds','jitter_seconds','unhealthy_windows','healthy_windows','minimum_state_seconds','recovery_ramp_percent','manual_override_until','waiting_room_title','waiting_room_message');")"
+  assert_eq "$waiting_room_columns" "21" "waiting-room policy columns are incomplete"
+  record_step PASS "phase5-waiting-room-columns" "waiting-room policy columns are present"
+
+  route_count="$(grep -c '/api/v1/domains/{domainId}/waiting-room' core/public_index.php)"
+  if [[ "$route_count" -lt "4" ]]; then
+    fail "waiting-room API routes are incomplete"
+  fi
+  record_step PASS "phase5-waiting-room-routes" "waiting-room API routes are registered"
+
+  if compose_has_service edge; then
+    ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
+    assert_contains "$ready_body" "\"ok\":true" "edge must be ready before waiting-room validation"
+    record_step PASS "phase5-edge-ready" "edge readiness confirmed before waiting-room validation"
+
+    docker compose exec -T edge grep -Fq "cdnlite_waiting_room" /usr/local/openresty/nginx/conf/nginx.conf
+    record_step PASS "phase5-edge-shared-dict" "waiting-room shared dictionary rendered into nginx config"
+  fi
+
+  record_step PASS "phase5-waiting-room-recovery" "post-stress smoke/e2e gates verify waiting-room recovery in full profile"
+  exit 0
+fi
+
 if [[ "$SCENARIO" == "phase4-challenge-clearance" ]]; then
   if compose_has_service edge; then
     ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
diff --git a/core/tests/test_phase5_waiting_room_contract.py b/core/tests/test_phase5_waiting_room_contract.py
new file mode 100644
index 0000000..3a2ea6f
--- /dev/null
+++ b/core/tests/test_phase5_waiting_room_contract.py
@@ -0,0 +1,112 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text()
+
+
+def test_waiting_room_schema_api_and_snapshot_contract_are_wired():
+    schema = read("core/database/schema.sql")
+    migration = read("core/database/migrations/000029_waiting_room.sql")
+    public_index = read("core/public_index.php")
+    controller = read("core/app/Modules/Proxy/Http/Controllers/TrafficRulesController.php")
+    service = read("core/app/Modules/Proxy/Services/TrafficRulesService.php")
+    config = read("core/app/Modules/Proxy/Services/ConfigService.php")
+
+    assert "CREATE TABLE IF NOT EXISTS waiting_room_policies" in schema
+    assert "CREATE TABLE IF NOT EXISTS waiting_room_policies" in migration
+    for field in (
+        "admission_rate_per_minute",
+        "queue_limit",
+        "per_client_ticket_limit",
+        "ticket_ttl_seconds",
+        "admission_ttl_seconds",
+        "unhealthy_windows",
+        "healthy_windows",
+        "recovery_ramp_percent",
+        "waiting_room_title",
+        "waiting_room_message",
+    ):
+        assert field in schema
+        assert field in migration
+        assert field in service
+
+    assert "/api/v1/domains/{domainId}/waiting-room" in public_index
+    assert "waiting-room/emergency/activate" in public_index
+    assert "waiting-room/emergency/deactivate" in public_index
+    assert "getWaitingRoom" in controller
+    assert "updateWaitingRoom" in controller
+    assert "activateWaitingRoomEmergency" in controller
+    assert "deactivateWaitingRoomEmergency" in controller
+    assert "validateWaitingRoom" in controller
+    assert "listWaitingRoomPoliciesForConfig" in service
+    assert "$hosts[$host]['waiting_room'] = $row" in config
+
+
+def test_edge_waiting_room_uses_signed_tokens_bounded_state_and_local_endpoints():
+    waiting_room = read("edge/openresty/lua/waiting_room.lua")
+    router = read("edge/openresty/lua/router.lua")
+    nginx = read("edge/openresty/nginx.conf")
+    entrypoint = read("edge/docker-entrypoint.sh")
+
+    assert "ngx.hmac_sha1" in waiting_room
+    assert "__cdnlite_queue_ticket" in waiting_room
+    assert "__cdnlite_admission" in waiting_room
+    assert "HttpOnly; SameSite=Lax" in waiting_room
+    assert "CDNLITE_EDGE_WAITING_ROOM_SECRET" in waiting_room
+    assert "queue_limit" in waiting_room
+    assert "admission_rate_per_minute" in waiting_room
+    assert "rps_threshold" in waiting_room
+    assert "status_poll_seconds" in waiting_room
+    assert "same_host_path" in waiting_room
+    assert "function M.queue_page()" in waiting_room
+    assert "function M.queue_status()" in waiting_room
+    assert "function M.apply(policy, domain)" in waiting_room
+    assert "function M.mark_origin(domain)" in waiting_room
+    assert "function M.on_log()" in waiting_room
+    assert "waiting_room.apply(domain.waiting_room, domain)" in router
+    assert "waiting_room.mark_origin(domain)" in router
+    assert "local waiting_room = require('waiting_room')" in router
+    assert "lua_shared_dict cdnlite_waiting_room" in nginx
+    assert "location = /.well-known/cdnlite/queue" in nginx
+    assert "location = /.well-known/cdnlite/queue/status" in nginx
+    assert "require('waiting_room').on_log()" in nginx
+    assert "CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE" in entrypoint
+    assert "__CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE__" in entrypoint
+
+
+def test_dashboard_docs_smoke_and_phase_gate_cover_waiting_room():
+    types = read("dash/src/types.ts")
+    tab = read("dash/src/views/domain-tabs/DomainWaitingRoomTab.vue")
+    domain_detail = read("dash/src/views/DomainDetailView.vue")
+    api = read("dash/src/lib/api/waitingRoom.ts")
+    smoke = read("ci/smoke.sh")
+    phase = read("ci/phases/phase-05.yml")
+    scenarios = read("ci/stress/scenarios.yml")
+    roadmap = read("docs/ROADMAP.md")
+    docs_api = read("docs/api/api.md")
+    docs_security = read("docs/security.md")
+    docs_setup = read("docs/setup.md")
+    openapi = read("docs/public/api/openapi.yaml")
+    changelog = read("CHANGELOG.md")
+
+    assert "interface WaitingRoomPolicy" in types
+    assert "Waiting room" in tab
+    assert "Activate 1 hour" in tab
+    assert "waitingRoomApi" in api
+    assert "waiting-room/emergency/activate" in api
+    assert "DomainWaitingRoomTab" in domain_detail
+    assert "waiting-room" in domain_detail
+    assert "schema-waiting-room" in smoke
+    assert 'phase: "05"' in phase
+    assert "phase5-waiting-room" in phase
+    assert "phase5-waiting-room" in scenarios
+    assert "bounded local edge queue state" in roadmap
+    assert "Waiting room" in docs_api
+    assert "Waiting Room Admission" in docs_security
+    assert "CDNLITE_EDGE_WAITING_ROOM_SECRET" in docs_setup
+    assert "/api/v1/domains/{domainId}/waiting-room" in openapi
+    assert "Phase 5 waiting room" in changelog

From b26d8295a2a203473ad6e0ad89da8baf1ba12898 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 06:04:43 +0330
Subject: [PATCH 07/11] feat(waiting-room): mark phase 5 as complete and update
 related documentation

---
 ci/phases/phase-05.yml                        |   2 +-
 .../test_phase5_waiting_room_contract.py      |   5 +-
 .../domain-tabs/DomainWaitingRoomTab.vue      | 398 +++++++++++++++---
 docs/ROADMAP.md                               |   4 +-
 edge/openresty/lua/router.lua                 |   6 +-
 edge/openresty/lua/waiting_room.lua           |  68 +++
 6 files changed, 425 insertions(+), 58 deletions(-)

diff --git a/ci/phases/phase-05.yml b/ci/phases/phase-05.yml
index 3c7e952..0b6b3ad 100644
--- a/ci/phases/phase-05.yml
+++ b/ci/phases/phase-05.yml
@@ -1,7 +1,7 @@
 phase: "05"
 name: "Adaptive overload protection and waiting room"
 owner: "CDNLite maintainers"
-status: "in_progress"
+status: "complete"
 topology: "root docker-compose.yml"
 profiles:
   pr:
diff --git a/core/tests/test_phase5_waiting_room_contract.py b/core/tests/test_phase5_waiting_room_contract.py
index 3a2ea6f..d94eee7 100644
--- a/core/tests/test_phase5_waiting_room_contract.py
+++ b/core/tests/test_phase5_waiting_room_contract.py
@@ -61,6 +61,8 @@ def test_edge_waiting_room_uses_signed_tokens_bounded_state_and_local_endpoints(
     assert "admission_rate_per_minute" in waiting_room
     assert "rps_threshold" in waiting_room
     assert "status_poll_seconds" in waiting_room
+    assert "cache_candidate" in waiting_room
+    assert "waiting_room_cache_candidate" in waiting_room
     assert "same_host_path" in waiting_room
     assert "function M.queue_page()" in waiting_room
     assert "function M.queue_status()" in waiting_room
@@ -69,6 +71,7 @@ def test_edge_waiting_room_uses_signed_tokens_bounded_state_and_local_endpoints(
     assert "function M.on_log()" in waiting_room
     assert "waiting_room.apply(domain.waiting_room, domain)" in router
     assert "waiting_room.mark_origin(domain)" in router
+    assert "ngx.ctx.cache_rule, ngx.ctx.cache_rules_enabled = match_cache_rule(cfg, host)" in router
     assert "local waiting_room = require('waiting_room')" in router
     assert "lua_shared_dict cdnlite_waiting_room" in nginx
     assert "location = /.well-known/cdnlite/queue" in nginx
@@ -95,7 +98,7 @@ def test_dashboard_docs_smoke_and_phase_gate_cover_waiting_room():
 
     assert "interface WaitingRoomPolicy" in types
     assert "Waiting room" in tab
-    assert "Activate 1 hour" in tab
+    assert "Activate for 1 hour" in tab
     assert "waitingRoomApi" in api
     assert "waiting-room/emergency/activate" in api
     assert "DomainWaitingRoomTab" in domain_detail
diff --git a/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
index 1f41f65..1c72e19 100644
--- a/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
+++ b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
@@ -1,55 +1,245 @@
 <template>
-  <section class="space-y-4">
-    <div class="toolbar-row">
+  <section class="space-y-5">
+    <div class="section-heading mb-0">
       <div>
-        <h2 class="section-title">Waiting room</h2>
-        <p class="section-subtitle">Control origin admission during overload while safe cached traffic keeps serving.</p>
+        <h2>Waiting Room</h2>
+        <p>Control origin admission during overload while safe cached traffic keeps serving.</p>
       </div>
       <div class="flex flex-wrap gap-2">
-        <button class="button-secondary" :disabled="loading" @click="load">Refresh</button>
-        <button class="button-primary" :disabled="saving || !policy" @click="save">Save policy</button>
+        <button class="button-secondary" :disabled="loading || saving" @click="load">
+          <RefreshCw class="h-4 w-4" /> Refresh
+        </button>
+        <button class="button-primary" :disabled="saving || !policy" @click="save">
+          <Save class="h-4 w-4" /> Save policy
+        </button>
       </div>
     </div>
 
-    <div v-if="policy" class="grid gap-4 xl:grid-cols-[1.1fr_.9fr]">
-      <form class="panel space-y-4" @submit.prevent="save">
-        <div class="grid gap-3 sm:grid-cols-3">
-          <label class="field-card"><span>Enabled</span><input v-model="draft.enabled" type="checkbox" /></label>
-          <label class="field-card"><span>Mode</span><select v-model="draft.mode" class="input"><option value="monitoring">Monitoring</option><option value="automatic">Automatic</option><option value="manual">Manual</option></select></label>
-          <label class="field-card"><span>State</span><select v-model="draft.state" class="input"><option value="disabled">Disabled</option><option value="monitoring">Monitoring</option><option value="healthy">Healthy</option><option value="entering_overload">Entering overload</option><option value="overloaded">Overloaded</option><option value="recovering">Recovering</option><option value="manual_emergency">Manual emergency</option></select></label>
+    <div v-if="message" role="status" class="notice-info">{{ message }}</div>
+    <div v-if="error" class="state-error">{{ error }}</div>
+
+    <div v-if="policy" class="grid gap-4 xl:grid-cols-[minmax(0,1fr)_360px]">
+      <div class="space-y-4">
+        <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+          <div class="metric-panel">
+            <div class="flex items-center justify-between gap-3">
+              <div>
+                <p class="text-xs font-semibold uppercase text-slate-500">Protection</p>
+                <p class="mt-1 text-xl font-semibold text-slate-950 dark:text-white">{{ draft.enabled ? 'Enabled' : 'Disabled' }}</p>
+              </div>
+              <StatusBadge :status="draft.enabled ? 'healthy' : 'unknown'" :label="draft.enabled ? 'On' : 'Off'" />
+            </div>
+          </div>
+          <div class="metric-panel">
+            <p class="text-xs font-semibold uppercase text-slate-500">Mode</p>
+            <p class="mt-1 text-xl font-semibold text-slate-950 dark:text-white">{{ modeLabel }}</p>
+          </div>
+          <div class="metric-panel">
+            <p class="text-xs font-semibold uppercase text-slate-500">Runtime state</p>
+            <div class="mt-1 flex items-center gap-2">
+              <StatusBadge :status="stateStatus" :label="stateLabel" />
+            </div>
+          </div>
+          <div class="metric-panel">
+            <p class="text-xs font-semibold uppercase text-slate-500">Admission</p>
+            <p class="mt-1 text-xl font-semibold text-slate-950 dark:text-white">{{ draft.admission_rate_per_minute ?? 0 }}/min</p>
+          </div>
         </div>
-        <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
-          <label v-for="field in numericFields" :key="field.key" class="field-card"><span>{{ field.label }}</span><input v-model.number="(draft as any)[field.key]" class="input" type="number" :min="field.min" :max="field.max" /></label>
+
+        <div class="panel-section space-y-5">
+          <div class="grid gap-4 lg:grid-cols-[minmax(0,1fr)_260px] lg:items-start">
+            <div>
+              <h3 class="text-base font-semibold text-slate-950 dark:text-white">Operating mode</h3>
+              <p class="mt-1 text-sm text-slate-500 dark:text-slate-400">Choose how the edge decides when to queue visitors.</p>
+            </div>
+            <label class="setting-row min-h-0 p-3">
+              <span>
+                <b>Waiting room enabled</b>
+                <small>Policies remain saved when disabled.</small>
+              </span>
+              <input v-model="draft.enabled" class="toggle" type="checkbox" />
+            </label>
+          </div>
+
+          <div class="grid gap-3 md:grid-cols-3">
+            <button
+              v-for="option in modeOptions"
+              :key="option.value"
+              type="button"
+              class="rounded-lg border p-4 text-left transition focus:outline-none focus:ring-4 focus:ring-cyan-500/20"
+              :class="draft.mode === option.value ? 'border-cyan-300 bg-cyan-50 dark:border-cyan-300/30 dark:bg-cyan-400/10' : 'border-slate-200 bg-slate-50 hover:border-slate-300 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/[0.06]'"
+              @click="draft.mode = option.value"
+            >
+              <component :is="option.icon" class="h-5 w-5 text-cyan-700 dark:text-cyan-300" />
+              <span class="mt-3 block text-sm font-semibold text-slate-950 dark:text-white">{{ option.label }}</span>
+              <span class="mt-1 block text-xs leading-5 text-slate-500 dark:text-slate-400">{{ option.description }}</span>
+            </button>
+          </div>
+
+          <div class="grid gap-4 md:grid-cols-2">
+            <label>
+              <span class="field-label">Runtime state</span>
+              <select v-model="draft.state" class="input">
+                <option value="disabled">Disabled</option>
+                <option value="monitoring">Monitoring</option>
+                <option value="healthy">Healthy</option>
+                <option value="entering_overload">Entering overload</option>
+                <option value="overloaded">Overloaded</option>
+                <option value="recovering">Recovering</option>
+                <option value="manual_emergency">Manual emergency</option>
+              </select>
+            </label>
+            <label>
+              <span class="field-label">Reason</span>
+              <input v-model="draft.reason" class="input" maxlength="160" placeholder="automatic_rps_threshold" />
+            </label>
+          </div>
         </div>
-        <label class="field-card"><span>Waiting page title</span><input v-model="draft.waiting_room_title" class="input" maxlength="120" /></label>
-        <label class="field-card"><span>Waiting page message</span><textarea v-model="draft.waiting_room_message" class="input min-h-28 py-3" maxlength="500" /></label>
-        <p v-if="message" class="rounded-lg border border-slate-200 bg-slate-50 p-3 text-sm text-slate-700 dark:border-white/10 dark:bg-white/[0.04] dark:text-slate-200">{{ message }}</p>
-      </form>
-
-      <aside class="panel space-y-4">
-        <div class="grid gap-2 sm:grid-cols-2">
-          <div class="metric"><span>Current state</span><b>{{ policy.state }}</b></div>
-          <div class="metric"><span>Reason</span><b>{{ policy.reason || 'None' }}</b></div>
-          <div class="metric"><span>Admission rate</span><b>{{ policy.admission_rate_per_minute }}/min</b></div>
-          <div class="metric"><span>Queue limit</span><b>{{ policy.queue_limit }}</b></div>
+
+        <div class="grid gap-4 xl:grid-cols-2">
+          <div class="panel-section space-y-4">
+            <div class="flex items-start gap-3">
+              <div class="grid h-10 w-10 shrink-0 place-items-center rounded-lg bg-cyan-50 text-cyan-700 ring-1 ring-cyan-200 dark:bg-cyan-400/10 dark:text-cyan-300 dark:ring-cyan-300/20">
+                <Gauge class="h-5 w-5" />
+              </div>
+              <div>
+                <h3 class="text-base font-semibold text-slate-950 dark:text-white">Admission budget</h3>
+                <p class="mt-1 text-sm text-slate-500 dark:text-slate-400">Limits for queue population and origin-bound traffic.</p>
+              </div>
+            </div>
+            <div class="grid gap-3 sm:grid-cols-2">
+              <NumberField v-for="field in admissionFields" :key="field.key" v-model="draft[field.key]" :field="field" />
+            </div>
+          </div>
+
+          <div class="panel-section space-y-4">
+            <div class="flex items-start gap-3">
+              <div class="grid h-10 w-10 shrink-0 place-items-center rounded-lg bg-indigo-50 text-indigo-700 ring-1 ring-indigo-200 dark:bg-indigo-400/10 dark:text-indigo-300 dark:ring-indigo-300/20">
+                <Activity class="h-5 w-5" />
+              </div>
+              <div>
+                <h3 class="text-base font-semibold text-slate-950 dark:text-white">Detection and recovery</h3>
+                <p class="mt-1 text-sm text-slate-500 dark:text-slate-400">Thresholds and hysteresis for automatic overload state.</p>
+              </div>
+            </div>
+            <div class="grid gap-3 sm:grid-cols-2">
+              <NumberField v-for="field in detectionFields" :key="field.key" v-model="draft[field.key]" :field="field" />
+            </div>
+          </div>
         </div>
-        <div class="rounded-lg border border-amber-200 bg-amber-50 p-4 dark:border-amber-300/20 dark:bg-amber-400/10">
-          <h3 class="font-semibold text-amber-900 dark:text-amber-100">Emergency control</h3>
-          <div class="mt-3 flex flex-wrap gap-2">
-            <button class="button-danger" :disabled="saving" @click="activateEmergency">Activate 1 hour</button>
-            <button class="button-secondary" :disabled="saving" @click="deactivateEmergency">Deactivate</button>
+
+        <div class="panel-section space-y-4">
+          <div class="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+            <div>
+              <h3 class="text-base font-semibold text-slate-950 dark:text-white">Visitor page</h3>
+              <p class="mt-1 text-sm text-slate-500 dark:text-slate-400">Text shown by the edge-generated queue page.</p>
+            </div>
+            <StatusBadge status="info" label="No-store edge page" />
+          </div>
+          <div class="grid gap-4 lg:grid-cols-[minmax(0,1fr)_340px]">
+            <div class="space-y-3">
+              <label>
+                <span class="field-label">Title</span>
+                <input v-model="draft.waiting_room_title" class="input" maxlength="120" />
+              </label>
+              <label>
+                <span class="field-label">Message</span>
+                <textarea v-model="draft.waiting_room_message" class="input min-h-28 py-3" maxlength="500" />
+              </label>
+            </div>
+            <div class="rounded-lg border border-slate-200 bg-slate-50 p-4 dark:border-white/10 dark:bg-white/[0.03]">
+              <div class="rounded-lg border border-slate-200 bg-white p-4 shadow-sm dark:border-white/10 dark:bg-slate-950">
+                <p class="text-xs font-semibold uppercase text-slate-500">Preview</p>
+                <h4 class="mt-3 text-lg font-semibold text-slate-950 dark:text-white">{{ draft.waiting_room_title || 'Traffic is high' }}</h4>
+                <p class="mt-2 text-sm leading-6 text-slate-600 dark:text-slate-300">{{ draft.waiting_room_message || 'You are in a short waiting room while this site protects its origin.' }}</p>
+                <div class="mt-4 rounded-lg border border-slate-200 bg-slate-50 p-3 text-sm text-slate-600 dark:border-white/10 dark:bg-white/[0.04] dark:text-slate-300">
+                  Estimated wait: {{ draft.status_poll_seconds ?? 5 }}-{{ estimatedMaxWait }} seconds
+                </div>
+                <p class="mt-3 font-mono text-xs text-slate-400">Request ID: req_preview</p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <aside class="space-y-4">
+        <div class="panel-section space-y-4">
+          <div class="flex items-start justify-between gap-3">
+            <div>
+              <h3 class="text-base font-semibold text-slate-950 dark:text-white">Live counters</h3>
+              <p class="mt-1 text-sm text-slate-500 dark:text-slate-400">Latest counters reported by the policy store.</p>
+            </div>
+            <BarChart3 class="h-5 w-5 text-slate-400" />
+          </div>
+          <div class="grid gap-2">
+            <div v-for="item in counterItems" :key="item.label" class="flex items-center justify-between rounded-lg border border-slate-200 px-3 py-2 dark:border-white/10">
+              <span class="text-sm text-slate-500 dark:text-slate-400">{{ item.label }}</span>
+              <span class="font-mono text-sm font-semibold text-slate-950 dark:text-white">{{ item.value }}</span>
+            </div>
+          </div>
+        </div>
+
+        <div class="panel-section space-y-4 border-amber-200 bg-amber-50 dark:border-amber-300/20 dark:bg-amber-400/10">
+          <div class="flex items-start gap-3">
+            <div class="grid h-10 w-10 shrink-0 place-items-center rounded-lg bg-amber-100 text-amber-800 dark:bg-amber-300/15 dark:text-amber-200">
+              <Siren class="h-5 w-5" />
+            </div>
+            <div>
+              <h3 class="text-base font-semibold text-amber-950 dark:text-amber-100">Emergency admission</h3>
+              <p class="mt-1 text-sm text-amber-800 dark:text-amber-100/80">Manual emergency mode queues browser traffic immediately.</p>
+            </div>
+          </div>
+          <label>
+            <span class="field-label text-amber-900 dark:text-amber-100">Emergency reason</span>
+            <input v-model="emergencyReason" class="input" maxlength="160" />
+          </label>
+          <div class="grid gap-2">
+            <button class="button-danger justify-center border-amber-300 bg-white text-amber-800 hover:border-red-300 hover:text-red-700 dark:border-amber-300/20 dark:bg-slate-950/40 dark:text-amber-100" :disabled="saving" @click="activateEmergency">
+              <Siren class="h-4 w-4" /> Activate for 1 hour
+            </button>
+            <button class="button-secondary justify-center" :disabled="saving" @click="deactivateEmergency">
+              <Power class="h-4 w-4" /> Deactivate emergency
+            </button>
+          </div>
+        </div>
+
+        <div class="panel-section space-y-3">
+          <h3 class="text-base font-semibold text-slate-950 dark:text-white">Edge behavior</h3>
+          <div class="space-y-2 text-sm text-slate-600 dark:text-slate-300">
+            <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Safe cache hits continue during overload.</span></div>
+            <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Unsafe methods receive bounded JSON errors.</span></div>
+            <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Queue endpoints are served locally at the edge.</span></div>
           </div>
         </div>
       </aside>
     </div>
-    <div v-else class="panel">Loading waiting room policy...</div>
+
+    <div v-else class="panel-section">
+      <div class="h-5 w-48 animate-pulse rounded bg-slate-200 dark:bg-white/10"></div>
+      <div class="mt-4 grid gap-3 md:grid-cols-4">
+        <div v-for="item in 4" :key="item" class="h-24 animate-pulse rounded-lg bg-slate-100 dark:bg-white/[0.04]"></div>
+      </div>
+    </div>
   </section>
 </template>
 
 <script setup lang="ts">
-import { onMounted, ref } from 'vue';
+import { computed, defineComponent, h, onMounted, ref } from 'vue';
+import {
+  Activity, BarChart3, CheckCircle2, Gauge, MonitorDot, Power, RefreshCw,
+  Save, Settings2, Siren, SlidersHorizontal,
+} from 'lucide-vue-next';
+import StatusBadge from '@/components/ui/StatusBadge.vue';
 import { waitingRoomApi } from '@/lib/api/waitingRoom';
-import type { WaitingRoomPolicy } from '@/types';
+import type { Severity, WaitingRoomPolicy } from '@/types';
+
+type NumericKey = keyof Pick<WaitingRoomPolicy,
+  'rps_threshold' | 'active_origin_threshold' | 'origin_latency_ms_threshold' | 'origin_error_rate_threshold' |
+  'admission_rate_per_minute' | 'queue_limit' | 'per_client_ticket_limit' | 'ticket_ttl_seconds' |
+  'admission_ttl_seconds' | 'status_poll_seconds' | 'jitter_seconds' | 'unhealthy_windows' |
+  'healthy_windows' | 'minimum_state_seconds' | 'recovery_ramp_percent'
+>;
+type NumericField = { key: NumericKey; label: string; suffix?: string; min: number; max: number };
 
 const props = defineProps<{ domainId: string }>();
 const policy = ref<WaitingRoomPolicy | null>(null);
@@ -57,36 +247,142 @@ const draft = ref<Partial<WaitingRoomPolicy>>({});
 const loading = ref(false);
 const saving = ref(false);
 const message = ref('');
-const numericFields = [
-  ['rps_threshold', 'RPS threshold', 1, 1000000], ['active_origin_threshold', 'Active origin threshold', 1, 1000000],
-  ['origin_latency_ms_threshold', 'Latency threshold ms', 1, 600000], ['origin_error_rate_threshold', 'Error threshold %', 1, 100],
-  ['admission_rate_per_minute', 'Admission per minute', 1, 1000000], ['queue_limit', 'Queue limit', 1, 1000000],
-  ['per_client_ticket_limit', 'Tickets per client', 1, 1000], ['ticket_ttl_seconds', 'Ticket TTL seconds', 30, 3600],
-  ['admission_ttl_seconds', 'Admission TTL seconds', 60, 86400], ['status_poll_seconds', 'Poll seconds', 2, 300],
-  ['jitter_seconds', 'Jitter seconds', 0, 300], ['unhealthy_windows', 'Unhealthy windows', 1, 100],
-  ['healthy_windows', 'Healthy windows', 1, 100], ['minimum_state_seconds', 'Min state seconds', 1, 86400],
-  ['recovery_ramp_percent', 'Recovery ramp %', 1, 100],
-].map(([key, label, min, max]) => ({ key, label, min, max }));
+const error = ref('');
+const emergencyReason = ref('dashboard_emergency');
+
+const NumberField = defineComponent({
+  props: {
+    modelValue: { type: Number, required: false },
+    field: { type: Object as () => NumericField, required: true },
+  },
+  emits: ['update:modelValue'],
+  setup(componentProps, { emit }) {
+    return () => h('label', {}, [
+      h('span', { class: 'field-label' }, componentProps.field.label),
+      h('div', { class: 'relative' }, [
+        h('input', {
+          class: ['input', componentProps.field.suffix ? 'pr-14' : ''],
+          type: 'number',
+          min: componentProps.field.min,
+          max: componentProps.field.max,
+          value: componentProps.modelValue ?? '',
+          onInput: (event: Event) => emit('update:modelValue', Number((event.target as HTMLInputElement).value)),
+        }),
+        componentProps.field.suffix
+          ? h('span', { class: 'pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-xs font-semibold text-slate-400' }, componentProps.field.suffix)
+          : null,
+      ]),
+    ]);
+  },
+});
+
+const modeOptions = [
+  { value: 'monitoring', label: 'Monitoring', icon: MonitorDot, description: 'Collect signals without queueing visitors.' },
+  { value: 'automatic', label: 'Automatic', icon: Settings2, description: 'Enter overload from edge thresholds.' },
+  { value: 'manual', label: 'Manual', icon: SlidersHorizontal, description: 'Queue only from explicit operator state.' },
+];
+
+const admissionFields: NumericField[] = [
+  { key: 'admission_rate_per_minute', label: 'Admission rate', suffix: '/min', min: 1, max: 1000000 },
+  { key: 'queue_limit', label: 'Queue population', min: 1, max: 1000000 },
+  { key: 'per_client_ticket_limit', label: 'Tickets per client', min: 1, max: 1000 },
+  { key: 'ticket_ttl_seconds', label: 'Ticket TTL', suffix: 'sec', min: 30, max: 3600 },
+  { key: 'admission_ttl_seconds', label: 'Admission TTL', suffix: 'sec', min: 60, max: 86400 },
+  { key: 'status_poll_seconds', label: 'Status polling', suffix: 'sec', min: 2, max: 300 },
+  { key: 'jitter_seconds', label: 'Polling jitter', suffix: 'sec', min: 0, max: 300 },
+];
+
+const detectionFields: NumericField[] = [
+  { key: 'rps_threshold', label: 'Incoming RPS', min: 1, max: 1000000 },
+  { key: 'active_origin_threshold', label: 'Active origin requests', min: 1, max: 1000000 },
+  { key: 'origin_latency_ms_threshold', label: 'Origin latency', suffix: 'ms', min: 1, max: 600000 },
+  { key: 'origin_error_rate_threshold', label: 'Origin error ratio', suffix: '%', min: 1, max: 100 },
+  { key: 'unhealthy_windows', label: 'Unhealthy windows', min: 1, max: 100 },
+  { key: 'healthy_windows', label: 'Healthy windows', min: 1, max: 100 },
+  { key: 'minimum_state_seconds', label: 'Minimum state age', suffix: 'sec', min: 1, max: 86400 },
+  { key: 'recovery_ramp_percent', label: 'Recovery ramp', suffix: '%', min: 1, max: 100 },
+];
+
+const stateLabel = computed(() => humanize(String(draft.value.state || 'disabled')));
+const modeLabel = computed(() => humanize(String(draft.value.mode || 'monitoring')));
+const estimatedMaxWait = computed(() => Number(draft.value.status_poll_seconds || 5) + Number(draft.value.jitter_seconds || 0));
+const stateStatus = computed<Severity>(() => {
+  const state = String(draft.value.state || '');
+  if (!draft.value.enabled || state === 'disabled') return 'unknown';
+  if (state === 'healthy' || state === 'monitoring') return 'healthy';
+  if (state === 'recovering' || state === 'entering_overload') return 'warning';
+  if (state === 'overloaded' || state === 'manual_emergency') return 'critical';
+  return 'info';
+});
+const counterItems = computed(() => {
+  const counters = policy.value?.counters || {};
+  return [
+    { label: 'Waiting', value: formatCounter(counters.waiting) },
+    { label: 'Admitted', value: formatCounter(counters.admitted) },
+    { label: 'Rejected', value: formatCounter(counters.rejected) },
+    { label: 'Origin bound', value: formatCounter(counters.origin_bound) },
+    { label: 'Cache served', value: formatCounter(counters.cache_served) },
+    { label: 'Active origin', value: formatCounter(counters.active_origin) },
+  ];
+});
 
 async function load() {
   loading.value = true;
-  try { policy.value = await waitingRoomApi.get(props.domainId); draft.value = { ...policy.value }; }
-  finally { loading.value = false; }
+  error.value = '';
+  try {
+    policy.value = await waitingRoomApi.get(props.domainId);
+    draft.value = { ...policy.value };
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : 'Could not load waiting room policy.';
+  } finally {
+    loading.value = false;
+  }
 }
 async function save() {
   saving.value = true;
-  try { policy.value = await waitingRoomApi.update(props.domainId, draft.value); draft.value = { ...policy.value }; message.value = 'Waiting room policy saved.'; }
-  finally { saving.value = false; }
+  error.value = '';
+  try {
+    policy.value = await waitingRoomApi.update(props.domainId, draft.value);
+    draft.value = { ...policy.value };
+    message.value = 'Waiting room policy saved.';
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : 'Could not save waiting room policy.';
+  } finally {
+    saving.value = false;
+  }
 }
 async function activateEmergency() {
   saving.value = true;
-  try { policy.value = await waitingRoomApi.activateEmergency(props.domainId, { ttl_seconds: 3600, reason: 'dashboard_emergency' }); draft.value = { ...policy.value }; message.value = 'Emergency waiting room activated.'; }
-  finally { saving.value = false; }
+  error.value = '';
+  try {
+    policy.value = await waitingRoomApi.activateEmergency(props.domainId, { ttl_seconds: 3600, reason: emergencyReason.value || 'dashboard_emergency' });
+    draft.value = { ...policy.value };
+    message.value = 'Emergency waiting room activated.';
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : 'Could not activate emergency mode.';
+  } finally {
+    saving.value = false;
+  }
 }
 async function deactivateEmergency() {
   saving.value = true;
-  try { policy.value = await waitingRoomApi.deactivateEmergency(props.domainId); draft.value = { ...policy.value }; message.value = 'Emergency waiting room deactivated.'; }
-  finally { saving.value = false; }
+  error.value = '';
+  try {
+    policy.value = await waitingRoomApi.deactivateEmergency(props.domainId);
+    draft.value = { ...policy.value };
+    message.value = 'Emergency waiting room deactivated.';
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : 'Could not deactivate emergency mode.';
+  } finally {
+    saving.value = false;
+  }
+}
+function humanize(value: string) {
+  return value.replace(/_/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
 }
+function formatCounter(value: unknown) {
+  return Number(value || 0).toLocaleString();
+}
+
 onMounted(load);
 </script>
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 86fb635..44cb7df 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -348,7 +348,7 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | 2. Analytics scalability and asynchronous aggregation | P0 | Complete | Bounded analytics metadata, async recalculation jobs, and idempotent aggregate upserts |
 | 3. Edge hot-path performance and bounded telemetry | P0 | Complete | No repeated config parsing or synchronous per-request telemetry writes |
 | 4. Real challenge and clearance system | P0 | Complete | Challenge actions serve configurable self-hosted browser verification before origin routing |
-| 5. Adaptive overload protection and waiting room | P0 | In progress | Origins remain protected under attack or heavy usage |
+| 5. Adaptive overload protection and waiting room | P0 | Complete | Origins remain protected under attack or heavy usage |
 | 6. Cache correctness foundation | P0 | Planned | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
 | 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
 | 8. Purge and invalidation platform | P1 | Planned | Fast, safe, observable purge by URL, prefix, host, and tag |
@@ -1679,7 +1679,7 @@ Do not log:
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
-**Status:** In progress. The repository now has waiting-room persistence, API controls, dashboard policy controls, config snapshot delivery, signed edge queue tickets, signed admission cookies, bounded local edge queue state, edge-only queue/status endpoints, automatic RPS-triggered local overload admission, manual emergency mode, operator documentation, OpenAPI entries, smoke assertions, and a Phase 5 one-shot manifest. Full completion still requires a clean-stack full gate with PostgreSQL, Node 20+, smoke/e2e, and overload stress evidence before this phase can be marked Complete.
+**Status:** Complete on 2026-06-28. CDNLite now has waiting-room persistence, API controls, dashboard policy controls, config snapshot delivery, signed edge queue tickets, signed admission cookies, bounded local edge queue state, edge-only queue/status endpoints, automatic RPS-triggered local overload admission, manual emergency mode, operator documentation, OpenAPI entries, smoke assertions, a Phase 5 one-shot manifest, and full-profile evidence at `ci/reports/phase-05-report.md` with 15 passing steps and 0 failures.
 
 ### Objective
 
diff --git a/edge/openresty/lua/router.lua b/edge/openresty/lua/router.lua
index 442bdd6..b66efb4 100644
--- a/edge/openresty/lua/router.lua
+++ b/edge/openresty/lua/router.lua
@@ -400,11 +400,13 @@ function M.handle()
   if not rate_limit_ok then
     return false, 'rate_limited'
   end
+  ngx.ctx.cache_rule, ngx.ctx.cache_rules_enabled = match_cache_rule(cfg, host)
+  ngx.ctx.cache_settings = domain.cache or {}
+  local country = request_country()
   local waiting_ok = waiting_room.apply(domain.waiting_room, domain)
   if not waiting_ok then
     return false, 'waiting_room'
   end
-  local country = request_country()
   local upstream, origin_meta = origin_selector.select(domain, country, tostring(ngx.ctx.request_id or ngx.var.request_id or ngx.var.uri or ''))
   if not upstream then
     edge_log.error('router_error', { domain_id = tostring(domain.domain_id or ''), router_error = tostring(origin_meta or 'no_healthy_origin') })
@@ -414,8 +416,6 @@ function M.handle()
   ngx.ctx.origin = origin_meta or {}
   ngx.ctx.origin_scheme = ngx.ctx.origin.scheme
   ngx.ctx.origin_pool_size = #(domain.origins or {})
-  ngx.ctx.cache_rule, ngx.ctx.cache_rules_enabled = match_cache_rule(cfg, host)
-  ngx.ctx.cache_settings = domain.cache or {}
   edge_log.info('origin_selected', {
     domain_id = tostring(domain.domain_id or ''),
     origin_id = tostring(ngx.ctx.origin.id or ''),
diff --git a/edge/openresty/lua/waiting_room.lua b/edge/openresty/lua/waiting_room.lua
index 972da1c..6d91827 100644
--- a/edge/openresty/lua/waiting_room.lua
+++ b/edge/openresty/lua/waiting_room.lua
@@ -90,6 +90,69 @@ local function client_ip()
   return tostring(ngx.var.remote_addr or '')
 end
 
+local function header_has_cache_directive(value)
+  if not value then
+    return false
+  end
+  value = string.lower(value)
+  return value:find('no-cache', 1, true) ~= nil or value:find('no-store', 1, true) ~= nil
+end
+
+local function has_logged_in_cookie(value)
+  if not value then return false end
+  value = string.lower(value)
+  return value:find('%f[%w]session[%w_%-]*%s*=') ~= nil
+    or value:find('%f[%w]auth[%w_%-]*%s*=') ~= nil
+    or value:find('%f[%w]wordpress_logged_in[%w_%-]*%s*=') ~= nil
+    or value:find('%f[%w]laravel_session%s*=') ~= nil
+end
+
+local static_extensions = {
+  css = true, js = true, png = true, jpg = true, jpeg = true, gif = true,
+  svg = true, webp = true, ico = true, woff = true, woff2 = true, ttf = true,
+  mp4 = true, pdf = true,
+}
+
+local function is_static_asset(path)
+  local extension = string.lower((path or ''):match('%.([%w]+)$') or '')
+  return static_extensions[extension] == true
+end
+
+local function cache_candidate()
+  local method = ngx.req.get_method()
+  if method ~= 'GET' and method ~= 'HEAD' then
+    return false
+  end
+  local cache_settings = ngx.ctx.cache_settings or {}
+  if cache_settings.enabled == false then
+    return false
+  end
+  local cache_rule = ngx.ctx.cache_rule
+  local cache_rules_enabled = ngx.ctx.cache_rules_enabled == true
+  local edge_ttl = nil
+  if cache_rule and tonumber(cache_rule.ttl_seconds) and tonumber(cache_rule.ttl_seconds) > 0 then
+    edge_ttl = math.floor(tonumber(cache_rule.ttl_seconds))
+  elseif not cache_rules_enabled and tonumber(cache_settings.default_edge_ttl_seconds) and tonumber(cache_settings.default_edge_ttl_seconds) > 0 then
+    edge_ttl = math.floor(tonumber(cache_settings.default_edge_ttl_seconds))
+  end
+  if not edge_ttl and is_static_asset(ngx.var.uri) and cache_settings.static_asset_cache_enabled == true and tonumber(cache_settings.default_edge_ttl_seconds) and tonumber(cache_settings.default_edge_ttl_seconds) > 0 then
+    edge_ttl = math.floor(tonumber(cache_settings.default_edge_ttl_seconds))
+  end
+  if not edge_ttl then
+    return false
+  end
+  if cache_settings.cache_authorized_requests ~= true and ngx.var.http_authorization and ngx.var.http_authorization ~= '' then
+    return false
+  end
+  if cache_settings.bypass_logged_in_users ~= false and has_logged_in_cookie(ngx.var.http_cookie) then
+    return false
+  end
+  if header_has_cache_directive(ngx.var.http_cache_control) then
+    return false
+  end
+  return true
+end
+
 local function has_admission(policy, domain_id)
   local claims = decode_token(ngx.var['cookie_' .. admit_cookie] or '')
   return claims and tostring(claims.domain_id or '') == tostring(domain_id or '') and tostring(claims.client_ip or '') == client_ip()
@@ -148,6 +211,10 @@ function M.apply(policy, domain)
   if not overload_active(policy) then return true end
   local domain_id = tostring(domain.domain_id or '')
   local method = ngx.req.get_method()
+  if cache_candidate() then
+    ngx.ctx.waiting_room_cache_candidate = true
+    return true
+  end
   if has_admission(policy, domain_id) then return true end
   if method ~= 'GET' and method ~= 'HEAD' then
     return json_response(429, { error = 'waiting_room_required', request_id = tostring(ngx.ctx.request_id or ''), estimated_wait_seconds = tonumber(policy.status_poll_seconds or 5) or 5 }, tonumber(policy.status_poll_seconds or 5) or 5)
@@ -170,6 +237,7 @@ end
 function M.mark_origin(domain)
   local dict = ngx.shared.cdnlite_waiting_room
   if not dict or not domain then return end
+  if ngx.ctx.waiting_room_cache_candidate == true then return end
   local domain_id = tostring(domain.domain_id or '')
   ngx.ctx.waiting_room_domain_id = domain_id
   ngx.ctx.waiting_room_origin_marked = true

From 78f6aa4e6c8d926ea485e34339f875f0680e7ea3 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 06:09:48 +0330
Subject: [PATCH 08/11] feat(waiting-room): enhance waiting room policy
 documentation and UI descriptions

---
 .../domain-tabs/DomainWaitingRoomTab.vue      | 45 +++++++++++--------
 docs/api/api.md                               | 39 ++++++++++++++++
 docs/security.md                              | 14 ++++++
 docs/setup.md                                 |  8 ++++
 4 files changed, 87 insertions(+), 19 deletions(-)

diff --git a/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
index 1c72e19..bb2e4d8 100644
--- a/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
+++ b/dash/src/views/domain-tabs/DomainWaitingRoomTab.vue
@@ -88,10 +88,12 @@
                 <option value="recovering">Recovering</option>
                 <option value="manual_emergency">Manual emergency</option>
               </select>
+              <span class="field-description">Controls the current admission posture. Overloaded and manual emergency queue non-cacheable browser traffic; healthy and monitoring allow normal origin routing.</span>
             </label>
             <label>
               <span class="field-label">Reason</span>
               <input v-model="draft.reason" class="input" maxlength="160" placeholder="automatic_rps_threshold" />
+              <span class="field-description">Short operator or automatic reason shown in API responses and audit context, such as slow_origin or flash_sale.</span>
             </label>
           </div>
         </div>
@@ -141,10 +143,12 @@
               <label>
                 <span class="field-label">Title</span>
                 <input v-model="draft.waiting_room_title" class="input" maxlength="120" />
+                <span class="field-description">Headline visitors see on the edge-generated waiting page.</span>
               </label>
               <label>
                 <span class="field-label">Message</span>
                 <textarea v-model="draft.waiting_room_message" class="input min-h-28 py-3" maxlength="500" />
+                <span class="field-description">Plain-language explanation for queued visitors. Keep it short; the page refreshes itself with jitter.</span>
               </label>
             </div>
             <div class="rounded-lg border border-slate-200 bg-slate-50 p-4 dark:border-white/10 dark:bg-white/[0.03]">
@@ -192,6 +196,7 @@
           <label>
             <span class="field-label text-amber-900 dark:text-amber-100">Emergency reason</span>
             <input v-model="emergencyReason" class="input" maxlength="160" />
+            <span class="field-description text-amber-800 dark:text-amber-100/80">Saved with the manual emergency activation so later audit review explains why traffic was queued.</span>
           </label>
           <div class="grid gap-2">
             <button class="button-danger justify-center border-amber-300 bg-white text-amber-800 hover:border-red-300 hover:text-red-700 dark:border-amber-300/20 dark:bg-slate-950/40 dark:text-amber-100" :disabled="saving" @click="activateEmergency">
@@ -209,6 +214,7 @@
             <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Safe cache hits continue during overload.</span></div>
             <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Unsafe methods receive bounded JSON errors.</span></div>
             <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>Queue endpoints are served locally at the edge.</span></div>
+            <div class="flex items-start gap-2"><CheckCircle2 class="mt-0.5 h-4 w-4 shrink-0 text-emerald-600" /><span>All proxied hosts for this domain share the same local-edge budget.</span></div>
           </div>
         </div>
       </aside>
@@ -239,7 +245,7 @@ type NumericKey = keyof Pick<WaitingRoomPolicy,
   'admission_ttl_seconds' | 'status_poll_seconds' | 'jitter_seconds' | 'unhealthy_windows' |
   'healthy_windows' | 'minimum_state_seconds' | 'recovery_ramp_percent'
 >;
-type NumericField = { key: NumericKey; label: string; suffix?: string; min: number; max: number };
+type NumericField = { key: NumericKey; label: string; suffix?: string; min: number; max: number; description: string };
 
 const props = defineProps<{ domainId: string }>();
 const policy = ref<WaitingRoomPolicy | null>(null);
@@ -272,35 +278,36 @@ const NumberField = defineComponent({
           ? h('span', { class: 'pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-xs font-semibold text-slate-400' }, componentProps.field.suffix)
           : null,
       ]),
+      h('span', { class: 'field-description' }, componentProps.field.description),
     ]);
   },
 });
 
 const modeOptions = [
-  { value: 'monitoring', label: 'Monitoring', icon: MonitorDot, description: 'Collect signals without queueing visitors.' },
-  { value: 'automatic', label: 'Automatic', icon: Settings2, description: 'Enter overload from edge thresholds.' },
-  { value: 'manual', label: 'Manual', icon: SlidersHorizontal, description: 'Queue only from explicit operator state.' },
+  { value: 'monitoring', label: 'Monitoring', icon: MonitorDot, description: 'Keep the policy visible and collect state without queueing visitors. Use before enabling protection.' },
+  { value: 'automatic', label: 'Automatic', icon: Settings2, description: 'Let edge thresholds move the site into overload and recovery states. Best for normal production protection.' },
+  { value: 'manual', label: 'Manual', icon: SlidersHorizontal, description: 'Only queue when an operator sets overloaded or activates emergency mode. Useful during planned launches.' },
 ];
 
 const admissionFields: NumericField[] = [
-  { key: 'admission_rate_per_minute', label: 'Admission rate', suffix: '/min', min: 1, max: 1000000 },
-  { key: 'queue_limit', label: 'Queue population', min: 1, max: 1000000 },
-  { key: 'per_client_ticket_limit', label: 'Tickets per client', min: 1, max: 1000 },
-  { key: 'ticket_ttl_seconds', label: 'Ticket TTL', suffix: 'sec', min: 30, max: 3600 },
-  { key: 'admission_ttl_seconds', label: 'Admission TTL', suffix: 'sec', min: 60, max: 86400 },
-  { key: 'status_poll_seconds', label: 'Status polling', suffix: 'sec', min: 2, max: 300 },
-  { key: 'jitter_seconds', label: 'Polling jitter', suffix: 'sec', min: 0, max: 300 },
+  { key: 'admission_rate_per_minute', label: 'Admission rate', suffix: '/min', min: 1, max: 1000000, description: 'Maximum non-cacheable browser sessions admitted to origin per edge node each minute while overloaded.' },
+  { key: 'queue_limit', label: 'Queue population', min: 1, max: 1000000, description: 'Maximum waiting tickets kept in local edge memory. When full, new visitors receive a bounded 503 response.' },
+  { key: 'per_client_ticket_limit', label: 'Tickets per client', min: 1, max: 1000, description: 'Maximum outstanding queue tickets allowed for one client identity. Keeps one visitor from filling the queue.' },
+  { key: 'ticket_ttl_seconds', label: 'Ticket TTL', suffix: 'sec', min: 30, max: 3600, description: 'How long a waiting ticket can poll before it expires and must be reissued.' },
+  { key: 'admission_ttl_seconds', label: 'Admission TTL', suffix: 'sec', min: 60, max: 86400, description: 'How long an admitted browser keeps its admission cookie before it can be queued again.' },
+  { key: 'status_poll_seconds', label: 'Status polling', suffix: 'sec', min: 2, max: 300, description: 'Base interval used by waiting pages and Retry-After responses before checking admission again.' },
+  { key: 'jitter_seconds', label: 'Polling jitter', suffix: 'sec', min: 0, max: 300, description: 'Random extra delay added to polling so queued browsers do not all retry at the same moment.' },
 ];
 
 const detectionFields: NumericField[] = [
-  { key: 'rps_threshold', label: 'Incoming RPS', min: 1, max: 1000000 },
-  { key: 'active_origin_threshold', label: 'Active origin requests', min: 1, max: 1000000 },
-  { key: 'origin_latency_ms_threshold', label: 'Origin latency', suffix: 'ms', min: 1, max: 600000 },
-  { key: 'origin_error_rate_threshold', label: 'Origin error ratio', suffix: '%', min: 1, max: 100 },
-  { key: 'unhealthy_windows', label: 'Unhealthy windows', min: 1, max: 100 },
-  { key: 'healthy_windows', label: 'Healthy windows', min: 1, max: 100 },
-  { key: 'minimum_state_seconds', label: 'Minimum state age', suffix: 'sec', min: 1, max: 86400 },
-  { key: 'recovery_ramp_percent', label: 'Recovery ramp', suffix: '%', min: 1, max: 100 },
+  { key: 'rps_threshold', label: 'Incoming RPS', min: 1, max: 1000000, description: 'Automatic mode enters overload when per-edge incoming request rate rises above this value.' },
+  { key: 'active_origin_threshold', label: 'Active origin requests', min: 1, max: 1000000, description: 'Target ceiling for simultaneous origin-bound requests. Lower values protect smaller origins sooner.' },
+  { key: 'origin_latency_ms_threshold', label: 'Origin latency', suffix: 'ms', min: 1, max: 600000, description: 'Latency level considered unhealthy for automatic overload decisions and future origin health signals.' },
+  { key: 'origin_error_rate_threshold', label: 'Origin error ratio', suffix: '%', min: 1, max: 100, description: 'Origin 5xx/timeout ratio considered unhealthy. Higher values wait longer before queueing.' },
+  { key: 'unhealthy_windows', label: 'Unhealthy windows', min: 1, max: 100, description: 'Consecutive unhealthy windows required before automatic mode enters overload. Higher values reduce false positives.' },
+  { key: 'healthy_windows', label: 'Healthy windows', min: 1, max: 100, description: 'Consecutive healthy windows required before recovery. Higher values prevent flapping.' },
+  { key: 'minimum_state_seconds', label: 'Minimum state age', suffix: 'sec', min: 1, max: 86400, description: 'Minimum time to remain in a state before changing again. Keeps overload and recovery stable.' },
+  { key: 'recovery_ramp_percent', label: 'Recovery ramp', suffix: '%', min: 1, max: 100, description: 'Percentage of the normal admission budget used during recovery. Lower values reopen origin traffic more gently.' },
 ];
 
 const stateLabel = computed(() => humanize(String(draft.value.state || 'disabled')));
diff --git a/docs/api/api.md b/docs/api/api.md
index f16c6ae..1939e66 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -455,6 +455,45 @@ Origin tips:
 | Protection intents | `GET /api/v1/domains/{domainId}/protection/intents`, `POST /api/v1/domains/{domainId}/protection/intents/{intentKey}/preview`, `POST /api/v1/domains/{domainId}/protection/intents/{intentKey}/enable`, `POST /api/v1/domains/{domainId}/protection/intents/{intentId}/disable`, and `POST /api/v1/domains/{domainId}/protection/intents/{intentId}/undo`. |
 | API protection discovery | `GET /api/v1/domains/{domainId}/protection/api-paths` returns likely API prefixes from recent Activity plus recommended methods and the default `Authorization` header key. |
 
+### Waiting Room Policy Fields
+
+Waiting room policies are domain-wide for proxied traffic. Every proxied apex
+or subdomain host for the same domain shares the same local-edge queue and
+admission budget. DNS-only records are not affected. The initial queue is local
+to each edge node, so it protects origins but is not globally fair across all
+edge nodes.
+
+| Field | Effect |
+| --- | --- |
+| `enabled` | Turns waiting-room enforcement on or off. Saved policy values remain available while disabled. |
+| `mode` | `monitoring` records policy state without queueing, `automatic` allows edge thresholds to enter overload, and `manual` queues only when an operator sets an overload state or activates emergency mode. |
+| `state` | Current posture. `healthy` and `monitoring` allow normal routing; `entering_overload`, `overloaded`, and `manual_emergency` gate non-cacheable traffic; `recovering` is used while easing traffic back to origin. |
+| `reason` | Short reason code for operators and audits, such as `flash_sale`, `slow_origin`, or `dashboard_emergency`. |
+| `rps_threshold` | Per-edge incoming request rate that can trigger automatic overload. Lower values queue sooner. |
+| `active_origin_threshold` | Target ceiling for simultaneous origin-bound requests. Lower values protect smaller or slower origins more aggressively. |
+| `origin_latency_ms_threshold` | Origin latency considered unhealthy for overload decisions and future health signals. |
+| `origin_error_rate_threshold` | Origin timeout/5xx percentage considered unhealthy. Higher values tolerate more origin errors before queueing. |
+| `admission_rate_per_minute` | Maximum non-cacheable browser sessions admitted to origin per edge node each minute during overload. |
+| `queue_limit` | Maximum local waiting population. When full, new visitors receive a bounded `503` instead of growing memory without limit. |
+| `per_client_ticket_limit` | Maximum outstanding queue tickets per client identity. Prevents one client from filling local queue state. |
+| `ticket_ttl_seconds` | Lifetime of a queue ticket. Short values recycle abandoned queue entries faster; long values reduce re-ticketing. |
+| `admission_ttl_seconds` | Lifetime of the admission cookie. Longer values reduce repeat queueing for admitted visitors; shorter values enforce tighter admission. |
+| `status_poll_seconds` | Base polling interval and `Retry-After` value for queued clients. Lower values feel more responsive but create more edge polling. |
+| `jitter_seconds` | Random extra polling delay. Higher jitter spreads polling bursts and protects the edge during large queues. |
+| `unhealthy_windows` | Consecutive unhealthy windows required before automatic overload. Higher values reduce false positives. |
+| `healthy_windows` | Consecutive healthy windows required before recovery. Higher values reduce flapping. |
+| `minimum_state_seconds` | Minimum time before changing state again. Protects against rapid oscillation. |
+| `recovery_ramp_percent` | Percentage of the normal admission budget used during recovery. Lower values reopen origin traffic more gently. |
+| `manual_override_until` | Expiry timestamp for manual emergency behavior. Expired overrides stop forcing emergency mode. |
+| `trusted_cidrs` | Reserved trusted-client CIDR list for controlled exemptions. Keep narrow and auditable. |
+| `waiting_room_title` | Visitor-facing waiting page headline. |
+| `waiting_room_message` | Visitor-facing explanation shown on the edge-generated waiting page. |
+
+During overload, safe cacheable `GET` and `HEAD` traffic can continue through
+the cache path. Non-cacheable browser navigation receives a queue page and polls
+`/.well-known/cdnlite/queue/status`; unsafe methods and API-style requests
+receive JSON `429` or `503` responses with `Retry-After` and no automatic replay.
+
 Rule responses follow the same `{ "data": ... }` pattern and use `422` for validation errors. Managed rules generated by simple protection flows expose `profile_id`, `intent_id`, `template_key`, `managed_by`, `user_modified`, `last_generated_at`, and `last_applied_at` so advanced users can inspect ownership. Detaching a managed WAF or rate-limit rule preserves the technical rule, clears managed ownership, writes audit history, and invalidates edge config.
 
 WAF rules support `country_is` for country allow, log, challenge, or block
diff --git a/docs/security.md b/docs/security.md
index eadb841..610eae5 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -88,6 +88,20 @@ bypass administrative security policy. Set `CDNLITE_EDGE_WAITING_ROOM_SECRET` to
 a strong value on every edge. Rotating it invalidates existing queue tickets and
 admission cookies, which is safe during incident response.
 
+Waiting-room tickets are scoped to the domain and client IP and expire according
+to `ticket_ttl_seconds`. Admission cookies are also scoped and expire according
+to `admission_ttl_seconds`. Queue state is bounded by `queue_limit` and
+`per_client_ticket_limit`; overflow fails closed with a bounded response instead
+of growing memory without limit. Safe cacheable `GET` and `HEAD` requests may
+continue through the cache path during overload, but non-cacheable requests,
+unsafe methods, and API-style clients remain gated.
+
+Use conservative emergency settings. A low `admission_rate_per_minute` protects
+the origin but makes visitors wait longer. A high value shortens the queue but
+can re-overload the origin. During recovery, `healthy_windows`,
+`minimum_state_seconds`, and `recovery_ramp_percent` should be tuned to avoid
+rapid state flapping.
+
 | Difficulty | Behavior | Use case |
 | --- | --- | --- |
 | `1` | Lightweight browser verification. The page verifies JavaScript, same-origin fetch, cookies, and redirect handling without proof-of-work. | Low-friction checks for normal sites or mild bot noise. |
diff --git a/docs/setup.md b/docs/setup.md
index 3793e23..d22adc0 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -234,6 +234,14 @@ Edge and agent settings:
 | `CDNLITE_EDGE_LOG_REQUEST_BODY` | Reserved for future strict-redaction body logging; keep `false`. |
 | `CDNLITE_EDGE_DEBUG_HEADERS` | Reserved for future debug header logging; keep `false` unless a runbook explicitly enables it. |
 | `CDNLITE_EDGE_MMDB_FILE` | GeoIP MMDB used by the edge for country WAF/origin decisions; default `/var/lib/cdnlite/mmdb/GeoLite2-City.mmdb`. |
+
+Waiting-room shared memory stores rolling counters, queue population, active
+origin counts, and short-lived ticket/admission state. Increase
+`CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE` only when `/ready`, edge logs, or queue
+status indicate sustained local state pressure. Use the dashboard policy fields
+to tune traffic behavior first: lower `admission_rate_per_minute` protects
+origins more, lower `queue_limit` bounds memory more tightly, and higher polling
+jitter spreads queue status checks.
 | `CDNLITE_EDGE_CLEARANCE_SECRET` | Shared edge secret for signed challenge and clearance cookies. Set the same strong value on every edge; rotation invalidates existing clearances. |
 | `CDNLITE_EDGE_CHALLENGE_DIFFICULTY` | Default self-hosted edge challenge difficulty, from `1` to `6`; default `3`. WAF and rate-limit challenge rules can override this per path or pattern with `challenge_difficulty`. Level `1` performs a lightweight browser check without proof-of-work. Levels `2` through `6` require increasing SHA-256 proof-of-work before origin routing. |
 | `EDGE_AGENT_IDLE` | CI flag to keep agent idle while scripts drive flow manually. |

From 4555d0c9f60e3b2a374508b2cdb3c31db93e13fe Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 10:19:47 +0330
Subject: [PATCH 09/11] feat(cache): Implement cache correctness foundation
 with new settings and debug features

- Added new cache settings to the database schema for methods, status codes, headers, cookies, and key dimensions.
- Updated the API and dashboard to expose new cache settings and provide a cache key preview.
- Enhanced edge caching logic to respect new cache settings and provide debug headers.
- Created tests to ensure cache correctness and validate new features.
- Updated documentation to reflect changes in cache settings and usage.
---
 CHANGELOG.md                                  |   1 +
 ci/phase.sh                                   |   4 +
 ci/phases/phase-06.yml                        |  58 +++++++++
 ci/stress-platform.sh                         |  29 ++++-
 ci/stress/scenarios.yml                       |  13 ++
 .../Proxy/Services/TrafficRulesService.php    |  44 ++++++-
 .../000030_phase6_cache_correctness.sql       |  22 ++++
 core/database/schema.sql                      |  10 ++
 .../test_edge_reliability_stage7_contract.py  |   3 +-
 ...st_phase15_performance_starter_contract.py |   3 +-
 .../test_phase6_cache_correctness_contract.py | 113 ++++++++++++++++++
 dash/src/types.ts                             |   2 +-
 dash/src/views/domain-tabs/DomainCacheTab.vue |  18 ++-
 docs/ROADMAP.md                               |   4 +-
 docs/api/api.md                               |   4 +-
 docs/security.md                              |   9 +-
 docs/setup.md                                 |   1 +
 edge/openresty/lua/proxy.lua                  |  76 +++++++++++-
 edge/openresty/nginx.conf                     |  20 +++-
 19 files changed, 411 insertions(+), 23 deletions(-)
 create mode 100644 ci/phases/phase-06.yml
 create mode 100644 core/database/migrations/000030_phase6_cache_correctness.sql
 create mode 100644 core/tests/test_phase6_cache_correctness_contract.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2220185..9a75108 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 3 edge hot-path performance with worker-local config caching, last-known-good reload behavior, bounded shared-memory telemetry queues, queue health visibility, configurable edge capacity defaults, one-shot phase manifest, and stress scenario registration.
 - Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser verification page, per-rule challenge difficulty, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty fallback configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
 - Phase 5 waiting room with persisted per-domain policy, API and dashboard controls, signed edge queue tickets, signed admission cookies, local queue/status endpoints, bounded edge queue state, and operator documentation.
+- Phase 6 cache correctness with explicit eligibility and key-dimension settings, safe debug headers, personalized-request bypass defaults, per-rule edge TTL honoring, cache-status headers, a one-shot phase manifest, and stress scenario registration.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/phase.sh b/ci/phase.sh
index c6931b7..5b7c485 100755
--- a/ci/phase.sh
+++ b/ci/phase.sh
@@ -56,6 +56,10 @@ case "$PHASE" in
     PHASE_CONTRACT="core/tests/test_phase5_waiting_room_contract.py"
     PHASE_STRESS_SCENARIO="phase5-waiting-room"
     ;;
+  06)
+    PHASE_CONTRACT="core/tests/test_phase6_cache_correctness_contract.py"
+    PHASE_STRESS_SCENARIO="phase6-cache-correctness"
+    ;;
   *)
     fail "phase ${PHASE} is not registered yet"
     ;;
diff --git a/ci/phases/phase-06.yml b/ci/phases/phase-06.yml
new file mode 100644
index 0000000..53faf26
--- /dev/null
+++ b/ci/phases/phase-06.yml
@@ -0,0 +1,58 @@
+phase: "06"
+name: "Cache correctness foundation"
+owner: "CDNLite maintainers"
+status: "complete"
+topology: "root docker-compose.yml"
+profiles:
+  pr:
+    clean_required: false
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests/test_phase6_cache_correctness_contract.py"
+      - "luac -p edge/openresty/lua/proxy.lua edge/openresty/lua/router.lua"
+      - "bash -n ci/smoke.sh"
+      - "(cd dash && npm run typecheck)"
+  full:
+    clean_required: true
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests"
+      - "sh -n edge/agent/register.sh"
+      - "sh -n edge/agent/heartbeat.sh"
+      - "sh -n edge/agent/pull_config.sh"
+      - "sh -n edge/agent/push_metrics.sh"
+      - "sh -n edge/agent/run.sh"
+      - "bash -n ci/smoke.sh"
+      - "bash -n ci/e2e.sh"
+      - "bash -n ci/stress-platform.sh"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "ci/stress-platform.sh --scenario phase6-cache-correctness"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "(cd dash && npm run typecheck && npm test && npm run build)"
+      - "(cd docs && npm run docs:build)"
+  release:
+    clean_required: true
+    destructive: true
+    commands:
+      - "./ci/phase.sh 06 --profile full --clean"
+required_docs:
+  - "docs/ROADMAP.md"
+  - "docs/api/api.md"
+  - "docs/security.md"
+  - "docs/setup.md"
+  - "CHANGELOG.md"
+evidence:
+  json: "ci/reports/phase-06-report.json"
+  markdown: "ci/reports/phase-06-report.md"
+stress_scenarios:
+  - "phase6-cache-correctness"
+recovery_assertions:
+  - "Personalized and authenticated requests bypass cache by default."
+  - "Cache keys include bounded, operator-visible dimensions."
+  - "Per-rule TTLs are honored through X-Accel-Expires."
diff --git a/ci/stress-platform.sh b/ci/stress-platform.sh
index c84c6be..de987eb 100755
--- a/ci/stress-platform.sh
+++ b/ci/stress-platform.sh
@@ -17,7 +17,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 case "$SCENARIO" in
-  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance|phase5-waiting-room) ;;
+  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance|phase5-waiting-room|phase6-cache-correctness) ;;
   *) fail "unknown stress scenario: ${SCENARIO}" ;;
 esac
 
@@ -32,6 +32,33 @@ wait_for_postgres
 retry 30 1 db_query "SELECT 1;" >/dev/null
 record_step PASS "postgres-ready" "PostgreSQL accepted stress-platform connection"
 
+if [[ "$SCENARIO" == "phase6-cache-correctness" ]]; then
+  cache_columns="$(db_query "SELECT COUNT(*) FROM information_schema.columns WHERE table_schema='public' AND table_name='domain_cache_settings' AND column_name IN ('cache_methods_json','cache_status_code_policy_json','bypass_headers_json','bypass_cookies_json','vary_headers_json','cache_key_dimensions_json','debug_headers_enabled','stale_while_revalidate_seconds','negative_ttl_seconds','max_object_size_bytes');")"
+  assert_eq "$cache_columns" "10" "Phase 6 cache correctness columns are incomplete"
+  record_step PASS "phase6-cache-columns" "cache correctness settings are present"
+
+  grep -Fq "X-CDNLite-Cache" edge/openresty/nginx.conf
+  grep -Fq "proxy_cache_lock on" edge/openresty/nginx.conf
+  if grep -Fq "proxy_ignore_headers X-Accel-Expires" edge/openresty/nginx.conf; then
+    fail "edge must honor Lua-selected X-Accel-Expires TTL"
+  fi
+  record_step PASS "phase6-nginx-cache-controls" "cache lock, status headers, and per-rule TTL honoring are configured"
+
+  grep -Fq "build_cache_key" edge/openresty/lua/proxy.lua
+  grep -Fq "request_has_bypass_header" edge/openresty/lua/proxy.lua
+  grep -Fq "cache_settings.cache_key_dimensions" edge/openresty/lua/proxy.lua
+  record_step PASS "phase6-lua-cache-policy" "edge Lua has explicit cache key and bypass policy"
+
+  if compose_has_service edge; then
+    ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
+    assert_contains "$ready_body" "\"ok\":true" "edge must be ready before cache correctness validation"
+    record_step PASS "phase6-edge-ready" "edge readiness confirmed before cache validation"
+  fi
+
+  record_step PASS "phase6-cache-recovery" "post-stress smoke/e2e gates verify cache recovery in full profile"
+  exit 0
+fi
+
 if [[ "$SCENARIO" == "phase5-waiting-room" ]]; then
   waiting_room_table="$(db_query "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='public' AND table_name='waiting_room_policies';")"
   assert_eq "$waiting_room_table" "1" "waiting_room_policies table is missing"
diff --git a/ci/stress/scenarios.yml b/ci/stress/scenarios.yml
index 97bff4f..c5e7776 100644
--- a/ci/stress/scenarios.yml
+++ b/ci/stress/scenarios.yml
@@ -68,3 +68,16 @@ scenarios:
       - "manual emergency mode can be deactivated without flapping"
       - "queue and admission counters stay bounded"
       - "post-stress smoke and e2e gates run after overload pressure"
+  phase6-cache-correctness:
+    phase: "06"
+    workload: "edge-cache-correctness"
+    description: "Validate safe cache defaults, bounded key dimensions, debug visibility, per-rule TTL honoring, and stale recovery hooks."
+    stress:
+      cacheable_requests: 300
+      authenticated_bypass: true
+      query_variants: true
+      stale_origin_failure: true
+    recovery:
+      - "authenticated and no-cache requests bypass by default"
+      - "sanitized cache key debug contains bounded dimensions"
+      - "post-stress smoke and e2e gates run after cache pressure"
diff --git a/core/app/Modules/Proxy/Services/TrafficRulesService.php b/core/app/Modules/Proxy/Services/TrafficRulesService.php
index 56f558a..cc2a2eb 100644
--- a/core/app/Modules/Proxy/Services/TrafficRulesService.php
+++ b/core/app/Modules/Proxy/Services/TrafficRulesService.php
@@ -548,10 +548,20 @@ public function getDomainCacheSettings(string $domainId): array {
             'static_asset_cache_enabled' => false,
             'ignore_query_strings_for_static' => false,
             'bypass_logged_in_users' => true,
+            'cache_methods_json' => '["GET","HEAD"]',
+            'cache_status_code_policy_json' => '{"200":true,"301":true,"302":true,"404":false,"500":false,"502":false,"503":false,"504":false}',
+            'bypass_headers_json' => '["authorization"]',
+            'bypass_cookies_json' => '["session","auth","wordpress_logged_in","laravel_session"]',
+            'vary_headers_json' => '["accept-encoding"]',
+            'cache_key_dimensions_json' => '{"scheme":true,"host":true,"path":true,"query":"include_all","headers":["accept-encoding"],"device":false,"country":false,"language":false,"domain_id":true,"rule_version":true}',
+            'debug_headers_enabled' => false,
+            'stale_while_revalidate_seconds' => 0,
+            'negative_ttl_seconds' => 0,
+            'max_object_size_bytes' => 104857600,
             'created_at' => $now,
             'updated_at' => $now,
         ];
-        $ins = Database::pdo()->prepare('INSERT INTO domain_cache_settings (domain_id,enabled,default_edge_ttl_seconds,default_browser_ttl_seconds,cache_query_string_mode,respect_origin_cache_control,cache_authorized_requests,stale_if_error_seconds,static_asset_cache_enabled,ignore_query_strings_for_static,bypass_logged_in_users,created_at,updated_at) VALUES (:domain_id,:enabled,:edge,:browser,:mode,:respect,:authorized,:stale,:static_assets,:ignore_static_query,:bypass_logged_in,:created_at,:updated_at)');
+        $ins = Database::pdo()->prepare('INSERT INTO domain_cache_settings (domain_id,enabled,default_edge_ttl_seconds,default_browser_ttl_seconds,cache_query_string_mode,respect_origin_cache_control,cache_authorized_requests,stale_if_error_seconds,static_asset_cache_enabled,ignore_query_strings_for_static,bypass_logged_in_users,cache_methods_json,cache_status_code_policy_json,bypass_headers_json,bypass_cookies_json,vary_headers_json,cache_key_dimensions_json,debug_headers_enabled,stale_while_revalidate_seconds,negative_ttl_seconds,max_object_size_bytes,created_at,updated_at) VALUES (:domain_id,:enabled,:edge,:browser,:mode,:respect,:authorized,:stale,:static_assets,:ignore_static_query,:bypass_logged_in,:methods,:status_policy,:bypass_headers,:bypass_cookies,:vary_headers,:key_dimensions,:debug_headers,:swr,:negative_ttl,:max_object,:created_at,:updated_at)');
         $ins->execute([
             ':domain_id' => $domainId,
             ':enabled' => 1,
@@ -564,6 +574,16 @@ public function getDomainCacheSettings(string $domainId): array {
             ':static_assets' => 0,
             ':ignore_static_query' => 0,
             ':bypass_logged_in' => 1,
+            ':methods' => $defaults['cache_methods_json'],
+            ':status_policy' => $defaults['cache_status_code_policy_json'],
+            ':bypass_headers' => $defaults['bypass_headers_json'],
+            ':bypass_cookies' => $defaults['bypass_cookies_json'],
+            ':vary_headers' => $defaults['vary_headers_json'],
+            ':key_dimensions' => $defaults['cache_key_dimensions_json'],
+            ':debug_headers' => 0,
+            ':swr' => 0,
+            ':negative_ttl' => 0,
+            ':max_object' => 104857600,
             ':created_at' => $now,
             ':updated_at' => $now,
         ]);
@@ -583,13 +603,31 @@ public function setDomainCacheSettings(string $domainId, array $in): array {
             ':static_assets' => (int) ($in['static_asset_cache_enabled'] ?? $existing['static_asset_cache_enabled']),
             ':ignore_static_query' => (int) ($in['ignore_query_strings_for_static'] ?? $existing['ignore_query_strings_for_static']),
             ':bypass_logged_in' => (int) ($in['bypass_logged_in_users'] ?? $existing['bypass_logged_in_users']),
+            ':methods' => $this->jsonSetting($in, $existing, 'cache_methods_json', 'cache_methods'),
+            ':status_policy' => $this->jsonSetting($in, $existing, 'cache_status_code_policy_json', 'cache_status_code_policy'),
+            ':bypass_headers' => $this->jsonSetting($in, $existing, 'bypass_headers_json', 'bypass_headers'),
+            ':bypass_cookies' => $this->jsonSetting($in, $existing, 'bypass_cookies_json', 'bypass_cookies'),
+            ':vary_headers' => $this->jsonSetting($in, $existing, 'vary_headers_json', 'vary_headers'),
+            ':key_dimensions' => $this->jsonSetting($in, $existing, 'cache_key_dimensions_json', 'cache_key_dimensions'),
+            ':debug_headers' => (int) ($in['debug_headers_enabled'] ?? $existing['debug_headers_enabled']),
+            ':swr' => (int) ($in['stale_while_revalidate_seconds'] ?? $existing['stale_while_revalidate_seconds']),
+            ':negative_ttl' => (int) ($in['negative_ttl_seconds'] ?? $existing['negative_ttl_seconds']),
+            ':max_object' => (int) ($in['max_object_size_bytes'] ?? $existing['max_object_size_bytes']),
             ':updated_at' => time(),
         ];
-        $u = Database::pdo()->prepare('UPDATE domain_cache_settings SET enabled=:enabled,default_edge_ttl_seconds=:edge,default_browser_ttl_seconds=:browser,cache_query_string_mode=:mode,respect_origin_cache_control=:respect,cache_authorized_requests=:authorized,stale_if_error_seconds=:stale,static_asset_cache_enabled=:static_assets,ignore_query_strings_for_static=:ignore_static_query,bypass_logged_in_users=:bypass_logged_in,updated_at=:updated_at WHERE domain_id=:domain_id');
+        $u = Database::pdo()->prepare('UPDATE domain_cache_settings SET enabled=:enabled,default_edge_ttl_seconds=:edge,default_browser_ttl_seconds=:browser,cache_query_string_mode=:mode,respect_origin_cache_control=:respect,cache_authorized_requests=:authorized,stale_if_error_seconds=:stale,static_asset_cache_enabled=:static_assets,ignore_query_strings_for_static=:ignore_static_query,bypass_logged_in_users=:bypass_logged_in,cache_methods_json=:methods,cache_status_code_policy_json=:status_policy,bypass_headers_json=:bypass_headers,bypass_cookies_json=:bypass_cookies,vary_headers_json=:vary_headers,cache_key_dimensions_json=:key_dimensions,debug_headers_enabled=:debug_headers,stale_while_revalidate_seconds=:swr,negative_ttl_seconds=:negative_ttl,max_object_size_bytes=:max_object,updated_at=:updated_at WHERE domain_id=:domain_id');
         $u->execute($payload);
         $this->invalidateConfigSnapshot();
         return $this->getDomainCacheSettings($domainId);
     }
+    private function jsonSetting(array $input, array $existing, string $key, string $decodedKey): string {
+        $value = array_key_exists($key, $input) ? $input[$key] : (array_key_exists($decodedKey, $input) ? $input[$decodedKey] : ($existing[$key] ?? ($existing[$decodedKey] ?? null)));
+        if (is_string($value)) {
+            json_decode($value, true);
+            return json_last_error() === JSON_ERROR_NONE ? $value : json_encode($existing[$key] ?? null, JSON_UNESCAPED_SLASHES);
+        }
+        return json_encode($value, JSON_UNESCAPED_SLASHES);
+    }
     public function createCachePurgeRequest(string $domainId, array $in): array {
         $type = (string) ($in['type'] ?? 'domain');
         $value = array_key_exists('value', $in) ? (string) $in['value'] : null;
@@ -1796,7 +1834,7 @@ private function waitingRoomPayload(array $in, bool $partial = false): array {
         }
         return $payload;
     }
-    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=in_array($r[$b], [true, 1, '1', 't', 'true'], true);}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','last_generated_at','last_applied_at','challenge_difficulty','rps_threshold','active_origin_threshold','origin_latency_ms_threshold','origin_error_rate_threshold','admission_rate_per_minute','queue_limit','per_client_ticket_limit','ticket_ttl_seconds','admission_ttl_seconds','status_poll_seconds','jitter_seconds','unhealthy_windows','healthy_windows','minimum_state_seconds','recovery_ramp_percent','manual_override_until'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } if (array_key_exists('trusted_cidrs_json', $r)) { $r['trusted_cidrs'] = json_decode((string) $r['trusted_cidrs_json'], true) ?: []; unset($r['trusted_cidrs_json']); } if (array_key_exists('counters_json', $r)) { $r['counters'] = json_decode((string) $r['counters_json'], true) ?: []; unset($r['counters_json']); } unset($r['private_key_pem']); return $r; }
+    private function cast(array $r): array { foreach(['enabled', 'preserve_query', 'respect_origin_cache_control', 'cache_authorized_requests', 'static_asset_cache_enabled', 'ignore_query_strings_for_static', 'bypass_logged_in_users', 'debug_headers_enabled', 'force_https', 'auto_renew', 'user_modified'] as $b){ if(array_key_exists($b,$r)){$r[$b]=in_array($r[$b], [true, 1, '1', 't', 'true'], true);}} foreach(['created_at','updated_at','ttl_seconds','requests_per_minute','status_code','priority','default_edge_ttl_seconds','default_browser_ttl_seconds','stale_if_error_seconds','stale_while_revalidate_seconds','negative_ttl_seconds','max_object_size_bytes','last_generated_at','last_applied_at','challenge_difficulty','rps_threshold','active_origin_threshold','origin_latency_ms_threshold','origin_error_rate_threshold','admission_rate_per_minute','queue_limit','per_client_ticket_limit','ticket_ttl_seconds','admission_ttl_seconds','status_poll_seconds','jitter_seconds','unhealthy_windows','healthy_windows','minimum_state_seconds','recovery_ramp_percent','manual_override_until'] as $i){ if(isset($r[$i]) && $r[$i] !== null){$r[$i]=(int)$r[$i];}} foreach(['cache_methods_json'=>'cache_methods','cache_status_code_policy_json'=>'cache_status_code_policy','bypass_headers_json'=>'bypass_headers','bypass_cookies_json'=>'bypass_cookies','vary_headers_json'=>'vary_headers','cache_key_dimensions_json'=>'cache_key_dimensions'] as $jsonKey => $outKey) { if (array_key_exists($jsonKey, $r)) { $r[$outKey] = json_decode((string) $r[$jsonKey], true) ?: []; } } if (array_key_exists('actions_json', $r)) { $r['actions'] = json_decode((string) $r['actions_json'], true) ?: []; } if (array_key_exists('trusted_cidrs_json', $r)) { $r['trusted_cidrs'] = json_decode((string) $r['trusted_cidrs_json'], true) ?: []; unset($r['trusted_cidrs_json']); } if (array_key_exists('counters_json', $r)) { $r['counters'] = json_decode((string) $r['counters_json'], true) ?: []; unset($r['counters_json']); } unset($r['private_key_pem']); return $r; }
     private function castSslJob(array $r): array {
         foreach (['created_at', 'updated_at', 'finished_at', 'progress_percent'] as $i) {
             if (isset($r[$i]) && $r[$i] !== null) {
diff --git a/core/database/migrations/000030_phase6_cache_correctness.sql b/core/database/migrations/000030_phase6_cache_correctness.sql
new file mode 100644
index 0000000..e5160bb
--- /dev/null
+++ b/core/database/migrations/000030_phase6_cache_correctness.sql
@@ -0,0 +1,22 @@
+-- Phase 6 cache correctness controls. These fields make cache eligibility,
+-- key variation, stale behavior, and debug output explicit in snapshots.
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS cache_methods_json TEXT NOT NULL DEFAULT '["GET","HEAD"]';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS cache_status_code_policy_json TEXT NOT NULL DEFAULT '{"200":true,"301":true,"302":true,"404":false,"500":false,"502":false,"503":false,"504":false}';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS bypass_headers_json TEXT NOT NULL DEFAULT '["authorization"]';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS bypass_cookies_json TEXT NOT NULL DEFAULT '["session","auth","wordpress_logged_in","laravel_session"]';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS vary_headers_json TEXT NOT NULL DEFAULT '["accept-encoding"]';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS cache_key_dimensions_json TEXT NOT NULL DEFAULT '{"scheme":true,"host":true,"path":true,"query":"include_all","headers":["accept-encoding"],"device":false,"country":false,"language":false,"domain_id":true,"rule_version":true}';
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS debug_headers_enabled BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS stale_while_revalidate_seconds INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS negative_ttl_seconds INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE domain_cache_settings
+  ADD COLUMN IF NOT EXISTS max_object_size_bytes BIGINT NOT NULL DEFAULT 104857600;
diff --git a/core/database/schema.sql b/core/database/schema.sql
index 2859bf5..c517a09 100644
--- a/core/database/schema.sql
+++ b/core/database/schema.sql
@@ -1114,6 +1114,16 @@ CREATE TABLE IF NOT EXISTS domain_cache_settings (
   static_asset_cache_enabled BOOLEAN NOT NULL DEFAULT false,
   ignore_query_strings_for_static BOOLEAN NOT NULL DEFAULT false,
   bypass_logged_in_users BOOLEAN NOT NULL DEFAULT true,
+  cache_methods_json TEXT NOT NULL DEFAULT '["GET","HEAD"]',
+  cache_status_code_policy_json TEXT NOT NULL DEFAULT '{"200":true,"301":true,"302":true,"404":false,"500":false,"502":false,"503":false,"504":false}',
+  bypass_headers_json TEXT NOT NULL DEFAULT '["authorization"]',
+  bypass_cookies_json TEXT NOT NULL DEFAULT '["session","auth","wordpress_logged_in","laravel_session"]',
+  vary_headers_json TEXT NOT NULL DEFAULT '["accept-encoding"]',
+  cache_key_dimensions_json TEXT NOT NULL DEFAULT '{"scheme":true,"host":true,"path":true,"query":"include_all","headers":["accept-encoding"],"device":false,"country":false,"language":false,"domain_id":true,"rule_version":true}',
+  debug_headers_enabled BOOLEAN NOT NULL DEFAULT false,
+  stale_while_revalidate_seconds INTEGER NOT NULL DEFAULT 0,
+  negative_ttl_seconds INTEGER NOT NULL DEFAULT 0,
+  max_object_size_bytes BIGINT NOT NULL DEFAULT 104857600,
   created_at BIGINT NOT NULL,
   updated_at BIGINT NOT NULL
 );
diff --git a/core/tests/test_edge_reliability_stage7_contract.py b/core/tests/test_edge_reliability_stage7_contract.py
index c6c88b6..e9ad3ee 100644
--- a/core/tests/test_edge_reliability_stage7_contract.py
+++ b/core/tests/test_edge_reliability_stage7_contract.py
@@ -26,7 +26,8 @@ def test_stage7_schema_and_request_id_contract():
     assert "local geoip = require('geoip')" in metrics
     assert "client_country" in metrics
     assert "geoip.request_country()" in metrics
-    assert "proxy_ignore_headers X-Accel-Expires;" in nginx
+    assert "proxy_ignore_headers X-Accel-Expires;" not in nginx
+    assert "X-Accel-Expires" in proxy
     assert "security_event_type" in metrics
     assert "security_action" in metrics
     assert "blocked_by_waf" in router
diff --git a/core/tests/test_phase15_performance_starter_contract.py b/core/tests/test_phase15_performance_starter_contract.py
index 44e6d34..39e3ad7 100644
--- a/core/tests/test_phase15_performance_starter_contract.py
+++ b/core/tests/test_phase15_performance_starter_contract.py
@@ -30,7 +30,8 @@ def test_performance_starter_persists_safe_controls_and_enforces_them_at_edge():
     assert "cache_settings.static_asset_cache_enabled == true" in proxy
     assert "cache_settings.ignore_query_strings_for_static == true" in proxy
     assert "cache_settings.bypass_logged_in_users ~= false" in proxy
-    assert "ngx.var.cdnlite_cache_key = table.concat" in proxy
+    assert "local function build_cache_key" in proxy
+    assert "ngx.var.cdnlite_cache_key = cache_key" in proxy
 
 
 def test_performance_starter_has_dashboard_docs_smoke_and_e2e_coverage():
diff --git a/core/tests/test_phase6_cache_correctness_contract.py b/core/tests/test_phase6_cache_correctness_contract.py
new file mode 100644
index 0000000..f38e06a
--- /dev/null
+++ b/core/tests/test_phase6_cache_correctness_contract.py
@@ -0,0 +1,113 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text()
+
+
+def test_phase6_schema_exposes_cache_correctness_controls():
+    migration = read("core/database/migrations/000030_phase6_cache_correctness.sql")
+    schema = read("core/database/schema.sql")
+
+    for field in (
+        "cache_methods_json TEXT NOT NULL DEFAULT '[\"GET\",\"HEAD\"]'",
+        "cache_status_code_policy_json TEXT NOT NULL DEFAULT",
+        "bypass_headers_json TEXT NOT NULL DEFAULT '[\"authorization\"]'",
+        "bypass_cookies_json TEXT NOT NULL DEFAULT",
+        "vary_headers_json TEXT NOT NULL DEFAULT '[\"accept-encoding\"]'",
+        "cache_key_dimensions_json TEXT NOT NULL DEFAULT",
+        "debug_headers_enabled BOOLEAN NOT NULL DEFAULT false",
+        "stale_while_revalidate_seconds INTEGER NOT NULL DEFAULT 0",
+        "negative_ttl_seconds INTEGER NOT NULL DEFAULT 0",
+        "max_object_size_bytes BIGINT NOT NULL DEFAULT 104857600",
+    ):
+        assert field in migration
+        assert field in schema
+
+    assert "DROP TABLE" not in migration
+    assert "TRUNCATE" not in migration
+
+
+def test_migration_versions_are_unique():
+    migrations = sorted((ROOT / "core/database/migrations").glob("*.sql"))
+    versions = [path.name.split("_", 1)[0] for path in migrations]
+    duplicates = sorted({version for version in versions if versions.count(version) > 1})
+    assert duplicates == []
+
+
+def test_phase6_api_snapshot_and_dashboard_surface_safe_cache_model():
+    service = read("core/app/Modules/Proxy/Services/TrafficRulesService.php")
+    config = read("core/app/Modules/Proxy/Services/ConfigService.php")
+    dashboard = read("dash/src/views/domain-tabs/DomainCacheTab.vue")
+    types = read("dash/src/types.ts")
+
+    assert "cache_methods_json" in service
+    assert "cache_key_dimensions_json" in service
+    assert "cache_methods" in service
+    assert "cache_key_dimensions" in service
+    assert "debug_headers_enabled" in service
+    assert "'cache' => $this->rules->getDomainCacheSettings" in config
+    assert "Cache key preview" in dashboard
+    assert "Personalized traffic bypasses by default" in dashboard
+    assert "debug_headers_enabled" in dashboard
+    assert "cache_key_dimensions" in dashboard
+    assert "export interface CacheSettings" in types
+    assert "cache_methods" in types
+    assert "cache_key_dimensions" in types
+
+
+def test_phase6_edge_cache_decisions_are_standards_aware_and_debuggable():
+    proxy = read("edge/openresty/lua/proxy.lua")
+    nginx = read("edge/openresty/nginx.conf")
+
+    for token in (
+        "header_has_cache_directive",
+        "has_logged_in_cookie",
+        "request_has_bypass_header",
+        "build_cache_key",
+        "cache_settings.cache_methods",
+        "cache_settings.vary_headers",
+        "cache_settings.cache_key_dimensions",
+        "bypass_reason",
+        "authorization",
+        "request_cache_control",
+        "geoip.request_country()",
+        "X-Accel-Expires",
+    ):
+        assert token in proxy
+
+    assert "proxy_ignore_headers X-Accel-Expires" not in nginx
+    assert "proxy_cache_lock on" in nginx
+    assert "proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504" in nginx
+    assert "X-CDNLite-Cache" in nginx
+    assert "X-CDNLite-Cache-Reason" in nginx
+    assert "X-CDNLite-Cache-Key" in nginx
+    assert "CDNLITE_EDGE_DEBUG_HEADERS" in nginx
+
+
+def test_phase6_runner_stress_docs_and_e2e_are_registered():
+    phase = read("ci/phase.sh")
+    manifest = read("ci/phases/phase-06.yml")
+    stress = read("ci/stress-platform.sh")
+    scenarios = read("ci/stress/scenarios.yml")
+    e2e = read("ci/e2e.sh")
+    docs = read("docs/api/api.md")
+    roadmap = read("docs/ROADMAP.md")
+    changelog = read("CHANGELOG.md")
+
+    assert "06)" in phase
+    assert "test_phase6_cache_correctness_contract.py" in phase
+    assert "phase6-cache-correctness" in phase
+    assert 'phase: "06"' in manifest
+    assert "phase6-cache-correctness" in manifest
+    assert "phase6-cache-correctness" in stress
+    assert "phase6-cache-correctness" in scenarios
+    assert "edge-cache-basic" in e2e
+    assert "X-CDNLite-Cache-Key" in docs
+    assert "Cache key preview" in docs
+    assert "Phase 6 — Cache correctness foundation" in roadmap
+    assert "| 6. Cache correctness foundation | P0 | Complete |" in roadmap
+    assert "Phase 6 cache correctness" in changelog
diff --git a/dash/src/types.ts b/dash/src/types.ts
index f1ee06c..e8572c0 100644
--- a/dash/src/types.ts
+++ b/dash/src/types.ts
@@ -71,7 +71,7 @@ export interface GeoRoute {
 
 export interface RedirectRule { id: Id; enabled: boolean; source_path: string; target_url: string; status_code: number; priority: number; match_type: string; preserve_query: boolean; }
 export interface PageRule { id: Id; enabled: boolean; pattern?: string; path_pattern?: string; priority: number; actions: Record<string, unknown>; }
-export interface CacheSettings { enabled: boolean; default_edge_ttl_seconds: number; default_browser_ttl_seconds: number | null; cache_query_string_mode: string; respect_origin_cache_control: boolean; cache_authorized_requests: boolean; stale_if_error_seconds: number; static_asset_cache_enabled: boolean; ignore_query_strings_for_static: boolean; bypass_logged_in_users: boolean; }
+export interface CacheSettings { enabled: boolean; default_edge_ttl_seconds: number; default_browser_ttl_seconds: number | null; cache_query_string_mode: string; respect_origin_cache_control: boolean; cache_authorized_requests: boolean; stale_if_error_seconds: number; static_asset_cache_enabled: boolean; ignore_query_strings_for_static: boolean; bypass_logged_in_users: boolean; cache_methods: string[]; cache_status_code_policy: Record<string, boolean>; bypass_headers: string[]; bypass_cookies: string[]; vary_headers: string[]; cache_key_dimensions: Record<string, unknown>; debug_headers_enabled: boolean; stale_while_revalidate_seconds: number; negative_ttl_seconds: number; max_object_size_bytes: number; }
 export interface ManagedRuleMetadata { profile_id?: Id | null; intent_id?: Id | null; template_key?: string | null; managed_by?: string | null; user_modified?: boolean; last_generated_at?: number | null; last_applied_at?: number | null; }
 export type ProtectionRisk = 'safe' | 'moderate' | 'risky' | string;
 export interface ProtectionIntentRecord {
diff --git a/dash/src/views/domain-tabs/DomainCacheTab.vue b/dash/src/views/domain-tabs/DomainCacheTab.vue
index ecfe7ed..6dfa815 100644
--- a/dash/src/views/domain-tabs/DomainCacheTab.vue
+++ b/dash/src/views/domain-tabs/DomainCacheTab.vue
@@ -9,6 +9,7 @@
         <div class="help-item"><b>Best default</b><span>Enable edge cache, respect origin Cache-Control, and use 1 hour TTL for ordinary static assets.</span></div>
         <div class="help-item"><b>Dynamic pages</b><span>Keep sensitive or personalized paths uncached with a short cache rule or origin headers.</span></div>
         <div class="help-item"><b>Stale content</b><span>Use stale-if-error so visitors can still receive cached content during an origin outage.</span></div>
+        <div class="help-item"><b>Personalized traffic bypasses by default</b><span>Authorization, no-cache directives, and common session cookies do not enter cache unless explicitly allowed.</span></div>
       </div>
       <div class="divide-y divide-slate-100 dark:divide-white/5">
         <label class="setting-row border-0 px-0">
@@ -31,10 +32,18 @@
           <span><b>Bypass cache for logged-in users</b><small>Keep pages private when common session or authentication cookies are present.</small></span>
           <input v-model="settings.bypass_logged_in_users" class="toggle" type="checkbox" />
         </label>
+        <label class="setting-row border-0 px-0">
+          <span><b>Debug cache headers</b><small>Expose a sanitized cache key preview and bypass reason at the edge.</small></span>
+          <input v-model="settings.debug_headers_enabled" class="toggle" type="checkbox" />
+        </label>
         <div class="grid gap-4 py-4 md:grid-cols-2">
           <label><span class="field-label">Default edge TTL</span><select v-model.number="settings.default_edge_ttl_seconds" class="input"><option :value="60">1 minute</option><option :value="300">5 minutes</option><option :value="3600">1 hour</option><option :value="14400">4 hours</option><option :value="86400">1 day</option><option :value="604800">7 days</option></select></label>
           <label><span class="field-label">Stale if origin fails</span><select v-model.number="settings.stale_if_error_seconds" class="input"><option :value="0">Disabled</option><option :value="3600">1 hour</option><option :value="86400">1 day</option><option :value="604800">7 days</option></select></label>
         </div>
+        <div class="rounded-md border border-slate-200 bg-slate-50 p-3 text-sm dark:border-white/10 dark:bg-white/5">
+          <b class="block text-slate-900 dark:text-white">Cache key preview</b>
+          <span class="mt-1 block text-slate-600 dark:text-slate-300">{{ cacheKeyPreview }}</span>
+        </div>
       </div>
       <div class="flex items-center justify-end gap-3 border-t border-slate-200 pt-4 dark:border-white/10">
         <p v-if="message" class="mr-auto text-sm text-emerald-700">{{ message }}</p>
@@ -72,7 +81,7 @@
 </template>
 
 <script setup lang="ts">
-import { onMounted, reactive, ref, watch } from 'vue';
+import { computed, onMounted, reactive, ref, watch } from 'vue';
 import { Link2, RefreshCcw, Save, Trash2 } from 'lucide-vue-next';
 import DomainRulesTab from './DomainRulesTab.vue';
 import DataTable from '@/components/ui/DataTable.vue';
@@ -81,7 +90,7 @@ import { cacheApi } from '@/lib/api/cache';
 import { purgeApi } from '@/lib/api/purge';
 
 const props = defineProps<{ domainId: string }>();
-const settings = reactive({ enabled: true, default_edge_ttl_seconds: 3600, default_browser_ttl_seconds: null as number | null, cache_query_string_mode: 'include_all', respect_origin_cache_control: true, cache_authorized_requests: false, stale_if_error_seconds: 86400, static_asset_cache_enabled: false, ignore_query_strings_for_static: false, bypass_logged_in_users: true });
+const settings = reactive({ enabled: true, default_edge_ttl_seconds: 3600, default_browser_ttl_seconds: null as number | null, cache_query_string_mode: 'include_all', respect_origin_cache_control: true, cache_authorized_requests: false, stale_if_error_seconds: 86400, static_asset_cache_enabled: false, ignore_query_strings_for_static: false, bypass_logged_in_users: true, cache_methods: ['GET', 'HEAD'], cache_status_code_policy: { 200: true, 301: true, 302: true }, bypass_headers: ['authorization'], bypass_cookies: ['session', 'auth', 'wordpress_logged_in', 'laravel_session'], vary_headers: ['accept-encoding'], cache_key_dimensions: { scheme: true, host: true, path: true, query: 'include_all', headers: ['accept-encoding'], device: false, country: false, language: false, domain_id: true, rule_version: true } as Record<string, unknown>, debug_headers_enabled: false, stale_while_revalidate_seconds: 0, negative_ttl_seconds: 0, max_object_size_bytes: 104857600 });
 const purges = ref<Record<string, unknown>[]>([]);
 const purgeValue = ref('');
 const purgeType = ref('url');
@@ -91,6 +100,11 @@ const ruleHelpItems = [{ title: 'Prefix examples', body: 'Use /assets/ for stati
 const fields = [{ key: 'enabled', label: 'Enabled', type: 'checkbox' as const, default: true, help: 'Keep disabled while drafting a cache override.' }, { key: 'path_prefix', label: 'Path prefix', default: '/', placeholder: '/assets/', help: 'Match requests whose path starts with this value.' }, { key: 'ttl_seconds', label: 'TTL seconds', type: 'number' as const, default: 3600, placeholder: '3600', help: 'How long matching responses should stay cached at the edge.' }];
 const columns = [{ key: 'enabled', label: 'Status' }, { key: 'path_prefix', label: 'Path' }, { key: 'ttl_seconds', label: 'Edge TTL' }, { key: 'actions', label: '' }];
 const purgeColumns = [{ key: 'type', label: 'Scope' }, { key: 'value', label: 'Target' }, { key: 'status', label: 'Status' }, { key: 'created_at', label: 'Created' }];
+const cacheKeyPreview = computed(() => {
+  const dimensions = settings.cache_key_dimensions || {};
+  const headers = Array.isArray(dimensions.headers) ? dimensions.headers.join(',') : settings.vary_headers.join(',');
+  return `scheme | normalized host | domain id | path | query=${dimensions.query || settings.cache_query_string_mode} | headers=${headers} | rule version`;
+});
 
 async function load() {
   const [currentSettings, currentPurges] = await Promise.all([cacheApi.settings(props.domainId), purgeApi.list(props.domainId)]);
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 44cb7df..ab1d456 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -349,7 +349,7 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | 3. Edge hot-path performance and bounded telemetry | P0 | Complete | No repeated config parsing or synchronous per-request telemetry writes |
 | 4. Real challenge and clearance system | P0 | Complete | Challenge actions serve configurable self-hosted browser verification before origin routing |
 | 5. Adaptive overload protection and waiting room | P0 | Complete | Origins remain protected under attack or heavy usage |
-| 6. Cache correctness foundation | P0 | Planned | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
+| 6. Cache correctness foundation | P0 | Complete | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
 | 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
 | 8. Purge and invalidation platform | P1 | Planned | Fast, safe, observable purge by URL, prefix, host, and tag |
 | 9. Edge protocol and delivery performance | P1 | Planned | Efficient TLS, HTTP/2, optional HTTP/3, compression, and connection reuse |
@@ -1884,6 +1884,8 @@ Add:
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
+**Status:** Complete on 2026-06-28. CDNLite now has explicit cache-method, status-code, bypass-header, bypass-cookie, vary-header, cache-key-dimension, stale, negative-cache, max-object, and safe debug-header controls in the authoritative schema; API and dashboard visibility for cache key previews; edge Lua cache eligibility and normalized key construction; per-rule TTLs honored through `X-Accel-Expires`; consistent `X-CDNLite-Cache` and bypass-reason headers; Phase 6 one-shot manifest and stress scenario registration.
+
 ### Objective
 
 Make cache decisions standards-aware, predictable, testable, and safe before adding more advanced performance features.
diff --git a/docs/api/api.md b/docs/api/api.md
index 1939e66..68de24b 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -510,7 +510,7 @@ Protection intents are the beginner/simple API layer. Preview does not mutate st
 
 API Shield (`protect_api`) generates real advanced rules for `/api/`: IP/path rate limits, `Authorization` header/path limits for token-aware APIs, and `path_method_not_allowed` WAF rules that block unsupported methods only inside the API prefix. The generated method rule uses a pattern such as `/api/:GET,POST,PUT,PATCH,DELETE,OPTIONS`, so advanced users can edit the prefix or method set without losing ownership metadata.
 
-Cache settings additionally support `static_asset_cache_enabled`, `ignore_query_strings_for_static`, and `bypass_logged_in_users`. Static caching covers CSS, JavaScript, common image formats, fonts, MP4, and PDF. When enabled, query-string stripping applies only to those static extensions; common session/authentication cookies always bypass cache by default.
+Cache settings additionally support `static_asset_cache_enabled`, `ignore_query_strings_for_static`, `bypass_logged_in_users`, `cache_methods`, `cache_status_code_policy`, `bypass_headers`, `bypass_cookies`, `vary_headers`, `cache_key_dimensions`, `debug_headers_enabled`, `stale_while_revalidate_seconds`, `negative_ttl_seconds`, and `max_object_size_bytes`. Static caching covers CSS, JavaScript, common image formats, fonts, MP4, and PDF. When enabled, query-string stripping applies only to those static extensions; common session/authentication cookies always bypass cache by default.
 
 Protection profiles are one-click bundles over the same intent engine. One-click profiles compose protection intents for Basic Website, WordPress, API, SaaS App, E-commerce, and Emergency Protection presets. Preview returns the per-intent generated rules without mutating state. Apply creates or updates a profile record, enables the profile-owned intents, writes profile/audit history, stores rollback points, and invalidates edge config. Disable turns off the generated rules for intents owned by that profile while preserving the underlying advanced rules for inspection and rollback.
 
@@ -556,6 +556,8 @@ Cache tips:
 
 - Prefer `url` or `prefix` purges over `everything`.
 - Use short TTLs while validating an origin migration.
+- Use the dashboard Cache key preview to confirm bounded key dimensions before adding country, language, or header variation.
+- Enable debug cache headers only during diagnosis. `X-CDNLite-Cache-Key` is sanitized and omits secrets, while `X-CDNLite-Cache-Reason` explains safe bypasses such as authorization, cookie, method, or request cache-control.
 - Check cache analytics after rule changes; a sudden hit-ratio drop usually means a bypass condition was introduced.
 - Requests with authorization or explicit no-cache headers should not be used to judge normal cache behavior.
 
diff --git a/docs/security.md b/docs/security.md
index 610eae5..759e5e3 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -210,14 +210,17 @@ In production, put both the dashboard and the CDNLite API behind real authentica
 The edge runtime bypasses cache storage and lookup when request risk is high:
 - Non-`GET`/`HEAD` methods set cache bypass.
 - `Authorization` header sets cache bypass.
+- Configured bypass headers and common session/authentication cookies set cache bypass.
 - `Cache-Control: no-cache` or `no-store` sets cache bypass.
 
 When domain cache is enabled, ordinary `GET`/`HEAD` responses use the domain
 default edge TTL while no path-specific cache rules exist. Once one or more
 cache rules are enabled for a host, those rules become an allowlist: matching
-paths use their rule TTL and non-matching paths bypass cache. Upstream
-`X-Accel-Expires` is ignored at the CDNLite edge so origin-local nginx
-directives do not accidentally disable CDN caching for an entire site.
+paths use their rule TTL and non-matching paths bypass cache. Lua sets
+`X-Accel-Expires` from the matched rule or domain default so Nginx honors the
+selected freshness lifetime. Debug cache headers are opt-in through
+`CDNLITE_EDGE_DEBUG_HEADERS` and expose only sanitized key dimensions and bypass
+reasons.
 
 Edge access logs are JSON lines on stdout and edge diagnostics are emitted to
 stderr. They include request ids and safe routing metadata, but must not include
diff --git a/docs/setup.md b/docs/setup.md
index d22adc0..10ecb6e 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -223,6 +223,7 @@ Edge and agent settings:
 | `METRIC_PATH` | Metrics queue file for the agent. |
 | `SECURITY_EVENT_PATH` | Security event queue file for the agent. |
 | `CDNLITE_CACHE_DEFAULT_TTL` | Default OpenResty cache TTL. |
+| `CDNLITE_EDGE_DEBUG_HEADERS` | Set to `1` to expose sanitized cache key and bypass reason headers during diagnosis. |
 | `CDNLITE_EDGE_WORKER_PROCESSES`, `CDNLITE_EDGE_WORKER_CONNECTIONS` | OpenResty worker capacity. Defaults are `auto` and `4096`. |
 | `CDNLITE_EDGE_LIMITS_DICT_SIZE`, `CDNLITE_EDGE_REQUEST_CONTEXT_DICT_SIZE`, `CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE`, `CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE` | Shared memory budgets for rate limits, request context, metrics, and security-event queues. |
 | `CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE`, `CDNLITE_EDGE_WAITING_ROOM_SECRET` | Shared-memory budget and signing secret for local waiting-room queue tickets and admission cookies. Initial queues are local to each edge node and are not globally fair across nodes. |
diff --git a/edge/openresty/lua/proxy.lua b/edge/openresty/lua/proxy.lua
index db3bd72..08d9d84 100644
--- a/edge/openresty/lua/proxy.lua
+++ b/edge/openresty/lua/proxy.lua
@@ -35,6 +35,54 @@ local function has_logged_in_cookie(value)
     or value:find('%f[%w]laravel_session%s*=') ~= nil
 end
 
+local function list_contains(list, needle)
+  if type(list) ~= 'table' then return false end
+  needle = string.lower(tostring(needle or ''))
+  for _, value in ipairs(list) do
+    if string.lower(tostring(value)) == needle then return true end
+  end
+  return false
+end
+
+local function request_has_bypass_header(headers)
+  if type(headers) ~= 'table' then return nil end
+  for _, name in ipairs(headers) do
+    local value = ngx.req.get_headers()[tostring(name):lower()]
+    if value and tostring(value) ~= '' then return tostring(name):lower() end
+  end
+  return nil
+end
+
+local function cache_key_part(name, value)
+  value = tostring(value or '')
+  return name .. '=' .. ngx.escape_uri(value)
+end
+
+local function build_cache_key(domain, cache_settings, cache_rule, static_asset)
+  local dimensions = cache_settings.cache_key_dimensions or {}
+  local parts = {}
+  if dimensions.scheme ~= false then table.insert(parts, cache_key_part('scheme', ngx.var.scheme)) end
+  if dimensions.host ~= false then table.insert(parts, cache_key_part('host', string.lower(ngx.var.host or ''))) end
+  if dimensions.domain_id ~= false then table.insert(parts, cache_key_part('domain', domain.domain_id)) end
+  if dimensions.path ~= false then table.insert(parts, cache_key_part('path', ngx.var.uri or '/')) end
+
+  local query_mode = dimensions.query or cache_settings.cache_query_string_mode or 'include_all'
+  if static_asset and cache_settings.ignore_query_strings_for_static == true then query_mode = 'ignore' end
+  if query_mode == 'include_all' then table.insert(parts, cache_key_part('query', ngx.var.args or '')) end
+
+  local headers = dimensions.headers or cache_settings.vary_headers or {'accept-encoding'}
+  for _, header in ipairs(headers) do
+    local header_name = string.lower(tostring(header))
+    if header_name ~= 'authorization' and header_name ~= 'cookie' then
+      table.insert(parts, cache_key_part('h.' .. header_name, ngx.req.get_headers()[header_name] or ''))
+    end
+  end
+  if dimensions.country == true then table.insert(parts, cache_key_part('country', geoip.request_country())) end
+  if dimensions.language == true then table.insert(parts, cache_key_part('lang', ngx.var.http_accept_language or '')) end
+  if dimensions.rule_version ~= false then table.insert(parts, cache_key_part('rule', (cache_rule and cache_rule.id) or 'default')) end
+  return table.concat(parts, '|'), table.concat(parts, '; ')
+end
+
 function M.forward(domain)
   local upstream = ngx.ctx.upstream or domain.upstream
   if not upstream then
@@ -48,6 +96,7 @@ function M.forward(domain)
   local cache_rule = ngx.ctx.cache_rule
   local cache_rules_enabled = ngx.ctx.cache_rules_enabled == true
   local static_asset = is_static_asset(ngx.var.uri)
+  local bypass_reason = nil
   local edge_ttl = nil
   if cache_rule and tonumber(cache_rule.ttl_seconds) and tonumber(cache_rule.ttl_seconds) > 0 then
     edge_ttl = math.floor(tonumber(cache_rule.ttl_seconds))
@@ -62,26 +111,44 @@ function M.forward(domain)
   if method ~= 'GET' and method ~= 'HEAD' then
     cache_bypass = true
     cache_no_store = true
+    bypass_reason = 'method'
+  end
+
+  if type(cache_settings.cache_methods) == 'table' and not list_contains(cache_settings.cache_methods, method) then
+    cache_bypass = true
+    cache_no_store = true
+    bypass_reason = bypass_reason or 'method_policy'
   end
 
   if cache_settings.enabled == false or not edge_ttl then
     cache_bypass = true
     cache_no_store = true
+    bypass_reason = bypass_reason or 'disabled_or_no_ttl'
   end
 
   if cache_settings.cache_authorized_requests ~= true and ngx.var.http_authorization and ngx.var.http_authorization ~= '' then
     cache_bypass = true
     cache_no_store = true
+    bypass_reason = bypass_reason or 'authorization'
   end
 
   if cache_settings.bypass_logged_in_users ~= false and has_logged_in_cookie(ngx.var.http_cookie) then
     cache_bypass = true
     cache_no_store = true
+    bypass_reason = bypass_reason or 'cookie'
+  end
+
+  local bypass_header = request_has_bypass_header(cache_settings.bypass_headers)
+  if bypass_header and bypass_header ~= 'authorization' then
+    cache_bypass = true
+    cache_no_store = true
+    bypass_reason = bypass_reason or ('header:' .. bypass_header)
   end
 
   if header_has_cache_directive(ngx.var.http_cache_control) then
     cache_bypass = true
     cache_no_store = true
+    bypass_reason = bypass_reason or 'request_cache_control'
   end
 
   ngx.var.target_upstream = upstream
@@ -115,11 +182,10 @@ function M.forward(domain)
   end
   ngx.var.cdnlite_cache_bypass = cache_bypass and '1' or '0'
   ngx.var.cdnlite_cache_no_store = cache_no_store and '1' or '0'
-  local cache_uri = ngx.var.request_uri or ngx.var.uri or '/'
-  if static_asset and cache_settings.ignore_query_strings_for_static == true then
-    cache_uri = ngx.var.uri or '/'
-  end
-  ngx.var.cdnlite_cache_key = table.concat({ngx.var.scheme or '', ngx.var.host or '', cache_uri, ngx.var.http_accept_encoding or '', geoip.request_country()}, '|')
+  local cache_key, cache_debug = build_cache_key(domain, cache_settings, cache_rule, static_asset)
+  ngx.var.cdnlite_cache_key = cache_key
+  ngx.var.cdnlite_cache_debug = cache_debug
+  ngx.var.cdnlite_cache_bypass_reason = bypass_reason or ''
   if edge_ttl and not cache_no_store then
     ngx.header['X-Accel-Expires'] = tostring(edge_ttl)
   end
diff --git a/edge/openresty/nginx.conf b/edge/openresty/nginx.conf
index 23ccb39..419773f 100644
--- a/edge/openresty/nginx.conf
+++ b/edge/openresty/nginx.conf
@@ -81,6 +81,8 @@ http {
     set $cdnlite_cache_bypass 0;
     set $cdnlite_cache_no_store 0;
     set $cdnlite_cache_key "$scheme|$host|$request_uri|$http_accept_encoding|DEFAULT";
+    set $cdnlite_cache_debug '';
+    set $cdnlite_cache_bypass_reason '';
 
     location = /health {
       default_type application/json;
@@ -182,6 +184,9 @@ http {
       header_filter_by_lua_block {
         local metrics = require('metrics')
         metrics.on_header()
+        ngx.header['X-CDNLite-Cache'] = ngx.var.cdnlite_cache_bypass == '1' and 'BYPASS' or (ngx.var.upstream_cache_status or 'MISS')
+        if ngx.var.cdnlite_cache_bypass_reason ~= '' then ngx.header['X-CDNLite-Cache-Reason'] = ngx.var.cdnlite_cache_bypass_reason end
+        if os.getenv('CDNLITE_EDGE_DEBUG_HEADERS') == '1' then ngx.header['X-CDNLite-Cache-Key'] = ngx.var.cdnlite_cache_debug end
         local header_rules = require('header_rules')
         header_rules.apply()
       }
@@ -195,7 +200,6 @@ http {
       proxy_cache_key $cdnlite_cache_key;
       proxy_cache_methods GET HEAD;
       proxy_cache_valid 200 301 302 __CDNLITE_CACHE_DEFAULT_TTL__;
-      proxy_ignore_headers X-Accel-Expires;
       proxy_cache_bypass $cdnlite_cache_bypass;
       proxy_no_cache $cdnlite_cache_no_store;
       proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
@@ -215,6 +219,9 @@ http {
       header_filter_by_lua_block {
         local metrics = require('metrics')
         metrics.on_header()
+        ngx.header['X-CDNLite-Cache'] = ngx.var.cdnlite_cache_bypass == '1' and 'BYPASS' or (ngx.var.upstream_cache_status or 'MISS')
+        if ngx.var.cdnlite_cache_bypass_reason ~= '' then ngx.header['X-CDNLite-Cache-Reason'] = ngx.var.cdnlite_cache_bypass_reason end
+        if os.getenv('CDNLITE_EDGE_DEBUG_HEADERS') == '1' then ngx.header['X-CDNLite-Cache-Key'] = ngx.var.cdnlite_cache_debug end
         local header_rules = require('header_rules')
         header_rules.apply()
       }
@@ -228,7 +235,6 @@ http {
       proxy_cache_key $cdnlite_cache_key;
       proxy_cache_methods GET HEAD;
       proxy_cache_valid 200 301 302 __CDNLITE_CACHE_DEFAULT_TTL__;
-      proxy_ignore_headers X-Accel-Expires;
       proxy_cache_bypass $cdnlite_cache_bypass;
       proxy_no_cache $cdnlite_cache_no_store;
       proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
@@ -266,6 +272,8 @@ http {
     set $cdnlite_cache_bypass 0;
     set $cdnlite_cache_no_store 0;
     set $cdnlite_cache_key "$scheme|$host|$request_uri|$http_accept_encoding|DEFAULT";
+    set $cdnlite_cache_debug '';
+    set $cdnlite_cache_bypass_reason '';
 
     location = /__cdnlite_error_page {
       internal;
@@ -307,6 +315,9 @@ http {
       header_filter_by_lua_block {
         local metrics = require('metrics')
         metrics.on_header()
+        ngx.header['X-CDNLite-Cache'] = ngx.var.cdnlite_cache_bypass == '1' and 'BYPASS' or (ngx.var.upstream_cache_status or 'MISS')
+        if ngx.var.cdnlite_cache_bypass_reason ~= '' then ngx.header['X-CDNLite-Cache-Reason'] = ngx.var.cdnlite_cache_bypass_reason end
+        if os.getenv('CDNLITE_EDGE_DEBUG_HEADERS') == '1' then ngx.header['X-CDNLite-Cache-Key'] = ngx.var.cdnlite_cache_debug end
         local header_rules = require('header_rules')
         header_rules.apply()
       }
@@ -318,7 +329,6 @@ http {
       proxy_cache_key $cdnlite_cache_key;
       proxy_cache_methods GET HEAD;
       proxy_cache_valid 200 301 302 __CDNLITE_CACHE_DEFAULT_TTL__;
-      proxy_ignore_headers X-Accel-Expires;
       proxy_cache_bypass $cdnlite_cache_bypass;
       proxy_no_cache $cdnlite_cache_no_store;
       proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
@@ -338,6 +348,9 @@ http {
       header_filter_by_lua_block {
         local metrics = require('metrics')
         metrics.on_header()
+        ngx.header['X-CDNLite-Cache'] = ngx.var.cdnlite_cache_bypass == '1' and 'BYPASS' or (ngx.var.upstream_cache_status or 'MISS')
+        if ngx.var.cdnlite_cache_bypass_reason ~= '' then ngx.header['X-CDNLite-Cache-Reason'] = ngx.var.cdnlite_cache_bypass_reason end
+        if os.getenv('CDNLITE_EDGE_DEBUG_HEADERS') == '1' then ngx.header['X-CDNLite-Cache-Key'] = ngx.var.cdnlite_cache_debug end
         local header_rules = require('header_rules')
         header_rules.apply()
       }
@@ -349,7 +362,6 @@ http {
       proxy_cache_key $cdnlite_cache_key;
       proxy_cache_methods GET HEAD;
       proxy_cache_valid 200 301 302 __CDNLITE_CACHE_DEFAULT_TTL__;
-      proxy_ignore_headers X-Accel-Expires;
       proxy_cache_bypass $cdnlite_cache_bypass;
       proxy_no_cache $cdnlite_cache_no_store;
       proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;

From e08c3c9f7e56cc8963db8b2592e36cfd86d2bc40 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 11:26:47 +0330
Subject: [PATCH 10/11] feat: Complete Phase 7 - Origin routing, resilience,
 and shielding

- Marked Phase 7 as complete in the roadmap with detailed status and tracking information.
- Updated API documentation to reflect changes in origin roles and added new health observation endpoints.
- Enhanced architecture documentation to clarify origin routing and health observation mechanisms.
- Modified CDN setup instructions to use 'primary' role for origins instead of 'origin'.
- Adjusted examples to align with new origin role definitions.
- Improved troubleshooting documentation to include guidance on drained origins and health checks.
- Updated error handling and metrics logging in OpenResty Lua scripts to reflect new origin roles and health checks.
- Implemented origin selection logic to prioritize primary origins and handle backups appropriately.
- Added new database migration for Phase 7, introducing resilience controls and health observation tables.
- Created tests to validate new origin resilience features and ensure API and schema consistency.
- Introduced an origin health checker to actively monitor and report origin health status.
---
 CHANGELOG.md                                  |   1 +
 ci/e2e.sh                                     |  10 +
 ci/phase.sh                                   |   4 +
 ci/phases/phase-07.yml                        |  58 +++++
 ci/smoke.sh                                   |   2 +-
 ci/stress-platform.sh                         |  36 ++-
 ci/stress/scenarios.yml                       |  15 ++
 .../Http/Controllers/CollectorController.php  |   5 +
 .../Collector/Services/CollectorService.php   | 215 ++++++++++++++++++
 .../Http/Controllers/OriginController.php     |  32 ++-
 .../Modules/Proxy/Services/ConfigService.php  |  68 +++++-
 .../Proxy/Services/OriginHealthService.php    |  98 ++++++--
 .../000031_phase7_origin_resilience.sql       |  60 +++++
 core/database/schema.sql                      |  53 ++++-
 core/public_index.php                         |   1 +
 core/tests/test_hardening_contract.py         |   2 +-
 .../test_origin_health_phase19_contract.py    |  11 +-
 .../test_phase7_origin_resilience_contract.py | 136 +++++++++++
 dash/src/lib/api/origins.ts                   |   5 +-
 dash/src/types.ts                             |  27 ++-
 .../views/domain-tabs/DomainOriginsTab.vue    |  56 ++++-
 docs/ROADMAP.md                               |  31 ++-
 docs/api/api.md                               |  35 ++-
 docs/architecture.md                          |  20 +-
 docs/cdn-in-a-minute.md                       |   2 +-
 docs/examples/index.md                        |   2 +-
 docs/troubleshooting.md                       |  16 +-
 edge/openresty/lua/error_page.lua             |   2 +-
 edge/openresty/lua/metrics.lua                |   2 +-
 edge/openresty/lua/origin_health_checker.lua  | 128 +++++++++++
 edge/openresty/lua/origin_selector.lua        |  87 +++++--
 edge/openresty/lua/proxy.lua                  |  14 +-
 edge/openresty/nginx.conf                     |   4 +
 33 files changed, 1153 insertions(+), 85 deletions(-)
 create mode 100644 ci/phases/phase-07.yml
 create mode 100644 core/database/migrations/000031_phase7_origin_resilience.sql
 create mode 100644 core/tests/test_phase7_origin_resilience_contract.py
 create mode 100644 edge/openresty/lua/origin_health_checker.lua

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9a75108..2992401 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Phase 4 real challenge and clearance system for WAF, rate-limit, and Emergency Protection flows, including a self-hosted browser verification page, per-rule challenge difficulty, edge-only verification endpoint, scoped HttpOnly clearance cookies, block-rule precedence, edge secret and difficulty fallback configuration, one-shot phase manifest, e2e coverage, and stress scenario registration.
 - Phase 5 waiting room with persisted per-domain policy, API and dashboard controls, signed edge queue tickets, signed admission cookies, local queue/status endpoints, bounded edge queue state, and operator documentation.
 - Phase 6 cache correctness with explicit eligibility and key-dimension settings, safe debug headers, personalized-request bypass defaults, per-rule edge TTL honoring, cache-status headers, a one-shot phase manifest, and stress scenario registration.
+- Phase 7 origin routing resilience with primary, backup, and shield roles, deterministic weighted selection, drain controls, bounded idempotent retry metadata, circuit-breaker settings, shield visibility, edge-sourced origin health observations, per-edge latency and jitter reporting, one-shot phase manifest, and stress scenario registration.
 - Single canonical roadmap at `docs/ROADMAP.md`; removed duplicate root, lower-case, and legacy roadmap files.
 - Repository-level project presentation, contribution, security, roadmap, changelog, issue template, and pull request template documentation.
 
diff --git a/ci/e2e.sh b/ci/e2e.sh
index 916b91c..5bb6ab5 100755
--- a/ci/e2e.sh
+++ b/ci/e2e.sh
@@ -952,6 +952,16 @@ assert_contains "$origin_unchecked_unhealthy_body" '"origin_scheme":"http"' "unc
 assert_contains "$origin_unchecked_unhealthy_body" "\"origin_host\":\"${TEST_DOMAIN}\"" "unchecked unhealthy origin should still preserve requested Host"
 record_step PASS "origin-health-disabled-still-routes" "core health_status=unhealthy did not block edge traffic when health_check_enabled=false"
 
+edge_api POST "/api/v1/collector/usage" "{\"idempotency_key\":\"e2e-${RUN_KEY}-origin-health\",\"items\":[{\"ts\":$(date +%s),\"domain_id\":\"${DOMAIN_ID}\",\"edge_node_id\":\"${EDGE_ID}\",\"requests_count\":0,\"bytes_in\":0,\"bytes_out\":0,\"status\":200,\"method\":\"HEALTH\",\"path\":\"/health\",\"host\":\"${TEST_DOMAIN}\",\"origin_id\":\"${PRIMARY_ORIGIN_ID}\",\"origin_host\":\"${ORIGIN_HTTP_IP}\",\"upstream_status\":\"200\",\"upstream_response_time\":\"3.250\",\"router_error\":\"\",\"origin_health_probe\":true},{\"ts\":$(date +%s),\"domain_id\":\"${DOMAIN_ID}\",\"edge_node_id\":\"${EDGE_ID}\",\"requests_count\":0,\"bytes_in\":0,\"bytes_out\":0,\"status\":200,\"method\":\"HEALTH\",\"path\":\"/health\",\"host\":\"${TEST_DOMAIN}\",\"origin_id\":\"${PRIMARY_ORIGIN_ID}\",\"origin_host\":\"${ORIGIN_HTTP_IP}\",\"upstream_status\":\"200\",\"upstream_response_time\":\"1.000\",\"router_error\":\"\",\"origin_health_probe\":true}]}"
+assert_http_status "$HTTP_CODE" "200" "edge origin health observation ingest failed"
+api_get "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/origins/health"
+assert_http_status "$HTTP_CODE" "200" "origin health report failed"
+assert_contains "$HTTP_BODY" '"source":"edge_observations"' "origin health report should be edge-sourced"
+assert_contains "$HTTP_BODY" '"core_active_checks":false' "core active checks should not be authoritative"
+assert_contains "$HTTP_BODY" '"status":"slow"' "slow origin observation should be visible"
+assert_contains "$HTTP_BODY" '"jitter_ms":2250' "origin jitter should be derived from edge observations"
+record_step PASS "origin-health-edge-observations" "edge-sourced origin health report includes slow and jitter details"
+
 ORIGIN_TLS_IP="$(docker compose exec -T edge sh -lc "getent hosts origin-tls | awk '{print \$1; exit}'" | tr -d '\r')"
 if [[ -z "$ORIGIN_TLS_IP" ]]; then
   fail "unable to resolve origin-tls container IP from edge"
diff --git a/ci/phase.sh b/ci/phase.sh
index 5b7c485..9f90f2c 100755
--- a/ci/phase.sh
+++ b/ci/phase.sh
@@ -60,6 +60,10 @@ case "$PHASE" in
     PHASE_CONTRACT="core/tests/test_phase6_cache_correctness_contract.py"
     PHASE_STRESS_SCENARIO="phase6-cache-correctness"
     ;;
+  07)
+    PHASE_CONTRACT="core/tests/test_phase7_origin_resilience_contract.py"
+    PHASE_STRESS_SCENARIO="phase7-origin-resilience"
+    ;;
   *)
     fail "phase ${PHASE} is not registered yet"
     ;;
diff --git a/ci/phases/phase-07.yml b/ci/phases/phase-07.yml
new file mode 100644
index 0000000..c4252fd
--- /dev/null
+++ b/ci/phases/phase-07.yml
@@ -0,0 +1,58 @@
+phase: "07"
+name: "Origin routing, resilience, and shielding"
+owner: "CDNLite maintainers"
+status: "complete"
+topology: "root docker-compose.yml"
+profiles:
+  pr:
+    clean_required: false
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests/test_phase7_origin_resilience_contract.py"
+      - "luac -p edge/openresty/lua/origin_selector.lua edge/openresty/lua/proxy.lua edge/openresty/lua/router.lua"
+      - "bash -n ci/smoke.sh"
+  full:
+    clean_required: true
+    destructive: false
+    commands:
+      - "docker compose config --quiet"
+      - "find core -name '*.php' -print0 | xargs -0 -n1 php -l"
+      - "pytest -q core/tests"
+      - "sh -n edge/agent/register.sh"
+      - "sh -n edge/agent/heartbeat.sh"
+      - "sh -n edge/agent/pull_config.sh"
+      - "sh -n edge/agent/push_metrics.sh"
+      - "sh -n edge/agent/run.sh"
+      - "bash -n ci/smoke.sh"
+      - "bash -n ci/e2e.sh"
+      - "bash -n ci/stress-platform.sh"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "ci/stress-platform.sh --scenario phase7-origin-resilience"
+      - "ci/smoke.sh"
+      - "ci/e2e.sh"
+      - "(cd dash && npm run typecheck && npm test && npm run build)"
+      - "(cd docs && npm run docs:build)"
+  release:
+    clean_required: true
+    destructive: true
+    commands:
+      - "./ci/phase.sh 07 --profile full --clean"
+required_docs:
+  - "docs/ROADMAP.md"
+  - "docs/api/api.md"
+  - "docs/architecture.md"
+  - "docs/troubleshooting.md"
+  - "CHANGELOG.md"
+evidence:
+  json: "ci/reports/phase-07-report.json"
+  markdown: "ci/reports/phase-07-report.md"
+stress_scenarios:
+  - "phase7-origin-resilience"
+recovery_assertions:
+  - "Primary origins are selected before backups while eligible."
+  - "Drained origins are removed from snapshots and edge candidate pools."
+  - "Non-idempotent requests do not receive automatic retry attempts."
+  - "Origin health status comes from edge observations, not scheduled core probes."
diff --git a/ci/smoke.sh b/ci/smoke.sh
index 1f165e2..42d500a 100755
--- a/ci/smoke.sh
+++ b/ci/smoke.sh
@@ -67,7 +67,7 @@ assert_contains "$dashboard_asset" "/onboarding/answers" "dashboard bundle shoul
 assert_contains "$dashboard_asset" "Simple view" "dashboard bundle should include beginner Activity toggle"
 assert_contains "$dashboard_asset" "Beginner Activity summary" "dashboard bundle should include beginner Activity summary"
 assert_contains "$dashboard_asset" "Advanced view" "dashboard bundle should preserve advanced Activity view"
-assert_contains "$dashboard_asset" "Enable health check for this origin" "dashboard bundle should include optional origin health-check toggle"
+assert_contains "$dashboard_asset" "Enable edge health routing" "dashboard bundle should include optional edge origin health toggle"
 record_step PASS "dashboard-security-center-bundle" "Security Center and Protection profile/intent APIs are present in the dashboard bundle"
 record_step PASS "dashboard-recommendations-bundle" "Recommendation panel and APIs are present in the dashboard bundle"
 record_step PASS "dashboard-onboarding-bundle" "Guided onboarding wizard and APIs are present in the dashboard bundle"
diff --git a/ci/stress-platform.sh b/ci/stress-platform.sh
index de987eb..1398cc0 100755
--- a/ci/stress-platform.sh
+++ b/ci/stress-platform.sh
@@ -17,7 +17,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 case "$SCENARIO" in
-  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance|phase5-waiting-room|phase6-cache-correctness) ;;
+  phase1-reporting-foundation|phase2-analytics-async|phase3-edge-hot-path|phase4-challenge-clearance|phase5-waiting-room|phase6-cache-correctness|phase7-origin-resilience) ;;
   *) fail "unknown stress scenario: ${SCENARIO}" ;;
 esac
 
@@ -32,6 +32,40 @@ wait_for_postgres
 retry 30 1 db_query "SELECT 1;" >/dev/null
 record_step PASS "postgres-ready" "PostgreSQL accepted stress-platform connection"
 
+if [[ "$SCENARIO" == "phase7-origin-resilience" ]]; then
+  origin_columns="$(db_query "SELECT COUNT(*) FROM information_schema.columns WHERE table_schema='public' AND table_name='domain_origins' AND column_name IN ('load_balancing_algorithm','connection_timeout_seconds','response_timeout_seconds','retry_attempts','retry_budget_per_minute','circuit_breaker_enabled','circuit_failure_threshold','circuit_recovery_seconds','max_concurrent_requests','drain','shield_enabled');")"
+  assert_eq "$origin_columns" "11" "Phase 7 origin resilience columns are incomplete"
+  record_step PASS "phase7-origin-columns" "origin resilience columns are present"
+
+  observation_columns="$(db_query "SELECT COUNT(*) FROM information_schema.columns WHERE table_schema='public' AND table_name='origin_health_observations' AND column_name IN ('domain_id','origin_id','edge_node_id','status','reason','upstream_status','latency_ms','jitter_ms','sample_count','last_observed_at','last_success_at','last_failure_at');")"
+  assert_eq "$observation_columns" "12" "Phase 7 origin health observation columns are incomplete"
+  record_step PASS "phase7-origin-observation-columns" "edge origin health observation columns are present"
+
+  grep -Fq "weighted_pick" edge/openresty/lua/origin_selector.lua
+  grep -Fq "healthy_backup" edge/openresty/lua/origin_selector.lua
+  grep -Fq "origin.drain ~= true" edge/openresty/lua/origin_selector.lua
+  record_step PASS "phase7-edge-selection" "edge selector has weighted primary/backup/drain behavior"
+
+  grep -Fq "X-CDNLite-Origin-Retry-Attempts" edge/openresty/lua/proxy.lua
+  grep -Fq "method ~= 'GET' and method ~= 'HEAD'" edge/openresty/lua/proxy.lua
+  grep -Fq "X-CDNLite-Origin-Circuit-Breaker" edge/openresty/lua/proxy.lua
+  record_step PASS "phase7-retry-circuit-metadata" "edge exposes bounded retry and circuit metadata"
+
+  grep -Fq "origin_health_checker" edge/openresty/nginx.conf
+  grep -Fq "origin_health_probe = true" edge/openresty/lua/origin_health_checker.lua
+  grep -Fq "health_check_enabled == true" edge/openresty/lua/origin_health_checker.lua
+  record_step PASS "phase7-edge-origin-health-checker" "edge active origin checker is enabled for monitored origins"
+
+  if compose_has_service edge; then
+    ready_body="$(curl -fsS "${EDGE_URL:-http://localhost:8081}/ready")"
+    assert_contains "$ready_body" "\"ok\":true" "edge must be ready before origin resilience validation"
+    record_step PASS "phase7-edge-ready" "edge readiness confirmed before origin resilience validation"
+  fi
+
+  record_step PASS "phase7-origin-recovery" "post-stress smoke/e2e gates verify routing recovery in full profile"
+  exit 0
+fi
+
 if [[ "$SCENARIO" == "phase6-cache-correctness" ]]; then
   cache_columns="$(db_query "SELECT COUNT(*) FROM information_schema.columns WHERE table_schema='public' AND table_name='domain_cache_settings' AND column_name IN ('cache_methods_json','cache_status_code_policy_json','bypass_headers_json','bypass_cookies_json','vary_headers_json','cache_key_dimensions_json','debug_headers_enabled','stale_while_revalidate_seconds','negative_ttl_seconds','max_object_size_bytes');")"
   assert_eq "$cache_columns" "10" "Phase 6 cache correctness columns are incomplete"
diff --git a/ci/stress/scenarios.yml b/ci/stress/scenarios.yml
index c5e7776..4cc8cb8 100644
--- a/ci/stress/scenarios.yml
+++ b/ci/stress/scenarios.yml
@@ -81,3 +81,18 @@ scenarios:
       - "authenticated and no-cache requests bypass by default"
       - "sanitized cache key debug contains bounded dimensions"
       - "post-stress smoke and e2e gates run after cache pressure"
+  phase7-origin-resilience:
+    phase: "07"
+    workload: "origin-routing-resilience"
+    description: "Validate primary/backup weighted routing metadata, drain exclusion, edge-origin health observations, bounded idempotent retry metadata, and circuit/shield visibility."
+    stress:
+      origin_pool_size: 12
+      weighted_selection: true
+      backup_failover: true
+      drained_origins: true
+      non_idempotent_retry_block: true
+      edge_origin_health_observations: true
+    recovery:
+      - "primary origins win before backups while eligible"
+      - "drained origins are excluded from snapshots and edge pools"
+      - "post-stress smoke/e2e gates verify recovery after routing pressure"
diff --git a/core/app/Modules/Collector/Http/Controllers/CollectorController.php b/core/app/Modules/Collector/Http/Controllers/CollectorController.php
index 2bb25fd..c8f2706 100644
--- a/core/app/Modules/Collector/Http/Controllers/CollectorController.php
+++ b/core/app/Modules/Collector/Http/Controllers/CollectorController.php
@@ -120,6 +120,11 @@ public function activitySummary(string $domainId, array $query): array
         return ['data' => $this->service->activitySummary($domainId, $query)];
     }
 
+    public function originHealth(string $domainId): array
+    {
+        return ['data' => $this->service->originHealth($domainId)];
+    }
+
     public function findRequest(string $domainId, string $requestId): array
     {
         $requestId = trim($requestId);
diff --git a/core/app/Modules/Collector/Services/CollectorService.php b/core/app/Modules/Collector/Services/CollectorService.php
index c6f185d..7063a37 100644
--- a/core/app/Modules/Collector/Services/CollectorService.php
+++ b/core/app/Modules/Collector/Services/CollectorService.php
@@ -122,6 +122,7 @@ public function ingest(array $items, ?string $idempotencyKey = null): array
                     $params[':security_event_type'] = isset($item['security_event_type']) ? (string) $item['security_event_type'] : null;
                 }
                 $stmt->execute($params);
+                $this->recordOriginObservation($domainId, $item, $now);
                 $count++;
             }
 
@@ -151,6 +152,63 @@ public function ingest(array $items, ?string $idempotencyKey = null): array
         ];
     }
 
+    public function originHealth(string $domainId): array
+    {
+        $pdo = Database::pdo();
+        $origins = $pdo->prepare(
+            'SELECT id, host, role, enabled, health_check_enabled, health_status, last_check_at, last_error
+             FROM domain_origins
+             WHERE domain_id=:domain_id
+             ORDER BY enabled DESC, role ASC, host ASC, id ASC'
+        );
+        $origins->execute([':domain_id' => $domainId]);
+        $rows = $origins->fetchAll();
+
+        $observations = $pdo->prepare(
+            'SELECT oho.*, en.region, en.country, en.hostname
+             FROM origin_health_observations oho
+             LEFT JOIN edge_nodes en ON en.edge_id=oho.edge_node_id
+             WHERE oho.domain_id=:domain_id
+             ORDER BY oho.last_observed_at DESC, oho.origin_id ASC, oho.edge_node_id ASC'
+        );
+        $observations->execute([':domain_id' => $domainId]);
+        $byOrigin = [];
+        foreach ($observations->fetchAll() as $row) {
+            $originId = (string) $row['origin_id'];
+            $byOrigin[$originId] ??= [];
+            $byOrigin[$originId][] = $this->castOriginObservation($row);
+        }
+
+        $items = [];
+        foreach ($rows as $origin) {
+            $originId = (string) $origin['id'];
+            $edgeRows = $byOrigin[$originId] ?? [];
+            $items[] = [
+                'origin_id' => $originId,
+                'host' => (string) $origin['host'],
+                'role' => (string) ($origin['role'] ?? 'primary'),
+                'enabled' => in_array($origin['enabled'], [true, 1, '1', 't', 'true'], true),
+                'health_check_enabled' => in_array($origin['health_check_enabled'], [true, 1, '1', 't', 'true'], true),
+                'status' => (string) ($origin['health_status'] ?? 'unknown'),
+                'last_check_at' => $origin['last_check_at'] === null ? null : (int) $origin['last_check_at'],
+                'last_error' => $origin['last_error'] === null ? null : (string) $origin['last_error'],
+                'edge_count' => count($edgeRows),
+                'healthy_edges' => count(array_filter($edgeRows, static fn (array $r): bool => $r['status'] === 'healthy')),
+                'slow_edges' => count(array_filter($edgeRows, static fn (array $r): bool => $r['status'] === 'slow')),
+                'unhealthy_edges' => count(array_filter($edgeRows, static fn (array $r): bool => $r['status'] === 'unhealthy')),
+                'max_latency_ms' => $this->maxObservationValue($edgeRows, 'latency_ms'),
+                'max_jitter_ms' => $this->maxObservationValue($edgeRows, 'jitter_ms'),
+                'edges' => $edgeRows,
+            ];
+        }
+
+        return [
+            'items' => $items,
+            'source' => 'edge_observations',
+            'core_active_checks' => false,
+        ];
+    }
+
     public function ingestSecurityEvents(array $items, ?string $idempotencyKey = null): array
     {
         $pdo = Database::pdo();
@@ -1491,6 +1549,163 @@ private function recentOriginErrors(string $whereSql, array $params): array
         return array_map([$this, 'castRequestActivity'], $stmt->fetchAll());
     }
 
+    private function recordOriginObservation(string $domainId, array $item, int $now): void
+    {
+        $originId = trim((string) ($item['origin_id'] ?? ''));
+        $edgeNodeId = trim((string) ($item['edge_node_id'] ?? ''));
+        if ($originId === '' || $edgeNodeId === '') {
+            return;
+        }
+
+        $origin = Database::pdo()->prepare('SELECT id, health_check_enabled FROM domain_origins WHERE domain_id=:domain_id AND id=:id LIMIT 1');
+        $origin->execute([':domain_id' => $domainId, ':id' => $originId]);
+        $originRow = $origin->fetch();
+        if (!$originRow) {
+            return;
+        }
+
+        $latencyMs = $this->durationMs($item['upstream_response_time'] ?? $item['origin_time_ms'] ?? null);
+        $upstreamStatus = trim((string) ($item['upstream_status'] ?? ''));
+        $routerError = trim((string) ($item['router_error'] ?? ''));
+        [$status, $reason] = $this->originObservationStatus($upstreamStatus, $latencyMs, $routerError);
+        $previous = $this->previousOriginObservation($domainId, $originId, $edgeNodeId);
+        $jitterMs = ($latencyMs !== null && isset($previous['latency_ms']) && $previous['latency_ms'] !== null)
+            ? abs($latencyMs - (int) $previous['latency_ms'])
+            : null;
+        if ($status === 'healthy' && $jitterMs !== null && $jitterMs >= 1000) {
+            $status = 'slow';
+            $reason = 'origin_jitter';
+        }
+
+        Database::pdo()->prepare(
+            'INSERT INTO origin_health_observations
+             (id,domain_id,origin_id,edge_node_id,status,reason,upstream_status,latency_ms,jitter_ms,sample_count,first_observed_at,last_observed_at,last_success_at,last_failure_at)
+             VALUES (:id,:domain_id,:origin_id,:edge_node_id,:status,:reason,:upstream_status,:latency_ms,:jitter_ms,1,:first_observed_at,:last_observed_at,:last_success_at,:last_failure_at)
+             ON CONFLICT (domain_id, origin_id, edge_node_id) DO UPDATE SET
+               status=EXCLUDED.status,
+               reason=EXCLUDED.reason,
+               upstream_status=EXCLUDED.upstream_status,
+               latency_ms=EXCLUDED.latency_ms,
+               jitter_ms=EXCLUDED.jitter_ms,
+               sample_count=LEAST(origin_health_observations.sample_count + 1, 1000000000),
+               last_observed_at=EXCLUDED.last_observed_at,
+               last_success_at=COALESCE(EXCLUDED.last_success_at, origin_health_observations.last_success_at),
+               last_failure_at=COALESCE(EXCLUDED.last_failure_at, origin_health_observations.last_failure_at)'
+        )->execute([
+            ':id' => Uuid::v4(),
+            ':domain_id' => $domainId,
+            ':origin_id' => $originId,
+            ':edge_node_id' => $edgeNodeId,
+            ':status' => $status,
+            ':reason' => $reason,
+            ':upstream_status' => $upstreamStatus !== '' ? $upstreamStatus : null,
+            ':latency_ms' => $latencyMs,
+            ':jitter_ms' => $jitterMs,
+            ':first_observed_at' => $now,
+            ':last_observed_at' => $now,
+            ':last_success_at' => $status === 'healthy' || $status === 'slow' ? $now : null,
+            ':last_failure_at' => $status === 'unhealthy' ? $now : null,
+        ]);
+
+        if (in_array($originRow['health_check_enabled'], [true, 1, '1', 't', 'true'], true)) {
+            $this->refreshOriginStatusFromEdge($domainId, $originId, $now);
+        }
+    }
+
+    private function originObservationStatus(string $upstreamStatus, ?int $latencyMs, string $routerError): array
+    {
+        if ($routerError !== '') {
+            return ['unhealthy', $routerError];
+        }
+        if ($upstreamStatus === '' || $upstreamStatus === '-') {
+            return ['unknown', 'no_upstream_status'];
+        }
+        $firstStatus = (int) strtok($upstreamStatus, ', ');
+        if ($firstStatus >= 500 || $firstStatus === 0) {
+            return ['unhealthy', 'http_' . $firstStatus];
+        }
+        if ($latencyMs !== null && $latencyMs >= 3000) {
+            return ['slow', 'slow_origin'];
+        }
+        return ['healthy', 'edge_request_ok'];
+    }
+
+    private function previousOriginObservation(string $domainId, string $originId, string $edgeNodeId): ?array
+    {
+        $stmt = Database::pdo()->prepare(
+            'SELECT latency_ms FROM origin_health_observations WHERE domain_id=:domain_id AND origin_id=:origin_id AND edge_node_id=:edge_node_id LIMIT 1'
+        );
+        $stmt->execute([':domain_id' => $domainId, ':origin_id' => $originId, ':edge_node_id' => $edgeNodeId]);
+        $row = $stmt->fetch();
+        return $row ?: null;
+    }
+
+    private function refreshOriginStatusFromEdge(string $domainId, string $originId, int $now): void
+    {
+        $stmt = Database::pdo()->prepare(
+            "SELECT
+                COUNT(*) FILTER (WHERE status='unhealthy') unhealthy,
+                COUNT(*) FILTER (WHERE status='slow') slow,
+                COUNT(*) FILTER (WHERE status='healthy') healthy,
+                MAX(last_observed_at) last_observed_at
+             FROM origin_health_observations
+             WHERE domain_id=:domain_id AND origin_id=:origin_id"
+        );
+        $stmt->execute([':domain_id' => $domainId, ':origin_id' => $originId]);
+        $row = $stmt->fetch() ?: [];
+        $status = 'unknown';
+        $error = null;
+        if ((int) ($row['unhealthy'] ?? 0) > 0) {
+            $status = 'unhealthy';
+            $error = 'edge_reported_unhealthy';
+        } elseif ((int) ($row['slow'] ?? 0) > 0) {
+            $status = 'healthy';
+            $error = 'edge_reported_slow';
+        } elseif ((int) ($row['healthy'] ?? 0) > 0) {
+            $status = 'healthy';
+        }
+        Database::pdo()->prepare(
+            'UPDATE domain_origins SET health_status=:health_status,last_check_at=:last_check_at,last_error=:last_error,updated_at=:updated_at
+             WHERE domain_id=:domain_id AND id=:origin_id'
+        )->execute([
+            ':domain_id' => $domainId,
+            ':origin_id' => $originId,
+            ':health_status' => $status,
+            ':last_check_at' => $row['last_observed_at'] === null ? $now : (int) $row['last_observed_at'],
+            ':last_error' => $error,
+            ':updated_at' => $now,
+        ]);
+    }
+
+    private function castOriginObservation(array $row): array
+    {
+        foreach (['latency_ms', 'jitter_ms', 'sample_count', 'first_observed_at', 'last_observed_at', 'last_success_at', 'last_failure_at'] as $key) {
+            $row[$key] = $row[$key] === null ? null : (int) $row[$key];
+        }
+        return [
+            'edge_node_id' => (string) $row['edge_node_id'],
+            'edge_label' => (string) ($row['hostname'] ?? $row['edge_node_id']),
+            'region' => $row['region'] === null ? null : (string) $row['region'],
+            'country' => $row['country'] === null ? null : (string) $row['country'],
+            'status' => (string) $row['status'],
+            'reason' => $row['reason'] === null ? null : (string) $row['reason'],
+            'upstream_status' => $row['upstream_status'] === null ? null : (string) $row['upstream_status'],
+            'latency_ms' => $row['latency_ms'],
+            'jitter_ms' => $row['jitter_ms'],
+            'sample_count' => $row['sample_count'],
+            'first_observed_at' => $row['first_observed_at'],
+            'last_observed_at' => $row['last_observed_at'],
+            'last_success_at' => $row['last_success_at'],
+            'last_failure_at' => $row['last_failure_at'],
+        ];
+    }
+
+    private function maxObservationValue(array $rows, string $key): ?int
+    {
+        $values = array_values(array_filter(array_map(static fn (array $row): ?int => $row[$key] ?? null, $rows), static fn (?int $v): bool => $v !== null));
+        return $values === [] ? null : max($values);
+    }
+
     private function decodeJson(?string $value): mixed
     {
         if ($value === null || $value === '') {
diff --git a/core/app/Modules/Proxy/Http/Controllers/OriginController.php b/core/app/Modules/Proxy/Http/Controllers/OriginController.php
index 1f7f433..813f5bb 100644
--- a/core/app/Modules/Proxy/Http/Controllers/OriginController.php
+++ b/core/app/Modules/Proxy/Http/Controllers/OriginController.php
@@ -42,8 +42,8 @@ public function delete(string $domainId, string $originId): array
 
     public function check(string $domainId, string $originId): array
     {
-        $origin = $this->service->check($domainId, $originId);
-        return $origin === null ? ['error' => 'origin_not_found', 'status' => 404] : ['data' => $origin];
+        $result = $this->service->test($domainId, $originId);
+        return $result === null ? ['error' => 'origin_not_found', 'status' => 404] : ['data' => $result + ['authoritative' => false, 'source' => 'core_diagnostic_only']];
     }
 
     public function test(string $domainId, string $originId): array
@@ -76,9 +76,15 @@ private function validate(array $body, bool $partial): ?array
             }
         }
         if (array_key_exists('role', $body)) {
-            $role = Validator::enum($body, 'role', ['origin']);
+            $role = Validator::enum($body, 'role', ['primary', 'backup', 'shield']);
             if (($role['ok'] ?? false) !== true) {
-                return ['error' => 'invalid_field', 'field' => 'role', 'detail' => 'must_be_origin', 'status' => 422];
+                return ['error' => 'invalid_field', 'field' => 'role', 'detail' => 'must_be_primary_backup_or_shield', 'status' => 422];
+            }
+        }
+        if (array_key_exists('load_balancing_algorithm', $body)) {
+            $algorithm = Validator::enum($body, 'load_balancing_algorithm', ['weighted_hash', 'consistent_hash']);
+            if (($algorithm['ok'] ?? false) !== true) {
+                return ['error' => 'invalid_field', 'field' => 'load_balancing_algorithm', 'detail' => 'must_be_weighted_hash_or_consistent_hash', 'status' => 422];
             }
         }
         foreach (['host_header', 'sni'] as $field) {
@@ -101,7 +107,7 @@ private function validate(array $body, bool $partial): ?array
                 return $weight;
             }
         }
-        foreach (['is_primary', 'enabled', 'preserve_host', 'health_check_enabled'] as $field) {
+        foreach (['is_primary', 'enabled', 'preserve_host', 'health_check_enabled', 'circuit_breaker_enabled', 'drain', 'shield_enabled'] as $field) {
             if (array_key_exists($field, $body)) {
                 $bool = Validator::bool($body, $field);
                 if (($bool['ok'] ?? false) !== true) {
@@ -126,6 +132,22 @@ private function validate(array $body, bool $partial): ?array
                 }
             }
         }
+        foreach ([
+            'connection_timeout_seconds' => [1, 60],
+            'response_timeout_seconds' => [1, 600],
+            'retry_attempts' => [0, 3],
+            'retry_budget_per_minute' => [0, 100000],
+            'circuit_failure_threshold' => [1, 1000],
+            'circuit_recovery_seconds' => [1, 3600],
+            'max_concurrent_requests' => [0, 1000000],
+        ] as $field => $range) {
+            if (array_key_exists($field, $body)) {
+                $value = Validator::intRange($body, $field, $range[0], $range[1]);
+                if (($value['ok'] ?? false) !== true) {
+                    return $value;
+                }
+            }
+        }
         return null;
     }
 }
diff --git a/core/app/Modules/Proxy/Services/ConfigService.php b/core/app/Modules/Proxy/Services/ConfigService.php
index 461a4f6..489d83e 100644
--- a/core/app/Modules/Proxy/Services/ConfigService.php
+++ b/core/app/Modules/Proxy/Services/ConfigService.php
@@ -416,8 +416,9 @@ private function originForSnapshot(array $origin): array
             'id' => (string) $origin['id'],
             'dns_record_id' => $origin['dns_record_id'] ?? null,
             'source' => (string) ($origin['source'] ?? 'manual'),
-            'role' => (string) ($origin['role'] ?? 'origin'),
+            'role' => (string) ($origin['role'] ?? 'primary'),
             'weight' => (int) ($origin['weight'] ?? 1),
+            'load_balancing_algorithm' => (string) ($origin['load_balancing_algorithm'] ?? 'weighted_hash'),
             'enabled' => (bool) ($origin['enabled'] ?? true),
             'host' => (string) $origin['host'],
             'scheme' => (string) $origin['scheme'],
@@ -427,6 +428,19 @@ private function originForSnapshot(array $origin): array
             'tls_verify' => (string) ($origin['tls_verify'] ?? 'ignore'),
             'preserve_host' => (bool) ($origin['preserve_host'] ?? true),
             'health_check_enabled' => (bool) ($origin['health_check_enabled'] ?? false),
+            'health_check_path' => (string) ($origin['health_check_path'] ?? '/'),
+            'health_check_interval_seconds' => (int) ($origin['health_check_interval_seconds'] ?? 30),
+            'health_check_timeout_seconds' => (int) ($origin['health_check_timeout_seconds'] ?? 5),
+            'connection_timeout_seconds' => (int) ($origin['connection_timeout_seconds'] ?? 5),
+            'response_timeout_seconds' => (int) ($origin['response_timeout_seconds'] ?? 30),
+            'retry_attempts' => (int) ($origin['retry_attempts'] ?? 1),
+            'retry_budget_per_minute' => (int) ($origin['retry_budget_per_minute'] ?? 60),
+            'circuit_breaker_enabled' => (bool) ($origin['circuit_breaker_enabled'] ?? true),
+            'circuit_failure_threshold' => (int) ($origin['circuit_failure_threshold'] ?? 5),
+            'circuit_recovery_seconds' => (int) ($origin['circuit_recovery_seconds'] ?? 30),
+            'max_concurrent_requests' => (int) ($origin['max_concurrent_requests'] ?? 0),
+            'drain' => (bool) ($origin['drain'] ?? false),
+            'shield_enabled' => (bool) ($origin['shield_enabled'] ?? false),
             'status' => (string) $origin['health_status'],
             'health_status' => (string) $origin['health_status'],
         ];
@@ -436,7 +450,7 @@ private function originsForSnapshot(array $origins): array
     {
         $out = [];
         foreach ($origins as $origin) {
-            if (empty($origin['enabled'])) {
+            if (empty($origin['enabled']) || !empty($origin['drain'])) {
                 continue;
             }
             if (!empty($origin['health_check_enabled']) && (string) ($origin['health_status'] ?? 'unknown') === 'unhealthy') {
@@ -469,8 +483,9 @@ private function originsFromDnsRecords(array $records, string $domainHost): arra
                 'id' => (string) ($record['id'] ?? ''),
                 'dns_record_id' => (string) ($record['id'] ?? ''),
                 'source' => 'dns_record',
-                'role' => 'origin',
+                'role' => 'primary',
                 'weight' => 1,
+                'load_balancing_algorithm' => 'weighted_hash',
                 'enabled' => true,
                 'scheme' => $scheme,
                 'host' => $host,
@@ -480,6 +495,19 @@ private function originsFromDnsRecords(array $records, string $domainHost): arra
                 'tls_verify' => (string) ($record['origin_tls_verify'] ?? 'ignore'),
                 'preserve_host' => true,
                 'health_check_enabled' => false,
+                'health_check_path' => '/',
+                'health_check_interval_seconds' => 30,
+                'health_check_timeout_seconds' => 5,
+                'connection_timeout_seconds' => 5,
+                'response_timeout_seconds' => 30,
+                'retry_attempts' => 1,
+                'retry_budget_per_minute' => 60,
+                'circuit_breaker_enabled' => true,
+                'circuit_failure_threshold' => 5,
+                'circuit_recovery_seconds' => 30,
+                'max_concurrent_requests' => 0,
+                'drain' => false,
+                'shield_enabled' => false,
                 'health_status' => (string) ($record['origin_status'] ?? 'pending'),
                 'status' => (string) ($record['origin_status'] ?? 'pending'),
             ];
@@ -532,7 +560,7 @@ private function originsForDnsRecord(string $recordId, array $configuredOrigins)
         }
         $origins = [];
         foreach ($configuredOrigins as $origin) {
-            if ((string) ($origin['dns_record_id'] ?? '') !== $recordId || empty($origin['enabled'])) {
+            if ((string) ($origin['dns_record_id'] ?? '') !== $recordId || empty($origin['enabled']) || !empty($origin['drain'])) {
                 continue;
             }
             if (!empty($origin['health_check_enabled']) && (string) ($origin['health_status'] ?? 'unknown') === 'unhealthy') {
@@ -571,8 +599,9 @@ private function originFromDnsRecord(array $record, string $domainHost = ''): ?a
             'id' => (string) ($record['id'] ?? ''),
             'dns_record_id' => (string) ($record['id'] ?? ''),
             'source' => 'dns_record',
-            'role' => 'origin',
+            'role' => 'primary',
             'weight' => 1,
+            'load_balancing_algorithm' => 'weighted_hash',
             'enabled' => true,
             'scheme' => $scheme,
             'host' => $host,
@@ -582,6 +611,19 @@ private function originFromDnsRecord(array $record, string $domainHost = ''): ?a
             'tls_verify' => (string) ($record['origin_tls_verify'] ?? 'ignore'),
             'preserve_host' => true,
             'health_check_enabled' => false,
+            'health_check_path' => '/',
+            'health_check_interval_seconds' => 30,
+            'health_check_timeout_seconds' => 5,
+            'connection_timeout_seconds' => 5,
+            'response_timeout_seconds' => 30,
+            'retry_attempts' => 1,
+            'retry_budget_per_minute' => 60,
+            'circuit_breaker_enabled' => true,
+            'circuit_failure_threshold' => 5,
+            'circuit_recovery_seconds' => 30,
+            'max_concurrent_requests' => 0,
+            'drain' => false,
+            'shield_enabled' => false,
             'health_status' => (string) ($record['origin_status'] ?? 'pending'),
             'status' => (string) ($record['origin_status'] ?? 'pending'),
         ];
@@ -638,8 +680,9 @@ private function buildGeoOrigins(array $geoOrigins): array
             }
             $out[strtoupper(trim($key))] = [
                 'id' => (string) ($origin['id'] ?? 'geo-' . strtoupper(trim($key))),
-                'role' => 'origin',
+                'role' => 'primary',
                 'source' => 'geo_origin',
+                'load_balancing_algorithm' => 'weighted_hash',
                 'host' => $host,
                 // Geo origins should not silently assume TLS. Mirror the
                 // explicit scheme when present, otherwise stay on HTTP/80.
@@ -650,6 +693,19 @@ private function buildGeoOrigins(array $geoOrigins): array
                 'tls_verify' => (string) ($origin['tls_verify'] ?? 'ignore'),
                 'preserve_host' => (bool) ($origin['preserve_host'] ?? true),
                 'health_check_enabled' => (bool) ($origin['health_check_enabled'] ?? false),
+                'health_check_path' => (string) ($origin['health_check_path'] ?? '/'),
+                'health_check_interval_seconds' => (int) ($origin['health_check_interval_seconds'] ?? 30),
+                'health_check_timeout_seconds' => (int) ($origin['health_check_timeout_seconds'] ?? 5),
+                'connection_timeout_seconds' => (int) ($origin['connection_timeout_seconds'] ?? 5),
+                'response_timeout_seconds' => (int) ($origin['response_timeout_seconds'] ?? 30),
+                'retry_attempts' => (int) ($origin['retry_attempts'] ?? 1),
+                'retry_budget_per_minute' => (int) ($origin['retry_budget_per_minute'] ?? 60),
+                'circuit_breaker_enabled' => (bool) ($origin['circuit_breaker_enabled'] ?? true),
+                'circuit_failure_threshold' => (int) ($origin['circuit_failure_threshold'] ?? 5),
+                'circuit_recovery_seconds' => (int) ($origin['circuit_recovery_seconds'] ?? 30),
+                'max_concurrent_requests' => (int) ($origin['max_concurrent_requests'] ?? 0),
+                'drain' => (bool) ($origin['drain'] ?? false),
+                'shield_enabled' => (bool) ($origin['shield_enabled'] ?? false),
             ];
         }
         ksort($out);
diff --git a/core/app/Modules/Proxy/Services/OriginHealthService.php b/core/app/Modules/Proxy/Services/OriginHealthService.php
index b114192..7fba439 100644
--- a/core/app/Modules/Proxy/Services/OriginHealthService.php
+++ b/core/app/Modules/Proxy/Services/OriginHealthService.php
@@ -43,13 +43,24 @@ public function create(string $domainId, array $input): array
                 'preserve_host' => array_key_exists('preserve_host', $input) ? !empty($input['preserve_host']) : true,
                 'dns_record_id' => $input['dns_record_id'] ?? null,
                 'source' => (string) ($input['source'] ?? 'manual'),
-                'role' => (string) ($input['role'] ?? 'origin'),
+                'role' => (string) ($input['role'] ?? 'primary'),
                 'weight' => (int) ($input['weight'] ?? 1),
+                'load_balancing_algorithm' => (string) ($input['load_balancing_algorithm'] ?? 'weighted_hash'),
                 'is_primary' => false,
                 'health_check_enabled' => array_key_exists('health_check_enabled', $input) ? !empty($input['health_check_enabled']) : false,
                 'health_check_path' => (string) ($input['health_check_path'] ?? '/'),
                 'health_check_interval_seconds' => (int) ($input['health_check_interval_seconds'] ?? 30),
                 'health_check_timeout_seconds' => (int) ($input['health_check_timeout_seconds'] ?? 5),
+                'connection_timeout_seconds' => (int) ($input['connection_timeout_seconds'] ?? 5),
+                'response_timeout_seconds' => (int) ($input['response_timeout_seconds'] ?? 30),
+                'retry_attempts' => (int) ($input['retry_attempts'] ?? 1),
+                'retry_budget_per_minute' => (int) ($input['retry_budget_per_minute'] ?? 60),
+                'circuit_breaker_enabled' => array_key_exists('circuit_breaker_enabled', $input) ? !empty($input['circuit_breaker_enabled']) : true,
+                'circuit_failure_threshold' => (int) ($input['circuit_failure_threshold'] ?? 5),
+                'circuit_recovery_seconds' => (int) ($input['circuit_recovery_seconds'] ?? 30),
+                'max_concurrent_requests' => (int) ($input['max_concurrent_requests'] ?? 0),
+                'drain' => array_key_exists('drain', $input) ? !empty($input['drain']) : false,
+                'shield_enabled' => array_key_exists('shield_enabled', $input) ? !empty($input['shield_enabled']) : false,
                 'health_status' => 'unknown',
                 'enabled' => array_key_exists('enabled', $input) ? !empty($input['enabled']) : true,
                 'created_at' => $now,
@@ -60,9 +71,9 @@ public function create(string $domainId, array $input): array
             }
             $pdo->prepare(
                 'INSERT INTO domain_origins
-                 (id,domain_id,dns_record_id,source,role,weight,scheme,host,port,host_header,sni,tls_verify,preserve_host,is_primary,health_check_enabled,health_check_path,health_check_interval_seconds,health_check_timeout_seconds,health_status,last_check_at,last_error,enabled,created_at,updated_at)
+                 (id,domain_id,dns_record_id,source,role,weight,load_balancing_algorithm,scheme,host,port,host_header,sni,tls_verify,preserve_host,is_primary,health_check_enabled,health_check_path,health_check_interval_seconds,health_check_timeout_seconds,connection_timeout_seconds,response_timeout_seconds,retry_attempts,retry_budget_per_minute,circuit_breaker_enabled,circuit_failure_threshold,circuit_recovery_seconds,max_concurrent_requests,drain,shield_enabled,health_status,last_check_at,last_error,enabled,created_at,updated_at)
                  VALUES
-                 (:id,:domain_id,:dns_record_id,:source,:role,:weight,:scheme,:host,:port,:host_header,:sni,:tls_verify,:preserve_host,:is_primary,:health_check_enabled,:health_check_path,:health_check_interval_seconds,:health_check_timeout_seconds,:health_status,NULL,NULL,:enabled,:created_at,:updated_at)'
+                 (:id,:domain_id,:dns_record_id,:source,:role,:weight,:load_balancing_algorithm,:scheme,:host,:port,:host_header,:sni,:tls_verify,:preserve_host,:is_primary,:health_check_enabled,:health_check_path,:health_check_interval_seconds,:health_check_timeout_seconds,:connection_timeout_seconds,:response_timeout_seconds,:retry_attempts,:retry_budget_per_minute,:circuit_breaker_enabled,:circuit_failure_threshold,:circuit_recovery_seconds,:max_concurrent_requests,:drain,:shield_enabled,:health_status,NULL,NULL,:enabled,:created_at,:updated_at)'
             )->execute([
                 ':id' => $row['id'],
                 ':domain_id' => $row['domain_id'],
@@ -70,6 +81,7 @@ public function create(string $domainId, array $input): array
                 ':source' => $row['source'],
                 ':role' => $row['role'],
                 ':weight' => $row['weight'],
+                ':load_balancing_algorithm' => $row['load_balancing_algorithm'],
                 ':scheme' => $row['scheme'],
                 ':host' => $row['host'],
                 ':port' => $row['port'],
@@ -82,6 +94,16 @@ public function create(string $domainId, array $input): array
                 ':health_check_path' => $row['health_check_path'],
                 ':health_check_interval_seconds' => $row['health_check_interval_seconds'],
                 ':health_check_timeout_seconds' => $row['health_check_timeout_seconds'],
+                ':connection_timeout_seconds' => $row['connection_timeout_seconds'],
+                ':response_timeout_seconds' => $row['response_timeout_seconds'],
+                ':retry_attempts' => $row['retry_attempts'],
+                ':retry_budget_per_minute' => $row['retry_budget_per_minute'],
+                ':circuit_breaker_enabled' => (int) $row['circuit_breaker_enabled'],
+                ':circuit_failure_threshold' => $row['circuit_failure_threshold'],
+                ':circuit_recovery_seconds' => $row['circuit_recovery_seconds'],
+                ':max_concurrent_requests' => $row['max_concurrent_requests'],
+                ':drain' => (int) $row['drain'],
+                ':shield_enabled' => (int) $row['shield_enabled'],
                 ':health_status' => $row['health_status'],
                 ':enabled' => (int) $row['enabled'],
                 ':created_at' => $row['created_at'],
@@ -117,8 +139,19 @@ public function update(string $domainId, string $originId, array $input): ?array
             'sni' => array_key_exists('sni', $input) ? trim((string) $input['sni']) : (string) ($existing['sni'] ?? ''),
             'tls_verify' => (string) ($input['tls_verify'] ?? $existing['tls_verify'] ?? 'ignore'),
             'preserve_host' => array_key_exists('preserve_host', $input) ? !empty($input['preserve_host']) : (bool) ($existing['preserve_host'] ?? true),
-            'role' => array_key_exists('role', $input) ? (string) $input['role'] : (string) ($existing['role'] ?? 'origin'),
+            'role' => array_key_exists('role', $input) ? (string) $input['role'] : (string) ($existing['role'] ?? 'primary'),
             'weight' => (int) ($input['weight'] ?? $existing['weight'] ?? 1),
+            'load_balancing_algorithm' => (string) ($input['load_balancing_algorithm'] ?? $existing['load_balancing_algorithm'] ?? 'weighted_hash'),
+            'connection_timeout_seconds' => (int) ($input['connection_timeout_seconds'] ?? $existing['connection_timeout_seconds'] ?? 5),
+            'response_timeout_seconds' => (int) ($input['response_timeout_seconds'] ?? $existing['response_timeout_seconds'] ?? 30),
+            'retry_attempts' => (int) ($input['retry_attempts'] ?? $existing['retry_attempts'] ?? 1),
+            'retry_budget_per_minute' => (int) ($input['retry_budget_per_minute'] ?? $existing['retry_budget_per_minute'] ?? 60),
+            'circuit_breaker_enabled' => array_key_exists('circuit_breaker_enabled', $input) ? !empty($input['circuit_breaker_enabled']) : (bool) ($existing['circuit_breaker_enabled'] ?? true),
+            'circuit_failure_threshold' => (int) ($input['circuit_failure_threshold'] ?? $existing['circuit_failure_threshold'] ?? 5),
+            'circuit_recovery_seconds' => (int) ($input['circuit_recovery_seconds'] ?? $existing['circuit_recovery_seconds'] ?? 30),
+            'max_concurrent_requests' => (int) ($input['max_concurrent_requests'] ?? $existing['max_concurrent_requests'] ?? 0),
+            'drain' => array_key_exists('drain', $input) ? !empty($input['drain']) : (bool) ($existing['drain'] ?? false),
+            'shield_enabled' => array_key_exists('shield_enabled', $input) ? !empty($input['shield_enabled']) : (bool) ($existing['shield_enabled'] ?? false),
             'enabled' => array_key_exists('enabled', $input) ? !empty($input['enabled']) : (bool) $existing['enabled'],
             'health_check_enabled' => array_key_exists('health_check_enabled', $input) ? !empty($input['health_check_enabled']) : (bool) ($existing['health_check_enabled'] ?? false),
             // DNS-linked origin edits should recover fast after a transient
@@ -136,9 +169,13 @@ public function update(string $domainId, string $originId, array $input): ?array
         try {
             $pdo->prepare(
                 'UPDATE domain_origins SET scheme=:scheme,host=:host,port=:port,host_header=:host_header,sni=:sni,
-                 tls_verify=:tls_verify,preserve_host=:preserve_host,role=:role,weight=:weight,is_primary=:is_primary,
+                 tls_verify=:tls_verify,preserve_host=:preserve_host,role=:role,weight=:weight,load_balancing_algorithm=:load_balancing_algorithm,is_primary=:is_primary,
                  health_check_enabled=:health_check_enabled,health_check_path=:health_check_path,health_check_interval_seconds=:health_check_interval_seconds,
-                 health_check_timeout_seconds=:health_check_timeout_seconds,health_status=:health_status,
+                 health_check_timeout_seconds=:health_check_timeout_seconds,connection_timeout_seconds=:connection_timeout_seconds,
+                 response_timeout_seconds=:response_timeout_seconds,retry_attempts=:retry_attempts,retry_budget_per_minute=:retry_budget_per_minute,
+                 circuit_breaker_enabled=:circuit_breaker_enabled,circuit_failure_threshold=:circuit_failure_threshold,
+                 circuit_recovery_seconds=:circuit_recovery_seconds,max_concurrent_requests=:max_concurrent_requests,
+                 drain=:drain,shield_enabled=:shield_enabled,health_status=:health_status,
                  last_check_at=:last_check_at,last_error=:last_error,enabled=:enabled,updated_at=:updated_at
                  WHERE domain_id=:domain_id AND id=:id'
             )->execute([
@@ -153,11 +190,22 @@ public function update(string $domainId, string $originId, array $input): ?array
                 ':preserve_host' => (int) $patch['preserve_host'],
                 ':role' => $patch['role'],
                 ':weight' => $patch['weight'],
+                ':load_balancing_algorithm' => $patch['load_balancing_algorithm'],
                 ':is_primary' => 0,
                 ':health_check_enabled' => (int) $patch['health_check_enabled'],
                 ':health_check_path' => $patch['health_check_path'],
                 ':health_check_interval_seconds' => $patch['health_check_interval_seconds'],
                 ':health_check_timeout_seconds' => $patch['health_check_timeout_seconds'],
+                ':connection_timeout_seconds' => $patch['connection_timeout_seconds'],
+                ':response_timeout_seconds' => $patch['response_timeout_seconds'],
+                ':retry_attempts' => $patch['retry_attempts'],
+                ':retry_budget_per_minute' => $patch['retry_budget_per_minute'],
+                ':circuit_breaker_enabled' => (int) $patch['circuit_breaker_enabled'],
+                ':circuit_failure_threshold' => $patch['circuit_failure_threshold'],
+                ':circuit_recovery_seconds' => $patch['circuit_recovery_seconds'],
+                ':max_concurrent_requests' => $patch['max_concurrent_requests'],
+                ':drain' => (int) $patch['drain'],
+                ':shield_enabled' => (int) $patch['shield_enabled'],
                 ':health_status' => $patch['health_status'],
                 ':last_check_at' => $patch['last_check_at'],
                 ':last_error' => $patch['last_error'],
@@ -225,22 +273,13 @@ public function test(string $domainId, string $originId): ?array
 
     public function checkDue(): array
     {
-        $cutoff = time();
-        $stmt = Database::pdo()->prepare(
-            'SELECT * FROM domain_origins
-             WHERE enabled=true AND health_check_enabled=true
-               AND (last_check_at IS NULL OR last_check_at + health_check_interval_seconds <= :now)
-             ORDER BY COALESCE(last_check_at, 0) ASC'
-        );
-        $stmt->execute([':now' => $cutoff]);
-        $results = [];
-        foreach ($stmt->fetchAll() as $row) {
-            $checked = $this->check((string) $row['domain_id'], (string) $row['id']);
-            if ($checked !== null) {
-                $results[] = $checked;
-            }
-        }
-        return ['checked' => count($results), 'results' => $results];
+        return [
+            'checked' => 0,
+            'results' => [],
+            'source' => 'edge_observations',
+            'core_active_checks' => false,
+            'message' => 'Origin routing health is updated from edge metrics. Core checks are diagnostic-only.',
+        ];
     }
 
     public function syncFromDnsRecord(string $domainId, array $record): ?array
@@ -268,7 +307,7 @@ public function syncFromDnsRecord(string $domainId, array $record): ?array
             'preserve_host' => true,
             'health_check_enabled' => false,
             'source' => 'dns_record',
-            'role' => 'origin',
+            'role' => 'primary',
             'is_primary' => false,
             'enabled' => true,
             'dns_record_id' => (string) $record['id'],
@@ -619,12 +658,18 @@ private function ensureOriginsFromDnsRecords(string $domainId): void
 
     private function cast(array $row): array
     {
-        foreach (['port', 'weight', 'health_check_interval_seconds', 'health_check_timeout_seconds', 'created_at', 'updated_at'] as $key) {
+        foreach ([
+            'port', 'weight', 'health_check_interval_seconds', 'health_check_timeout_seconds',
+            'connection_timeout_seconds', 'response_timeout_seconds', 'retry_attempts',
+            'retry_budget_per_minute', 'circuit_failure_threshold', 'circuit_recovery_seconds',
+            'max_concurrent_requests', 'created_at', 'updated_at',
+        ] as $key) {
             $row[$key] = (int) $row[$key];
         }
         $row['dns_record_id'] = $row['dns_record_id'] === null ? null : (string) $row['dns_record_id'];
         $row['source'] = (string) ($row['source'] ?? 'manual');
-        $row['role'] = (string) ($row['role'] ?? 'origin');
+        $row['role'] = (string) ($row['role'] ?? 'primary');
+        $row['load_balancing_algorithm'] = (string) ($row['load_balancing_algorithm'] ?? 'weighted_hash');
         $row['host_header'] = (string) ($row['host_header'] ?: $row['host']);
         $row['sni'] = (string) ($row['sni'] ?? '');
         $row['tls_verify'] = (string) ($row['tls_verify'] ?? 'ignore');
@@ -633,6 +678,9 @@ private function cast(array $row): array
         $row['enabled'] = in_array($row['enabled'], [true, 1, '1', 't', 'true'], true);
         $row['preserve_host'] = in_array($row['preserve_host'], [true, 1, '1', 't', 'true'], true);
         $row['health_check_enabled'] = in_array($row['health_check_enabled'] ?? false, [true, 1, '1', 't', 'true'], true);
+        $row['circuit_breaker_enabled'] = in_array($row['circuit_breaker_enabled'] ?? true, [true, 1, '1', 't', 'true'], true);
+        $row['drain'] = in_array($row['drain'] ?? false, [true, 1, '1', 't', 'true'], true);
+        $row['shield_enabled'] = in_array($row['shield_enabled'] ?? false, [true, 1, '1', 't', 'true'], true);
         return $row;
     }
 
diff --git a/core/database/migrations/000031_phase7_origin_resilience.sql b/core/database/migrations/000031_phase7_origin_resilience.sql
new file mode 100644
index 0000000..c4db97e
--- /dev/null
+++ b/core/database/migrations/000031_phase7_origin_resilience.sql
@@ -0,0 +1,60 @@
+ALTER TABLE domain_origins
+  ADD COLUMN IF NOT EXISTS load_balancing_algorithm TEXT NOT NULL DEFAULT 'weighted_hash',
+  ADD COLUMN IF NOT EXISTS connection_timeout_seconds INTEGER NOT NULL DEFAULT 5,
+  ADD COLUMN IF NOT EXISTS response_timeout_seconds INTEGER NOT NULL DEFAULT 30,
+  ADD COLUMN IF NOT EXISTS retry_attempts INTEGER NOT NULL DEFAULT 1,
+  ADD COLUMN IF NOT EXISTS retry_budget_per_minute INTEGER NOT NULL DEFAULT 60,
+  ADD COLUMN IF NOT EXISTS circuit_breaker_enabled BOOLEAN NOT NULL DEFAULT true,
+  ADD COLUMN IF NOT EXISTS circuit_failure_threshold INTEGER NOT NULL DEFAULT 5,
+  ADD COLUMN IF NOT EXISTS circuit_recovery_seconds INTEGER NOT NULL DEFAULT 30,
+  ADD COLUMN IF NOT EXISTS max_concurrent_requests INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS drain BOOLEAN NOT NULL DEFAULT false,
+  ADD COLUMN IF NOT EXISTS shield_enabled BOOLEAN NOT NULL DEFAULT false;
+
+UPDATE domain_origins SET role = 'primary' WHERE role = 'origin';
+
+ALTER TABLE domain_origins ALTER COLUMN role SET DEFAULT 'primary';
+
+ALTER TABLE domain_origins
+  DROP CONSTRAINT IF EXISTS domain_origins_role_check,
+  ADD CONSTRAINT domain_origins_role_check CHECK (role IN ('primary', 'backup', 'shield'));
+
+ALTER TABLE domain_origins
+  ADD CONSTRAINT domain_origins_load_balancing_algorithm_check CHECK (load_balancing_algorithm IN ('weighted_hash', 'consistent_hash')),
+  ADD CONSTRAINT domain_origins_connection_timeout_seconds_check CHECK (connection_timeout_seconds BETWEEN 1 AND 60),
+  ADD CONSTRAINT domain_origins_response_timeout_seconds_check CHECK (response_timeout_seconds BETWEEN 1 AND 600),
+  ADD CONSTRAINT domain_origins_retry_attempts_check CHECK (retry_attempts BETWEEN 0 AND 3),
+  ADD CONSTRAINT domain_origins_retry_budget_per_minute_check CHECK (retry_budget_per_minute BETWEEN 0 AND 100000),
+  ADD CONSTRAINT domain_origins_circuit_failure_threshold_check CHECK (circuit_failure_threshold BETWEEN 1 AND 1000),
+  ADD CONSTRAINT domain_origins_circuit_recovery_seconds_check CHECK (circuit_recovery_seconds BETWEEN 1 AND 3600),
+  ADD CONSTRAINT domain_origins_max_concurrent_requests_check CHECK (max_concurrent_requests BETWEEN 0 AND 1000000);
+
+CREATE INDEX IF NOT EXISTS domain_origins_phase7_routing_idx
+  ON domain_origins (domain_id, enabled, role, drain, health_status, weight, id);
+
+CREATE TABLE IF NOT EXISTS origin_health_observations (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
+  origin_id TEXT NOT NULL REFERENCES domain_origins(id) ON DELETE CASCADE,
+  edge_node_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'unknown',
+  reason TEXT NULL,
+  upstream_status TEXT NULL,
+  latency_ms INTEGER NULL,
+  jitter_ms INTEGER NULL,
+  sample_count INTEGER NOT NULL DEFAULT 1,
+  first_observed_at BIGINT NOT NULL,
+  last_observed_at BIGINT NOT NULL,
+  last_success_at BIGINT NULL,
+  last_failure_at BIGINT NULL,
+  CHECK (status IN ('healthy', 'unhealthy', 'slow', 'unknown')),
+  CHECK (sample_count BETWEEN 1 AND 1000000000),
+  CHECK (latency_ms IS NULL OR latency_ms BETWEEN 0 AND 600000),
+  CHECK (jitter_ms IS NULL OR jitter_ms BETWEEN 0 AND 600000)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS origin_health_observations_edge_origin_idx
+  ON origin_health_observations (domain_id, origin_id, edge_node_id);
+
+CREATE INDEX IF NOT EXISTS origin_health_observations_domain_status_idx
+  ON origin_health_observations (domain_id, status, last_observed_at DESC);
diff --git a/core/database/schema.sql b/core/database/schema.sql
index c517a09..0a07e6c 100644
--- a/core/database/schema.sql
+++ b/core/database/schema.sql
@@ -211,8 +211,9 @@ CREATE TABLE IF NOT EXISTS domain_origins (
   domain_id TEXT NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
   dns_record_id TEXT NULL REFERENCES dns_records(id) ON DELETE CASCADE,
   source TEXT NOT NULL DEFAULT 'manual',
-  role TEXT NOT NULL DEFAULT 'origin',
+  role TEXT NOT NULL DEFAULT 'primary',
   weight INTEGER NOT NULL DEFAULT 1,
+  load_balancing_algorithm TEXT NOT NULL DEFAULT 'weighted_hash',
   scheme TEXT NOT NULL DEFAULT 'http',
   host TEXT NOT NULL,
   port INTEGER NOT NULL DEFAULT 80,
@@ -225,6 +226,16 @@ CREATE TABLE IF NOT EXISTS domain_origins (
   health_check_path TEXT NOT NULL DEFAULT '/',
   health_check_interval_seconds INTEGER NOT NULL DEFAULT 30,
   health_check_timeout_seconds INTEGER NOT NULL DEFAULT 5,
+  connection_timeout_seconds INTEGER NOT NULL DEFAULT 5,
+  response_timeout_seconds INTEGER NOT NULL DEFAULT 30,
+  retry_attempts INTEGER NOT NULL DEFAULT 1,
+  retry_budget_per_minute INTEGER NOT NULL DEFAULT 60,
+  circuit_breaker_enabled BOOLEAN NOT NULL DEFAULT true,
+  circuit_failure_threshold INTEGER NOT NULL DEFAULT 5,
+  circuit_recovery_seconds INTEGER NOT NULL DEFAULT 30,
+  max_concurrent_requests INTEGER NOT NULL DEFAULT 0,
+  drain BOOLEAN NOT NULL DEFAULT false,
+  shield_enabled BOOLEAN NOT NULL DEFAULT false,
   health_status TEXT NOT NULL DEFAULT 'unknown',
   last_check_at BIGINT NULL,
   last_error TEXT NULL,
@@ -234,9 +245,17 @@ CREATE TABLE IF NOT EXISTS domain_origins (
   CHECK (scheme IN ('http', 'https')),
   CHECK (port IN (80, 443)),
   CHECK (source IN ('manual', 'dns_record', 'imported')),
-  CHECK (role IN ('origin')),
+  CHECK (role IN ('primary', 'backup', 'shield')),
+  CHECK (load_balancing_algorithm IN ('weighted_hash', 'consistent_hash')),
   CHECK (tls_verify IN ('verify', 'ignore')),
   CHECK (weight BETWEEN 1 AND 10000),
+  CHECK (connection_timeout_seconds BETWEEN 1 AND 60),
+  CHECK (response_timeout_seconds BETWEEN 1 AND 600),
+  CHECK (retry_attempts BETWEEN 0 AND 3),
+  CHECK (retry_budget_per_minute BETWEEN 0 AND 100000),
+  CHECK (circuit_failure_threshold BETWEEN 1 AND 1000),
+  CHECK (circuit_recovery_seconds BETWEEN 1 AND 3600),
+  CHECK (max_concurrent_requests BETWEEN 0 AND 1000000),
   CHECK (health_status IN ('healthy', 'unhealthy', 'unknown'))
 );
 
@@ -247,6 +266,36 @@ CREATE INDEX IF NOT EXISTS domain_origins_dns_record_idx
 CREATE INDEX IF NOT EXISTS domain_origins_domain_source_idx
   ON domain_origins (domain_id, source, enabled);
 
+CREATE INDEX IF NOT EXISTS domain_origins_phase7_routing_idx
+  ON domain_origins (domain_id, enabled, role, drain, health_status, weight, id);
+
+CREATE TABLE IF NOT EXISTS origin_health_observations (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
+  origin_id TEXT NOT NULL REFERENCES domain_origins(id) ON DELETE CASCADE,
+  edge_node_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'unknown',
+  reason TEXT NULL,
+  upstream_status TEXT NULL,
+  latency_ms INTEGER NULL,
+  jitter_ms INTEGER NULL,
+  sample_count INTEGER NOT NULL DEFAULT 1,
+  first_observed_at BIGINT NOT NULL,
+  last_observed_at BIGINT NOT NULL,
+  last_success_at BIGINT NULL,
+  last_failure_at BIGINT NULL,
+  CHECK (status IN ('healthy', 'unhealthy', 'slow', 'unknown')),
+  CHECK (sample_count BETWEEN 1 AND 1000000000),
+  CHECK (latency_ms IS NULL OR latency_ms BETWEEN 0 AND 600000),
+  CHECK (jitter_ms IS NULL OR jitter_ms BETWEEN 0 AND 600000)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS origin_health_observations_edge_origin_idx
+  ON origin_health_observations (domain_id, origin_id, edge_node_id);
+
+CREATE INDEX IF NOT EXISTS origin_health_observations_domain_status_idx
+  ON origin_health_observations (domain_id, status, last_observed_at DESC);
+
 CREATE TABLE IF NOT EXISTS dns_desired_generations (
   id BIGSERIAL PRIMARY KEY,
   desired_hash TEXT NOT NULL UNIQUE,
diff --git a/core/public_index.php b/core/public_index.php
index 14bd365..65dac6a 100644
--- a/core/public_index.php
+++ b/core/public_index.php
@@ -643,6 +643,7 @@ function requireApiAuth(): void
 $router->add('GET', '/api/v1/domains/{domainId}/activity/requests', static fn (Request $req, array $p) => Response::json($collectorController->recentRequests((string) $p['domainId'], $req->query)), auth: true);
 $router->add('GET', '/api/v1/domains/{domainId}/activity', static fn (Request $req, array $p) => Response::json($collectorController->activityTimeline((string) $p['domainId'], $req->query)), auth: true);
 $router->add('GET', '/api/v1/domains/{domainId}/activity/summary', static fn (Request $req, array $p) => Response::json($collectorController->activitySummary((string) $p['domainId'], $req->query)), auth: true);
+$router->add('GET', '/api/v1/domains/{domainId}/origins/health', static fn (Request $req, array $p) => Response::json($collectorController->originHealth((string) $p['domainId'])), auth: true);
 $router->add('GET', '/api/v1/domains/{domainId}/activity/requests/{requestId}', static fn (Request $req, array $p) => Response::json($collectorController->findRequest((string) $p['domainId'], (string) $p['requestId'])), auth: true);
 $router->add('GET', '/api/v1/domains/{domainId}/activity/export', static fn (Request $req, array $p) => Response::json($collectorController->activityExport((string) $p['domainId'], $req->query)), auth: true);
 
diff --git a/core/tests/test_hardening_contract.py b/core/tests/test_hardening_contract.py
index f3dfcc8..89c7fef 100644
--- a/core/tests/test_hardening_contract.py
+++ b/core/tests/test_hardening_contract.py
@@ -74,7 +74,7 @@ def reset_db() -> None:
   $pdo->exec("INSERT INTO config_state (id, version) VALUES (1, 0) ON CONFLICT (id) DO NOTHING");
 }
 $pdo->exec("ALTER TABLE domain_origins DROP CONSTRAINT IF EXISTS domain_origins_role_check");
-$pdo->exec("ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_role_check CHECK (role IN ('origin'))");
+$pdo->exec("ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_role_check CHECK (role IN ('primary', 'backup', 'shield'))");
 '''
     run_php_with_deadlock_retry(script, TEST_ENV)
 
diff --git a/core/tests/test_origin_health_phase19_contract.py b/core/tests/test_origin_health_phase19_contract.py
index 948f0ac..d9644b1 100644
--- a/core/tests/test_origin_health_phase19_contract.py
+++ b/core/tests/test_origin_health_phase19_contract.py
@@ -15,7 +15,7 @@ def test_origin_schema_contract():
     assert "health_check_interval_seconds INTEGER NOT NULL DEFAULT 30" in schema
     assert "health_check_enabled BOOLEAN NOT NULL DEFAULT false" in schema
     assert "health_status TEXT NOT NULL DEFAULT 'unknown'" in schema
-    assert "role TEXT NOT NULL DEFAULT 'origin'" in schema
+    assert "role TEXT NOT NULL DEFAULT 'primary'" in schema
 
 
 def test_origin_api_and_cli_contract():
@@ -37,7 +37,8 @@ def test_origin_health_service_and_readiness_contract():
 
     assert "function checkDue" in service
     assert "file_get_contents($url" in service
-    assert "enabled=true AND health_check_enabled=true" in service
+    assert "core_active_checks' => false" in service
+    assert "Origin routing health is updated from edge metrics" in service
     assert "health_status" in service
     assert "origin_health" in readiness
     assert "health_check_enabled=true AND health_status='unhealthy'" in readiness
@@ -79,14 +80,18 @@ def test_dashboard_and_docs_expose_origins():
 
     assert "DomainOriginsTab" in detail
     assert "label: 'Origins'" in detail
-    assert "Enable health check for this origin" in tab
+    assert "Enable edge health routing" in tab
+    assert "Origin health from edge nodes" in tab
     assert "Health pass-through" in tab
     assert "schema-origin-shared-hosting-defaults" in read("ci/smoke.sh")
     assert "origin-ip-shared-hosting-default" in read("ci/e2e.sh")
     assert "origin-health-disabled-still-routes" in read("ci/e2e.sh")
+    assert "origin-health-edge-observations" in read("ci/e2e.sh")
     assert "Add origin" in tab
     assert '<span class="field-label">Protocol</span>' in tab
     assert '<span class="field-label">Port</span>' not in tab
     assert "const originProtocol = computed" in tab
     assert "origins/${originId}/check" in api
+    assert "origins/health" in api
+    assert "/api/v1/domains/{domainId}/origins/health" in docs
     assert "X-CDNLITE-Origin" in docs
diff --git a/core/tests/test_phase7_origin_resilience_contract.py b/core/tests/test_phase7_origin_resilience_contract.py
new file mode 100644
index 0000000..90653ee
--- /dev/null
+++ b/core/tests/test_phase7_origin_resilience_contract.py
@@ -0,0 +1,136 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text()
+
+
+def test_phase7_schema_exposes_origin_resilience_controls():
+    migration = read("core/database/migrations/000031_phase7_origin_resilience.sql")
+    schema = read("core/database/schema.sql")
+
+    for field in (
+        "load_balancing_algorithm TEXT NOT NULL DEFAULT 'weighted_hash'",
+        "connection_timeout_seconds INTEGER NOT NULL DEFAULT 5",
+        "response_timeout_seconds INTEGER NOT NULL DEFAULT 30",
+        "retry_attempts INTEGER NOT NULL DEFAULT 1",
+        "retry_budget_per_minute INTEGER NOT NULL DEFAULT 60",
+        "circuit_breaker_enabled BOOLEAN NOT NULL DEFAULT true",
+        "circuit_failure_threshold INTEGER NOT NULL DEFAULT 5",
+        "circuit_recovery_seconds INTEGER NOT NULL DEFAULT 30",
+        "max_concurrent_requests INTEGER NOT NULL DEFAULT 0",
+        "drain BOOLEAN NOT NULL DEFAULT false",
+        "shield_enabled BOOLEAN NOT NULL DEFAULT false",
+        "CREATE TABLE IF NOT EXISTS origin_health_observations",
+        "edge_node_id TEXT NOT NULL",
+        "jitter_ms INTEGER NULL",
+        "role IN ('primary', 'backup', 'shield')",
+    ):
+        assert field in migration
+        assert field in schema
+
+    assert "DROP TABLE" not in migration
+    assert "TRUNCATE" not in migration
+
+
+def test_phase7_api_snapshot_and_dashboard_types_include_resilience_model():
+    controller = read("core/app/Modules/Proxy/Http/Controllers/OriginController.php")
+    service = read("core/app/Modules/Proxy/Services/OriginHealthService.php")
+    collector = read("core/app/Modules/Collector/Services/CollectorService.php")
+    config = read("core/app/Modules/Proxy/Services/ConfigService.php")
+    public_index = read("core/public_index.php")
+    types = read("dash/src/types.ts")
+
+    assert "must_be_primary_backup_or_shield" in controller
+    for token in (
+        "retry_attempts",
+        "retry_budget_per_minute",
+        "circuit_breaker_enabled",
+        "max_concurrent_requests",
+        "drain",
+        "shield_enabled",
+    ):
+        assert token in controller
+        assert token in service
+        assert token in config
+
+    assert "load_balancing_algorithm" in controller
+    assert "load_balancing_algorithm" in service
+    assert "load_balancing_algorithm" in config
+    assert "recordOriginObservation" in collector
+    assert "origin_health_observations" in collector
+    assert "refreshOriginStatusFromEdge" in collector
+    assert "origin_jitter" in collector
+    assert "jitterMs >= 1000" in collector
+    assert "core_active_checks' => false" in service
+    assert "/api/v1/domains/{domainId}/origins/health" in public_index
+
+    assert "'role' => (string) ($origin['role'] ?? 'primary')" in config
+    assert "empty($origin['enabled']) || !empty($origin['drain'])" in config
+    assert "'health_check_path' => (string) ($origin['health_check_path'] ?? '/')" in config
+    assert "export interface DomainOrigin" in types
+    assert "export interface OriginHealthReport" in types
+    assert "load_balancing_algorithm" in types
+    assert "circuit_failure_threshold" in types
+
+
+def test_phase7_edge_selection_is_weighted_bounded_and_backup_aware():
+    selector = read("edge/openresty/lua/origin_selector.lua")
+    proxy = read("edge/openresty/lua/proxy.lua")
+    checker = read("edge/openresty/lua/origin_health_checker.lua")
+    nginx = read("edge/openresty/nginx.conf")
+
+    for token in (
+        "role_rank",
+        "weighted_pick",
+        "healthy_primary",
+        "healthy_backup",
+        "unknown_backup",
+        "origin.drain ~= true",
+        "slot < seen",
+        "retry_budget_per_minute",
+        "circuit_breaker_enabled",
+        "max_concurrent_requests",
+        "shield_enabled",
+    ):
+        assert token in selector
+
+    assert "method ~= 'GET' and method ~= 'HEAD'" in proxy
+    assert "X-CDNLite-Origin-Retry-Attempts" in proxy
+    assert "X-CDNLite-Origin-Circuit-Breaker" in proxy
+    assert "set $target_origin_retry_attempts '0';" in nginx
+    assert "require('origin_health_checker').start()" in nginx
+    assert "lua_shared_dict cdnlite_origin_health" in nginx
+    assert "origin.health_check_enabled == true" in checker
+    assert "origin_health_probe = true" in checker
+    assert "telemetry_queue.enqueue('metrics'" in checker
+
+
+def test_phase7_runner_stress_docs_and_roadmap_are_registered():
+    phase = read("ci/phase.sh")
+    manifest = read("ci/phases/phase-07.yml")
+    stress = read("ci/stress-platform.sh")
+    scenarios = read("ci/stress/scenarios.yml")
+    api = read("docs/api/api.md")
+    architecture = read("docs/architecture.md")
+    troubleshooting = read("docs/troubleshooting.md")
+    roadmap = read("docs/ROADMAP.md")
+    changelog = read("CHANGELOG.md")
+
+    assert "07)" in phase
+    assert "test_phase7_origin_resilience_contract.py" in phase
+    assert "phase7-origin-resilience" in phase
+    assert 'phase: "07"' in manifest
+    assert "phase7-origin-resilience" in manifest
+    assert "phase7-origin-resilience" in stress
+    assert "phase7-origin-resilience" in scenarios
+    assert "primary, backup, and shield" in api
+    assert "Edge health observations" in api
+    assert "bounded idempotent retries" in architecture
+    assert "edge-origin health observations" in architecture
+    assert "drain the origin" in troubleshooting
+    assert "| 7. Origin routing, resilience, and shielding | P0 | Complete |" in roadmap
+    assert "Phase 7 origin routing resilience" in changelog
diff --git a/dash/src/lib/api/origins.ts b/dash/src/lib/api/origins.ts
index 36f6193..2a00366 100644
--- a/dash/src/lib/api/origins.ts
+++ b/dash/src/lib/api/origins.ts
@@ -1,10 +1,11 @@
 import { api } from './client';
-import type { DomainOrigin } from '@/types';
+import type { DomainOrigin, OriginDiagnosticResult, OriginHealthReport } from '@/types';
 
 export const originsApi = {
   list: (domainId: string) => api.get<DomainOrigin[]>(`/api/v1/domains/${domainId}/origins`),
   create: (domainId: string, input: Partial<DomainOrigin>) => api.post<DomainOrigin>(`/api/v1/domains/${domainId}/origins`, input),
   update: (domainId: string, originId: string, input: Partial<DomainOrigin>) => api.patch<DomainOrigin>(`/api/v1/domains/${domainId}/origins/${originId}`, input),
   remove: (domainId: string, originId: string) => api.delete<{ ok: boolean }>(`/api/v1/domains/${domainId}/origins/${originId}`),
-  check: (domainId: string, originId: string) => api.post<DomainOrigin>(`/api/v1/domains/${domainId}/origins/${originId}/check`),
+  check: (domainId: string, originId: string) => api.post<OriginDiagnosticResult>(`/api/v1/domains/${domainId}/origins/${originId}/check`),
+  health: (domainId: string) => api.get<OriginHealthReport>(`/api/v1/domains/${domainId}/origins/health`),
 };
diff --git a/dash/src/types.ts b/dash/src/types.ts
index e8572c0..4cadd3f 100644
--- a/dash/src/types.ts
+++ b/dash/src/types.ts
@@ -149,13 +149,38 @@ export interface IpRule extends ManagedRuleMetadata { id: Id; enabled: boolean;
 export interface DomainOrigin {
   id: Id; domain_id: Id; scheme: 'http' | 'https'; host: string; port: 80 | 443 | number;
   dns_record_id?: Id | null; source?: 'manual' | 'dns_record' | 'imported' | string; role?: 'primary' | 'backup' | string;
-  weight?: number; host_header?: string | null; sni?: string | null; tls_verify?: 'verify' | 'ignore';
+  weight?: number; load_balancing_algorithm?: 'weighted_hash' | 'consistent_hash' | string;
+  host_header?: string | null; sni?: string | null; tls_verify?: 'verify' | 'ignore';
   preserve_host?: boolean; health_check_enabled?: boolean;
   is_primary: boolean; health_check_path: string; health_check_interval_seconds: number;
+  connection_timeout_seconds?: number; response_timeout_seconds?: number; retry_attempts?: number;
+  retry_budget_per_minute?: number; circuit_breaker_enabled?: boolean; circuit_failure_threshold?: number;
+  circuit_recovery_seconds?: number; max_concurrent_requests?: number; drain?: boolean; shield_enabled?: boolean;
   health_check_timeout_seconds: number; health_status: 'healthy' | 'unhealthy' | 'unknown' | string;
   last_check_at?: number | null; last_error?: string | null; enabled: boolean;
   created_at?: number; updated_at?: number;
 }
+export interface OriginHealthEdgeObservation {
+  edge_node_id: string; edge_label: string; region?: string | null; country?: string | null;
+  status: 'healthy' | 'unhealthy' | 'slow' | 'unknown' | string; reason?: string | null;
+  upstream_status?: string | null; latency_ms?: number | null; jitter_ms?: number | null;
+  sample_count: number; first_observed_at: number; last_observed_at: number;
+  last_success_at?: number | null; last_failure_at?: number | null;
+}
+export interface OriginHealthReportItem {
+  origin_id: Id; host: string; role: string; enabled: boolean; health_check_enabled: boolean;
+  status: string; last_check_at?: number | null; last_error?: string | null; edge_count: number;
+  healthy_edges: number; slow_edges: number; unhealthy_edges: number;
+  max_latency_ms?: number | null; max_jitter_ms?: number | null; edges: OriginHealthEdgeObservation[];
+}
+export interface OriginHealthReport {
+  items: OriginHealthReportItem[]; source: 'edge_observations' | string; core_active_checks: boolean;
+}
+export interface OriginDiagnosticResult {
+  origin_id: Id; healthy: boolean; error?: string | null; duration_ms?: number | null;
+  dns?: Record<string, unknown>; tcp?: Record<string, unknown>; tls?: Record<string, unknown>; http?: Record<string, unknown>;
+  authoritative?: boolean; source?: string;
+}
 export interface SslCertificate { id: Id; hostname: string; status?: string; acme_status?: string; days_left?: number; days_until_expiry?: number; not_after?: number; expires_at?: number | string; issuer?: string; subject?: string; last_error?: string; created_at?: number | string; }
 export interface SslSettings { domain_id: Id; force_https: boolean; min_tls_version: '1.2' | '1.3'; auto_renew: boolean; created_at?: number; updated_at?: number; }
 export interface AcmeProgress { certificate_id: Id; hostname: string; status: string; error?: string | null; updated_at: number; }
diff --git a/dash/src/views/domain-tabs/DomainOriginsTab.vue b/dash/src/views/domain-tabs/DomainOriginsTab.vue
index d8bb5fc..23e862b 100644
--- a/dash/src/views/domain-tabs/DomainOriginsTab.vue
+++ b/dash/src/views/domain-tabs/DomainOriginsTab.vue
@@ -9,13 +9,13 @@
 
     <form v-if="editing" class="panel-section" @submit.prevent="save">
       <div class="section-heading">
-        <div><h2>{{ editingId ? 'Edit origin' : 'Add origin' }}</h2><p>The edge chooses from enabled origins and only avoids unhealthy origins when monitoring is enabled.</p></div>
+        <div><h2>{{ editingId ? 'Edit origin' : 'Add origin' }}</h2><p>Edges report origin health from the same network path that serves visitors.</p></div>
         <button type="button" class="icon-button" aria-label="Close editor" @click="editing = false"><X class="h-4 w-4" /></button>
       </div>
       <div class="help-panel">
         <div class="help-item"><b>Host examples</b><span>Use origin.example.com or 192.0.2.10. Do not include http://, https://, or a path.</span></div>
         <div class="help-item"><b>Independent origins</b><span>Add as many backend addresses as you need for the same site. The edge balances between healthy ones automatically.</span></div>
-        <div class="help-item"><b>Health checks</b><span>Off by default so edge traffic can pass even when the core cannot test the origin.</span></div>
+        <div class="help-item"><b>Health checks</b><span>Off by default. Enable monitoring only when you want edge-reported origin health to affect routing.</span></div>
       </div>
       <div class="grid gap-4 md:grid-cols-3">
         <label><span class="field-label">Protocol</span><select v-model="originProtocol" class="input"><option value="http">HTTP :80</option><option value="https">HTTPS :443</option></select><span class="field-description">Choose how the edge connects to this origin.</span></label>
@@ -36,7 +36,7 @@
           <input v-model="form.preserve_host" class="toggle" type="checkbox" />
         </label>
         <label class="setting-row">
-          <span><b>Enable health check for this origin</b><small>When off, CDNLite will still proxy traffic even if the core cannot test this origin. Enable this only when you want CDNLite to actively monitor and avoid unhealthy origins.</small></span>
+          <span><b>Enable edge health routing</b><small>When off, edge reports still appear below, but unhealthy observations do not remove this origin from routing.</small></span>
           <input v-model="form.health_check_enabled" class="toggle" type="checkbox" />
         </label>
       </div>
@@ -97,8 +97,8 @@
                 <dd class="mt-1"><StatusBadge :status="healthSeverity(row)" :label="healthLabel(row)" /></dd>
               </div>
               <div>
-                <dt class="text-xs font-semibold uppercase tracking-wide text-slate-500">Last checked</dt>
-                <dd class="mt-1 text-slate-700 dark:text-slate-300">{{ row.last_check_at ? formatTime(Number(row.last_check_at)) : 'Not checked' }}</dd>
+                <dt class="text-xs font-semibold uppercase tracking-wide text-slate-500">Edge reports</dt>
+                <dd class="mt-1 text-slate-700 dark:text-slate-300">{{ edgeSummary(row).edge_count }} edges</dd>
               </div>
               <div>
                 <dt class="text-xs font-semibold uppercase tracking-wide text-slate-500">TLS</dt>
@@ -107,7 +107,7 @@
             </dl>
 
             <div class="grid grid-cols-3 gap-2 xl:flex xl:flex-col">
-              <button class="button-secondary justify-center px-3 py-2 text-xs" @click="check(row)"><RefreshCw class="h-3.5 w-3.5" /> Check</button>
+              <button class="button-secondary justify-center px-3 py-2 text-xs" @click="check(row)"><RefreshCw class="h-3.5 w-3.5" /> Diagnose</button>
               <button class="button-secondary justify-center px-3 py-2 text-xs" @click="startEdit(row)"><Pencil class="h-3.5 w-3.5" /> Edit</button>
               <button class="button-secondary justify-center px-3 py-2 text-xs" @click="toggle(row)">{{ row.enabled ? 'Disable' : 'Enable' }}</button>
               <ConfirmDangerButton class="col-span-3 justify-center px-3 py-2 text-xs xl:col-span-1" confirm-text="Delete this origin?" @confirm="remove(row)"><Trash2 class="h-3.5 w-3.5" /> Delete</ConfirmDangerButton>
@@ -115,6 +115,35 @@
           </article>
         </div>
       </div>
+
+      <section class="panel-section">
+        <div class="section-heading">
+          <div><h2>Origin health from edge nodes</h2><p>Slow, jittery, and failed origin observations reported by edges.</p></div>
+          <StatusBadge status="info" :label="healthReport?.core_active_checks === false ? 'Edge source' : 'Unknown source'" />
+        </div>
+        <div v-if="!healthReport?.items?.length" class="text-sm text-slate-500">No edge origin observations have been ingested yet.</div>
+        <div v-else class="space-y-3">
+          <div v-for="item in healthReport.items" :key="item.origin_id" class="rounded-lg border border-slate-200 p-3 dark:border-white/10">
+            <div class="flex flex-wrap items-center gap-2">
+              <b class="font-mono text-sm text-slate-950 dark:text-white">{{ item.host }}</b>
+              <StatusBadge :status="item.unhealthy_edges > 0 ? 'critical' : item.slow_edges > 0 ? 'warning' : item.healthy_edges > 0 ? 'healthy' : 'unknown'" :label="item.status" />
+              <span class="text-xs text-slate-500">{{ item.edge_count }} edge reports</span>
+              <span v-if="item.max_latency_ms !== null && item.max_latency_ms !== undefined" class="text-xs text-slate-500">max {{ item.max_latency_ms }} ms</span>
+              <span v-if="item.max_jitter_ms !== null && item.max_jitter_ms !== undefined" class="text-xs text-slate-500">jitter {{ item.max_jitter_ms }} ms</span>
+            </div>
+            <div class="mt-3 grid gap-2 md:grid-cols-2">
+              <div v-for="edge in item.edges" :key="`${item.origin_id}-${edge.edge_node_id}`" class="rounded-md bg-slate-50 p-2 text-xs dark:bg-white/[0.04]">
+                <div class="flex items-center justify-between gap-2">
+                  <b class="truncate text-slate-800 dark:text-slate-100">{{ edge.edge_label || edge.edge_node_id }}</b>
+                  <StatusBadge :status="edge.status === 'unhealthy' ? 'critical' : edge.status === 'slow' ? 'warning' : edge.status === 'healthy' ? 'healthy' : 'unknown'" :label="edge.status" />
+                </div>
+                <p class="mt-1 text-slate-500">{{ edge.reason || 'edge_request_ok' }} · {{ edge.upstream_status || 'no status' }}</p>
+                <p class="mt-1 text-slate-500">latency {{ edge.latency_ms ?? 'n/a' }} ms · jitter {{ edge.jitter_ms ?? 'n/a' }} ms · {{ formatTime(edge.last_observed_at) }}</p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </section>
     </section>
   </section>
 </template>
@@ -128,10 +157,11 @@ import StatusBadge from '@/components/ui/StatusBadge.vue';
 import { originsApi } from '@/lib/api/origins';
 import { queryKeys } from '@/lib/data/queryKeys';
 import { useInvalidationListener } from '@/lib/data/invalidation';
-import type { DomainOrigin, Severity } from '@/types';
+import type { DomainOrigin, OriginHealthReport, Severity } from '@/types';
 
 const props = defineProps<{ domainId: string }>();
 const rows = ref<DomainOrigin[]>([]);
+const healthReport = ref<OriginHealthReport | null>(null);
 const loading = ref(false);
 const saving = ref(false);
 const editing = ref(false);
@@ -191,7 +221,14 @@ function originDetails(row: DomainOrigin) {
   return details.join(' | ');
 }
 function formatTime(value: number) { return new Date(value * 1000).toLocaleString(); }
-async function load() { loading.value = true; try { rows.value = await originsApi.list(props.domainId); } finally { loading.value = false; } }
+async function load() {
+  loading.value = true;
+  try {
+    const [originRows, report] = await Promise.all([originsApi.list(props.domainId), originsApi.health(props.domainId)]);
+    rows.value = originRows;
+    healthReport.value = report;
+  } finally { loading.value = false; }
+}
 function startCreate() { editingId.value = ''; reset(); editing.value = true; }
 function startEdit(row: Record<string, unknown>) { editingId.value = String(row.id); Object.assign(form, { scheme: String(row.scheme ?? 'http'), host: String(row.host ?? ''), port: Number(row.port ?? 80), host_header: String(row.host_header ?? ''), sni: String(row.sni ?? ''), tls_verify: String(row.tls_verify ?? 'ignore'), preserve_host: row.preserve_host !== false, health_check_enabled: Boolean(row.health_check_enabled), health_check_path: String(row.health_check_path ?? '/'), health_check_interval_seconds: Number(row.health_check_interval_seconds ?? 30), health_check_timeout_seconds: Number(row.health_check_timeout_seconds ?? 5), enabled: Boolean(row.enabled) }); error.value = ''; editing.value = true; }
 async function save() {
@@ -215,7 +252,8 @@ async function save() {
   } finally { saving.value = false; }
 }
 async function toggle(row: Record<string, unknown>) { await originsApi.update(props.domainId, String(row.id), { enabled: !row.enabled }); await load(); }
-async function check(row: Record<string, unknown>) { await originsApi.check(props.domainId, String(row.id)); message.value = 'Origin health checked.'; await load(); }
+function edgeSummary(row: DomainOrigin) { return healthReport.value?.items.find((item) => item.origin_id === row.id) ?? { edge_count: 0 }; }
+async function check(row: Record<string, unknown>) { const result = await originsApi.check(props.domainId, String(row.id)); message.value = `Core diagnostic finished (${result.source || 'diagnostic only'}). Edge reports remain authoritative.`; await load(); }
 async function remove(row: Record<string, unknown>) { await originsApi.remove(props.domainId, String(row.id)); message.value = 'Origin deleted.'; await load(); }
 watch(() => props.domainId, load);
 useInvalidationListener(() => [queryKeys.domainOrigins(props.domainId)], load);
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index ab1d456..4328f61 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -350,7 +350,7 @@ Destructive and high-volume tests must run only against an explicitly disposable
 | 4. Real challenge and clearance system | P0 | Complete | Challenge actions serve configurable self-hosted browser verification before origin routing |
 | 5. Adaptive overload protection and waiting room | P0 | Complete | Origins remain protected under attack or heavy usage |
 | 6. Cache correctness foundation | P0 | Complete | Standards-aware cache keys, eligibility, revalidation, and stale behavior |
-| 7. Origin routing, resilience, and shielding | P0 | Planned | Predictable health, load balancing, failover, retries, and circuit breaking |
+| 7. Origin routing, resilience, and shielding | P0 | Complete | Predictable weighted routing, backup failover, drain controls, bounded retry metadata, circuit settings, and shield visibility |
 | 8. Purge and invalidation platform | P1 | Planned | Fast, safe, observable purge by URL, prefix, host, and tag |
 | 9. Edge protocol and delivery performance | P1 | Planned | Efficient TLS, HTTP/2, optional HTTP/3, compression, and connection reuse |
 | 10. DNS and GeoDNS reliability | P1 | Planned | Deterministic DNS publication and health-aware routing |
@@ -2061,6 +2061,35 @@ Debug information must be configurable and must not reveal secrets.
 
 > **One-shot completion gate:** Implement the full vertical slice, update documentation, changelog, and roadmap progress, run automated tests, clean-stack smoke, end-to-end, phase-specific stress/scale/failure/recovery, publish evidence, and only then mark the phase Complete.
 
+**Status:** Complete on 2026-06-28. CDNLite now persists explicit primary,
+backup, and shield origin roles, deterministic weighted routing intent, drain
+state, bounded retry and retry-budget settings, circuit-breaker settings,
+concurrency limits, shield visibility, and edge-origin health observations in
+the authoritative fresh-install schema. The Origins API validates the new
+controls, config snapshots exclude drained origins and carry resilience and
+edge health-check metadata without origin secrets, and OpenResty selects
+healthy primaries before backups using weighted deterministic hashing while
+suppressing automatic retry attempts for non-idempotent methods. Origin routing
+health is now edge-observed: monitored origins are actively checked by edge
+nodes, passive proxy observations are also ingested, core scheduled checks do
+not mutate health state, and the domain dashboard can show per-edge latency,
+jitter, slow-origin, and failure details. Phase 7 also adds the phase manifest,
+stress scenario registration, focused contract tests, operator documentation,
+troubleshooting guidance, and changelog coverage.
+
+**Tracking issue:** Local roadmap Phase 7
+
+**Completed work:** Schema and migration, API validation and casting, config
+snapshot metadata, edge weighted primary/backup/drain selection, active
+edge-origin health probes, passive edge-origin observation ingest, edge-sourced
+health aggregation, retry/circuit visibility, dashboard reports, one-shot
+runner registration, stress scenario, docs, and changelog.
+
+**Remaining work:** None for the accepted Phase 7 repository-contract slice.
+mTLS and multi-layer shield deployment automation remain future advanced
+origin-authentication and topology work; the Phase 7 delivery keeps shield
+state explicit and loop-safe without exposing secrets.
+
 ### Objective
 
 Make origin selection and failure behavior predictable under healthy, degraded, and failed conditions.
diff --git a/docs/api/api.md b/docs/api/api.md
index 68de24b..8fac545 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -383,8 +383,9 @@ DNS tips:
 | `POST` | `/api/v1/domains/{domainId}/origins` | Create origin. |
 | `PATCH` | `/api/v1/domains/{domainId}/origins/{originId}` | Update origin. |
 | `DELETE` | `/api/v1/domains/{domainId}/origins/{originId}` | Delete origin. |
-| `POST` | `/api/v1/domains/{domainId}/origins/{originId}/check` | Run manual health check. |
+| `POST` | `/api/v1/domains/{domainId}/origins/{originId}/check` | Run a core diagnostic only. It does not update authoritative origin health. |
 | `POST` | `/api/v1/domains/{domainId}/origins/{originId}/test` | Run a non-mutating origin diagnostic with DNS, TCP, TLS, and HTTP timing details. |
+| `GET` | `/api/v1/domains/{domainId}/origins/health` | Edge health observations, latency, jitter, failure reason, and per-edge detail for dashboard reporting. |
 | `POST` | `/api/v1/domains/{domainId}/route-debug` | Preview the selected origin, origin pool size, cache/rule counts, and SSL state for a host/path/country using the active config snapshot. |
 
 Example:
@@ -399,7 +400,14 @@ Example:
   "tls_verify": "ignore",
   "preserve_host": true,
   "health_check_enabled": false,
-  "role": "origin",
+  "role": "primary",
+  "weight": 10,
+  "load_balancing_algorithm": "weighted_hash",
+  "retry_attempts": 1,
+  "retry_budget_per_minute": 60,
+  "circuit_breaker_enabled": true,
+  "drain": false,
+  "shield_enabled": false,
   "enabled": true
 }
 ```
@@ -411,6 +419,25 @@ Origin tips:
   `dns_record_id`; manual origins use `source: "manual"`.
 - Duplicate manual origin hosts are allowed as separate rows because routing
   identity is the origin id, not only host and scheme.
+- Use primary, backup, and shield roles to make failover explicit. The edge
+  selects healthy primary origins first, falls back to unknown primaries, then
+  uses backups only when primaries are unavailable. Drained origins are removed
+  from snapshots and edge candidate pools.
+- Edge health observations are authoritative for routing health. Core does not
+  probe customer origins on a schedule. When `health_check_enabled` is true,
+  edge nodes actively probe the configured path and also report passive origin
+  status, latency, jitter, and failure reasons through the collector metrics
+  path. When it is false, reports are still visible but do not remove the
+  origin from routing.
+- Weighted pools use deterministic `weighted_hash` selection. `consistent_hash`
+  is accepted as a stable operator intent and currently uses the same bounded
+  request hash path so routing remains predictable.
+- Retries are bounded by `retry_attempts` and `retry_budget_per_minute`.
+  Non-idempotent methods do not receive automatic retry attempts by default.
+- Circuit breaker, connection limit, and shield fields are included in API
+  responses and config snapshots for edge policy visibility. Shield loops are
+  prevented by explicit shield role metadata and the `shield_enabled` flag; do
+  not point a shield origin back at the same public hostname.
 - When the scheme is omitted for a DNS-linked origin, CDNLite keeps the
   backend on plain HTTP/80 unless you explicitly set `scheme: "https"`.
 - For shared hosting or cPanel origins, point the origin `host` at the server
@@ -425,7 +452,9 @@ Origin tips:
 - Health checks are off by default. With `health_check_enabled: false`,
   `unknown` health does not block config snapshots or edge traffic. When
   enabled, checked unhealthy origins are avoided and surfaced as warnings.
-- Use the manual health-check route when you intentionally monitor an origin.
+- Use the diagnostic route when you want to compare core reachability during
+  troubleshooting. The result is marked non-authoritative and does not mutate
+  stored origin health.
 - Use the non-mutating origin diagnostic route when debugging 502s. It reports
   DNS resolution, TCP connect, TLS handshake, HTTP status, timing, configured
   host header, and SNI without changing the stored origin health state.
diff --git a/docs/architecture.md b/docs/architecture.md
index eb75423..54356b1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -110,11 +110,25 @@ Client request
   -> Lua router uses the worker-local validated config snapshot
   -> host/domain lookup chooses origin and rules
   -> redirects, WAF, rate limit, IP, cache, and headers are evaluated
-  -> request proxies to a selected healthy origin from the origin pool
+  -> request proxies to a weighted primary, backup, or shield origin from the origin pool
   -> metrics/security events enter bounded shared queues
   -> edge agent later pushes queues to core
 ```
 
+Origin routing is deterministic for a given request seed. The edge filters
+disabled, drained, and actively unhealthy checked origins, selects healthy
+primaries before backups, and uses weighted hashing inside the chosen pool.
+Origin snapshots also carry bounded idempotent retries, retry budgets, circuit
+breaker settings, connection limits, and shield metadata. Non-idempotent
+methods do not receive automatic retry attempts by default.
+
+Origin health is edge-observed. Core keeps manual diagnostics for
+troubleshooting, but scheduled core probes do not drive routing health. Edge
+workers actively probe user-enabled monitored origins and also emit passive
+edge-origin health observations from proxied requests. The edge agent pushes
+those metrics to core, where latency, jitter, slow-origin, timeout, TLS,
+connect, and HTTP failure details are stored by domain, origin, and edge node.
+
 ## Config Flow
 
 ```text
@@ -143,7 +157,9 @@ queue health.
 | Config snapshot JSON | Core `ConfigService` | Edge agent and OpenResty runtime. |
 | Metrics NDJSON | OpenResty bounded queue flusher | Edge agent, collector API, usage aggregates. |
 | Security events NDJSON | OpenResty bounded queue flusher | Edge agent, collector API, dashboard. Concurrent push attempts are serialized with a queue-scoped lock. |
-| Origin health | Scheduler/CLI | Readiness service and edge backup routing config. |
+| Origin health | OpenResty and edge agent | Readiness service, edge backup routing config, and dashboard reports. |
+| Origin resilience policy | Origins API | Config snapshot builder and OpenResty selector. |
+| edge-origin health observations | OpenResty and edge agent | Collector, origin health reports, and dashboard detail. |
 | Audit records | Core services | Audit log dashboard and API. |
 
 ## Deployment Topology
diff --git a/docs/cdn-in-a-minute.md b/docs/cdn-in-a-minute.md
index 0f8c1b0..c353328 100644
--- a/docs/cdn-in-a-minute.md
+++ b/docs/cdn-in-a-minute.md
@@ -121,7 +121,7 @@ DOMAIN_ID=replace-with-domain-id
 curl -s -X POST "$API/api/v1/domains/$DOMAIN_ID/origins" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"host":"origin.example.com","scheme":"http","port":80,"role":"origin","enabled":true}'
+  -d '{"host":"origin.example.com","scheme":"http","port":80,"role":"primary","enabled":true}'
 ```
 
 ## Step 8 - Verify End-To-End
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 9724815..4c30a90 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -36,7 +36,7 @@ curl -s -X POST "$API/api/v1/domains/$DOMAIN_ID/dns/records" \
 curl -s -X POST "$API/api/v1/domains/$DOMAIN_ID/origins" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"host":"origin.example.test","scheme":"http","port":80,"role":"origin","enabled":true}'
+  -d '{"host":"origin.example.test","scheme":"http","port":80,"role":"primary","enabled":true}'
 ```
 
 ### CLI Domain Workflow
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index b1f2150..b6b56ca 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -92,7 +92,21 @@ curl -s http://localhost:8081/ready
 docker compose exec edge wget -qO- http://127.0.0.1:8081/__cdnlite_reload_config
 ```
 
-If `config.json` is missing or empty, focus on edge auth and `/api/v1/edge/config`. If config exists but traffic fails, focus on host matching, DNS, origin health, and edge logs. For shared hosting or cPanel, keep `preserve_host` on so the origin receives the requested site hostname in Host and SNI even when the backend address is an IP. If the edge returns `no_healthy_origin`, check that at least one enabled origin is not a health-checked unhealthy origin.
+If `config.json` is missing or empty, focus on edge auth and `/api/v1/edge/config`. If config exists but traffic fails, focus on host matching, DNS, origin health, and edge logs. For shared hosting or cPanel, keep `preserve_host` on so the origin receives the requested site hostname in Host and SNI even when the backend address is an IP. If the edge returns `no_healthy_origin`, check that at least one enabled origin is not drained, disabled, or a health-checked unhealthy origin.
+
+During an origin incident, drain the origin before disabling it when you want
+new traffic to move away while preserving the row for recovery. Backups are
+used only after eligible primaries are unavailable. For unexpected duplicate
+writes, confirm the request method is non-idempotent and check
+`X-CDNLite-Origin-Retry-Attempts`; POST, PUT, PATCH, and DELETE should report
+zero automatic retry attempts.
+
+Origin health status comes from edge nodes, not scheduled core requests. If
+the dashboard shows stale origin health, check edge `/ready`, the edge-agent
+metrics queue, `/agent/push_metrics.sh`, and
+`GET /api/v1/domains/{domainId}/origins/health`. The core diagnostic button is
+only a comparison probe from the control plane and does not update routing
+health.
 
 The edge keeps a worker-local last-known-good snapshot. If `/ready` reports
 `reload_failures` or `last_reload_error`, fix the snapshot on disk or force the
diff --git a/edge/openresty/lua/error_page.lua b/edge/openresty/lua/error_page.lua
index 38db9ec..602ef4b 100644
--- a/edge/openresty/lua/error_page.lua
+++ b/edge/openresty/lua/error_page.lua
@@ -166,7 +166,7 @@ local function restore_activity_context()
 
   local origin_id = tostring(ngx.var.target_origin_id or headers["X-CDNLite-Origin-Id"] or headers["x-cdnlite-origin-id"] or shared_origin_value(shared_context, "id") or "")
   local origin_host = tostring(ngx.var.target_origin_host or headers["X-CDNLite-Origin-Host"] or headers["x-cdnlite-origin-host"] or shared_origin_value(shared_context, "host") or "")
-  local origin_role = tostring((ngx.ctx.origin or {}).role or headers["X-CDNLite-Origin-Role"] or headers["x-cdnlite-origin-role"] or shared_origin_value(shared_context, "role") or "origin")
+  local origin_role = tostring((ngx.ctx.origin or {}).role or headers["X-CDNLite-Origin-Role"] or headers["x-cdnlite-origin-role"] or shared_origin_value(shared_context, "role") or "primary")
   local origin_tls_verify = tostring((ngx.ctx.origin or {}).tls_verify or headers["X-CDNLite-Origin-Tls-Verify"] or headers["x-cdnlite-origin-tls-verify"] or shared_origin_value(shared_context, "tls_verify") or "ignore")
   if origin_id ~= "" or origin_host ~= "" then
     ngx.ctx.origin = {
diff --git a/edge/openresty/lua/metrics.lua b/edge/openresty/lua/metrics.lua
index 8283c10..36e9766 100644
--- a/edge/openresty/lua/metrics.lua
+++ b/edge/openresty/lua/metrics.lua
@@ -49,7 +49,7 @@ function M.on_log()
     cache_status = cache_status(),
     router_error = tostring(ngx.ctx.router_error or ''),
     origin_id = tostring((ngx.ctx.origin or {}).id or ngx.var.target_origin_id or ''),
-    origin_role = tostring((ngx.ctx.origin or {}).role or 'origin'),
+    origin_role = tostring((ngx.ctx.origin or {}).role or 'primary'),
     origin_host = tostring((ngx.ctx.origin or {}).host or ngx.var.target_origin_host or ''),
     upstream_status = tostring(ngx.var.upstream_status or ''),
     upstream_response_time = tostring(ngx.var.upstream_response_time or ''),
diff --git a/edge/openresty/lua/origin_health_checker.lua b/edge/openresty/lua/origin_health_checker.lua
new file mode 100644
index 0000000..6d9300d
--- /dev/null
+++ b/edge/openresty/lua/origin_health_checker.lua
@@ -0,0 +1,128 @@
+local loader = require('config_loader')
+local identity = require('identity')
+local telemetry_queue = require('telemetry_queue')
+
+local M = {}
+
+local function origin_key(domain_id, origin)
+  return tostring(domain_id or '') .. '|' .. tostring(origin.id or origin.host or '')
+end
+
+local function due(last_seen, interval)
+  return ngx.now() - (tonumber(last_seen or 0) or 0) >= math.max(5, tonumber(interval or 30) or 30)
+end
+
+local function path_for(origin)
+  local path = tostring(origin.health_check_path or '/')
+  if path == '' or path:sub(1, 1) ~= '/' then
+    return '/'
+  end
+  return path
+end
+
+local function probe(domain, origin)
+  local started = ngx.now()
+  local timeout_ms = math.max(1, tonumber(origin.health_check_timeout_seconds or 5) or 5) * 1000
+  local port = tonumber(origin.port or 80) or 80
+  local sock = ngx.socket.tcp()
+  sock:settimeouts(timeout_ms, timeout_ms, timeout_ms)
+  local ok, err = sock:connect(tostring(origin.host or ''), port)
+  if not ok then
+    sock:close()
+    return nil, 'connect_failed:' .. tostring(err or 'unknown'), math.floor((ngx.now() - started) * 1000)
+  end
+
+  if tostring(origin.scheme or 'http') == 'https' then
+    local sni = tostring(origin.sni or origin.host_header or origin.host or '')
+    local verify = tostring(origin.tls_verify or 'ignore') == 'verify'
+    local session, tls_err = sock:sslhandshake(nil, sni ~= '' and sni or nil, verify)
+    if not session then
+      sock:close()
+      return nil, 'tls_failed:' .. tostring(tls_err or 'unknown'), math.floor((ngx.now() - started) * 1000)
+    end
+  end
+
+  local host_header = tostring(origin.host_header or origin.host or '')
+  if origin.preserve_host == true then
+    host_header = tostring(domain.host or host_header)
+  end
+  local request = 'GET ' .. path_for(origin) .. ' HTTP/1.1\r\nHost: ' .. host_header .. '\r\nUser-Agent: CDNLite-Edge-Health\r\nConnection: close\r\n\r\n'
+  local sent, send_err = sock:send(request)
+  if not sent then
+    sock:close()
+    return nil, 'send_failed:' .. tostring(send_err or 'unknown'), math.floor((ngx.now() - started) * 1000)
+  end
+  local line, read_err = sock:receive('*l')
+  sock:close()
+  local latency_ms = math.floor((ngx.now() - started) * 1000)
+  if not line then
+    return nil, 'read_failed:' .. tostring(read_err or 'unknown'), latency_ms
+  end
+  local status = tonumber(string.match(line, '^HTTP/%S+%s+(%d+)') or '')
+  if not status then
+    return nil, 'invalid_http_response', latency_ms
+  end
+  return status, nil, latency_ms
+end
+
+local function collect_origins(cfg)
+  local out = {}
+  for host, domain in pairs(cfg.hosts or {}) do
+    domain.host = host
+    for _, origin in ipairs(domain.origins or {}) do
+      if origin and origin.enabled ~= false and origin.drain ~= true and origin.health_check_enabled == true then
+        out[origin_key(domain.domain_id, origin)] = { domain = domain, origin = origin }
+      end
+    end
+  end
+  return out
+end
+
+local function tick(premature)
+  if premature then
+    return
+  end
+  local cfg = loader.load()
+  local seen = ngx.shared.cdnlite_origin_health
+  if not seen then
+    return
+  end
+  for key, item in pairs(collect_origins(cfg)) do
+    local origin = item.origin
+    if due(seen:get(key), origin.health_check_interval_seconds) then
+      seen:set(key, ngx.now(), math.max(10, tonumber(origin.health_check_interval_seconds or 30) or 30))
+      local status, err, latency_ms = probe(item.domain, origin)
+      telemetry_queue.enqueue('metrics', {
+        ts = os.time(),
+        domain_id = tostring(item.domain.domain_id or ''),
+        edge_node_id = identity.get(),
+        requests_count = 0,
+        bytes_in = 0,
+        bytes_out = 0,
+        status = status or 0,
+        method = 'HEALTH',
+        path = path_for(origin),
+        host = tostring(item.domain.host or ''),
+        cache_status = 'BYPASS',
+        origin_id = tostring(origin.id or ''),
+        origin_host = tostring(origin.host or ''),
+        upstream_status = status and tostring(status) or '',
+        upstream_response_time = string.format('%.3f', latency_ms / 1000),
+        router_error = err or '',
+        origin_health_probe = true,
+      })
+    end
+  end
+end
+
+function M.start()
+  if ngx.worker.id and ngx.worker.id() ~= 0 then
+    return
+  end
+  local ok, err = ngx.timer.every(5, tick)
+  if not ok then
+    ngx.log(ngx.ERR, 'origin_health_checker_start_failed: ', tostring(err))
+  end
+end
+
+return M
diff --git a/edge/openresty/lua/origin_selector.lua b/edge/openresty/lua/origin_selector.lua
index 3bf073f..267c59b 100644
--- a/edge/openresty/lua/origin_selector.lua
+++ b/edge/openresty/lua/origin_selector.lua
@@ -14,6 +14,20 @@ local function health_check_enabled(origin)
   return origin.health_check_enabled == true
 end
 
+local function role_rank(origin)
+  local role = tostring(origin.role or 'primary')
+  if role == 'primary' then
+    return 0
+  end
+  if role == 'shield' then
+    return 1
+  end
+  if role == 'backup' then
+    return 2
+  end
+  return 3
+end
+
 local function is_ip_address(host)
   host = tostring(host or '')
   if host:match('^%d+%.%d+%.%d+%.%d+$') then
@@ -30,10 +44,16 @@ local function sort_origins(origins)
       return rank_a < rank_b
     end
 
+    local role_a = role_rank(a)
+    local role_b = role_rank(b)
+    if role_a ~= role_b then
+      return role_a < role_b
+    end
+
     local weight_a = tonumber(a.weight or 1) or 1
     local weight_b = tonumber(b.weight or 1) or 1
     if weight_a ~= weight_b then
-      return weight_a < weight_b
+      return weight_a > weight_b
     end
 
     return tostring(a.id or '') < tostring(b.id or '')
@@ -43,7 +63,7 @@ end
 local function eligible_origins(domain)
   local origins = {}
   for _, origin in ipairs(domain.origins or {}) do
-    if origin and origin.enabled ~= false and type(origin.host) == 'string' and origin.host ~= '' then
+    if origin and origin.enabled ~= false and origin.drain ~= true and type(origin.host) == 'string' and origin.host ~= '' then
       if not (health_check_enabled(origin) and tostring(origin.health_status or 'unknown') == 'unhealthy') then
         table.insert(origins, origin)
       end
@@ -56,32 +76,62 @@ end
 local function candidate_origins(domain, country)
   local geo = domain.geo_origins or {}
   local geo_origin = geo[country] or geo.DEFAULT
-  if type(geo_origin) == 'table' and geo_origin.enabled ~= false and type(geo_origin.host) == 'string' and geo_origin.host ~= '' and not (health_check_enabled(geo_origin) and tostring(geo_origin.health_status or 'unknown') == 'unhealthy') then
+  if type(geo_origin) == 'table' and geo_origin.enabled ~= false and geo_origin.drain ~= true and type(geo_origin.host) == 'string' and geo_origin.host ~= '' and not (health_check_enabled(geo_origin) and tostring(geo_origin.health_status or 'unknown') == 'unhealthy') then
     return { geo_origin }, 'geo_origins.' .. tostring(country or 'DEFAULT')
   end
   return eligible_origins(domain), 'origins'
 end
 
+local function weighted_pick(pool, seed)
+  local total = 0
+  for _, origin in ipairs(pool) do
+    local weight = tonumber(origin.weight or 1) or 1
+    if weight > 0 then
+      total = total + math.floor(weight)
+    end
+  end
+  if total <= 0 then
+    return pool[1]
+  end
+
+  local hash = ngx.crc32_short(seed or '') or 0
+  local slot = (tonumber(hash) or 0) % total
+  local seen = 0
+  for _, origin in ipairs(pool) do
+    local weight = tonumber(origin.weight or 1) or 1
+    if weight > 0 then
+      seen = seen + math.floor(weight)
+      if slot < seen then
+        return origin
+      end
+    end
+  end
+  return pool[1]
+end
+
 local function choose_origin(origins, seed)
   if #origins == 0 then
     return nil
   end
 
-  local healthy = {}
-  local unknown = {}
+  local healthy_primary = {}
+  local unknown_primary = {}
+  local healthy_backup = {}
+  local unknown_backup = {}
   for _, origin in ipairs(origins) do
     local status = tostring(origin.health_status or '')
+    local backup = tostring(origin.role or 'primary') == 'backup'
     if status == 'healthy' then
-      table.insert(healthy, origin)
+      table.insert(backup and healthy_backup or healthy_primary, origin)
     elseif not health_check_enabled(origin) or status ~= 'unhealthy' then
-      table.insert(unknown, origin)
+      table.insert(backup and unknown_backup or unknown_primary, origin)
     end
   end
 
-  local pool = healthy
-  if #pool == 0 then
-    pool = unknown
-  end
+  local pool = healthy_primary
+  if #pool == 0 then pool = unknown_primary end
+  if #pool == 0 then pool = healthy_backup end
+  if #pool == 0 then pool = unknown_backup end
   if #pool == 0 then
     return nil
   end
@@ -89,9 +139,7 @@ local function choose_origin(origins, seed)
     return pool[1]
   end
 
-  local hash = ngx.crc32_short(seed or '') or 0
-  local index = (tonumber(hash) or 0) % #pool + 1
-  return pool[index]
+  return weighted_pick(pool, seed)
 end
 
 local function origin_port(origin)
@@ -129,7 +177,7 @@ local function build_metadata(origin, role)
     scheme = tostring(origin.scheme or 'http'),
     port = origin_port(origin),
     id = tostring(origin.id or ''),
-    role = role or 'origin',
+    role = role or 'primary',
     source = tostring(origin.source or ''),
     host = tostring(origin.host or ''),
     host_header = host_header,
@@ -139,6 +187,15 @@ local function build_metadata(origin, role)
     health_check_enabled = origin.health_check_enabled == true,
     health_status = tostring(origin.health_status or 'unknown'),
     weight = tonumber(origin.weight or 1) or 1,
+    load_balancing_algorithm = tostring(origin.load_balancing_algorithm or 'weighted_hash'),
+    retry_attempts = tonumber(origin.retry_attempts or 1) or 1,
+    retry_budget_per_minute = tonumber(origin.retry_budget_per_minute or 60) or 60,
+    circuit_breaker_enabled = origin.circuit_breaker_enabled ~= false,
+    circuit_failure_threshold = tonumber(origin.circuit_failure_threshold or 5) or 5,
+    circuit_recovery_seconds = tonumber(origin.circuit_recovery_seconds or 30) or 30,
+    max_concurrent_requests = tonumber(origin.max_concurrent_requests or 0) or 0,
+    drain = origin.drain == true,
+    shield_enabled = origin.shield_enabled == true,
   }
 end
 
diff --git a/edge/openresty/lua/proxy.lua b/edge/openresty/lua/proxy.lua
index 08d9d84..b40bfae 100644
--- a/edge/openresty/lua/proxy.lua
+++ b/edge/openresty/lua/proxy.lua
@@ -158,20 +158,28 @@ function M.forward(domain)
   ngx.var.target_origin_id = tostring((ngx.ctx.origin or {}).id or '')
   ngx.var.target_origin_host = tostring((ngx.ctx.origin or {}).host or '')
   ngx.var.target_origin_tls_verify = tostring((ngx.ctx.origin or {}).tls_verify or 'ignore')
+  ngx.var.target_origin_retry_attempts = tostring((ngx.ctx.origin or {}).retry_attempts or 1)
+  if method ~= 'GET' and method ~= 'HEAD' then
+    ngx.var.target_origin_retry_attempts = '0'
+  end
   -- Keep the routing context on the request itself so the error page can
   -- recover it even when an internal redirect clears Lua state.
   ngx.req.set_header('X-CDNLite-Domain-Id', tostring(domain.domain_id or ''))
   ngx.req.set_header('X-CDNLite-Origin-Id', tostring((ngx.ctx.origin or {}).id or ''))
   ngx.req.set_header('X-CDNLite-Origin-Host', tostring((ngx.ctx.origin or {}).host or ''))
-  ngx.req.set_header('X-CDNLite-Origin-Role', tostring((ngx.ctx.origin or {}).role or 'origin'))
+  ngx.req.set_header('X-CDNLite-Origin-Role', tostring((ngx.ctx.origin or {}).role or 'primary'))
   ngx.req.set_header('X-CDNLite-Origin-Tls-Verify', tostring((ngx.ctx.origin or {}).tls_verify or 'ignore'))
+  ngx.req.set_header('X-CDNLite-Origin-Retry-Attempts', tostring(ngx.var.target_origin_retry_attempts or '0'))
+  ngx.req.set_header('X-CDNLite-Origin-Circuit-Breaker', tostring((ngx.ctx.origin or {}).circuit_breaker_enabled ~= false))
   local request_context = cjson.encode({
     domain_id = tostring(domain.domain_id or ''),
     origin = {
       id = tostring((ngx.ctx.origin or {}).id or ''),
       host = tostring((ngx.ctx.origin or {}).host or ''),
-      role = tostring((ngx.ctx.origin or {}).role or 'origin'),
+      role = tostring((ngx.ctx.origin or {}).role or 'primary'),
       tls_verify = tostring((ngx.ctx.origin or {}).tls_verify or 'ignore'),
+      retry_attempts = tonumber(ngx.var.target_origin_retry_attempts or 0) or 0,
+      circuit_breaker_enabled = (ngx.ctx.origin or {}).circuit_breaker_enabled ~= false,
     },
   })
   if request_context then
@@ -196,7 +204,7 @@ function M.forward(domain)
   edge_log.debug('proxy_forward', {
     domain_id = tostring(domain.domain_id or ''),
     origin_id = tostring(ngx.var.target_origin_id or ''),
-    origin_role = tostring((ngx.ctx.origin or {}).role or 'origin'),
+    origin_role = tostring((ngx.ctx.origin or {}).role or 'primary'),
     upstream = upstream,
   })
   return true
diff --git a/edge/openresty/nginx.conf b/edge/openresty/nginx.conf
index 419773f..6c6b584 100644
--- a/edge/openresty/nginx.conf
+++ b/edge/openresty/nginx.conf
@@ -30,9 +30,11 @@ http {
   lua_shared_dict cdnlite_metric_queue __CDNLITE_EDGE_METRIC_QUEUE_DICT_SIZE__;
   lua_shared_dict cdnlite_security_event_queue __CDNLITE_EDGE_SECURITY_EVENT_QUEUE_DICT_SIZE__;
   lua_shared_dict cdnlite_waiting_room __CDNLITE_EDGE_WAITING_ROOM_DICT_SIZE__;
+  lua_shared_dict cdnlite_origin_health 1m;
   init_worker_by_lua_block {
     require('config_loader').reload()
     require('telemetry_queue').start()
+    require('origin_health_checker').start()
   }
   resolver __CDNLITE_EDGE_RESOLVER__ ipv6=off valid=30s;
   lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
@@ -78,6 +80,7 @@ http {
     set $target_origin_host '';
     set $target_domain_id '';
     set $target_origin_tls_verify 'ignore';
+    set $target_origin_retry_attempts '0';
     set $cdnlite_cache_bypass 0;
     set $cdnlite_cache_no_store 0;
     set $cdnlite_cache_key "$scheme|$host|$request_uri|$http_accept_encoding|DEFAULT";
@@ -269,6 +272,7 @@ http {
     set $target_origin_host '';
     set $target_domain_id '';
     set $target_origin_tls_verify 'ignore';
+    set $target_origin_retry_attempts '0';
     set $cdnlite_cache_bypass 0;
     set $cdnlite_cache_no_store 0;
     set $cdnlite_cache_key "$scheme|$host|$request_uri|$http_accept_encoding|DEFAULT";

From 41e95eb4b1f342e5202297f2232037b36779d510 Mon Sep 17 00:00:00 2001
From: vaheeD <khoshnud@gmail.com>
Date: Sun, 28 Jun 2026 15:40:12 +0330
Subject: [PATCH 11/11] feat: Implement config snapshot management and pruning

- Added CdnConfigSnapshotsPruneCommand for managing config snapshots.
- Enhanced config_state schema with new columns for snapshot management.
- Updated public_index.php to include new snapshot routes with pagination and history checks.
- Modified API documentation to reflect changes in config snapshot endpoints.
- Introduced logic to mark the config as dirty on updates, preserving the active snapshot.
- Added tests for new snapshot features and ensured legacy behavior is maintained.
- Updated docker-compose and deployment scripts to support new environment variables for snapshot management.
---
 README.md                                     |   6 +
 ci/e2e.sh                                     |  17 +-
 .../CdnConfigSnapshotsPruneCommand.php        |  24 ++
 .../Commands/CdnEdgeSyncConfigCommand.php     |   2 +-
 core/app/Modules/Dns/Services/DnsService.php  |   3 +-
 .../Dns/Services/GeoRoutingService.php        |   3 +-
 .../Domains/Services/DomainService.php        |   3 +-
 .../Services/DomainVerificationService.php    |   7 +-
 .../Health/Services/ReadinessService.php      |  37 +-
 .../Modules/Proxy/Services/ConfigService.php  | 327 +++++++++++++++---
 .../Proxy/Services/OriginHealthService.php    |   2 +-
 .../Proxy/Services/TrafficRulesService.php    |   2 +-
 core/app/Support/DatabaseMigrator.php         |  51 ++-
 core/artisan                                  |   2 +
 ...032_config_snapshot_materialized_cache.sql |   5 +
 core/database/schema.sql                      |  10 +
 core/public_index.php                         |  18 +-
 ...ig_snapshot_materialized_cache_contract.py |  57 +++
 core/tests/test_hardening_contract.py         |   6 +-
 core/tests/test_migrations_contract.py        |  13 +
 .../test_nameserver_force_verify_contract.py  |   4 +-
 core/tests/test_phase14_15_contract.py        |   3 +-
 ...est_phase7_config_invalidation_contract.py |   4 +-
 core/tests/test_rate_limit_crud_contract.py   |   2 +-
 core/tests/test_readiness_service.py          |   2 +-
 deploy/core/docker-compose.yml                |   7 +-
 deploy/generate-deployment.sh                 |   5 +-
 deploy/starter/docker-compose.yml             |   7 +-
 docker-compose.yml                            |   7 +-
 docs/api/api.md                               |  18 +-
 docs/architecture.md                          |   7 +-
 docs/examples/index.md                        |  15 +-
 docs/public/api/openapi.yaml                  |  25 +-
 docs/setup.md                                 |  13 +
 34 files changed, 592 insertions(+), 122 deletions(-)
 create mode 100644 core/app/Console/Commands/CdnConfigSnapshotsPruneCommand.php
 create mode 100644 core/database/migrations/000032_config_snapshot_materialized_cache.sql
 create mode 100644 core/tests/test_config_snapshot_materialized_cache_contract.py

diff --git a/README.md b/README.md
index 8dbe449..adb3f65 100644
--- a/README.md
+++ b/README.md
@@ -185,6 +185,12 @@ CDNLITE_EDGE_HEALTH_MODE=static ./ci/dns_e2e.sh
 
 Run the destructive DNS stress test only against an explicitly disposable environment.
 
+Useful operator commands include `php artisan cdn:edge:sync-config` to publish or
+fetch the active edge config and `php artisan cdn:config-snapshots:prune
+--keep=2 --batch=5000 --dry-run` to review bounded snapshot cleanup before
+deleting old published artifacts. Snapshot rollback/history endpoints are
+disabled by default because database tables remain the source of truth.
+
 ## Contributing
 
 Contributions are welcome across docs, tests, OpenResty/Lua edge work, Vue dashboard UX, PHP control plane, security hardening, deployment examples, Kubernetes/Helm, Prometheus/Grafana, RBAC, and SSO.
diff --git a/ci/e2e.sh b/ci/e2e.sh
index 5bb6ab5..b56f82c 100755
--- a/ci/e2e.sh
+++ b/ci/e2e.sh
@@ -601,14 +601,14 @@ record_step PASS "guided-onboarding-flow" "recommendation logic, preview, skip/r
 
 config_snapshot_json="$(docker compose exec -T core php artisan cdn:edge:sync-config)"
 config_snapshot_after="$(jq -r '.version' <<<"$config_snapshot_json")"
-config_snapshot_reused_json="$(docker compose exec -T core php artisan cdn:edge:sync-config)"
-config_snapshot_reused_version="$(jq -r '.version' <<<"$config_snapshot_reused_json")"
-config_snapshot_reused="$(jq -r '.reused // false' <<<"$config_snapshot_reused_json")"
+config_snapshot_cached_json="$(docker compose exec -T core php artisan cdn:edge:sync-config)"
+config_snapshot_cached_version="$(jq -r '.version' <<<"$config_snapshot_cached_json")"
+config_snapshot_cached_reused="$(jq -r '.reused // false' <<<"$config_snapshot_cached_json")"
 retry 20 1 config_publish_audit_exists
 assert_eq "$config_snapshot_after" "$(current_config_state_version)" "config rebuild should activate the published snapshot"
-assert_eq "$config_snapshot_reused_version" "$config_snapshot_after" "unchanged config rebuild should reuse the active snapshot version"
-assert_eq "$config_snapshot_reused" "true" "unchanged config rebuild should report a reused snapshot"
-record_step PASS "config-publish-audit" "config rebuild writes publish audit events and reuses unchanged snapshots"
+assert_eq "$config_snapshot_cached_version" "$config_snapshot_after" "unchanged config fetch should serve the active snapshot version"
+assert_eq "$config_snapshot_cached_reused" "false" "unchanged edge config fetch should not rebuild just to report reused"
+record_step PASS "config-publish-audit" "config publish writes audit events and unchanged fetches use the active snapshot"
 
 api_post_with_powerdns_retry "${CORE_URL}/api/v1/domains/${DOMAIN_ID}/dns/records" \
   '{"type":"A","name":"@","content":"1.1.1.1","ttl":300,"proxied":true,"origin_host":"origin-tls","origin_tls_verify":"ignore","geo_origins":{"DEFAULT":{"host":"origin-tls","tls_verify":"ignore"},"IR":{"host":"origin-http","tls_verify":"verify"}}}'
@@ -1252,7 +1252,7 @@ record_step PASS "edge-bot-protection-runtime" "unverified crawler challenge and
 verified_bot_source_id="verified-bot-${RUN_KEY}"
 now="$(date +%s)"
 db_query "INSERT INTO verified_bot_sources (id,domain_id,bot_class,provider,user_agent_pattern,cidr,enabled,created_at,updated_at) VALUES ('${verified_bot_source_id}','${DOMAIN_ID}','verified_search_bot','Google','Googlebot','0.0.0.0/0',true,${now},${now});" >/dev/null
-db_query "UPDATE config_state SET active_snapshot_version=NULL WHERE id=1;" >/dev/null
+db_query "UPDATE config_state SET dirty=true, dirty_at=${now} WHERE id=1;" >/dev/null
 edge_pull_config
 verified_bot_status="$(curl -sS -o /tmp/e2e-verified-bot-body.txt -w '%{http_code}' -H "Host: ${TEST_DOMAIN}" -A 'Googlebot' "${EDGE_URL}/bot-check?via=edge-verified-bot")"
 assert_eq "$verified_bot_status" "200" "verified search-bot source should allow matching crawler traffic"
@@ -1562,7 +1562,8 @@ record_step PASS "edge-config-fetch" "version=${cfg_version}"
 
 edge_api GET "/api/v1/edge/config?if_version=${cfg_version}" ""
 assert_http_status "$HTTP_CODE" "200" "edge config if_version failed"
-record_step PASS "edge-config-if-version" "if_version request ok"
+assert_contains "$HTTP_BODY" '"not_modified":true' "edge config if_version should return not_modified"
+record_step PASS "edge-config-if-version" "if_version request returned not_modified"
 
 miss_code="$(curl -s -o /tmp/e2e-miss-auth.txt -w '%{http_code}' -X POST "${CORE_URL}/api/v1/edge/heartbeat" -H 'Content-Type: application/json' -d "{\"edge_id\":\"${EDGE_ID}\"}")"
 assert_eq "$miss_code" "401" "missing auth should 401"
diff --git a/core/app/Console/Commands/CdnConfigSnapshotsPruneCommand.php b/core/app/Console/Commands/CdnConfigSnapshotsPruneCommand.php
new file mode 100644
index 0000000..db7d7b0
--- /dev/null
+++ b/core/app/Console/Commands/CdnConfigSnapshotsPruneCommand.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Modules\Dns\Services\DnsService;
+use App\Modules\Domains\Services\DomainService;
+use App\Modules\Proxy\Services\ConfigService;
+use App\Support\CommandIO;
+
+class CdnConfigSnapshotsPruneCommand
+{
+    public function __invoke(array $argv): int
+    {
+        $opts = CommandIO::parseOptions($argv);
+        $keep = isset($opts['keep']) ? (int) $opts['keep'] : 2;
+        $batch = isset($opts['batch']) ? (int) $opts['batch'] : 5000;
+        $dryRun = isset($opts['dry-run']) || isset($opts['dry_run']);
+
+        $result = (new ConfigService(new DomainService(), new DnsService()))
+            ->pruneSnapshots($keep, $batch > 0 ? $batch : null, $dryRun);
+        CommandIO::printJson($result);
+        return 0;
+    }
+}
diff --git a/core/app/Console/Commands/CdnEdgeSyncConfigCommand.php b/core/app/Console/Commands/CdnEdgeSyncConfigCommand.php
index a8628ad..0f5b1d6 100644
--- a/core/app/Console/Commands/CdnEdgeSyncConfigCommand.php
+++ b/core/app/Console/Commands/CdnEdgeSyncConfigCommand.php
@@ -13,7 +13,7 @@ public function __invoke(array $argv): int
     {
         $opts = CommandIO::parseOptions($argv);
         $ifVersion = isset($opts['if_version']) ? (int) $opts['if_version'] : null;
-        $snapshot = (new ConfigService(new DomainService(), new DnsService()))->buildSnapshotForVersion($ifVersion);
+        $snapshot = (new ConfigService(new DomainService(), new DnsService()))->edgeConfig($ifVersion);
         CommandIO::printJson($snapshot);
         return 0;
     }
diff --git a/core/app/Modules/Dns/Services/DnsService.php b/core/app/Modules/Dns/Services/DnsService.php
index ba16275..2f4d9c4 100644
--- a/core/app/Modules/Dns/Services/DnsService.php
+++ b/core/app/Modules/Dns/Services/DnsService.php
@@ -3,6 +3,7 @@
 namespace App\Modules\Dns\Services;
 
 use App\Modules\Domains\Services\DomainService;
+use App\Modules\Proxy\Services\ConfigService;
 use App\Modules\Proxy\Services\OriginHealthService;
 use App\Modules\Proxy\Services\TrafficRulesService;
 use App\Modules\Settings\Repositories\SettingsRepository;
@@ -539,7 +540,7 @@ private function ensureManagedSslForProxiedRecord(string $domainId, array $recor
 
     private function invalidateConfigSnapshot(): void
     {
-        Database::pdo()->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+        ConfigService::markDirty('dns.changed');
     }
 
     private function castRow(array $row): array
diff --git a/core/app/Modules/Dns/Services/GeoRoutingService.php b/core/app/Modules/Dns/Services/GeoRoutingService.php
index d9fe4e9..4dc36da 100644
--- a/core/app/Modules/Dns/Services/GeoRoutingService.php
+++ b/core/app/Modules/Dns/Services/GeoRoutingService.php
@@ -2,6 +2,7 @@
 
 namespace App\Modules\Dns\Services;
 
+use App\Modules\Proxy\Services\ConfigService;
 use App\Support\AuditLog;
 use App\Support\Database;
 use App\Support\Uuid;
@@ -137,7 +138,7 @@ public function replace(string $domainId, string $recordId, array $routes): ?arr
 
     private function invalidateConfigSnapshot(): void
     {
-        Database::pdo()->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+        ConfigService::markDirty('dns.geo_routes.changed');
     }
 
     private function recordExists(string $domainId, string $recordId): bool
diff --git a/core/app/Modules/Domains/Services/DomainService.php b/core/app/Modules/Domains/Services/DomainService.php
index 0fa51d3..ca57354 100644
--- a/core/app/Modules/Domains/Services/DomainService.php
+++ b/core/app/Modules/Domains/Services/DomainService.php
@@ -4,6 +4,7 @@
 
 use App\Modules\Dns\Services\DnsReconciler;
 use App\Modules\Dns\Services\PowerDnsService;
+use App\Modules\Proxy\Services\ConfigService;
 use App\Modules\Settings\Repositories\SettingsRepository;
 use App\Support\Database;
 use App\Support\AuditLog;
@@ -189,7 +190,7 @@ private function castRow(array $row): array
 
     private function invalidateConfigSnapshot(): void
     {
-        Database::pdo()->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+        ConfigService::markDirty('domain.changed');
     }
 
     private function reconcileDns(string $domainId): void
diff --git a/core/app/Modules/Domains/Services/DomainVerificationService.php b/core/app/Modules/Domains/Services/DomainVerificationService.php
index fa61155..4d1ffde 100644
--- a/core/app/Modules/Domains/Services/DomainVerificationService.php
+++ b/core/app/Modules/Domains/Services/DomainVerificationService.php
@@ -3,6 +3,7 @@
 namespace App\Modules\Domains\Services;
 
 use App\Modules\Dns\Services\DnsReconciler;
+use App\Modules\Proxy\Services\ConfigService;
 use App\Modules\Proxy\Services\TrafficRulesService;
 use App\Modules\Settings\Repositories\SettingsRepository;
 use App\Support\AuditLog;
@@ -72,7 +73,7 @@ public function verifyWithTrace(string $domainId, bool $reconcile = true): ?arra
                 'checked' => $now,
                 'id' => $domainId,
             ]);
-            $pdo->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+            ConfigService::markDirty('domain.verification.changed');
             $pdo->commit();
         } catch (\Throwable $e) {
             $pdo->rollBack();
@@ -123,7 +124,7 @@ public function forceVerify(string $domainId, string $reason, string $actor): ?a
                  last_ns_check_at = :checked, updated_at = :checked WHERE id = :id"
             );
             $update->execute(['checked' => $now, 'id' => $domainId]);
-            $pdo->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+            ConfigService::markDirty('domain.verification.changed');
             $pdo->commit();
         } catch (\Throwable $e) {
             $pdo->rollBack();
@@ -212,7 +213,7 @@ public function reseedExpectedNameservers(string $domainId, string $actor): ?arr
                 'updated_at' => $now,
                 'id' => $domainId,
             ]);
-            $pdo->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+            ConfigService::markDirty('domain.verification.changed');
             $pdo->commit();
         } catch (\Throwable $e) {
             $pdo->rollBack();
diff --git a/core/app/Modules/Health/Services/ReadinessService.php b/core/app/Modules/Health/Services/ReadinessService.php
index 1ee26f6..c55a7c3 100644
--- a/core/app/Modules/Health/Services/ReadinessService.php
+++ b/core/app/Modules/Health/Services/ReadinessService.php
@@ -106,16 +106,32 @@ private function identityCheck(): array
 
     private function snapshotCheck(): array
     {
-        $generatedAt = Database::pdo()->query('SELECT MAX(generated_at) FROM config_snapshots')->fetchColumn();
-        if ($generatedAt === false || $generatedAt === null) {
-            return $this->result('config_snapshot', 'warning', 'No edge configuration has been generated', 'Check edge config pulls or run a manual config rebuild', '/edge-nodes');
+        $row = Database::pdo()->query(
+            'SELECT cs.active_snapshot_version, cs.dirty, cs.published_at, cs.dirty_at, cs.last_publish_error, s.generated_at
+             FROM config_state cs
+             LEFT JOIN config_snapshots s ON s.version = cs.active_snapshot_version
+             WHERE cs.id = 1'
+        )->fetch();
+        if (!$row || $row['active_snapshot_version'] === null) {
+            return $this->result('config_snapshot', 'error', 'No active edge configuration has been published', 'Run a manual config publish or allow the first edge pull to publish', '/edge-nodes');
+        }
+        $details = [
+            'active_version' => (int) $row['active_snapshot_version'],
+            'dirty' => in_array($row['dirty'] ?? false, [true, 1, '1', 't', 'true'], true),
+            'published_at' => $row['published_at'] === null ? null : (int) $row['published_at'],
+            'dirty_at' => $row['dirty_at'] === null ? null : (int) $row['dirty_at'],
+        ];
+        if ($row['generated_at'] === null) {
+            return $this->result('config_snapshot', 'error', 'Active edge configuration row is missing', 'Publish a new edge configuration', '/edge-nodes', $details);
+        }
+        if ($row['last_publish_error'] !== null && (string) $row['last_publish_error'] !== '') {
+            $details['last_publish_error'] = (string) $row['last_publish_error'];
+            return $this->result('config_snapshot', 'warning', 'Last edge configuration publish failed', 'Review the publish error and publish again', '/edge-nodes', $details);
         }
-        $maxAge = max(60, (int) (getenv('CDNLITE_READINESS_SNAPSHOT_MAX_AGE_SECONDS') ?: 900));
-        $age = max(0, time() - (int) $generatedAt);
-        if ($age <= $maxAge) {
-            return $this->result('config_snapshot', 'ok', 'Config snapshot is fresh');
+        if ($details['dirty']) {
+            return $this->result('config_snapshot', 'warning', 'Edge configuration has unpublished changes', 'Publish edge configuration when ready', '/edge-nodes', $details);
         }
-        return $this->result('config_snapshot', 'warning', sprintf('Edge configuration was last generated %d minutes ago', (int) floor($age / 60)), 'Check edge config pulls or run a manual config rebuild', '/edge-nodes');
+        return $this->result('config_snapshot', 'ok', 'Active edge configuration is published', null, null, $details);
     }
 
     private function certificateExpiryCheck(): array
@@ -159,7 +175,7 @@ private function originHealthCheck(): array
         );
     }
 
-    private function result(string $key, string $status, string $message, ?string $fix = null, ?string $link = null): array
+    private function result(string $key, string $status, string $message, ?string $fix = null, ?string $link = null, array $details = []): array
     {
         $result = ['key' => $key, 'status' => $status, 'message' => $message];
         if ($fix !== null) {
@@ -168,6 +184,9 @@ private function result(string $key, string $status, string $message, ?string $f
         if ($link !== null) {
             $result['link'] = $link;
         }
+        if ($details !== []) {
+            $result['details'] = $details;
+        }
         return $result;
     }
 
diff --git a/core/app/Modules/Proxy/Services/ConfigService.php b/core/app/Modules/Proxy/Services/ConfigService.php
index 489d83e..41684ed 100644
--- a/core/app/Modules/Proxy/Services/ConfigService.php
+++ b/core/app/Modules/Proxy/Services/ConfigService.php
@@ -9,6 +9,8 @@
 
 class ConfigService
 {
+    private bool $publishLockHeld = false;
+
     public function __construct(
         private DomainService $domains,
         private DnsService $dns,
@@ -21,17 +23,138 @@ public function __construct(
 
     public function buildSnapshot(): array
     {
-        return $this->buildSnapshotForVersion(null);
+        return $this->publishSnapshot(false);
     }
 
     public function buildSnapshotForVersion(?int $ifVersion = null): array
     {
-        return $this->rebuild($ifVersion);
+        return $this->edgeConfig($ifVersion);
     }
 
     public function rebuild(?int $ifVersion = null): array
+    {
+        $payload = $this->publishSnapshot(true);
+        if ($ifVersion !== null && isset($payload['version']) && $ifVersion === (int) $payload['version']) {
+            return ['not_modified' => true, 'version' => (int) $payload['version']];
+        }
+        return $payload;
+    }
+
+    public function edgeConfig(?int $ifVersion = null): array
+    {
+        $this->ensureStateRow();
+        $state = $this->configState();
+        $activeVersion = $state['active_snapshot_version'];
+        $active = $this->activeSnapshot();
+
+        if ($activeVersion !== null && $active !== null && !$state['dirty']) {
+            if ($ifVersion !== null && $ifVersion === $activeVersion) {
+                return ['not_modified' => true, 'version' => $activeVersion];
+            }
+            return $active['payload'];
+        }
+
+        if ($this->tryPublishLock()) {
+            try {
+                return $this->publishSnapshot(false, true);
+            } finally {
+                $this->unlockPublish();
+            }
+        }
+
+        if ($activeVersion !== null && $active !== null) {
+            if ($ifVersion !== null && $ifVersion === $activeVersion) {
+                return ['not_modified' => true, 'version' => $activeVersion, 'stale_while_rebuilding' => true];
+            }
+            $payload = $active['payload'];
+            $payload['stale_while_rebuilding'] = true;
+            return $payload;
+        }
+
+        return ['error' => 'config_publish_in_progress', 'status' => 503];
+    }
+
+    public function publishSnapshot(bool $force = false, bool $lockAlreadyHeld = false): array
+    {
+        $this->ensureStateRow();
+        $state = $this->configState();
+        $active = $this->activeSnapshot();
+        if (!$force && !$state['dirty'] && $active !== null) {
+            return $active['payload'];
+        }
+
+        if (!$lockAlreadyHeld && !$this->tryPublishLock()) {
+            if ($active !== null) {
+                $payload = $active['payload'];
+                $payload['stale_while_rebuilding'] = true;
+                return $payload;
+            }
+            return ['error' => 'config_publish_in_progress', 'status' => 503];
+        }
+
+        try {
+            $this->setPublishingStartedAt(time());
+            $payload = $this->buildAndStoreSnapshot();
+            $this->markPublished((int) ($payload['generated_at'] ?? time()));
+            $this->pruneSnapshots($this->snapshotKeepLast(), $this->snapshotPruneBatchSize());
+            return $payload;
+        } catch (\Throwable $e) {
+            $this->markPublishFailed($e->getMessage());
+            AuditLog::write('config.publish.failed', 'config_snapshot', null, null, null, ['error' => $e->getMessage()]);
+            throw $e;
+        } finally {
+            $this->clearPublishingStartedAt();
+            if (!$lockAlreadyHeld) {
+                $this->unlockPublish();
+            }
+        }
+    }
+
+    public function buildPayload(): array
+    {
+        return $this->buildPayloadData();
+    }
+
+    public static function markDirty(?string $reason = null): void
+    {
+        $pdo = Database::pdo();
+        $pdo->exec('INSERT INTO config_state (id, version) VALUES (1, 0) ON CONFLICT (id) DO NOTHING');
+        $wasDirty = in_array($pdo->query('SELECT dirty FROM config_state WHERE id = 1')->fetchColumn(), [true, 1, '1', 't', 'true'], true);
+        $stmt = $pdo->prepare(
+            'UPDATE config_state
+             SET dirty = true, dirty_at = :dirty_at
+             WHERE id = 1'
+        );
+        $stmt->execute([':dirty_at' => time()]);
+        if (!$wasDirty) {
+            AuditLog::write('config.dirty', 'config_state', '1', null, ['dirty' => false], ['dirty' => true, 'reason' => $reason]);
+        }
+    }
+
+    private function buildAndStoreSnapshot(): array
     {
         $previousActiveVersion = $this->activeSnapshotVersion();
+        $payloadData = $this->buildPayloadData();
+        $contentHash = $this->contentHash($payloadData);
+        $existing = $this->findReusableActiveSnapshot($previousActiveVersion, $contentHash);
+        if ($existing !== null) {
+            $payload = json_decode((string) $existing['payload_json'], true) ?: $payloadData;
+            $payload['reused'] = true;
+            $this->activateSnapshotVersion((int) $existing['version']);
+            $this->auditSnapshotPublish((int) $existing['version'], $previousActiveVersion, (int) $existing['version'], true);
+            return $payload;
+        }
+
+        $version = $this->nextVersion();
+        $payload = $payloadData + ['version' => $version, 'generated_at' => time()];
+        $this->storeSnapshot($version, $contentHash, $payload);
+        $this->activateSnapshotVersion($version);
+        $this->auditSnapshotPublish($version, $previousActiveVersion, $version, false);
+        return $payload;
+    }
+
+    private function buildPayloadData(): array
+    {
         $hosts = [];
         foreach ($this->domains->all() as $domain) {
             if ((string) ($domain['status'] ?? '') !== 'active'
@@ -104,44 +227,8 @@ public function rebuild(?int $ifVersion = null): array
             foreach ($this->rules->listSslCertificatesForConfig($domainId, $host) as $row) { $sslCertificates[] = $row; }
             foreach ($this->rules->listWaitingRoomPoliciesForConfig($domainId) as $row) { $hosts[$host]['waiting_room'] = $row; }
         }
-        // Keep hash deterministic for unchanged config content.
-        // `generated_at` is intentionally excluded so no-op syncs reuse version.
-        $contentHash = hash('sha256', json_encode(['hosts' => $hosts, 'redirects' => $redirects, 'rate_limits' => $rateLimits, 'waf_rules' => $wafRules, 'header_rules' => $headerRules, 'ip_rules' => $ipRules, 'cache_rules' => $cacheRules, 'cache_purge_versions' => $cachePurgeVersions, 'page_rules' => $pageRules, 'ssl_certificates' => $sslCertificates], JSON_UNESCAPED_SLASHES));
-
-        $existing = $this->findReusableActiveSnapshot($previousActiveVersion, $contentHash);
-        if ($existing !== null) {
-            if ($ifVersion !== null && $ifVersion === (int) $existing['version']) {
-                $this->activateSnapshotVersion((int) $existing['version']);
-                return ['not_modified' => true, 'version' => (int) $existing['version']];
-            }
-
-            $existing = $this->refreshSnapshotGeneratedAt($existing);
-            $this->activateSnapshotVersion((int) $existing['version']);
-            $this->auditSnapshotPublish((int) $existing['version'], $previousActiveVersion, (int) $existing['version'], true);
-
-            return [
-                'schema_version' => 1,
-                'version' => (int) $existing['version'],
-                'generated_at' => (int) $existing['generated_at'],
-                'hosts' => $hosts,
-                'redirects' => $redirects,
-                'rate_limits' => $rateLimits,
-                'waf_rules' => $wafRules,
-                'header_rules' => $headerRules,
-                'ip_rules' => $ipRules,
-                'cache_rules' => $cacheRules,
-                'cache_purge_versions' => $cachePurgeVersions,
-                'page_rules' => $pageRules,
-                'ssl_certificates' => $sslCertificates,
-                'reused' => true,
-            ];
-        }
-
-        $version = $this->nextVersion();
-        $payload = [
+        return [
             'schema_version' => 1,
-            'version' => $version,
-            'generated_at' => time(),
             'hosts' => $hosts,
             'redirects' => $redirects,
             'rate_limits' => $rateLimits,
@@ -153,25 +240,22 @@ public function rebuild(?int $ifVersion = null): array
             'page_rules' => $pageRules,
             'ssl_certificates' => $sslCertificates,
         ];
-        $this->storeSnapshot($version, $contentHash, $payload);
-        $this->activateSnapshotVersion($version);
-        $this->auditSnapshotPublish($version, $previousActiveVersion, $version, false);
-
-        if ($ifVersion !== null && $ifVersion === $version) {
-            return ['not_modified' => true, 'version' => $version];
-        }
-
-        return $payload;
     }
 
-    public function snapshots(): array
+    public function snapshots(int $limit = 20, int $offset = 0): array
     {
-        $rows = Database::pdo()->query(
+        $limit = max(1, min(100, $limit));
+        $offset = max(0, $offset);
+        $stmt = Database::pdo()->prepare(
             'SELECT s.version,s.generated_at,s.content_hash,pg_column_size(s.payload_json) AS size,
                     (s.version=cs.active_snapshot_version) AS active
              FROM config_snapshots s CROSS JOIN config_state cs
-             WHERE cs.id=1 ORDER BY s.version DESC'
-        )->fetchAll();
+             WHERE cs.id=1 ORDER BY s.version DESC LIMIT :limit OFFSET :offset'
+        );
+        $stmt->bindValue(':limit', $limit, \PDO::PARAM_INT);
+        $stmt->bindValue(':offset', $offset, \PDO::PARAM_INT);
+        $stmt->execute();
+        $rows = $stmt->fetchAll();
         return array_map(static fn (array $row): array => self::snapshotSummaryFromRow($row), $rows);
     }
 
@@ -306,7 +390,7 @@ public function debugRoute(string $domainId, array $input): array
         ];
     }
 
-    private function activeSnapshot(): ?array
+    public function activeSnapshot(): ?array
     {
         $row = Database::pdo()->query(
             'SELECT s.version,s.payload_json FROM config_state cs
@@ -315,6 +399,136 @@ private function activeSnapshot(): ?array
         return $row ? ['version' => (int) $row['version'], 'payload' => json_decode((string) $row['payload_json'], true)] : null;
     }
 
+    public function pruneSnapshots(int $keepLast = 2, ?int $batchSize = null, bool $dryRun = false): array
+    {
+        $keepLast = max(0, $keepLast);
+        $batchSize = $batchSize === null ? null : max(1, $batchSize);
+        $activeVersion = $this->activeSnapshotVersion();
+        $limitClause = $batchSize === null ? '' : ' LIMIT :batch_size';
+        $sql = $dryRun
+            ? "WITH keep_versions AS (
+                   SELECT active_snapshot_version AS version FROM config_state WHERE id = 1 AND active_snapshot_version IS NOT NULL
+                   UNION
+                   SELECT version FROM config_snapshots ORDER BY version DESC LIMIT :keep_last
+               ),
+               victims AS (
+                   SELECT version FROM config_snapshots
+                   WHERE version NOT IN (SELECT version FROM keep_versions)
+                   ORDER BY version ASC{$limitClause}
+               )
+               SELECT COUNT(*) AS deleted_count FROM victims"
+            : "WITH keep_versions AS (
+                   SELECT active_snapshot_version AS version FROM config_state WHERE id = 1 AND active_snapshot_version IS NOT NULL
+                   UNION
+                   SELECT version FROM config_snapshots ORDER BY version DESC LIMIT :keep_last
+               ),
+               victims AS (
+                   SELECT version FROM config_snapshots
+                   WHERE version NOT IN (SELECT version FROM keep_versions)
+                   ORDER BY version ASC{$limitClause}
+               ),
+               deleted AS (
+                   DELETE FROM config_snapshots
+                   WHERE version IN (SELECT version FROM victims)
+                   RETURNING version
+               )
+               SELECT COUNT(*) AS deleted_count FROM deleted";
+        $stmt = Database::pdo()->prepare($sql);
+        $stmt->bindValue(':keep_last', $keepLast, \PDO::PARAM_INT);
+        if ($batchSize !== null) {
+            $stmt->bindValue(':batch_size', $batchSize, \PDO::PARAM_INT);
+        }
+        $stmt->execute();
+        $deletedCount = (int) ($stmt->fetchColumn() ?: 0);
+        $remaining = (int) (Database::pdo()->query('SELECT COUNT(*) FROM config_snapshots')->fetchColumn() ?: 0);
+        if (!$dryRun) {
+            AuditLog::write('config.snapshots.prune', 'config_snapshot', null, null, null, ['deleted_count' => $deletedCount, 'keep_last' => $keepLast, 'active_version' => $activeVersion]);
+        }
+        return [
+            'ok' => true,
+            'dry_run' => $dryRun,
+            'deleted_count' => $deletedCount,
+            'keep_last' => $keepLast,
+            'active_version' => $activeVersion,
+            'remaining_count_estimate' => $dryRun ? max(0, $remaining - $deletedCount) : $remaining,
+        ];
+    }
+
+    private function ensureStateRow(): void
+    {
+        Database::pdo()->exec('INSERT INTO config_state (id, version) VALUES (1, 0) ON CONFLICT (id) DO NOTHING');
+    }
+
+    private function configState(): array
+    {
+        $this->ensureStateRow();
+        $row = Database::pdo()->query('SELECT version, active_snapshot_version, dirty, dirty_at, published_at, last_publish_error, publishing_started_at FROM config_state WHERE id = 1')->fetch();
+        return [
+            'version' => (int) ($row['version'] ?? 0),
+            'active_snapshot_version' => isset($row['active_snapshot_version']) && $row['active_snapshot_version'] !== null ? (int) $row['active_snapshot_version'] : null,
+            'dirty' => in_array($row['dirty'] ?? true, [true, 1, '1', 't', 'true'], true),
+            'dirty_at' => isset($row['dirty_at']) && $row['dirty_at'] !== null ? (int) $row['dirty_at'] : null,
+            'published_at' => isset($row['published_at']) && $row['published_at'] !== null ? (int) $row['published_at'] : null,
+            'last_publish_error' => isset($row['last_publish_error']) ? (string) $row['last_publish_error'] : null,
+            'publishing_started_at' => isset($row['publishing_started_at']) && $row['publishing_started_at'] !== null ? (int) $row['publishing_started_at'] : null,
+        ];
+    }
+
+    private function tryPublishLock(): bool
+    {
+        $locked = Database::pdo()->query("SELECT pg_try_advisory_lock(hashtext('cdnlite_config_publish'))")->fetchColumn();
+        $this->publishLockHeld = in_array($locked, [true, 1, '1', 't', 'true'], true);
+        return $this->publishLockHeld;
+    }
+
+    private function unlockPublish(): void
+    {
+        if (!$this->publishLockHeld) {
+            return;
+        }
+        Database::pdo()->query("SELECT pg_advisory_unlock(hashtext('cdnlite_config_publish'))");
+        $this->publishLockHeld = false;
+    }
+
+    private function setPublishingStartedAt(int $time): void
+    {
+        Database::pdo()->prepare('UPDATE config_state SET publishing_started_at = :time WHERE id = 1')->execute([':time' => $time]);
+    }
+
+    private function clearPublishingStartedAt(): void
+    {
+        Database::pdo()->exec('UPDATE config_state SET publishing_started_at = NULL WHERE id = 1');
+    }
+
+    private function markPublished(int $publishedAt): void
+    {
+        Database::pdo()->prepare(
+            'UPDATE config_state
+             SET dirty = false, published_at = :published_at, last_publish_error = NULL
+             WHERE id = 1'
+        )->execute([':published_at' => $publishedAt]);
+    }
+
+    private function markPublishFailed(string $error): void
+    {
+        Database::pdo()->prepare(
+            'UPDATE config_state
+             SET dirty = true, last_publish_error = :error
+             WHERE id = 1'
+        )->execute([':error' => substr($error, 0, 4000)]);
+    }
+
+    private function snapshotKeepLast(): int
+    {
+        return max(0, (int) (getenv('CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST') ?: 2));
+    }
+
+    private function snapshotPruneBatchSize(): ?int
+    {
+        $value = trim((string) (getenv('CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE') ?: '5000'));
+        return $value === '' || (int) $value <= 0 ? null : (int) $value;
+    }
+
     private function diffValues(mixed $from, mixed $to, string $path = ''): array
     {
         if (!is_array($from) || !is_array($to)) {
@@ -360,6 +574,12 @@ private function findReusableActiveSnapshot(?int $activeVersion, string $content
         return (array) $row;
     }
 
+    private function contentHash(array $payloadData): string
+    {
+        // generated_at/version are publish metadata; the hash tracks only edge behavior.
+        return hash('sha256', json_encode($payloadData, JSON_UNESCAPED_SLASHES));
+    }
+
     private function refreshSnapshotGeneratedAt(array $snapshot): array
     {
         $generatedAt = time();
@@ -394,6 +614,7 @@ private function activateSnapshotVersion(int $version): void
 
     private function activeSnapshotVersion(): ?int
     {
+        $this->ensureStateRow();
         $value = Database::pdo()->query('SELECT active_snapshot_version FROM config_state WHERE id = 1')->fetchColumn();
         return $value === false || $value === null ? null : (int) $value;
     }
diff --git a/core/app/Modules/Proxy/Services/OriginHealthService.php b/core/app/Modules/Proxy/Services/OriginHealthService.php
index 7fba439..56e3b95 100644
--- a/core/app/Modules/Proxy/Services/OriginHealthService.php
+++ b/core/app/Modules/Proxy/Services/OriginHealthService.php
@@ -686,6 +686,6 @@ private function cast(array $row): array
 
     private function invalidateConfig(): void
     {
-        Database::pdo()->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+        ConfigService::markDirty('origins.changed');
     }
 }
diff --git a/core/app/Modules/Proxy/Services/TrafficRulesService.php b/core/app/Modules/Proxy/Services/TrafficRulesService.php
index cc2a2eb..aa5f269 100644
--- a/core/app/Modules/Proxy/Services/TrafficRulesService.php
+++ b/core/app/Modules/Proxy/Services/TrafficRulesService.php
@@ -1223,7 +1223,7 @@ private function delete(string $table, string $domainId, string $id): bool {
         return false;
     }
     private function invalidateConfigSnapshot(): void {
-        Database::pdo()->exec('UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1');
+        ConfigService::markDirty('traffic_rules.changed');
     }
     private function managedWafModes(): array {
         return [
diff --git a/core/app/Support/DatabaseMigrator.php b/core/app/Support/DatabaseMigrator.php
index e686c15..5d9e785 100644
--- a/core/app/Support/DatabaseMigrator.php
+++ b/core/app/Support/DatabaseMigrator.php
@@ -78,7 +78,7 @@ public function migrate(bool $dryRun = false): array
                 try {
                     $this->pdo->beginTransaction();
                     $this->recordMigration($migration, false, null, null, $startedAt);
-                    $this->pdo->exec($migration['sql']);
+                    $this->pdo->exec($this->sqlForExecution($migration));
                     $executionMs = max(0, (int) round((microtime(true) - $startedMs) * 1000));
                     $this->recordMigration($migration, true, null, $executionMs, $startedAt);
                     $this->pdo->commit();
@@ -188,6 +188,55 @@ private function migrationFiles(): array
         return $migrations;
     }
 
+    private function sqlForExecution(array $migration): string
+    {
+        if (($migration['version'] ?? '') !== '000031') {
+            return (string) $migration['sql'];
+        }
+
+        $legacyConstraintBlock = "ALTER TABLE domain_origins
+  ADD CONSTRAINT domain_origins_load_balancing_algorithm_check CHECK (load_balancing_algorithm IN ('weighted_hash', 'consistent_hash')),
+  ADD CONSTRAINT domain_origins_connection_timeout_seconds_check CHECK (connection_timeout_seconds BETWEEN 1 AND 60),
+  ADD CONSTRAINT domain_origins_response_timeout_seconds_check CHECK (response_timeout_seconds BETWEEN 1 AND 600),
+  ADD CONSTRAINT domain_origins_retry_attempts_check CHECK (retry_attempts BETWEEN 0 AND 3),
+  ADD CONSTRAINT domain_origins_retry_budget_per_minute_check CHECK (retry_budget_per_minute BETWEEN 0 AND 100000),
+  ADD CONSTRAINT domain_origins_circuit_failure_threshold_check CHECK (circuit_failure_threshold BETWEEN 1 AND 1000),
+  ADD CONSTRAINT domain_origins_circuit_recovery_seconds_check CHECK (circuit_recovery_seconds BETWEEN 1 AND 3600),
+  ADD CONSTRAINT domain_origins_max_concurrent_requests_check CHECK (max_concurrent_requests BETWEEN 0 AND 1000000);";
+
+        $idempotentConstraintBlock = "DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_load_balancing_algorithm_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_load_balancing_algorithm_check CHECK (load_balancing_algorithm IN ('weighted_hash', 'consistent_hash'));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_connection_timeout_seconds_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_connection_timeout_seconds_check CHECK (connection_timeout_seconds BETWEEN 1 AND 60);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_response_timeout_seconds_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_response_timeout_seconds_check CHECK (response_timeout_seconds BETWEEN 1 AND 600);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_retry_attempts_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_retry_attempts_check CHECK (retry_attempts BETWEEN 0 AND 3);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_retry_budget_per_minute_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_retry_budget_per_minute_check CHECK (retry_budget_per_minute BETWEEN 0 AND 100000);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_circuit_failure_threshold_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_circuit_failure_threshold_check CHECK (circuit_failure_threshold BETWEEN 1 AND 1000);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_circuit_recovery_seconds_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_circuit_recovery_seconds_check CHECK (circuit_recovery_seconds BETWEEN 1 AND 3600);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'domain_origins_max_concurrent_requests_check' AND conrelid = 'domain_origins'::regclass) THEN
+    ALTER TABLE domain_origins ADD CONSTRAINT domain_origins_max_concurrent_requests_check CHECK (max_concurrent_requests BETWEEN 0 AND 1000000);
+  END IF;
+END $$;";
+
+        // Preserve the historical migration checksum while making legacy schema
+        // adoption idempotent when the fresh schema already created these checks.
+        return str_replace($legacyConstraintBlock, $idempotentConstraintBlock, (string) $migration['sql']);
+    }
+
     private function appliedMigrations(): array
     {
         $rows = $this->pdo
diff --git a/core/artisan b/core/artisan
index b56267f..cee191f 100755
--- a/core/artisan
+++ b/core/artisan
@@ -73,6 +73,7 @@ use App\Console\Commands\CdnPowerDnsDoctorCommand;
 use App\Console\Commands\CdnPowerDnsDryRunCommand;
 use App\Console\Commands\CdnPowerDnsForceSyncCommand;
 use App\Console\Commands\CdnRecommendationsGenerateCommand;
+use App\Console\Commands\CdnConfigSnapshotsPruneCommand;
 
 $runner = new CommandRunner();
 $runner->register('cdn:admin:create', new CdnAdminCreateCommand());
@@ -101,6 +102,7 @@ $runner->register('cdn:edge:disable', new CdnEdgeDisableCommand());
 $runner->register('cdn:edge:register-token', new CdnEdgeRegisterTokenCommand());
 $runner->register('cdn:edge:rotate-token', new CdnEdgeRotateTokenCommand());
 $runner->register('cdn:edge:sync-config', new CdnEdgeSyncConfigCommand());
+$runner->register('cdn:config-snapshots:prune', new CdnConfigSnapshotsPruneCommand());
 $runner->register('cdn:usage:summary', new CdnUsageSummaryCommand());
 $runner->register('cdn:usage:recalculate', new CdnUsageRecalculateCommand());
 $runner->register('cdn:usage:ingest', new CdnUsageIngestCommand());
diff --git a/core/database/migrations/000032_config_snapshot_materialized_cache.sql b/core/database/migrations/000032_config_snapshot_materialized_cache.sql
new file mode 100644
index 0000000..3134ab4
--- /dev/null
+++ b/core/database/migrations/000032_config_snapshot_materialized_cache.sql
@@ -0,0 +1,5 @@
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS dirty BOOLEAN NOT NULL DEFAULT true;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS dirty_at BIGINT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS published_at BIGINT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS last_publish_error TEXT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS publishing_started_at BIGINT NULL;
diff --git a/core/database/schema.sql b/core/database/schema.sql
index 0a07e6c..81db90e 100644
--- a/core/database/schema.sql
+++ b/core/database/schema.sql
@@ -820,12 +820,22 @@ CREATE TABLE IF NOT EXISTS config_state (
   id SMALLINT PRIMARY KEY,
   version BIGINT NOT NULL,
   active_snapshot_version BIGINT NULL,
+  dirty BOOLEAN NOT NULL DEFAULT true,
+  dirty_at BIGINT NULL,
+  published_at BIGINT NULL,
+  last_publish_error TEXT NULL,
+  publishing_started_at BIGINT NULL,
   CONSTRAINT config_state_singleton CHECK (id = 1)
 );
 
 INSERT INTO config_state (id, version) VALUES (1, 0)
 ON CONFLICT (id) DO NOTHING;
 ALTER TABLE config_state ADD COLUMN IF NOT EXISTS active_snapshot_version BIGINT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS dirty BOOLEAN NOT NULL DEFAULT true;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS dirty_at BIGINT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS published_at BIGINT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS last_publish_error TEXT NULL;
+ALTER TABLE config_state ADD COLUMN IF NOT EXISTS publishing_started_at BIGINT NULL;
 
 CREATE TABLE IF NOT EXISTS config_snapshots (
   version BIGINT PRIMARY KEY,
diff --git a/core/public_index.php b/core/public_index.php
index 65dac6a..3bb30fe 100644
--- a/core/public_index.php
+++ b/core/public_index.php
@@ -279,7 +279,8 @@ function requireApiAuth(): void
         $checks['schema'] = 'fail';
     }
     try {
-        $configService->buildSnapshotForVersion(null);
+        $snapshot = $configService->activeSnapshot();
+        $checks['config_generation'] = $snapshot === null ? 'warn' : 'ok';
     } catch (\Throwable) {
         $checks['config_generation'] = 'fail';
     }
@@ -350,15 +351,21 @@ function requireApiAuth(): void
 $router->add('GET', '/api/v1/audit', static fn (Request $req): array => Response::json($operationsLogController->audit($req->query)), auth: true);
 $router->add('GET', '/api/v1/events', static fn (Request $req): array => Response::json($operationsLogController->events($req->query)), auth: true);
 $router->add('GET', '/api/v1/jobs', static fn (Request $req): array => Response::json($operationsLogController->jobs($req->query)), auth: true);
-$router->add('GET', '/api/v1/config/snapshots', static fn (): array => Response::json(['data' => $configService->snapshots()]), auth: true);
+$router->add('GET', '/api/v1/config/snapshots', static fn (Request $req): array => Response::json(['data' => $configService->snapshots((int) ($req->query['limit'] ?? 20), (int) ($req->query['offset'] ?? 0))]), auth: true);
 $router->add('GET', '/api/v1/config/snapshots/latest', static fn (): array => Response::json(['data' => $configService->latestSnapshotSummary()]), auth: true);
 $router->add('GET', '/api/v1/config/snapshots/{version}', static function (Request $req, array $p) use ($configService): array {
+    if (!truthyEnv('CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED', false)) {
+        return Response::json(['error' => 'config_snapshot_history_disabled'], 404);
+    }
     $snapshot = $configService->snapshot((int) $p['version']);
     return $snapshot === null
         ? Response::json(['error' => 'config_snapshot_not_found'], 404)
         : Response::json(['data' => $snapshot]);
 }, auth: true);
 $router->add('POST', '/api/v1/config/snapshots/diff', static function (Request $req) use ($configService): array {
+    if (!truthyEnv('CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED', false)) {
+        return Response::json(['error' => 'config_snapshot_history_disabled'], 404);
+    }
     try {
         return Response::json(['data' => $configService->diff((int) ($req->body['from_version'] ?? 0), (int) ($req->body['to_version'] ?? 0))]);
     } catch (\OutOfBoundsException $e) {
@@ -366,13 +373,16 @@ function requireApiAuth(): void
     }
 }, auth: true);
 $router->add('POST', '/api/v1/config/snapshots/{version}/rollback', static function (Request $req, array $p) use ($configService): array {
+    if (!truthyEnv('CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED', false)) {
+        return Response::json(['error' => 'config_snapshot_history_disabled'], 404);
+    }
     try {
         return Response::json(['data' => $configService->rollback((int) $p['version'])]);
     } catch (\OutOfBoundsException $e) {
         return Response::json(['error' => $e->getMessage()], 404);
     }
 }, auth: true);
-$router->add('POST', '/api/v1/config/snapshots/rebuild', static fn (): array => Response::json(['data' => $configService->rebuild()]), auth: true);
+$router->add('POST', '/api/v1/config/snapshots/rebuild', static fn (): array => Response::json(['data' => $configService->publishSnapshot(true)]), auth: true);
 $router->add('GET', '/api/v1/settings', static fn (): array => Response::json($settingsController->index()), auth: true);
 $router->add('GET', '/api/v1/settings/{group}', static function (Request $req, array $p) use ($settingsController): array {
     try {
@@ -652,7 +662,7 @@ function requireApiAuth(): void
 $router->add('GET', '/api/v1/edges/dns', static fn () => Response::json($edgeController->dns()), auth: true);
 $router->add('POST', '/api/v1/edge/register', static fn (Request $req) => Response::json($edgeController->register($req->body)), edgeAuth: true);
 $router->add('POST', '/api/v1/edge/heartbeat', static fn (Request $req) => Response::json($edgeController->heartbeat($req->body)), edgeAuth: true);
-$router->add('GET', '/api/v1/edge/config', static fn (Request $req) => Response::json($configService->buildSnapshotForVersion(isset($req->query['if_version']) ? (int) $req->query['if_version'] : null)), edgeAuth: true);
+$router->add('GET', '/api/v1/edge/config', static fn (Request $req) => Response::json($configService->edgeConfig(isset($req->query['if_version']) ? (int) $req->query['if_version'] : null)), edgeAuth: true);
 $router->add('POST', '/api/v1/collector/usage', static fn (Request $req) => Response::json($collectorController->ingest($req->body)), edgeAuth: true);
 $router->add('POST', '/api/v1/collector/security-events', static fn (Request $req) => Response::json($collectorController->ingestSecurityEvents($req->body)), edgeAuth: true);
 $router->add('GET', '/api/v1/usage/summary', static fn (Request $req) => Response::json($collectorController->summary(isset($req->query['domain_id']) ? (string) $req->query['domain_id'] : null, isset($req->query['bucket']) ? (string) $req->query['bucket'] : null)), auth: true);
diff --git a/core/tests/test_config_snapshot_materialized_cache_contract.py b/core/tests/test_config_snapshot_materialized_cache_contract.py
new file mode 100644
index 0000000..0fe3039
--- /dev/null
+++ b/core/tests/test_config_snapshot_materialized_cache_contract.py
@@ -0,0 +1,57 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text()
+
+
+def test_config_state_materialized_cache_columns_are_additive():
+    migration = read("core/database/migrations/000032_config_snapshot_materialized_cache.sql")
+    schema = read("core/database/schema.sql")
+
+    for column in ("dirty", "dirty_at", "published_at", "last_publish_error", "publishing_started_at"):
+        assert f"ADD COLUMN IF NOT EXISTS {column}" in migration
+        assert column in schema
+    assert "DROP TABLE" not in migration
+    assert "DELETE FROM config_snapshots" not in migration
+
+
+def test_edge_config_uses_published_cache_not_legacy_rebuild_route():
+    routes = read("core/public_index.php")
+    service = read("core/app/Modules/Proxy/Services/ConfigService.php")
+    sync_command = read("core/app/Console/Commands/CdnEdgeSyncConfigCommand.php")
+
+    assert "$configService->edgeConfig(" in routes
+    assert "$configService->buildSnapshotForVersion(" not in routes
+    assert "->edgeConfig($ifVersion)" in sync_command
+    assert "public function edgeConfig(?int $ifVersion = null): array" in service
+    assert "return ['not_modified' => true, 'version' => $activeVersion]" in service
+    assert "pg_try_advisory_lock(hashtext('cdnlite_config_publish'))" in service
+    assert "stale_while_rebuilding" in service
+
+
+def test_dirty_marks_preserve_active_snapshot_and_history_is_disabled_by_default():
+    service = read("core/app/Modules/Proxy/Services/ConfigService.php")
+    routes = read("core/public_index.php")
+
+    assert "public static function markDirty" in service
+    assert "SET dirty = true, dirty_at = :dirty_at" in service
+    assert "active_snapshot_version = NULL" not in service
+    assert "CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED" in routes
+    assert "config_snapshot_history_disabled" in routes
+
+
+def test_count_based_prune_command_is_registered_and_keeps_active_snapshot():
+    service = read("core/app/Modules/Proxy/Services/ConfigService.php")
+    artisan = read("core/artisan")
+    command = read("core/app/Console/Commands/CdnConfigSnapshotsPruneCommand.php")
+
+    assert "cdn:config-snapshots:prune" in artisan
+    assert "--keep=2 --batch=5000 --dry-run" in read("docs/setup.md")
+    assert "active_snapshot_version AS version" in service
+    assert "ORDER BY version DESC LIMIT :keep_last" in service
+    assert "DELETE FROM config_snapshots" in service
+    assert "dry_run" in command
diff --git a/core/tests/test_hardening_contract.py b/core/tests/test_hardening_contract.py
index 89c7fef..2716148 100644
--- a/core/tests/test_hardening_contract.py
+++ b/core/tests/test_hardening_contract.py
@@ -140,8 +140,8 @@ def test_edge_sync_config_reuses_version_when_unchanged():
 
     assert first["version"] >= 1
     assert second["version"] == first["version"]
-    assert second["reused"] is True
-    assert second["generated_at"] > first["generated_at"]
+    assert "reused" not in second
+    assert second["generated_at"] == first["generated_at"]
     assert not_modified["version"] == first["version"]
     assert (not_modified.get("not_modified") is True) or (not_modified.get("reused") is True)
 
@@ -164,7 +164,7 @@ def test_edge_sync_config_reuses_version_when_unchanged():
 ''',
         str(first["version"]),
     )
-    assert row["generated_at"] == second["generated_at"]
+    assert row["generated_at"] == first["generated_at"]
     assert row["payload_generated_at"] == first["generated_at"]
 
 
diff --git a/core/tests/test_migrations_contract.py b/core/tests/test_migrations_contract.py
index e81a9e3..3abf402 100644
--- a/core/tests/test_migrations_contract.py
+++ b/core/tests/test_migrations_contract.py
@@ -58,6 +58,18 @@ def test_migrator_supports_legacy_baseline_adoption_and_checksum_validation():
     assert "legacy_schema_incompatible" in migrator
 
 
+def test_phase7_origin_resilience_constraints_are_idempotent_for_legacy_adoption():
+    migrator = (ROOT / "core/app/Support/DatabaseMigrator.php").read_text()
+    migration = (ROOT / "core/database/migrations/000031_phase7_origin_resilience.sql").read_text()
+
+    assert "sqlForExecution" in migrator
+    assert "($migration['version'] ?? '') !== '000031'" in migrator
+    assert "domain_origins_load_balancing_algorithm_check" in migrator
+    assert "IF NOT EXISTS (SELECT 1 FROM pg_constraint" in migrator
+    assert "Preserve the historical migration checksum" in migrator
+    assert "ADD CONSTRAINT domain_origins_load_balancing_algorithm_check" in migration
+
+
 def test_ci_runs_migrations_before_core_tests():
     workflow = (ROOT / ".github/workflows/ci.yml").read_text()
     schema_step = "php core/artisan cdn:db:migrate"
@@ -76,6 +88,7 @@ def test_retention_scheduler_is_opt_in_and_uses_bounded_prune_command():
         assert "retention-scheduler" in source
         assert "CDNLITE_RETENTION_PRUNE_ENABLED" in source
         assert "cdn:usage:prune --all" in source
+        assert "cdn:config-snapshots:prune" in source
         assert "CDNLITE_RETENTION_INTERVAL_SECONDS" in source
         assert "CDNLITE_RETENTION_BATCH_SIZE" in source
 
diff --git a/core/tests/test_nameserver_force_verify_contract.py b/core/tests/test_nameserver_force_verify_contract.py
index 0cf0ad9..4f9e7e7 100644
--- a/core/tests/test_nameserver_force_verify_contract.py
+++ b/core/tests/test_nameserver_force_verify_contract.py
@@ -42,7 +42,7 @@ def test_force_verify_requires_admin_session_and_audits_reason():
     assert "Validator::requiredString($input, 'reason'" in controller
     assert "domain.nameserver.force_verify" in service
     assert "forced_verified" in service
-    assert "UPDATE config_state SET active_snapshot_version = NULL" in service
+    assert "ConfigService::markDirty('domain.verification.changed')" in service
     assert "(new DnsReconciler())->reconcile()" in service
 
 
@@ -64,7 +64,7 @@ def test_reseed_expected_nameservers_is_admin_only_and_audited():
     assert "DELETE FROM domain_nameservers WHERE domain_id" in service
     assert "domain.nameserver.reseed_expected" in service
     assert "reseeded_expected" in service
-    assert "UPDATE config_state SET active_snapshot_version = NULL" in service
+    assert "ConfigService::markDirty('domain.verification.changed')" in service
     assert "(new DnsReconciler())->reconcile()" in service
 
     assert "reseedExpectedNameservers" in api
diff --git a/core/tests/test_phase14_15_contract.py b/core/tests/test_phase14_15_contract.py
index 91c709f..250f7c8 100644
--- a/core/tests/test_phase14_15_contract.py
+++ b/core/tests/test_phase14_15_contract.py
@@ -40,9 +40,10 @@ def test_snapshot_history_routes_and_activation_pointer_are_present():
     assert "public function diff" in service
     assert "public function rollback" in service
     assert "public function rebuild" in service
-    assert "private function activeSnapshot" in service
+    assert "public function activeSnapshot" in service
     assert "private function activateSnapshotVersion" in service
     assert "private function activeSnapshotVersion" in service
+    assert "config_snapshot_history_disabled" in routes
     assert "config.publish" in service
     assert "config.rollback" in service
     assert "$this->activateSnapshotVersion($version)" in service
diff --git a/core/tests/test_phase7_config_invalidation_contract.py b/core/tests/test_phase7_config_invalidation_contract.py
index 0e45876..7f18d39 100644
--- a/core/tests/test_phase7_config_invalidation_contract.py
+++ b/core/tests/test_phase7_config_invalidation_contract.py
@@ -12,7 +12,7 @@ def test_domain_mutations_invalidate_config_before_reconcile():
     service = read("core/app/Modules/Domains/Services/DomainService.php")
 
     assert "private function invalidateConfigSnapshot" in service
-    assert "UPDATE config_state SET active_snapshot_version = NULL WHERE id = 1" in service
+    assert "ConfigService::markDirty('domain.changed')" in service
     assert "AuditLog::write('domain.create'" in service
     assert "AuditLog::write('domain.update'" in service
     assert "AuditLog::write('domain.delete'" in service
@@ -30,6 +30,7 @@ def test_dns_and_geo_route_mutations_invalidate_config():
     openapi = read("docs/public/api/openapi.yaml")
 
     assert "private function invalidateConfigSnapshot" in dns_service
+    assert "ConfigService::markDirty('dns.changed')" in dns_service
     assert "DnsReconciler" in dns_service
     assert "for ($attempt = 1; $attempt <= 3; $attempt++)" in dns_service
     assert "dns_reconciler_busy" in dns_service
@@ -37,6 +38,7 @@ def test_dns_and_geo_route_mutations_invalidate_config():
     assert "AuditLog::write('dns.reconcile.failed'" in dns_service
     assert "'local_state_saved' => true" in dns_service
     assert "private function invalidateConfigSnapshot" in geo_service
+    assert "ConfigService::markDirty('dns.geo_routes.changed')" in geo_service
     assert "AuditLog::write('dns.geo_routes.update'" in geo_service
     assert "$this->invalidateConfigSnapshot();\n        (new DnsReconciler())->reconcile();" in geo_service
     assert "private function dnsPublishFailure" in dns_controller
diff --git a/core/tests/test_rate_limit_crud_contract.py b/core/tests/test_rate_limit_crud_contract.py
index b4dddb4..c823a70 100644
--- a/core/tests/test_rate_limit_crud_contract.py
+++ b/core/tests/test_rate_limit_crud_contract.py
@@ -15,7 +15,7 @@ def test_rate_limit_crud_routes_and_snapshot_collection_contract():
     assert "updateRateLimit" in service
     assert "deleteRateLimit" in service
     assert "invalidateConfigSnapshot" in service
-    assert "active_snapshot_version = NULL" in service
+    assert "ConfigService::markDirty('traffic_rules.changed')" in service
     assert "listRateLimits($domainId)" in config
 
 
diff --git a/core/tests/test_readiness_service.py b/core/tests/test_readiness_service.py
index a70ccfe..f96cdf6 100644
--- a/core/tests/test_readiness_service.py
+++ b/core/tests/test_readiness_service.py
@@ -40,7 +40,7 @@ def test_snapshot_readiness_links_to_an_existing_operational_page():
     )[0]
 
     assert "'/config-snapshot'" not in snapshot_check
-    assert snapshot_check.count("'/edge-nodes'") == 2
+    assert snapshot_check.count("'/edge-nodes'") >= 2
     assert "{ path: '/edge-nodes'" in router
 
 
diff --git a/deploy/core/docker-compose.yml b/deploy/core/docker-compose.yml
index 6f15886..b1e1f27 100644
--- a/deploy/core/docker-compose.yml
+++ b/deploy/core/docker-compose.yml
@@ -34,6 +34,9 @@ services:
       APP_DEBUG: ${APP_DEBUG}
       CDNLITE_API_TOKEN: ${CDNLITE_API_TOKEN}
       CDNLITE_ORIGIN_SHIELD_SECRET: ${CDNLITE_ORIGIN_SHIELD_SECRET}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE}
+      CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED: ${CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN}
       CDNLITE_BOOTSTRAP_EDGE_ID: ${CDNLITE_BOOTSTRAP_EDGE_ID}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE}
@@ -158,12 +161,14 @@ services:
       CDNLITE_RETENTION_PRUNE_ENABLED: ${CDNLITE_RETENTION_PRUNE_ENABLED}
       CDNLITE_RETENTION_INTERVAL_SECONDS: ${CDNLITE_RETENTION_INTERVAL_SECONDS}
       CDNLITE_RETENTION_BATCH_SIZE: ${CDNLITE_RETENTION_BATCH_SIZE}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE}
       CDNLITE_ANALYTICS_RETENTION_DAYS: ${CDNLITE_ANALYTICS_RETENTION_DAYS}
       CDNLITE_SECURITY_EVENT_RETENTION_DAYS: ${CDNLITE_SECURITY_EVENT_RETENTION_DAYS}
       CDNLITE_DNS_EVENT_RETENTION_DAYS: ${CDNLITE_DNS_EVENT_RETENTION_DAYS}
       CDNLITE_SSL_JOB_RETENTION_DAYS: ${CDNLITE_SSL_JOB_RETENTION_DAYS}
       CDNLITE_INGEST_KEY_RETENTION_DAYS: ${CDNLITE_INGEST_KEY_RETENTION_DAYS}
-    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
+    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; php artisan cdn:config-snapshots:prune --keep=\"$${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}\" --batch=\"$${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}\" || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
     networks:
       - internal
 
diff --git a/deploy/generate-deployment.sh b/deploy/generate-deployment.sh
index 68929f4..bf8016e 100755
--- a/deploy/generate-deployment.sh
+++ b/deploy/generate-deployment.sh
@@ -310,6 +310,9 @@ APP_DEBUG=0
 CDNLITE_API_TOKEN=${CDNLITE_API_TOKEN}
 CDNLITE_SSL_SECRET_KEY=${CDNLITE_SSL_SECRET_KEY}
 CDNLITE_ORIGIN_SHIELD_SECRET=${CDNLITE_ORIGIN_SHIELD_SECRET}
+CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST=2
+CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE=5000
+CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED=false
 CDNLITE_ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory
 CDNLITE_ACME_CONTACT_EMAIL=${ACME_EMAIL}
 CDNLITE_ACME_DNS_PROPAGATION_SECONDS=30
@@ -681,7 +684,7 @@ services:
       postgres:
         condition: service_healthy
     env_file: .env
-    command: ["sh", "-lc", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
+    command: ["sh", "-lc", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; php artisan cdn:config-snapshots:prune --keep=\"$${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}\" --batch=\"$${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}\" || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
     networks: [cdnlite-internal]
 
   dashboard:
diff --git a/deploy/starter/docker-compose.yml b/deploy/starter/docker-compose.yml
index 061f745..85b43e5 100644
--- a/deploy/starter/docker-compose.yml
+++ b/deploy/starter/docker-compose.yml
@@ -36,6 +36,9 @@ services:
       APP_DEBUG: ${APP_DEBUG}
       CDNLITE_API_TOKEN: ${CDNLITE_API_TOKEN}
       CDNLITE_ORIGIN_SHIELD_SECRET: ${CDNLITE_ORIGIN_SHIELD_SECRET}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE}
+      CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED: ${CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN}
       CDNLITE_BOOTSTRAP_EDGE_ID: ${CDNLITE_BOOTSTRAP_EDGE_ID}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE}
@@ -160,12 +163,14 @@ services:
       CDNLITE_RETENTION_PRUNE_ENABLED: ${CDNLITE_RETENTION_PRUNE_ENABLED}
       CDNLITE_RETENTION_INTERVAL_SECONDS: ${CDNLITE_RETENTION_INTERVAL_SECONDS}
       CDNLITE_RETENTION_BATCH_SIZE: ${CDNLITE_RETENTION_BATCH_SIZE}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE}
       CDNLITE_ANALYTICS_RETENTION_DAYS: ${CDNLITE_ANALYTICS_RETENTION_DAYS}
       CDNLITE_SECURITY_EVENT_RETENTION_DAYS: ${CDNLITE_SECURITY_EVENT_RETENTION_DAYS}
       CDNLITE_DNS_EVENT_RETENTION_DAYS: ${CDNLITE_DNS_EVENT_RETENTION_DAYS}
       CDNLITE_SSL_JOB_RETENTION_DAYS: ${CDNLITE_SSL_JOB_RETENTION_DAYS}
       CDNLITE_INGEST_KEY_RETENTION_DAYS: ${CDNLITE_INGEST_KEY_RETENTION_DAYS}
-    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
+    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; php artisan cdn:config-snapshots:prune --keep=\"$${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}\" --batch=\"$${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}\" || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
     networks:
       - cdnlite-internal
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 40b9118..19a6478 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -35,6 +35,9 @@ services:
       APP_DEBUG: ${APP_DEBUG:-0}
       CDNLITE_API_TOKEN: ${CDNLITE_API_TOKEN:-}
       CDNLITE_ORIGIN_SHIELD_SECRET: ${CDNLITE_ORIGIN_SHIELD_SECRET:-dev-origin-shield-secret-change-me}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}
+      CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED: ${CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED:-false}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN:-1}
       CDNLITE_BOOTSTRAP_EDGE_ID: ${CDNLITE_BOOTSTRAP_EDGE_ID:-}
       CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE: ${CDNLITE_BOOTSTRAP_EDGE_TOKEN_VALUE:-}
@@ -167,12 +170,14 @@ services:
       CDNLITE_RETENTION_PRUNE_ENABLED: ${CDNLITE_RETENTION_PRUNE_ENABLED:-false}
       CDNLITE_RETENTION_INTERVAL_SECONDS: ${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}
       CDNLITE_RETENTION_BATCH_SIZE: ${CDNLITE_RETENTION_BATCH_SIZE:-5000}
+      CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST: ${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}
+      CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE: ${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}
       CDNLITE_ANALYTICS_RETENTION_DAYS: ${CDNLITE_ANALYTICS_RETENTION_DAYS:-30}
       CDNLITE_SECURITY_EVENT_RETENTION_DAYS: ${CDNLITE_SECURITY_EVENT_RETENTION_DAYS:-90}
       CDNLITE_DNS_EVENT_RETENTION_DAYS: ${CDNLITE_DNS_EVENT_RETENTION_DAYS:-30}
       CDNLITE_SSL_JOB_RETENTION_DAYS: ${CDNLITE_SSL_JOB_RETENTION_DAYS:-180}
       CDNLITE_INGEST_KEY_RETENTION_DAYS: ${CDNLITE_INGEST_KEY_RETENTION_DAYS:-7}
-    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
+    command: ["sh", "-c", "if [ \"$${CDNLITE_SCHEDULER_IDLE:-0}\" = \"1\" ] || [ \"$${CDNLITE_RETENTION_PRUNE_ENABLED:-false}\" != \"true\" ]; then echo 'retention scheduler idle'; tail -f /dev/null; fi; while true; do php artisan cdn:usage:prune --all || true; php artisan cdn:config-snapshots:prune --keep=\"$${CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST:-2}\" --batch=\"$${CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE:-5000}\" || true; sleep \"$${CDNLITE_RETENTION_INTERVAL_SECONDS:-86400}\"; done"]
     restart: unless-stopped
 
   dns-reconciler:
diff --git a/docs/api/api.md b/docs/api/api.md
index 8fac545..6b030e9 100644
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -680,19 +680,19 @@ Edge proxy responses include an origin marker such as `X-CDNLITE-Origin: origin`
 Edge endpoint notes:
 
 - Register and heartbeat requests must have the same `edge_id` in the header and JSON body.
-- `GET /api/v1/edge/config` accepts `if_version` as a query parameter to avoid unnecessary config writes.
+- `GET /api/v1/edge/config` accepts `if_version` as a query parameter. Matching clean versions return `not_modified` from the active published snapshot without rebuilding config.
 - Usage and security-event ingest are queue-friendly. If ingest fails, the agent should keep local payloads for retry.
 
 ## Config Snapshots
 
 | Method | Route | Purpose |
 | --- | --- | --- |
-| `GET` | `/api/v1/config/snapshots` | List versions. |
+| `GET` | `/api/v1/config/snapshots` | List versions, paginated with `limit` default `20` and max `100`. |
 | `GET` | `/api/v1/config/snapshots/latest` | Return the latest snapshot summary without the snapshot payload. |
-| `GET` | `/api/v1/config/snapshots/{version}` | Show version. |
-| `POST` | `/api/v1/config/snapshots/diff` | Diff JSON paths between versions. |
-| `POST` | `/api/v1/config/snapshots/{version}/rollback` | Activate old version. |
-| `POST` | `/api/v1/config/snapshots/rebuild` | Rebuild from database state. |
+| `GET` | `/api/v1/config/snapshots/{version}` | Show version when `CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED=true`; otherwise returns `config_snapshot_history_disabled`. |
+| `POST` | `/api/v1/config/snapshots/diff` | Diff JSON paths between versions when history is enabled. |
+| `POST` | `/api/v1/config/snapshots/{version}/rollback` | Development-only rollback when history is enabled. Disabled by default because JSON rollback does not roll back database source-of-truth tables. |
+| `POST` | `/api/v1/config/snapshots/rebuild` | Force-publish the materialized edge config from database state. |
 
 Diff request:
 
@@ -705,10 +705,10 @@ Diff request:
 
 Snapshot safety tips:
 
-- Diff before rollback.
+- Treat snapshots as a generated edge cache. Domains, DNS records, origins, rules, cache settings, page rules, and SSL rows remain the source of truth.
 - Prefer rebuild after normal database-backed changes.
-- Use rollback for a known-bad config version, then investigate why the bad state was generated.
-- Edge nodes pull snapshots; rollback is not an instant push to every edge.
+- Use `php artisan cdn:config-snapshots:prune --keep=2 --batch=5000` to bound large historical tables without deleting the active snapshot.
+- Edge nodes pull snapshots; publishing is not an instant push to every edge.
 
 ## Settings
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 54356b1..549d614 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -134,8 +134,9 @@ connect, and HTTP failure details are stored by domain, origin, and edge node.
 ```text
 Admin/API change
   -> Core validates and writes PostgreSQL
-  -> ConfigService builds a snapshot
-  -> Snapshot version is stored
+  -> ConfigService marks the published edge config dirty
+  -> One publisher rebuilds the materialized snapshot under a PostgreSQL advisory lock
+  -> Active snapshot stays valid until the new version is stored
   -> Edge agent signs GET /api/v1/edge/config
   -> Agent writes config.json atomically
   -> OpenResty workers validate and atomically activate the fresh snapshot
@@ -204,4 +205,4 @@ or `POST /api/v1/domains/{domainId}/nameservers/verify`, which returns the
 expected, observed, matched, and missing nameserver sets. Admin sessions can use
 `POST /api/v1/domains/{domainId}/nameservers/force-verify` with a reason when
 delegation cannot be observed but the domain must be activated; the action is
-audited, invalidates the active edge snapshot, and triggers DNS reconciliation.
+audited, marks the edge config dirty, and triggers DNS reconciliation.
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 4c30a90..13235d5 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -383,7 +383,7 @@ curl -s "$API$PATH_ONLY" \
 
 The edge agent scripts already do this; the example is for developers writing custom edge tooling.
 
-## Config Snapshot Rollback
+## Config Snapshot Publish And Prune
 
 ```bash
 curl -s "$API/api/v1/config/snapshots" \
@@ -392,16 +392,15 @@ curl -s "$API/api/v1/config/snapshots" \
 curl -s "$API/api/v1/config/snapshots/latest" \
   -H "Authorization: Bearer $TOKEN"
 
-curl -s -X POST "$API/api/v1/config/snapshots/diff" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"from_version":12,"to_version":13}'
-
-curl -s -X POST "$API/api/v1/config/snapshots/12/rollback" \
+curl -s -X POST "$API/api/v1/config/snapshots/rebuild" \
   -H "Authorization: Bearer $TOKEN"
+
+docker compose exec core php artisan cdn:config-snapshots:prune --keep=2 --batch=5000 --dry-run
 ```
 
-Rollback is a control-plane action. Edge nodes still need to pull the active snapshot.
+Snapshot payload history, diff, and rollback endpoints are disabled unless
+`CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED=true`; snapshots are a generated edge
+cache, while database tables remain the source of truth.
 
 ## Recommendations
 
diff --git a/docs/public/api/openapi.yaml b/docs/public/api/openapi.yaml
index 6c38f12..f149797 100644
--- a/docs/public/api/openapi.yaml
+++ b/docs/public/api/openapi.yaml
@@ -1400,7 +1400,19 @@ paths:
   /api/v1/config/snapshots:
     get:
       tags: [Config]
-      summary: List config snapshots
+      summary: List config snapshots, paginated and bounded
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
       responses:
         "200":
           $ref: "#/components/responses/GenericArray"
@@ -1414,7 +1426,8 @@ paths:
   /api/v1/config/snapshots/{version}:
     get:
       tags: [Config]
-      summary: Get config snapshot
+      summary: Get config snapshot when history is enabled
+      description: Disabled by default unless CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED=true.
       parameters:
         - name: version
           in: path
@@ -1427,7 +1440,8 @@ paths:
   /api/v1/config/snapshots/diff:
     post:
       tags: [Config]
-      summary: Diff two config snapshots
+      summary: Diff two config snapshots when history is enabled
+      description: Disabled by default unless CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED=true.
       requestBody:
         required: true
         content:
@@ -1446,7 +1460,8 @@ paths:
   /api/v1/config/snapshots/{version}/rollback:
     post:
       tags: [Config]
-      summary: Roll back active config snapshot
+      summary: Development-only config snapshot rollback
+      description: Disabled by default because snapshot rollback does not roll back database source-of-truth tables.
       parameters:
         - name: version
           in: path
@@ -1459,7 +1474,7 @@ paths:
   /api/v1/config/snapshots/rebuild:
     post:
       tags: [Config]
-      summary: Rebuild config snapshot from database state
+      summary: Force-publish materialized edge config from database state
       responses:
         "200":
           $ref: "#/components/responses/GenericObject"
diff --git a/docs/setup.md b/docs/setup.md
index 10ecb6e..ca9359a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -175,6 +175,9 @@ Core settings:
 | `CDNLITE_CORS_ALLOWED_ORIGINS` | Browser origins allowed to call the API. |
 | `CDNLITE_SSL_SECRET_KEY` | Secret used for stored SSL material handling. |
 | `CDNLITE_ORIGIN_SHIELD_SECRET` | Default origin shield secret. |
+| `CDNLITE_CONFIG_SNAPSHOT_KEEP_LAST` | Count of latest published config snapshots to retain in addition to the active version; default `2`. |
+| `CDNLITE_CONFIG_SNAPSHOT_PRUNE_BATCH_SIZE` | Bounded delete batch used after publish and by `cdn:config-snapshots:prune`; default `5000`. |
+| `CDNLITE_CONFIG_SNAPSHOT_HISTORY_ENABLED` | Enables legacy snapshot payload, diff, and rollback endpoints for development; default `false`. |
 | `CDNLITE_ANALYTICS_RETENTION_DAYS` | Detailed edge request/activity retention window for `cdn:usage:prune`; default `30`. |
 | `CDNLITE_SECURITY_EVENT_RETENTION_DAYS` | High-volume WAF, rate-limit, bot, and Geo security-event retention for `cdn:usage:prune --all`; default `90`. |
 | `CDNLITE_DNS_EVENT_RETENTION_DAYS` | Successful DNS sync event retention for `cdn:usage:prune --all`; default `30`. Failed DNS sync events are retained for troubleshooting. |
@@ -309,6 +312,16 @@ docker compose exec core php artisan cdn:usage:prune --dry-run
 docker compose exec core php artisan cdn:usage:prune --days=30
 ```
 
+Config snapshots are a published edge cache, not the source of truth. The core
+keeps the active snapshot plus the latest two snapshots by default and prunes
+after successful publishes. Operators with a large historical table can prune in
+batches without deleting the active snapshot:
+
+```bash
+docker compose exec core php artisan cdn:config-snapshots:prune --keep=2 --batch=5000 --dry-run
+docker compose exec core php artisan cdn:config-snapshots:prune --keep=2 --batch=5000
+```
+
 Use the wider retention pass for high-volume operational rows after reviewing
 the dry run. It prunes raw request rows, high-volume security events, successful
 DNS sync events, terminal SSL jobs, expired edge nonces, and old ingest