cachegate 1.3.1 → 1.4.0

package/cascade.js

@@ -0,0 +1,206 @@
+// model-router/cascade.js
+//
+// Cascade routing (roadmap Phase 2 step 34): for a `router:` virtual model,
+// dispatch to the tier's top-ranked candidate (router.js already produced
+// that order), estimate how confident that response is, and if it's below a
+// threshold, escalate to the NEXT-ranked candidate instead of accepting the
+// cheap answer. This is orthogonal to failover.js's error-driven retry: a
+// cheap candidate could fail outright (failover retries on error) or succeed
+// unconfidently (cascade escalates on low confidence); both can apply to the
+// same request.
+//
+// Gated off by default (CASCADE_ENABLED). Like every speculative feature in
+// this codebase (step 22's local embeddings, step 25's guardrails), it ships
+// inert and only activates when a deployment explicitly opts in.
+//
+// Confidence is per-provider, and there is no single obviously-right answer
+// for every provider:
+//   - OpenAI: native logprobs. The request asks for logprobs only when
+//     cascade is active for that dispatch (see providers/openai.js); the
+//     response's per-token natural log-probabilities are reduced to one
+//     number via the geometric mean, exp(mean(logprobs)) - a defensible
+//     [0,1] figure, not an invented score.
+//   - Anthropic: no logprobs. Confidence comes from a grader model (one
+//     bounded extra request, not the 2-3x cost multiplier self-consistency
+//     would impose) - the caller supplies that as an injected async
+//     estimator, because a grader is a real provider call and therefore
+//     lives where provider calls live (server.js), not in this pure module.
+//     This module owns only the pure, testable halves of the grader: the
+//     prompt builder and the numeric-score parser.
+//
+// Pure control flow, mirroring coalescing.js's factoring: no provider
+// clients, no network, no metrics store. Directly unit-testable with fake
+// dispatch and confidence functions.
+
+const failover = require('./failover');
+
+// Gated off by default - cascade is genuinely more speculative than health
+// scoring (grading one LLM's confidence in another LLM is inherently fuzzy),
+// so it must prove itself before ever defaulting on.
+const CASCADE_ENABLED = process.env.CASCADE_ENABLED === 'true';
+
+// The confidence floor below which a successful response is escalated to the
+// next-ranked candidate instead of accepted. Env-tunable; the default is a
+// deliberately ordinary starting point, not a claim about any specific
+// provider/model's real confidence distribution.
+const CASCADE_CONFIDENCE_THRESHOLD = Number(process.env.CASCADE_CONFIDENCE_THRESHOLD) || 0.5;
+
+function isEnabled() {
+  return CASCADE_ENABLED;
+}
+
+function threshold() {
+  return CASCADE_CONFIDENCE_THRESHOLD;
+}
+
+/**
+ * Confidence from an OpenAI response's native logprobs: the geometric mean of
+ * per-token probabilities, exp(mean(logprobs)) - a number in [0,1]. `result`
+ * is the shape providers/openai.js returns; its `raw` field is the full SDK
+ * response, whose `choices[0].logprobs.content[]` carries
+ * `{token, logprob, bytes, top_logprobs}` when the request asked for
+ * logprobs (providers/openai.js only asks when cascade is active for the
+ * dispatch).
+ *
+ * Returns null when there is no logprobs data (the request didn't ask, or
+ * the provider didn't return any) - a missing confidence signal must never
+ * be treated as low confidence (fail-open), the same discipline router.js's
+ * "insufficient data must never shed" holds to.
+ */
+function openaiLogprobConfidence(result) {
+  const content = result && result.raw && result.raw.choices
+    && result.raw.choices[0] && result.raw.choices[0].logprobs
+    && result.raw.choices[0].logprobs.content;
+  if (!Array.isArray(content) || content.length === 0) return null;
+  const logprobs = content
+    .map((entry) => (entry && typeof entry.logprob === 'number' ? entry.logprob : null))
+    .filter((v) => v !== null && Number.isFinite(v));
+  if (logprobs.length === 0) return null;
+  const mean = logprobs.reduce((sum, v) => sum + v, 0) / logprobs.length;
+  return Math.exp(mean);
+}
+
+/**
+ * Parse a grader model's reply into a [0,1] confidence number, or null. The
+ * grader is prompted to reply with only a number; this tolerates surrounding
+ * prose/whitespace but never invents a score it can't read (null, not a
+ * guess, when there's no numeric token).
+ */
+function parseGraderScore(text) {
+  if (typeof text !== 'string') return null;
+  const match = text.match(/[+-]?(?:\d+\.?\d*|\.\d+)/);
+  if (!match) return null;
+  const value = Number(match[0]);
+  if (!Number.isFinite(value)) return null;
+  return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * Build the grader prompt messages: the original question plus the candidate
+ * response, asking for a single 0-1 number. `questionMessages` is the
+ * request's own messages (the question); `responseContent` is what the
+ * candidate answered.
+ */
+function buildGraderMessages(questionMessages, responseContent) {
+  const question = questionMessages
+    .map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
+    .join('\n');
+  return [{
+    role: 'user',
+    content: [
+      'Question:',
+      question,
+      '',
+      'Response:',
+      String(responseContent == null ? '' : responseContent),
+      '',
+      'Does this response fully and confidently answer the question? Reply with only a number between 0 and 1 (0 = not at all, 1 = fully and confidently).'
+    ].join('\n')
+  }];
+}
+
+/**
+ * Cascade orchestration for a virtual model's ranked candidates when cascade
+ * is active: walks the list once, failing over on ERROR and escalating on LOW
+ * CONFIDENCE. Reuses failover.isRetryableError so the "is this error worth
+ * retrying" decision has exactly one source of truth (failover.js); the walk
+ * itself is re-derived here only because cascade adds a second reason to move
+ * to the next candidate that failover.dispatchWithFailover doesn't know
+ * about. failover.dispatchWithFailover remains the path when cascade is
+ * disabled - the default is byte-identical to before this module existed.
+ *
+ * @param {Array<{provider: string, model: string}>} candidates ranked order
+ *   (router.js's pickCandidate().rankedCandidates)
+ * @param {(candidate) => Promise<any>} dispatch one candidate's provider call
+ * @param {(result) => Promise<number|null>} estimateConfidence per-result
+ *   confidence; null means "no signal" and is treated as CONFIDENT (fail-open)
+ * @param {object} [options]
+ * @param {number} [options.threshold] confidence floor for escalation
+ * @param {(candidate, err, isLastCandidate) => void} [options.onAttemptFailed]
+ *   error metric hook (same contract as failover.dispatchWithFailover's)
+ * @param {(fromCandidate, toCandidate, cheapResult, failedOver) => void} [options.onEscalated]
+ *   hook fired when a low-confidence success is escalated away (the cheap
+ *   result's cost is the caller's to record here; it is deliberately NOT
+ *   returned - rejecting it is the whole point of cascade). `failedOver` is
+ *   true when an earlier candidate in this same walk already errored -
+ *   informational only; the escalated-away candidate's OWN quality_score
+ *   should always be recorded as non-perfect (e.g. 0.5) regardless of
+ *   `failedOver`'s value, since a low-confidence rejection alone already
+ *   disqualifies it from a perfect score - `failedOver` being false doesn't
+ *   make a rejected answer any better.
+ * @returns {Promise<{result, candidate, attempts, cascaded, failedOver}>}
+ */
+async function tryWithCascade(candidates, dispatch, estimateConfidence, options = {}) {
+  const {
+    threshold: confidenceThreshold = threshold(),
+    onAttemptFailed,
+    onEscalated
+  } = options;
+
+  let lastErr;
+  let failedOver = false;
+  let cascaded = false;
+
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const isLastCandidate = i === candidates.length - 1;
+    let result;
+    try {
+      result = await dispatch(candidate);
+    } catch (err) {
+      lastErr = err;
+      failedOver = true;
+      if (onAttemptFailed) onAttemptFailed(candidate, err, isLastCandidate);
+      if (!failover.isRetryableError(err) || isLastCandidate) throw err;
+      continue; // failover: try the next candidate
+    }
+
+    // Skip confidence estimation entirely on the last candidate: its result
+    // could never change the outcome (there's nowhere left to escalate TO),
+    // so paying for it would be pure waste - and for Anthropic candidates,
+    // that "cost" is a real grader-model API call plus the latency of
+    // waiting on it, not a free computation like OpenAI's logprobs.
+    const confidence = isLastCandidate ? null : await estimateConfidence(result);
+    if (typeof confidence === 'number' && confidence < confidenceThreshold && !isLastCandidate) {
+      // Low confidence, and a next candidate exists: escalate rather than
+      // accept the cheap answer.
+      if (onEscalated) onEscalated(candidate, candidates[i + 1], result, failedOver);
+      cascaded = true;
+      continue;
+    }
+    return { result, candidate, attempts: i + 1, cascaded, failedOver };
+  }
+
+  // Unreachable when candidates.length > 0 (the loop either returns or
+  // throws); kept honest for an empty list, mirroring failover.js.
+  throw lastErr;
+}
+
+module.exports = {
+  isEnabled,
+  threshold,
+  openaiLogprobConfidence,
+  parseGraderScore,
+  buildGraderMessages,
+  tryWithCascade
+};

