cachegate 1.3.1 → 1.4.0

package/server.js

@@ -30,30 +30,116 @@ const semanticCache = require('./semanticCache');
 const metrics = require('./metrics');
 const router = require('./router');
 const streaming = require('./streaming');
-const anthropicProvider = require('./providers/anthropic');
-const openaiProvider = require('./providers/openai');
+const providers = require('./providers');
+// Kept as aliases: the cascade/grader paths below name these two explicitly
+// (OpenAI's logprobs are the only native confidence signal; Anthropic falls
+// back to a grader model). Everything that generalizes goes through
+// `providers` - see providers/index.js for why.
+const anthropicProvider = providers.get('anthropic');
+const openaiProvider = providers.get('openai');
 const failover = require('./failover');
+const coalescing = require('./coalescing');
+const cascade = require('./cascade');
+const tracing = require('./tracing');
+const pii = require('./pii');
+const guardrails = require('./guardrails');
+
+// Status-coded error for config/validation failures inside the dispatch
+// (the /v1 catch below reads err.status to pick the HTTP code, but ONLY
+// on the explicit-model path - see that catch's own comment on why the
+// virtual-model/failover path never honors it). skipMetric marks a
+// pre-dispatch validation failure (missing key, unsupported model) that
+// never actually reached a provider - the ORIGINAL inline
+// `return res.status(...)` code never called metrics.record() for these
+// either, so this restores that (a static misconfiguration isn't a live
+// provider-health signal; it shouldn't pollute the Provider alerts table
+// the same way a real dispatch failure does).
+function httpError(status, message, { skipMetric = false } = {}) {
+  const err = new Error(message);
+  err.status = status;
+  err.skipMetric = skipMetric;
+  return err;
+}
+
+// Applies pii.redact() to every string in a messages array (text content
+// and the `text` field of multimodal content parts), returning a NEW
+// array. Non-string content (images, etc.) passes through untouched. Only
+// called when pii.isEnabled(), so redaction is identity when the flag is
+// off.
+function redactMessages(messages) {
+  return messages.map((m) => {
+    if (!m || typeof m !== 'object') return m;
+    if (typeof m.content === 'string') {
+      return { ...m, content: pii.redact(m.content).text };
+    }
+    if (Array.isArray(m.content)) {
+      return {
+        ...m,
+        content: m.content.map((part) => {
+          if (typeof part === 'string') return pii.redact(part).text;
+          if (part && typeof part === 'object' && typeof part.text === 'string') {
+            return { ...part, text: pii.redact(part.text).text };
+          }
+          return part;
+        })
+      };
+    }
+    return m;
+  });
+}
 
 const app = express();
