cachegate 1.3.0 → 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/failover.js

@@ -1,76 +1,76 @@
-// model-router/failover.js
-//
-// Pure control flow for trying a virtual model's ranked candidates in
-// order until one succeeds - isolated from the actual provider-calling
-// code (server.js's dispatchToProvider) so it's directly unit-testable
-// with a fake dispatch function, no live API keys or network calls
-// needed. Same reasoning as providers/*.js's own
-// applyStreamEvent/applyStreamChunk factoring: the trickiest logic
-// shouldn't require a real provider to test.
-//
-// Addresses ROADMAP.md's gap #2 ("no provider failover on a
-// 5xx/rate-limit"): router.js's pickCandidate() already ranks every
-// candidate in a tier by the configured strategy, but server.js used
-// to dispatch to the top-ranked one only - if it failed, the whole
-// request failed, even when a second healthy candidate existed in the
-// same tier. This module is what actually walks that ranked list.
-
-// Whether a failed dispatch attempt is worth retrying against the NEXT
-// candidate, vs failing the request outright. The distinction: is the
-// REQUEST itself broken (retrying elsewhere would fail identically),
-// or did THIS provider fail in a way another provider might not (rate
-// limit, an outage, a bad or expired key)? Bad request (400) and
-// unknown model (404) are the request's own fault, not retried - the
-// Anthropic and OpenAI SDKs both set `.status` on a thrown APIError.
-// A network-level failure with no HTTP response at all (no `.status`)
-// is treated as the provider's fault too, since it's not the
-// request's content that's the problem. An auth failure (401) or
-// missing-key misconfiguration is ALSO treated as retryable on
-// purpose: a different candidate in the tier may use a different
-// provider whose key is fine, so the request can still succeed - the
-// broken key itself still surfaces on the dashboard's Provider alerts
-// table via the metrics.record() call made before moving on (see
-// server.js), so failover keeps requests succeeding without hiding
-// the underlying problem from whoever needs to go fix that key.
-function isRetryableError(err) {
-  const status = err && (err.status || err.statusCode);
-  return status !== 400 && status !== 404;
-}
-
-/**
- * Calls `dispatch(candidate)` for each candidate in order until one
- * resolves. On a rejection, calls `onAttemptFailed(candidate, err,
- * isLastCandidate)` (for logging/metrics only - it has no bearing on
- * control flow) and, unless the error is non-retryable or this was
- * the last candidate, moves on to the next one. Rethrows the error
- * from the LAST attempt if every candidate fails - the caller decides
- * what HTTP status/response that becomes.
- *
- * Resolves to `{ result, candidate, attempts }` on success -
- * `attempts` is 1 when the first candidate just worked, >1 when
- * failover actually happened (worth logging distinctly - see
- * server.js's caller).
- *
- * @param {Array<{provider: string, model: string}>} candidates ranked
- *   order, e.g. router.js's pickCandidate().rankedCandidates
- * @param {(candidate) => Promise<any>} dispatch
- * @param {(candidate, err, isLastCandidate) => void} [onAttemptFailed]
- */
-async function dispatchWithFailover(candidates, dispatch, onAttemptFailed) {
-  let lastErr;
-  for (let i = 0; i < candidates.length; i++) {
-    const candidate = candidates[i];
-    const isLastCandidate = i === candidates.length - 1;
-    try {
-      const result = await dispatch(candidate);
-      return { result, candidate, attempts: i + 1 };
-    } catch (err) {
-      lastErr = err;
-      if (onAttemptFailed) onAttemptFailed(candidate, err, isLastCandidate);
-      if (!isRetryableError(err) || isLastCandidate) throw err;
-    }
-  }
-  throw lastErr; // unreachable when candidates.length > 0; kept honest for an empty list
-}
-
-module.exports = { isRetryableError, dispatchWithFailover };
+// model-router/failover.js
+//
+// Pure control flow for trying a virtual model's ranked candidates in
+// order until one succeeds - isolated from the actual provider-calling
+// code (server.js's dispatchToProvider) so it's directly unit-testable
+// with a fake dispatch function, no live API keys or network calls
+// needed. Same reasoning as providers/*.js's own
+// applyStreamEvent/applyStreamChunk factoring: the trickiest logic
+// shouldn't require a real provider to test.
+//
+// Addresses ROADMAP.md's gap #2 ("no provider failover on a
+// 5xx/rate-limit"): router.js's pickCandidate() already ranks every
+// candidate in a tier by the configured strategy, but server.js used
+// to dispatch to the top-ranked one only - if it failed, the whole
+// request failed, even when a second healthy candidate existed in the
+// same tier. This module is what actually walks that ranked list.
+
+// Whether a failed dispatch attempt is worth retrying against the NEXT
+// candidate, vs failing the request outright. The distinction: is the
+// REQUEST itself broken (retrying elsewhere would fail identically),
+// or did THIS provider fail in a way another provider might not (rate
+// limit, an outage, a bad or expired key)? Bad request (400) and
+// unknown model (404) are the request's own fault, not retried - the
+// Anthropic and OpenAI SDKs both set `.status` on a thrown APIError.
+// A network-level failure with no HTTP response at all (no `.status`)
+// is treated as the provider's fault too, since it's not the
+// request's content that's the problem. An auth failure (401) or
+// missing-key misconfiguration is ALSO treated as retryable on
+// purpose: a different candidate in the tier may use a different
+// provider whose key is fine, so the request can still succeed - the
+// broken key itself still surfaces on the dashboard's Provider alerts
+// table via the metrics.record() call made before moving on (see
+// server.js), so failover keeps requests succeeding without hiding
+// the underlying problem from whoever needs to go fix that key.
+function isRetryableError(err) {
+  const status = err && (err.status || err.statusCode);
+  return status !== 400 && status !== 404;
+}
+
+/**
+ * Calls `dispatch(candidate)` for each candidate in order until one
+ * resolves. On a rejection, calls `onAttemptFailed(candidate, err,
+ * isLastCandidate)` (for logging/metrics only - it has no bearing on
+ * control flow) and, unless the error is non-retryable or this was
+ * the last candidate, moves on to the next one. Rethrows the error
+ * from the LAST attempt if every candidate fails - the caller decides
+ * what HTTP status/response that becomes.
+ *
+ * Resolves to `{ result, candidate, attempts }` on success -
+ * `attempts` is 1 when the first candidate just worked, >1 when
+ * failover actually happened (worth logging distinctly - see
+ * server.js's caller).
+ *
+ * @param {Array<{provider: string, model: string}>} candidates ranked
+ *   order, e.g. router.js's pickCandidate().rankedCandidates
+ * @param {(candidate) => Promise<any>} dispatch
+ * @param {(candidate, err, isLastCandidate) => void} [onAttemptFailed]
+ */
+async function dispatchWithFailover(candidates, dispatch, onAttemptFailed) {
+  let lastErr;
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const isLastCandidate = i === candidates.length - 1;
+    try {
+      const result = await dispatch(candidate);
+      return { result, candidate, attempts: i + 1 };
+    } catch (err) {
+      lastErr = err;
+      if (onAttemptFailed) onAttemptFailed(candidate, err, isLastCandidate);
+      if (!isRetryableError(err) || isLastCandidate) throw err;
+    }
+  }
+  throw lastErr; // unreachable when candidates.length > 0; kept honest for an empty list
+}
+
+module.exports = { isRetryableError, dispatchWithFailover };

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 };