package/coalescing.js

@@ -0,0 +1,65 @@
+// model-router/coalescing.js
+//
+// Request coalescing (single-flight, roadmap step 24): N identical
+// concurrent cache-MISS requests share ONE upstream dispatch instead of N.
+// Keyed by the exact cache key (cache.buildCacheKey), so only byte-
+// identical requests coalesce - near-duplicates are the semantic cache's
+// job, not this. A leader creates + stores the dispatch promise BEFORE
+// awaiting it, so a second caller arriving mid-flight finds it; joiners
+// await that same promise. The map entry self-removes when it settles.
+
+const MAX_INFLIGHT = Number(process.env.COALESCE_MAX_INFLIGHT) || 500;
+const WAIT_TIMEOUT_MS = Number(process.env.COALESCE_WAIT_TIMEOUT_MS) || 3000;
+
+const inFlight = new Map(); // cacheKey -> { promise, traceId }
+
+// Returns { result, coalesced, joinedTraceId? }. coalesced:true means this
+// caller joined an existing in-flight dispatch (and should record a
+// `coalesced` metric, zero NEW cost); coalesced:false means this caller was
+// the leader, or dispatched independently after a join-timeout / capacity
+// skip. `traceId` is this caller's own request trace id (stored when this
+// caller becomes the leader); `joinedTraceId` is returned to a joiner only,
+// pointing at the leader's trace id, so a joiner's metrics row can record
+// both "who I am" (its own trace_id) and "whose dispatch I shared"
+// (joined_trace_id) - the joiner never stopped being its own request.
+async function joinOrRun(key, dispatch, traceId) {
+  const existing = inFlight.get(key);
+
+  if (existing) {
+    // Joiner: await the leader, but only for a bounded wait. If the leader
+    // hangs past WAIT_TIMEOUT_MS, fail OPEN (dispatch independently) rather
+    // than hang forever on someone else's stuck request. A leader that
+    // REJECTS before the timeout propagates that rejection to the joiner
+    // (Promise.race settles with the first settled promise), so a joiner
+    // never gets a false success.
+    const outcome = await Promise.race([
+      existing.promise.then((result) => ({ result, coalesced: true, joinedTraceId: existing.traceId })),
+      new Promise((resolve) => setTimeout(() => resolve(undefined), WAIT_TIMEOUT_MS))
+    ]);
+    if (outcome !== undefined) return outcome;
+    // timed out -> fall through to an independent dispatch below
+  } else if (inFlight.size < MAX_INFLIGHT) {
+    // Leader (and only while there's room): create + store the promise
+    // BEFORE awaiting it, so the next caller finds it. Self-removes on
+    // settle, success or failure.
+    const promise = dispatch();
+    inFlight.set(key, { promise, traceId });
+    try {
+      const result = await promise;
+      return { result, coalesced: false };
+    } finally {
+      // Remove only if it is still OUR entry (a timed-out joiner that
+      // dispatched independently never stored its own, so this guard is
+      // defensive against any future change that does).
+      if (inFlight.get(key) && inFlight.get(key).promise === promise) inFlight.delete(key);
+    }
+  }
+
+  // Timed-out joiner, or map at capacity: dispatch independently, no map
+  // entry (skip coalescing). The capacity path is a defensive cap against a
+  // pathological high-cardinality burst, not a real-world leak (entries
+  // already self-remove on settle).
+  return { result: await dispatch(), coalesced: false };
+}
+
+module.exports = { joinOrRun };