-// Any deployment behind a reverse proxy or load balancer (nginx,
-// Traefik, Render, Heroku, ...) forwards the real client IP in
-// X-Forwarded-For rather than as the raw socket address. Express's own
-// default (`trust proxy` unset, i.e. false) makes express-rate-limit
-// refuse that header outright the moment it's present - it throws
-// ERR_ERL_UNEXPECTED_X_FORWARDED_FOR inside its key generator on every
-// request through a rate-limited route, rather than risk keying
-// per-caller limits off a spoofable header it hasn't been told to
-// trust. Found running this behind a single-hop proxy in production
-// (Cachegate Cloud, 2026-09-04) - not fatal to the request itself, but
-// it means the per-IP rate limiter was keying off the proxy's own IP
-// for every caller instead of each real client, so brute-force/abuse
-// limiting on auth-style routes was effectively shared across ALL
-// users rather than per-user. `1` (trust exactly one hop) is the
-// correct value for a single reverse-proxy topology - the common case
-// this engine actually runs behind. A deployment with more than one
-// proxy hop in front of it should set this to the real hop count
-// instead (see Express's own `trust proxy` docs) rather than assume 1.
-app.set('trust proxy', 1);
+// Step 36 (observability): initialize OTel once, at module load. A no-op
+// unless OTEL_ENABLED + OTEL_EXPORTER_OTLP_ENDPOINT are both set (see
+// tracing.js) - so both the standalone server and a wrapping deployment
+// (cachegate-cloud's cloud-server.js) get tracing without any extra call.
+tracing.initTracing();
+// `trust proxy`, now CONFIGURABLE and secure by default. The previous hardcoded `1` was chosen for
+// Cachegate Cloud's single-hop topology (2026-09-04) and is right THERE, but it is the wrong default
+// for the topology this engine's own README documents (`docker run -p 4000:4000`: no proxy at all).
+// In that topology `1` trusts a client-controlled X-Forwarded-For, so any caller can present a fresh
+// IP on every request and the per-IP limiter on the key-holding routes is defeated - fail-OPEN, and
+// silent. `false` behind a real proxy is fail-CLOSED and loud: the limiter keys globally, one env var
+// away from correct. Every other security decision in this file fails closed (no DATABASE_URL, no
+// API_KEY_ENCRYPTION_SECRET, auth) and this should not be the exception.
+//
+// Deployment note: a proxied deployment MUST now set TRUST_PROXY explicitly - Cachegate Cloud sets
+// TRUST_PROXY=1 in render.yaml and RENDER-ENV-MAP.md. Upgrade impact is a boot-time warning on Render
+// (see below) plus a CHANGELOG entry, not a silent change of limiter scope.
+function resolveTrustProxy(raw) {
+  const value = raw == null ? '' : String(raw).trim();
+  if (value === '') {
+    // Only warn where a proxy demonstrably exists: Render sets RENDER/RENDER_EXTERNAL_URL. Warning on
+    // every unset boot would be noise in the topology where false is the correct answer.
+    if (process.env.RENDER || process.env.RENDER_EXTERNAL_URL) {
+      console.warn(
+        '⚠️  TRUST_PROXY is unset and this looks like a proxied deployment: assuming NO proxy. ' +
+        'Set TRUST_PROXY=1 (single hop) or the real hop count, or per-IP rate limiting will be global.'
+      );
+    }
+    return false;
+  }
+  const lower = value.toLowerCase();
+  if (['false', '0', 'off', 'no'].includes(lower)) return false;
+  if (lower === 'true') return true;
+  if (/^\d+$/.test(value)) return parseInt(value, 10);
+  // Express also accepts a list of addresses/CIDRs plus the keywords loopback/linklocal/uniquelocal -
+  // the form a real multi-hop deployment needs - so that is passed through. A guess here is not
+  // harmless: a typo that express cannot parse would fall back to trusting nothing (or everything),
+  // silently changing limiter scope, which is the class of bug this whole block exists to prevent.
+  const tokens = value.split(',').map((t) => t.trim()).filter(Boolean);
+  const valid = tokens.length > 0 && tokens.every((t) =>
+    ['loopback', 'linklocal', 'uniquelocal'].includes(t.toLowerCase()) ||
+    /^[0-9a-fA-F:.]+(\/\d{1,3})?$/.test(t));
+  if (valid) return tokens;
+  throw new Error(
+    `TRUST_PROXY="${value}" is not a value express can use. Expected false/true, a hop count, or a ` +
+    'comma-separated list of IPs/CIDRs (loopback, linklocal, uniquelocal are also accepted). ' +
+    'Refusing to start rather than silently changing rate-limiter scope.'
+  );
+}
+
+app.set('trust proxy', resolveTrustProxy(process.env.TRUST_PROXY));
 // No X-Powered-By: Express - free, standard hardening (avoids handing a
 // public-facing service's framework fingerprint to every caller for no
 // benefit).