package/embeddings.js

@@ -1,22 +1,67 @@
 // model-router/embeddings.js
 //
-// The only embedding backend right now is OpenAI's - which means
-// semantic caching needs an OPENAI_API_KEY configured even for a
-// deployment that only ever talks to Anthropic for chat. That's a real
-// constraint, not hidden: isEnabled() is what semanticCache.js checks
-// before doing anything, and it degrades to "disabled" (not an error)
-// when the key isn't set, same as the Redis cache does when REDIS_URL
-// isn't set.
+// Two embedding backends, selected by SEMANTIC_CACHE_LOCAL_EMBEDDINGS
+// (default OFF, roadmap step 22.4):
+//
+// - OpenAI (default): text-embedding-3-small, 1536-dim, needs
+//   OPENAI_API_KEY. The pre-existing behavior, unchanged - which means
+//   a deployment that only chats with Anthropic still needs an OpenAI key
+//   for semantic caching, exactly as before.
+// - Local (opt-in): all-MiniLM-L6-v2 via @huggingface/transformers, 384-dim,
+//   pure JS/WASM - no native build, no API key, fully self-hosted. The
+//   model is downloaded and cached by transformers.js on FIRST use, so the
+//   first local embed() is slow; later calls are in-process.
+//
+// OPERATIONAL NOTE (not silent): flipping this flag on a deployment with
+// an existing semantic cache orphans every previously-stored entry -
+// semanticCache.js's cosineSimilarity() returns 0 for a length mismatch
+// (its own guard) rather than throwing, so old 1536-dim entries simply
+// never match again and age out via MAX_CANDIDATES_PER_MODEL's cap / TTL.
+// Not a crash, but the cache warms up from zero again.
 
 const { OpenAI } = require('openai');
 
+const LOCAL_EMBEDDING_DIMENSIONS = 384; // all-MiniLM-L6-v2
+const OPENAI_EMBEDDING_DIMENSIONS = 1536; // text-embedding-3-small
+
 let client;
 function getClient() {
   if (!client) client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
   return client;
 }
 
+// The local pipeline is lazy: @huggingface/transformers is heavy (WASM +
+// model download on first use), so it must never load unless the flag is
+// on. @huggingface/transformers (v3, same pipeline() API) rather than the
+// frozen @xenova/transformers: the older package pins a vulnerable
+// protobufjs transitively (CVSS 9.8) that ships to every installer.
+let localPipeline;
+async function getLocalPipeline() {
+  if (!localPipeline) {
+    const { pipeline } = await import('@huggingface/transformers');
+    localPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+  }
+  return localPipeline;
+}
+
+function useLocal() {
+  return process.env.SEMANTIC_CACHE_LOCAL_EMBEDDINGS === 'true';
+}
+
+// Which backend is active, exposed so tests can pin "the flag actually
+// switches backends" without downloading a model.
+function activeBackend() {
+  return useLocal() ? 'local' : 'openai';
+}
+
+// Factored out of embed() so the timeout contract is directly testable
+// (kept for the OpenAI network path; the local path is in-process).
+function embedTimeoutMs() {
+  return Number(process.env.EMBEDDING_TIMEOUT_MS) || 5000;
+}
+
 function isEnabled() {
+  if (useLocal()) return true;
   return Boolean(process.env.OPENAI_API_KEY);
 }
 