@@ -151,8 +237,10 @@ const seams = {
   // (See the callers below: they never cache a client built from a
   // non-default resolver's key, so a decrypted per-tenant secret never
   // outlives the one request it was resolved for.)
-  resolveProviderKey: (scope, provider) =>
-    (provider === 'anthropic' ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY) || null,
+  resolveProviderKey: (scope, provider) => {
+    const key = providers.envKey(provider);
+    return (key ? process.env[key] : null) || null;
+  },
 
   // Passed straight through as express-rate-limit's own `keyGenerator`.
   // Default: undefined, so express-rate-limit's own per-IP default
@@ -280,25 +368,31 @@ app.use('/v1', rateLimiter, requireInternalKey, express.json({ limit: process.en
 // tenant), every call below builds a fresh client instead of caching
 // one - a decrypted secret must never outlive the one request it was
 // resolved for.
-let anthropicClient;
-let openaiClient;
+// One cached client per provider for the default (unscoped) resolver. A
+// scoped resolver may return a per-tenant decrypted secret, so those clients
+// are deliberately NOT cached - a decrypted key must never outlive the request
+// it was resolved for.
+const defaultClients = new Map();
 
-async function getAnthropicClient(scope) {
-  const key = await seams.resolveProviderKey(scope, 'anthropic');
+async function getProviderClient(scope, provider) {
+  const mod = providers.get(provider);
+  if (!mod) throw Object.assign(new Error(`unknown provider: ${provider}`), { status: 500 });
+  const key = await seams.resolveProviderKey(scope, provider);
   if (scope == null) {
-    if (!anthropicClient) anthropicClient = anthropicProvider.buildClient(key);
-    return anthropicClient;
+    if (!defaultClients.has(provider)) defaultClients.set(provider, mod.buildClient(key));
+    return defaultClients.get(provider);
   }
-  return anthropicProvider.buildClient(key);
+  return mod.buildClient(key);
 }
 
-async function getOpenAiClient(scope) {
-  const key = await seams.resolveProviderKey(scope, 'openai');
-  if (scope == null) {
-    if (!openaiClient) openaiClient = openaiProvider.buildClient(key);
-    return openaiClient;
-  }
-  return openaiProvider.buildClient(key);
+const getAnthropicClient = (scope) => getProviderClient(scope, 'anthropic');
+const getOpenAiClient = (scope) => getProviderClient(scope, 'openai');
+
+// Thin wrappers kept for the call sites that genuinely mean "this one
+// provider" (cascade confidence, the grader). Everything else asks the
+// registry: providerForModel() is the single answer to "who serves this?".
+function providerForModel(model) {
+  return providers.detectProvider(model);
 }
 
 function isModelAnthropic(model) {
@@ -352,6 +446,7 @@ app.get('/stats', requireInternalKey, readEndpointLimiter, async (req, res) => {
     const totalCostUsd = recent.reduce((sum, r) => sum + (r.cost_usd || 0), 0);
     const exactHits = recent.filter((r) => r.cache_hit && r.cache_type !== 'semantic').length;
     const semanticHits = recent.filter((r) => r.cache_hit && r.cache_type === 'semantic').length;
+    const savedUsd = metrics.computeSavings(recent).total;
     res.json({
       sample_size: recent.length,
       cache_hit_rate: {
@@ -360,6 +455,7 @@ app.get('/stats', requireInternalKey, readEndpointLimiter, async (req, res) => {
         combined: recent.length ? (exactHits + semanticHits) / recent.length : 0
       },
       total_cost_usd: totalCostUsd,
+      saved_usd: savedUsd,
       by_provider: byProvider,
       // Internal routing configuration - which providers have a key
       // configured, which virtual-model tiers exist, and which strategy picks
@@ -476,17 +572,75 @@ function streamCachedReplay(res, entry, cacheType) {
 // against more than one provider in the same request. Throws an error
 // with `.status` set so failover.isRetryableError() can decide whether
 // it's worth trying the next candidate.
-async function dispatchToProvider(scope, provider, payload) {
-  if (provider === 'anthropic') {
-    if (!(await seams.resolveProviderKey(scope, 'anthropic'))) {
-      throw Object.assign(new Error('ANTHROPIC_API_KEY not configured'), { status: 500 });
-    }
-    return anthropicProvider.chat(await getAnthropicClient(scope), payload);
+// `options` is provider-specific dispatch hints (cascade routing, step 34).
+// It reaches only providers/openai.js today (requestLogprobs); Anthropic
+// ignores it. Kept backward-compatible - existing callers pass no options.
+async function dispatchToProvider(scope, provider, payload, options = {}) {
+  const mod = providers.get(provider);
+  if (!mod) throw Object.assign(new Error(`unknown provider: ${provider}`), { status: 500 });
+  if (!(await seams.resolveProviderKey(scope, provider))) {
+    // Names the variable the provider actually needs - the message is built
+    // from the registry, so it cannot drift from resolveProviderKey above.
+    throw Object.assign(new Error(`${providers.envKey(provider)} not configured`), { status: 500 });
   }
-  if (!(await seams.resolveProviderKey(scope, 'openai'))) {
-    throw Object.assign(new Error('OPENAI_API_KEY not configured'), { status: 500 });
+  return mod.chat(await getProviderClient(scope, provider), payload, options);
+}
+
+// Step 34 (cascade routing): per-provider confidence estimation. OpenAI's
+// path is pure (cascade.openaiLogprobConfidence over the logprobs the
+// dispatch asked for). Anthropic has no native logprobs, so its confidence
+// comes from a grader model - one bounded extra request to a small/cheap
+// model asking "does this response fully and confidently answer the
+// question? reply with a number 0-1" (Claude's recommendation over
+// self-consistency, which multiplies cost 2-3x on every cheap-tier dispatch
+// and works directly against cascade's own cheap-first reason to exist).
+//
+// The grader is opt-in (CASCADE_GRADER_MODEL): unset means Anthropic
+// candidates return null confidence - fail-open, no escalation, the same
+// "insufficient data must never escalate" discipline as everywhere else.
+// The grader's own provider call is recorded like any other real dispatch so
+// its cost is never invisible.
+function buildConfidenceEstimator(scope, payload, requestedModel, traceId) {
+  return async (result) => {
+    if (!result) return null;
+    if (result.provider === 'openai') return cascade.openaiLogprobConfidence(result);
+    if (result.provider === 'anthropic') return graderConfidence(scope, payload, requestedModel, result, traceId);
+    return null;
+  };
+}
+
+async function graderConfidence(scope, payload, requestedModel, result, traceId) {
+  const graderModel = process.env.CASCADE_GRADER_MODEL;
+  if (!graderModel) return null; // no grader configured -> no signal -> fail open
+  // Any chat-capable provider can grade (it is asked to reply with a number),
+  // so this asks the registry rather than hardcoding two names.
+  const graderProvider = providerForModel(graderModel);
+  if (!graderProvider) return null;
+  try {
+    const grade = await dispatchToProvider(scope, graderProvider, {
+      model: graderModel,
+      messages: cascade.buildGraderMessages(payload.messages, result.content),
+      temperature: 0,
+      max_tokens: 8 // the grader only needs to emit a single 0-1 number
+    });
+    metrics.record(scope, {
+      provider: grade.provider,
+      model: grade.model,
+      requested_model: requestedModel,
+      cache_hit: false,
+      quality_score: 1.0,
+      trace_id: traceId,
+      latency_ms: grade.latency_ms,
+      cost_usd: grade.cost_usd
+    });
+    return cascade.parseGraderScore(grade.content);
+  } catch (err) {
+    // A grader failure (missing key, provider down) must never fail the
+    // request being graded - treat it as "no confidence signal" and accept
+    // the candidate's answer (fail-open).
+    console.warn('⚠️ Cascade grader failed, accepting candidate without a confidence signal:', err.message);
+    return null;
   }
-  return openaiProvider.chat(await getOpenAiClient(scope), payload);
 }
 
 // The real streaming dispatch path: an actual cache miss, forwarded
@@ -499,18 +653,15 @@ async function dispatchToProvider(scope, provider, payload) {
 // about which model answered - a materially harder problem than the
 // non-streaming case, left as a documented gap rather than shipped
 // half-working (see ROADMAP.md).
-async function handleStreamingDispatch(req, res, payload, requestedModel, routingDecision) {
+async function handleStreamingDispatch(req, res, payload, requestedModel, routingDecision, traceId) {
   const scope = req.scope;
-  let providerName;
-  if (isModelAnthropic(payload.model)) {
-    providerName = 'anthropic';
-    if (!(await seams.resolveProviderKey(scope, 'anthropic'))) return res.status(500).json({ error: 'ANTHROPIC_API_KEY not configured' });
-  } else if (isModelOpenAi(payload.model)) {
-    providerName = 'openai';
-    if (!(await seams.resolveProviderKey(scope, 'openai'))) return res.status(500).json({ error: 'OPENAI_API_KEY not configured' });
-  } else {
+  const providerName = providerForModel(payload.model);
+  if (!providerName) {
     return res.status(400).json({ error: `Unsupported model: ${payload.model}` });
   }
+  if (!(await seams.resolveProviderKey(scope, providerName))) {
+    return res.status(500).json({ error: `${providers.envKey(providerName)} not configured` });
+  }
 
   streaming.startSse(res);
   const id = streaming.genId();
@@ -523,8 +674,8 @@ async function handleStreamingDispatch(req, res, payload, requestedModel, routin
 
   let result;
   try {
-    const client = providerName === 'anthropic' ? await getAnthropicClient(scope) : await getOpenAiClient(scope);
-    const chatStreamFn = providerName === 'anthropic' ? anthropicProvider.chatStream : openaiProvider.chatStream;
+    const client = await getProviderClient(scope, providerName);
+    const chatStreamFn = providers.get(providerName).chatStream;
     result = await chatStreamFn(client, payload, {
       signal: controller.signal,
       onDelta: (text) => res.write(streaming.deltaChunk({ id, model: payload.model, content: text }))
@@ -543,6 +694,8 @@ async function handleStreamingDispatch(req, res, payload, requestedModel, routin
       model: payload.model,
       requested_model: requestedModel,
       cache_hit: false,
+      quality_score: 0.0,
+      trace_id: traceId,
       error: err.message,
       error_type: metrics.classifyErrorType(err.message)
     });
@@ -568,12 +721,30 @@ async function handleStreamingDispatch(req, res, payload, requestedModel, routin
     model: result.model,
     requested_model: requestedModel,
     cache_hit: false,
+    quality_score: 1.0,
+    trace_id: traceId,
     latency_ms: result.latency_ms,
     cost_usd: result.cost_usd
   });
 }
 
+// The one request-scoped correlation id (step 36.1): generated once per
+// incoming request, returned as X-Cachegate-Trace-Id, and threaded through
+// every metrics.record() this request makes - so a support conversation or a
+// customer's own log line can reference the exact id that ties together every
+// metrics row (cache hit, each dispatch attempt, a cascade's cheap+escalated
+// pair, a coalesced joiner+leader pair) this request produced. Same generator
+// family as streaming.genId() (crypto.randomBytes hex), no second scheme.
 app.post('/v1/chat/completions', async (req, res) => {
+  const traceId = crypto.randomBytes(16).toString('hex');
+  res.setHeader('X-Cachegate-Trace-Id', traceId);
+  const modelName = (req.body && req.body.model) || 'chat.completion';
+  await tracing.withRootSpan(modelName, { trace_id: traceId }, () =>
+    handleCompletion(req, res, traceId)
+  );
+});
+
+async function handleCompletion(req, res, traceId) {
   const payload = req.body;
   const scope = req.scope; // set by requireInternalKey/seams.authenticate - null unless configured
 
@@ -620,13 +791,51 @@ app.post('/v1/chat/completions', async (req, res) => {
     payload.model = routingDecision.model;
   }
 
+  // Step 25 (joint wiring): PII redaction + injection policy run BEFORE
+  // the cache lookup, so redacted content is what gets cached (never raw
+  // PII) and a blocked request never reaches a provider or a cache write.
+  // Both modules are gated off by default, so this is a no-op unless the
+  // deployment opts in.
+  if (pii.isEnabled()) {
+    payload.messages = redactMessages(payload.messages);
+  }
+  const policy = guardrails.evaluate(payload.messages);
+  if (policy.decision === 'block') {
+    return res.status(403).json({ error: 'Request blocked by content policy.' });
+  }
+  if (policy.decision !== 'allow') {
+    // flag/log: pass through but record the detection. Console for now - a
+    // dedicated metric column is a possible follow-up (same as the
+    // coalesced column step 24 added).
+    console.warn(`[guardrails] ${policy.decision}: ${policy.reasons.join(', ')}`);
+  }
+
   // 1. Try the exact-match cache first - free, zero-risk, checked
   // before anything else (keyed on the resolved concrete model, so a
   // routed request and a direct request for the same concrete model
   // share the same cache entries). A hit is served the same way
   // whether or not the caller asked for stream:true - see
   // streamCachedReplay() for the streaming case.
-  const cached = await cache.get(scope, payload);
+  const cached = await tracing.withSpan('cache.exact', { trace_id: traceId }, () => cache.get(scope, payload));
+
+  // R4 (review 2026-09-10): the measurement that decides whether URL/email literal slotting earns its
+  // keep. One line per request carrying (a) whether the exact cache hit and (b) which slotting rules
+  // fired, so a week of logs splits hit rate by slotting instead of arguing about it. slottingFlags
+  // also reports the GATED rules (date, number), which is what makes the number/date decision priceable
+  // without turning it on - that gate stays off.
+  //
+  // Only this path: slotting lives in the exact-cache key. The semantic path embeds the raw prompt, so
+  // slotting does not touch it and a line there would measure nothing.
+  //
+  // Honest limit, stated here rather than discovered later: this is the hit rate AMONG requests that
+  // slot, not the rate they would have had WITHOUT slotting. The true counterfactual needs a second
+  // lookup per request, which is a behaviour change - and this measurement is not allowed to change the
+  // thing it measures.
+  if (process.env.CACHE_SLOT_STATS !== '0') {
+    const sf = cache.slottingFlags(payload.messages);
+    console.log(`[cacheslot] hit=${cached ? 1 : 0} model=${payload.model} url=${sf.url} email=${sf.email} date=${sf.date} number=${sf.number} numbers_gate=${sf.numbers_gate}`);
+  }
+
   if (cached) {
     metrics.record(scope, {
       provider: cached.provider,
@@ -634,6 +843,7 @@ app.post('/v1/chat/completions', async (req, res) => {
       requested_model: requestedModel,
       cache_hit: true,
       cache_type: 'exact',
+      trace_id: traceId,
       latency_ms: 0,
       cost_usd: 0
     });
@@ -661,7 +871,7 @@ app.post('/v1/chat/completions', async (req, res) => {
   // prompt, not an identical one). This costs one embedding call
   // whether or not it finds anything; see semanticCache.js for why
   // that's a deliberate tradeoff, not overhead to optimize away.
-  const semanticMatch = await semanticCache.findMatch(scope, payload);
+  const semanticMatch = await tracing.withSpan('cache.semantic', { trace_id: traceId }, () => semanticCache.findMatch(scope, payload));
   if (semanticMatch) {
     const hit = semanticMatch.entry;
     metrics.record(scope, {
@@ -671,6 +881,7 @@ app.post('/v1/chat/completions', async (req, res) => {
       cache_hit: true,
       cache_type: 'semantic',
       semantic_similarity: semanticMatch.similarity,
+      trace_id: traceId,
       latency_ms: 0,
       cost_usd: 0
     });
@@ -701,76 +912,220 @@ app.post('/v1/chat/completions', async (req, res) => {
   // so the two need different error-reporting strategies (see
   // handleStreamingDispatch's error frame vs. this path's 502 JSON).
   if (wantsStream) {
-    return handleStreamingDispatch(req, res, payload, requestedModel, routingDecision);
+    return handleStreamingDispatch(req, res, payload, requestedModel, routingDecision, traceId);
   }
 
   try {
-    let result;
-    let failedOver = false;
-
-    if (routingDecision) {
-      // Virtual model: try the ranked candidates in order (router.js's
-      // own health/strategy scoring already produced this order),
-      // falling over to the next one when a provider fails in a way
-      // that isn't the REQUEST's own fault - see
-      // failover.isRetryableError for exactly what that means. Every
-      // failed attempt is recorded on the dashboard the same way a
-      // non-failed-over error would be (below), so failover keeps the
-      // request succeeding without hiding the underlying provider
-      // problem from the Provider alerts table.
-      const attempt = await failover.dispatchWithFailover(
-        routingDecision.rankedCandidates,
-        (candidate) => dispatchToProvider(scope, candidate.provider, { ...payload, model: candidate.model }),
-        (candidate, err) => metrics.record(scope, {
-          provider: candidate.provider,
-          model: candidate.model,
+    // 2.5. Request coalescing (step 24): identical concurrent cache-miss
+    // requests share ONE upstream dispatch (single-flight). Keyed on the
+    // exact cache key, so only byte-identical requests coalesce. The
+    // callback below is the leader's dispatch - provider call, cache
+    // writes, and the leader's cache-miss metric - and a joiner awaits
+    // that same promise instead of dispatching again.
+    // The coalescing span carries a leader/joiner role attribute so a trace
+    // visibly distinguishes the request that actually dispatched (leader)
+    // from the ones that shared its upstream call (joiners). The role is only
+    // known after joinOrRun settles, so the attribute is set before end().
+    const coalesceSpan = tracing.startSpan('coalescing', { trace_id: traceId });
+    let joined;
+    try {
+      joined = await coalescing.joinOrRun(
+        cache.buildCacheKey(scope, payload),
+        async () => {
+        let result;
+        let failedOver = false;
+        let cascaded = false;
+
+        if (routingDecision) {
+          // Virtual model: try the ranked candidates in order (router.js's
+          // own health/strategy scoring already produced this order),
+          // falling over to the next one when a provider fails in a way
+          // that isn't the REQUEST's own fault - see
+          // failover.isRetryableError for exactly what that means. Every
+          // failed attempt is recorded on the dashboard the same way a
+          // non-failed-over error would be (below), so failover keeps the
+          // request succeeding without hiding the underlying provider
+          // problem from the Provider alerts table.
+          //
+          // Step 34 (cascade routing): when CASCADE_ENABLED, the same walk
+          // ALSO escalates on a successful-but-low-confidence response -
+          // orthogonal to failover (which retries on ERROR). The default
+          // (cascade off) stays on failover.dispatchWithFailover, byte-
+          // identical to before cascade existed.
+          const onAttemptFailed = (candidate, err) => metrics.record(scope, {
+            provider: candidate.provider,
+            model: candidate.model,
+            requested_model: requestedModel,
+            cache_hit: false,
+            quality_score: 0.0,
+            trace_id: traceId,
+            error: err.message,
+            error_type: metrics.classifyErrorType(err.message)
+          });
+
+          // Each provider dispatch attempt - a failover retry or a cascade
+          // escalation - is its own child span, not folded into one, so a
+          // trace visibly shows "escalate to a bigger model" as a distinct
+          // step, not just `cascaded: true` after the fact.
+          const dispatchAttempt = (candidate) => tracing.withSpan(
+            'dispatch',
+            { provider: candidate.provider, model: candidate.model, trace_id: traceId },
+            () => dispatchToProvider(
+              scope,
+              candidate.provider,
+              { ...payload, model: candidate.model },
+              { requestLogprobs: cascade.isEnabled() && candidate.provider === 'openai' }
+            )
+          );
+
+          let attempt;
+          if (cascade.isEnabled()) {
+            attempt = await cascade.tryWithCascade(
+              routingDecision.rankedCandidates,
+              dispatchAttempt,
+              buildConfidenceEstimator(scope, payload, requestedModel, traceId),
+              {
+                threshold: cascade.threshold(),
+                onAttemptFailed,
+                onEscalated: (fromCandidate, toCandidate, cheapResult) => {
+                  // The cheap answer is rejected (that's cascade's point),
+                  // but its dispatch was a real provider call with real cost
+                  // - record it so the spend is never invisible. It is NOT
+                  // marked `cascaded`: that flag belongs to the dispatch we
+                  // escalated TO (the final record below).
+                  //
+                  // quality_score is ALWAYS 0.5 here, never 1.0 - caught in
+                  // review: the original version scored it 1.0 whenever no
+                  // earlier candidate had failed over, meaning a candidate
+                  // whose answer was just rejected for low confidence still
+                  // got a PERFECT quality score. That directly corrupts the
+                  // exact signal Step 33's shed logic depends on: a provider
+                  // that's frequently escalated past due to low confidence
+                  // would show a misleadingly perfect avgQualityScore instead
+                  // of the "this one needs a second look" signal it should.
+                  // A low-confidence rejection alone already disqualifies a
+                  // perfect score, regardless of whether failover ALSO
+                  // happened earlier in the same walk.
+                  metrics.record(scope, {
+                    provider: cheapResult.provider,
+                    model: cheapResult.model,
+                    requested_model: requestedModel,
+                    cache_hit: false,
+                    quality_score: 0.5,
+                    trace_id: traceId,
+                    latency_ms: cheapResult.latency_ms,
+                    cost_usd: cheapResult.cost_usd
+                  });
+                  console.warn(`⚠️ Model router cascade: ${fromCandidate.provider}/${fromCandidate.model} answered with low confidence, escalating to ${toCandidate.provider}/${toCandidate.model}`);
+                }
+              }
+            );
+            cascaded = attempt.cascaded;
+          } else {
+            attempt = await failover.dispatchWithFailover(
+              routingDecision.rankedCandidates,
+              dispatchAttempt,
+              onAttemptFailed
+            );
+          }
+          result = attempt.result;
+          failedOver = attempt.failedOver !== undefined ? attempt.failedOver : attempt.attempts > 1;
+          payload.model = result.model; // the candidate that actually served it, if failover/cascade moved past the first choice
+          if (failedOver) {
+            console.warn(`⚠️ Model router failover: ${routingDecision.provider}/${routingDecision.model} unavailable, served by ${attempt.candidate.provider}/${attempt.candidate.model} instead (attempt ${attempt.attempts}/${routingDecision.rankedCandidates.length})`);
+          }
+        } else if (providerForModel(payload.model)) {
+          const directProvider = providerForModel(payload.model);
+          if (!(await seams.resolveProviderKey(scope, directProvider))) {
+            throw httpError(500, `${providers.envKey(directProvider)} not configured`, { skipMetric: true });
+          }
+          result = await providers.get(directProvider)
+            .chat(await getProviderClient(scope, directProvider), payload, {
+              requestLogprobs: cascade.isEnabled() && directProvider === 'openai'
+            });
+        } else {
+          throw httpError(400, `Unsupported model: ${payload.model}`, { skipMetric: true });
+        }
+
+        // Store in both caches - exact-match for identical future
+        // requests, semantic for near-duplicate ones. Both no-op quietly if
+        // their prerequisites (Redis / OPENAI_API_KEY) aren't configured.
+        // Cascade (step 34): only the response that PASSES confidence gets
+        // cached. A rejected low-confidence answer was already escalated
+        // away inside tryWithCascade, so `result` here is always the final
+        // accepted response - never the cheap one we threw away.
+        await cache.set(scope, payload, result);
+        await semanticCache.store(scope, payload, result);
+
+        metrics.record(scope, {
+          provider: result.provider,
+          model: result.model,
           requested_model: requestedModel,
           cache_hit: false,
-          error: err.message,
-          error_type: metrics.classifyErrorType(err.message)
-        })
+          quality_score: failedOver ? 0.5 : 1.0,
+          ...(cascaded ? { cascaded: true } : {}),
+          trace_id: traceId,
+          latency_ms: result.latency_ms,
+          cost_usd: result.cost_usd
+        });
+
+        return { result, failedOver, cascaded };
+        },
+        traceId
       );
-      result = attempt.result;
-      failedOver = attempt.attempts > 1;
-      payload.model = result.model; // the candidate that actually served it, if failover moved past the first choice
-      if (failedOver) {
-        console.warn(`⚠️ Model router failover: ${routingDecision.provider}/${routingDecision.model} unavailable, served by ${attempt.candidate.provider}/${attempt.candidate.model} instead (attempt ${attempt.attempts}/${routingDecision.rankedCandidates.length})`);
-      }
-    } else if (isModelAnthropic(payload.model)) {
-      if (!(await seams.resolveProviderKey(scope, 'anthropic'))) {
-        return res.status(500).json({ error: 'ANTHROPIC_API_KEY not configured' });
-      }
-      result = await anthropicProvider.chat(await getAnthropicClient(scope), payload);
-    } else if (isModelOpenAi(payload.model)) {
-      if (!(await seams.resolveProviderKey(scope, 'openai'))) {
-        return res.status(500).json({ error: 'OPENAI_API_KEY not configured' });
+    } finally {
+      if (joined) {
+        coalesceSpan.setAttribute('coalescing.role', joined.coalesced ? 'joiner' : 'leader');
+        if (joined.coalesced && joined.joinedTraceId) {
+          coalesceSpan.setAttribute('coalescing.joined_trace_id', joined.joinedTraceId);
+        }
       }
-      result = await openaiProvider.chat(await getOpenAiClient(scope), payload);
-    } else {
-      return res.status(400).json({ error: `Unsupported model: ${payload.model}` });
+      coalesceSpan.end();
     }
 
-    // Store in both caches - exact-match for identical future
-    // requests, semantic for near-duplicate ones. Both no-op quietly if
-    // their prerequisites (Redis / OPENAI_API_KEY) aren't configured.
-    await cache.set(scope, payload, result);
-    await semanticCache.store(scope, payload, result);
+    const { result: dispatchOutcome, coalesced: wasCoalesced, joinedTraceId } = joined;
+    const { result, failedOver, cascaded } = dispatchOutcome;
 
-    metrics.record(scope, {
-      provider: result.provider,
-      model: result.model,
-      requested_model: requestedModel,
-      cache_hit: false,
-      latency_ms: result.latency_ms,
-      cost_usd: result.cost_usd
-    });
+    if (wasCoalesced) {
+      // Joiner: shared the leader's upstream call - record it distinctly
+      // (coalesced: true, zero NEW cost) so coalescing is measurable, not
+      // just asserted. The leader's record above is the single source of
+      // cost for the one upstream call that actually happened.
+      //
+      // quality_score is INHERITED from the leader (failedOver came back
+      // on the same shared dispatchOutcome), not omitted like a cache hit
+      // - a joiner isn't "no independent dispatch happened" in the same
+      // sense a cache hit is; it received the exact same result as the
+      // leader, over the exact same failedOver-or-not path, so its
+      // quality signal is identical, not absent. Omitting it would
+      // systematically under-sample avgQualityScore precisely for the
+      // busiest, most-coalesced request shapes - the opposite of what a
+      // signal meant to feed future routing decisions should do. `cascaded`
+      // inherits for the exact same reason: a joiner received the
+      // escalated result, so it must be visible as escalated too.
+      metrics.record(scope, {
+        provider: result.provider,
+        model: result.model,
+        requested_model: requestedModel,
+        cache_hit: false,
+        coalesced: true,
+        quality_score: failedOver ? 0.5 : 1.0,
+        ...(cascaded ? { cascaded: true } : {}),
+        trace_id: traceId,
+        ...(joinedTraceId ? { joined_trace_id: joinedTraceId } : {}),
+        latency_ms: result.latency_ms,
+        cost_usd: 0
+      });
+    }
 
     res.json({
       cached: false,
+      coalesced: wasCoalesced ? true : undefined,
       provider: result.provider,
       model: result.model,
       routed_from: routingDecision ? requestedModel : undefined,
       failover: failedOver ? true : undefined,
+      cascaded: cascaded ? true : undefined,
       latency_ms: result.latency_ms,
       usage: result.usage,
       cost_usd: result.cost_usd,
@@ -784,23 +1139,44 @@ app.post('/v1/chat/completions', async (req, res) => {
     });
   } catch (err) {
     console.error('❌ Model router error:', err.message);
-    if (!routingDecision) {
+    if (!routingDecision && !err.skipMetric) {
       // Virtual-model attempts already record one metrics entry PER
       // candidate as each fails (see the onAttemptFailed callback
       // above), including whichever one was last - recording again
-      // here would double-count it.
+      // here would double-count it. skipMetric is the OTHER exclusion:
+      // a pre-dispatch validation failure (missing key, unsupported
+      // model - see httpError()'s own comment) never reached a
+      // provider at all, so recording it here would be new behavior,
+      // not a restoration - the original inline `return res.status(...)`
+      // code never touched metrics for these either.
       metrics.record(scope, {
-        provider: isModelAnthropic(payload.model) ? 'anthropic' : 'openai',
+        // `|| 'openai'` keeps the pre-registry fallback for a model nothing
+        // claims, so this metric row is not a behavior change.
+        provider: providerForModel(payload.model) || 'openai',
         model: payload.model,
         requested_model: requestedModel,
         cache_hit: false,
+        quality_score: 0.0,
+        trace_id: traceId,
         error: err.message,
         error_type: metrics.classifyErrorType(err.message)
       });
     }
-    res.status(502).json({ error: err.message });
+    // err.status is only honored on the explicit-model path (where it
+    // can ONLY come from this file's own httpError() calls above - a
+    // deliberate 500/400 for a config/validation failure). The virtual-
+    // model/failover path always falls back to 502 regardless of
+    // err.status: dispatchToProvider() sets .status=500 on ITS OWN
+    // thrown errors too, but only for failover.isRetryableError()'s
+    // internal retry decision - that was never meant to reach the
+    // client as the final status once every candidate is exhausted
+    // (see the dedicated test for this exact contract: exhausted
+    // failover -> 502, always, whatever the last candidate's own
+    // error looked like).
+    const status = !routingDecision && err.status ? err.status : 502;
+    res.status(status).json({ error: err.message });
   }
-});
+}
 
 // Step 14 (ROADMAP.md): metrics.pruneOlderThan() has existed since the
 // day metrics.js was written, but nothing ever actually CALLED it - the
@@ -873,4 +1249,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { app, isAuthConfigured, resolveEnvPathFromArgv, configure };
+module.exports = { app, isAuthConfigured, resolveEnvPathFromArgv, resolveTrustProxy, configure };