@@ -24,19 +69,36 @@ async function embed(text) {
   if (!isEnabled()) {
     throw new Error('OPENAI_API_KEY not configured - embeddings unavailable');
   }
+
+  if (useLocal()) {
+    // Local path: no network on the hot path after first use, but the
+    // FIRST call loads (and possibly downloads) the model - the same
+    // try/catch in semanticCache.js that degrades OpenAI timeouts to
+    // "skip semantic caching" also covers a local-load failure.
+    const pipeline = await getLocalPipeline();
+    const output = await pipeline(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  }
+
+  // OpenAI path (unchanged): a hard timeout per embedding call. These run
+  // on the hot request path (semanticCache.js's findMatch/store, one or
+  // two per miss), so a hung embedding provider must not be able to stall
+  // every chat request. AbortSignal.timeout aborts the underlying fetch,
+  // and the thrown error is caught by semanticCache.js's own try/catch,
+  // which degrades to "skip semantic caching" rather than failing.
   const model = process.env.EMBEDDING_MODEL || 'text-embedding-3-small';
-  // A hard timeout per embedding call: these run on the hot request path
-  // (semanticCache.js's findMatch/store, one or two per miss), so a hung
-  // embedding provider must not be able to stall every chat request -
-  // including ones that never touch embeddings at all if the semantic
-  // cache is enabled. AbortSignal.timeout aborts the underlying fetch, and
-  // the thrown error is caught by semanticCache.js's own try/catch, which
-  // degrades to "skip semantic caching" rather than failing the request.
   const response = await getClient().embeddings.create(
     { model, input: text },
-    { signal: AbortSignal.timeout(Number(process.env.EMBEDDING_TIMEOUT_MS) || 5000) }
+    { signal: AbortSignal.timeout(embedTimeoutMs()) }
   );
   return response.data[0].embedding;
 }
 
-module.exports = { isEnabled, embed };
+module.exports = {
+  isEnabled,
+  embed,
+  embedTimeoutMs,
+  activeBackend,
+  LOCAL_EMBEDDING_DIMENSIONS,
+  OPENAI_EMBEDDING_DIMENSIONS
+};

package/guardrails.js

@@ -0,0 +1,80 @@
+// model-router/guardrails.js
+//
+// Prompt-injection detection + the policy-enforcement hook shape (roadmap
+// step 25, Track B). Heuristic, not a classifier: a small set of
+// high-signal patterns that catch the common injection shapes. Gated off
+// by default behind GUARDRAILS_ENABLED. Standalone for now - not wired
+// into server.js (the pre-dispatch wiring is the joint follow-up once
+// pii.js lands, same reason Track A is also standalone).
+//
+// Because these are heuristics (and therefore false-positive-prone), the
+// default action on a detection is `flag` (record + pass through), NOT
+// `block`. A deployment that wants to reject on a hit sets
+// GUARDRAILS_INJECTION_ACTION=block; the hook shape is what that decision
+// plugs into, so block/flag/log are all expressible without a code change.
+
+const INJECTION_PATTERNS = [
+  // Instruction-override: "ignore previous instructions", "disregard all
+  // prior rules", etc.
+  { id: 'ignore_previous_instructions', regex: /(?:ignore|disregard|forget|overwrite|override)\s+(?:all\s+)?(?:previous|prior|earlier|above|your)\s+(?:instructions?|rules?|prompts?)/i },
+  // System-prompt leak probes: "reveal your system prompt", "show me your
+  // instructions".
+  { id: 'system_prompt_leak', regex: /(?:reveal|show|print|display|repeat|output)\s+(?:me\s+)?(?:your|the)\s+(?:system\s+)?(?:prompt|instructions?|rules?|message|context)/i },
+  // Role-play jailbreak framing: "pretend you are", "act as", "roleplay as".
+  { id: 'roleplay_jailbreak', regex: /\b(?:pretend|act|roleplay|imagine|pose)\s+(?:you\s+are|as|to\s+be)\b/i },
+  // "developer mode" / "dev mode" jailbreak framing.
+  { id: 'developer_mode', regex: /\b(?:developer|dev)\s+mode\b/i },
+  // DAN / "do anything now".
+  { id: 'dan_jailbreak', regex: /\bDAN\b|\bdo\s+anything\s+now\b/i },
+  // "no restrictions", "bypass your filters", "remove your guardrails".
+  { id: 'no_restrictions', regex: /(?:no|without|bypass|ignore|remove)\s+(?:your\s+)?(?:restrictions?|limits?|limitations?|rules?|guardrails?|filters?)/i }
+];
+
+// Scans one piece of text and returns the ids of every matched pattern
+// (empty array = clean). Pure - no env, no I/O.
+function detectInjection(text) {
+  const hits = [];
+  for (const pattern of INJECTION_PATTERNS) {
+    if (pattern.regex.test(String(text))) hits.push(pattern.id);
+  }
+  return hits;
+}
+
+function extractPromptText(messages) {
+  if (!Array.isArray(messages)) return '';
+  return messages
+    .map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+    .join('\n');
+}
+
+function isEnabled() {
+  return process.env.GUARDRAILS_ENABLED === 'true';
+}
+
+// The policy-enforcement hook: evaluate a request's messages and return a
+// decision + reasons. `decision` is one of allow/block/flag/log. The
+// shape is deliberately minimal so pii.js's redaction and the future
+// server.js wiring can feed additional findings into the same decision
+// without reshaping this module.
+//
+// Gated on isEnabled() INSIDE evaluate() itself, not just left to the
+// caller to check - same "always callable, flag decides" contract as
+// pii.js's redact(). Without this, a future server.js call site that
+// forgot its own `if (guardrails.isEnabled())` guard would silently
+// flag/block on every request regardless of the deployment's own
+// GUARDRAILS_ENABLED setting - exactly the gap this module's own header
+// comment claims doesn't exist ("gated off by default").
+function evaluate(messages) {
+  if (!isEnabled()) {
+    return { decision: 'allow', reasons: [] };
+  }
+  const text = extractPromptText(messages);
+  const hits = detectInjection(text);
+  if (hits.length === 0) {
+    return { decision: 'allow', reasons: [] };
+  }
+  const action = process.env.GUARDRAILS_INJECTION_ACTION || 'flag'; // block | flag | log
+  return { decision: action, reasons: hits };
+}
+
+module.exports = { detectInjection, evaluate, isEnabled, INJECTION_PATTERNS };

package/metrics.js

@@ -105,6 +105,11 @@ async function ensureSchema() {
         error_type TEXT
       );
       ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS scope TEXT;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS coalesced BOOLEAN;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS quality_score REAL;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS cascaded BOOLEAN;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS trace_id TEXT;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS joined_trace_id TEXT;
       CREATE INDEX IF NOT EXISTS router_metrics_ts_idx ON router_metrics (ts DESC);
       CREATE INDEX IF NOT EXISTS router_metrics_provider_ts_idx ON router_metrics (provider, ts DESC);
       CREATE INDEX IF NOT EXISTS router_metrics_scope_ts_idx ON router_metrics (scope, ts DESC);
@@ -127,6 +132,11 @@ function rowFromPg(dbRow) {
     model: dbRow.model || undefined,
     requested_model: dbRow.requested_model || undefined,
     cache_hit: dbRow.cache_hit === null ? undefined : dbRow.cache_hit,
+    coalesced: dbRow.coalesced === null ? undefined : dbRow.coalesced,
+    cascaded: dbRow.cascaded === null ? undefined : dbRow.cascaded,
+    quality_score: dbRow.quality_score === null ? undefined : dbRow.quality_score,
+    trace_id: dbRow.trace_id || undefined,
+    joined_trace_id: dbRow.joined_trace_id || undefined,
     cache_type: dbRow.cache_type || undefined,
     latency_ms: dbRow.latency_ms === null ? undefined : dbRow.latency_ms,
     cost_usd: dbRow.cost_usd === null ? undefined : dbRow.cost_usd,
@@ -140,19 +150,24 @@ async function recordToPostgres(scope, entry) {
     await ensureSchema();
     await getPool().query(
       `INSERT INTO router_metrics
-         (scope, provider, model, requested_model, cache_hit, cache_type, latency_ms, cost_usd, error, error_type)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+         (scope, provider, model, requested_model, cache_hit, coalesced, cascaded, quality_score, cache_type, latency_ms, cost_usd, error, error_type, trace_id, joined_trace_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)`,
       [
         scope != null ? String(scope) : null,
         entry.provider ?? null,
         entry.model ?? null,
         entry.requested_model ?? null,
         entry.cache_hit ?? null,
+        entry.coalesced ?? null,
+        entry.cascaded ?? null,
+        entry.quality_score ?? null,
         entry.cache_type ?? null,
         entry.latency_ms ?? null,
         entry.cost_usd ?? null,
         entry.error ?? null,
-        entry.error_type ?? null
+        entry.error_type ?? null,
+        entry.trace_id ?? null,
+        entry.joined_trace_id ?? null
       ]
     );
   } catch (err) {
@@ -427,6 +442,13 @@ async function providerStats(scope, windowSize = 50) {
     const avgLatencyMs = latencies.length
       ? latencies.reduce((sum, e) => sum + e.latency_ms, 0) / latencies.length
       : null;
+    // Mean quality across entries that actually HAVE a quality_score
+    // (cache hits, coalesced joiners, and pre-this-change rows don't set
+    // one) - same null-tolerant pattern avgLatencyMs uses for latency.
+    const qualityScores = recent.filter((e) => typeof e.quality_score === 'number');
+    const avgQualityScore = qualityScores.length
+      ? qualityScores.reduce((sum, e) => sum + e.quality_score, 0) / qualityScores.length
+      : null;
     // The MOST RECENT error only, not a tally of every type seen in the
     // window - an alert should reflect "what's wrong right now," not a
     // mix that might include something already fixed earlier in the
@@ -439,6 +461,7 @@ async function providerStats(scope, windowSize = 50) {
       sampleSize: recent.length,
       errorRate: recent.length ? errorEntries.length / recent.length : 0,
       avgLatencyMs,
+      avgQualityScore,
       lastErrorType: lastError ? lastError.error_type || classifyErrorType(lastError.error) : null,
       lastErrorAt: lastError ? lastError.timestamp : null
     };
@@ -472,6 +495,61 @@ async function providerStats(scope, windowSize = 50) {
  * underlying log, two different questions - not accidentally
  * duplicated logic.
  */
+
+// Shared "$ saved" formula (mirrors cachegate-cloud's usage.mjs
+// estimatedSavings / estimatedSavingsGlobal, 2026-09-05 Phase 2 step 20):
+// for each model, the average cost of a cache-MISS (cache_hit === false,
+// no error) times that model's cache-HIT count, summed across models. A
+// model with hits but no recorded miss yet contributes 0 - never a
+// cross-model average (usage.mjs's own documented honesty floor). Rows
+// with no model are skipped. Pure (takes rows, returns { total, perDay })
+// so it's directly unit-testable and shared by rangeSummary() and
+// server.js's GET /stats without duplicating the formula.
+function computeSavings(rows) {
+  const all = new Map(); // model -> accumulator
+  const perDay = new Map(); // YYYY-MM-DD -> Map(model -> accumulator)
+  const accFor = (map, key) => {
+    let acc = map.get(key);
+    if (!acc) {
+      acc = { missCostSum: 0, missCount: 0, hits: 0 };
+      map.set(key, acc);
+    }
+    return acc;
+  };
+  for (const row of rows) {
+    if (!row.model) continue;
+    const acc = accFor(all, row.model);
+    const date = row.timestamp.slice(0, 10);
+    let dayMap = perDay.get(date);
+    if (!dayMap) {
+      dayMap = new Map();
+      perDay.set(date, dayMap);
+    }
+    const dayAcc = accFor(dayMap, row.model);
+    if (row.cache_hit === true) {
+      acc.hits += 1;
+      dayAcc.hits += 1;
+    } else if (row.cache_hit === false && !row.error) {
+      acc.missCostSum += row.cost_usd || 0;
+      acc.missCount += 1;
+      dayAcc.missCostSum += row.cost_usd || 0;
+      dayAcc.missCount += 1;
+    }
+  }
+  const sum = (map) => {
+    let total = 0;
+    for (const acc of map.values()) {
+      if (acc.hits > 0 && acc.missCount > 0) {
+        total += (acc.missCostSum / acc.missCount) * acc.hits;
+      }
+    }
+    return total;
+  };
+  const out = new Map();
+  for (const [date, map] of perDay) out.set(date, sum(map));
+  return { total: sum(all), perDay: out };
+}
+
 async function rangeSummary(scope, days = 14) {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
 
@@ -508,7 +586,7 @@ async function rangeSummary(scope, days = 14) {
   for (const row of inRange) {
     const date = row.timestamp.slice(0, 10); // YYYY-MM-DD (UTC, from toISOString())
     if (!dailyByDate.has(date)) {
-      dailyByDate.set(date, { date, requests: 0, cost_usd: 0, exact_hits: 0, semantic_hits: 0, misses: 0, errors: 0 });
+      dailyByDate.set(date, { date, requests: 0, cost_usd: 0, saved_usd: 0, exact_hits: 0, semantic_hits: 0, misses: 0, errors: 0 });
     }
     const bucket = dailyByDate.get(date);
     bucket.requests += 1;
@@ -541,6 +619,8 @@ async function rangeSummary(scope, days = 14) {
     }
   }
 
+  const savings = computeSavings(inRange);
+
   const providerSummary = {};
   for (const [name, p] of Object.entries(byProvider)) {
     providerSummary[name] = {
@@ -555,6 +635,7 @@ async function rangeSummary(scope, days = 14) {
     days,
     sample_size: inRange.length,
     total_cost_usd: totalCostUsd,
+    saved_usd: savings.total,
     cache_hit_rate: {
       exact: inRange.length ? exactHits / inRange.length : 0,
       semantic: inRange.length ? semanticHits / inRange.length : 0,
@@ -562,7 +643,9 @@ async function rangeSummary(scope, days = 14) {
     },
     error_rate: inRange.length ? errors / inRange.length : 0,
     by_provider: providerSummary,
-    daily: [...dailyByDate.values()].sort((a, b) => a.date.localeCompare(b.date))
+    daily: [...dailyByDate.values()]
+      .sort((a, b) => a.date.localeCompare(b.date))
+      .map((d) => ({ ...d, saved_usd: savings.perDay.get(d.date) || 0 }))
   };
 }
 
@@ -647,6 +730,7 @@ module.exports = {
   readRecent,
   providerStats,
   rangeSummary,
+  computeSavings,
   pruneOlderThan,
   pruneScopedOlderThan,
   currentLogPath,