pi-smart-router 0.2.0 → 0.3.0

package/specs/001-build-smart-router/contracts/telemetry-contrib.schema.json

@@ -143,9 +143,37 @@
           "model_override",
           "compaction_pin_break",
           "feedback_good",
-          "feedback_bad"
+          "feedback_bad",
+          "tool_failure_chain",
+          "stop_reason_invalid",
+          "reprompt_detected",
+          "high_edit_distance",
+          "provider_failover",
+          "stop_reason_length",
+          "infra_error"
         ]
       }
+    },
+    "tool_failure_chain_count": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "description": "Consecutive identical tool failures at routing time (privacy-safe scalar)."
+    },
+    "stop_reason_invalid": {
+      "type": ["boolean", "null"],
+      "description": "True when provider stop_reason indicates invalid task completion."
+    },
+    "reprompt_rate": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Normalized session re-prompt rate without storing prompt text."
+    },
+    "edit_distance_proxy": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Normalized prompt-length delta proxy for edit/re-prompt detection."
     }
   }
 }

package/src/config/pi-model-mapper.ts

@@ -2,10 +2,17 @@
  * Pi model registry → ModelProfile mapper.
  *
  * Maps pi `Model` objects (provider + id) to router fleet entries using
- * pattern-based lookup for known families. Unknown models receive conservative
- * economical-cloud defaults.
+ * pattern-based lookup for known families. When `config/benchmark-profiles.json`
+ * contains a row for the model id (SP-134/136 ingest output), capability
+ * vectors are grounded in benchmark scores instead of regex defaults.
+ * Unknown models or missing benchmark rows receive conservative pattern defaults.
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { z } from 'zod';
+
 import type {
   ModelCapabilities,
   ModelLimits,
@@ -15,6 +22,103 @@ import type {
   Tier,
 } from '../domain/types/entities.js';
 
+/** Checked-in ingest artifact from `npm run routing:ingest-benchmarks` (SP-134). */
+export const DEFAULT_BENCHMARK_PROFILES_PATH = resolve('config', 'benchmark-profiles.json');
+
+const benchmarkCapabilitiesSchema = z.object({
+  reasoning: z.number().min(0).max(1),
+  code_gen: z.number().min(0).max(1),
+  tool_use: z.number().min(0).max(1),
+});
+
+const benchmarkModelRowSchema = z.object({
+  model_id: z.string().min(1),
+  capabilities: benchmarkCapabilitiesSchema,
+});
+
+const benchmarkProfilesArtifactSchema = z.object({
+  version: z.literal(1),
+  models: z.array(benchmarkModelRowSchema).min(1),
+});
+
+let benchmarkProfilesPathOverride: string | null | undefined;
+let benchmarkCapabilitiesByModelId: ReadonlyMap<string, ModelCapabilities> | null | undefined;
+
+/**
+ * Test hook — override benchmark artifact path (null disables benchmark grounding).
+ */
+export function setBenchmarkProfilesPathForTests(filePath: string | null): void {
+  benchmarkProfilesPathOverride = filePath;
+  benchmarkCapabilitiesByModelId = undefined;
+}
+
+/** Test hook — clear cached benchmark artifact between cases. */
+export function resetBenchmarkProfilesCacheForTests(): void {
+  benchmarkProfilesPathOverride = undefined;
+  benchmarkCapabilitiesByModelId = undefined;
+}
+
+function resolveBenchmarkProfilesPath(): string | null {
+  if (benchmarkProfilesPathOverride === null) {
+    return null;
+  }
+  return benchmarkProfilesPathOverride ?? DEFAULT_BENCHMARK_PROFILES_PATH;
+}
+
+function loadBenchmarkCapabilitiesMap(): ReadonlyMap<string, ModelCapabilities> | null {
+  if (benchmarkCapabilitiesByModelId !== undefined) {
+    return benchmarkCapabilitiesByModelId;
+  }
+
+  const filePath = resolveBenchmarkProfilesPath();
+  if (filePath === null || !existsSync(filePath)) {
+    benchmarkCapabilitiesByModelId = null;
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(filePath, 'utf8');
+    const parsed: unknown = JSON.parse(raw);
+    const result = benchmarkProfilesArtifactSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new Error(result.error.message);
+    }
+
+    const map = new Map<string, ModelCapabilities>();
+    for (const row of result.data.models) {
+      map.set(row.model_id, { ...row.capabilities });
+    }
+    benchmarkCapabilitiesByModelId = map;
+    return map;
+  } catch (err: unknown) {
+    console.warn('benchmark profiles artifact invalid; using regex capability defaults', {
+      path: filePath,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    benchmarkCapabilitiesByModelId = null;
+    return null;
+  }
+}
+
+function lookupBenchmarkCapabilities(modelId: string): ModelCapabilities | undefined {
+  return loadBenchmarkCapabilitiesMap()?.get(modelId);
+}
+
+function withBenchmarkCapabilities(
+  defaults: ModelFamilyDefaults,
+  modelId: string,
+): ModelFamilyDefaults {
+  const grounded = lookupBenchmarkCapabilities(modelId);
+  if (grounded === undefined) {
+    return defaults;
+  }
+
+  return {
+    ...defaults,
+    capabilities: { ...grounded },
+  };
+}
+
 /** Pi registry `Model.cost` shape — per-token USD rates. */
 export interface PiRegistryCost {
   readonly input: number;
@@ -262,19 +366,19 @@ export function mapPiModelToProfile(input: PiModelInput): ModelProfile {
       id: input.id,
       ...(input.name !== undefined ? { name: input.name } : {}),
     };
-    return buildProfile(localInput, LOCAL_DEFAULTS);
+    return buildProfile(localInput, withBenchmarkCapabilities(LOCAL_DEFAULTS, input.id));
   }
 
   if (input.id === OPAQUE_FLEET_DEFAULT_ID) {
-    return buildProfile(input, CURSOR_AUTO_DEFAULTS);
+    return buildProfile(input, withBenchmarkCapabilities(CURSOR_AUTO_DEFAULTS, input.id));
   }
 
   const matched = matchPatternRules(input.id);
   if (matched) {
-    return buildProfile(input, matched);
+    return buildProfile(input, withBenchmarkCapabilities(matched, input.id));
   }
 
-  return buildProfile(input, UNKNOWN_DEFAULTS);
+  return buildProfile(input, withBenchmarkCapabilities(UNKNOWN_DEFAULTS, input.id));
 }
 
 /**

package/src/domain/matching/hydra-input.ts

@@ -1,13 +1,26 @@
 /**
- * HyDRA embedding input builder — SP-112, GitHub #60.
+ * HyDRA embedding input builder — SP-112, SP-138, GitHub #60, #76.
  *
- * Prefixes prompt text with session metadata so requirement vectors reflect
- * turn context, not only the latest user string.
+ * Prefixes the latest user turn with session metadata so requirement vectors
+ * reflect turn context, not only the latest user string. Prior assistant
+ * responses are excluded from the encoder body per HyDRA reference (#76).
  */
 
-import type { RoutingRequest } from '../types/index.js';
+import type { Message, RoutingRequest } from '../types/index.js';
 import type { TriageResult } from '../triage/triage-engine.js';
 
+const FAILURE_PATTERNS = [
+  'error',
+  'fail',
+  'exception',
+  'timed out',
+  'timeout',
+  'econnrefused',
+  'enotfound',
+  'econnreset',
+  'epipe',
+] as const;
+
 function resolveMessageCount(request: RoutingRequest): number {
   return request.messages?.length ?? 0;
 }
@@ -28,10 +41,73 @@ function resolveTurnType(request: RoutingRequest): string {
   return request.turn_type ?? 'unknown';
 }
 
+function resolveCompactionFlag(request: RoutingRequest): 0 | 1 {
+  return request.compaction_flag ? 1 : 0;
+}
+
+function looksLikeToolFailure(content: string): boolean {
+  const lower = content.toLowerCase();
+  return FAILURE_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+
+/**
+ * Observational loop-pressure flag: 1 when the latest tool message looks
+ * like a failure. Mirrors loop-escalation heuristics without session pin state.
+ */
+function resolveLoopPressure(request: RoutingRequest): 0 | 1 {
+  const messages = request.messages;
+  if (!messages || messages.length === 0) {
+    return 0;
+  }
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]!;
+    if (message.role === 'tool') {
+      return looksLikeToolFailure(message.content) ? 1 : 0;
+    }
+  }
+
+  return 0;
+}
+
+function messageHasAttachmentIndicator(message: Message): boolean {
+  if (message.tool_blocks && message.tool_blocks.length > 0) {
+    return true;
+  }
+
+  if (message.role !== 'user') {
+    return false;
+  }
+
+  const lower = message.content.toLowerCase();
+  return lower.includes('data:image');
+}
+
+function resolveAttachmentFlag(request: RoutingRequest): 0 | 1 {
+  return request.messages?.some((message) => messageHasAttachmentIndicator(message)) ? 1 : 0;
+}
+
+/**
+ * Latest user turn text only — excludes prior assistant responses (#76).
+ */
+function resolveHydraPromptText(request: RoutingRequest): string {
+  const messages = request.messages;
+  if (messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i]!;
+      if (message.role === 'user' && message.content.trim()) {
+        return message.content;
+      }
+    }
+  }
+
+  return request.prompt_text;
+}
+
 /**
- * Build HyDRA encoder input: metadata prefix + prompt text.
+ * Build HyDRA encoder input: seven-flag metadata prefix + latest user text.
  *
- * Format: `[turns:N|tools:0|tokens:N|type:...] {prompt_text}`
+ * Format: `[turns:N|tools:0|tokens:N|type:...|compact:0|loop:0|attach:0] {text}`
  *
  * Metadata affects capability prediction only; tier selection uses the
  * cluster/feature gate (SP-103) separately.
@@ -47,7 +123,10 @@ export function buildHydraInput(
     `tools:${resolveHasToolContext(request) ? 1 : 0}`,
     `tokens:${resolveEstimatedInputTokens(request)}`,
     `type:${resolveTurnType(request)}`,
+    `compact:${resolveCompactionFlag(request)}`,
+    `loop:${resolveLoopPressure(request)}`,
+    `attach:${resolveAttachmentFlag(request)}`,
   ].join('|');
 
-  return `[${flags}] ${request.prompt_text}`;
+  return `[${flags}] ${resolveHydraPromptText(request)}`;
 }

package/src/domain/pipeline/router-pipeline.ts

@@ -58,6 +58,11 @@ import {
   buildTierFeatures,
   scoreLowIntensity,
 } from '../routing/tier-features.js';
+import {
+  applyIsotonicCalibratorTimed,
+  resolveIsotonicCalibrator,
+  type IsotonicCalibratorArtifact,
+} from '../routing/isotonic-calibrator.js';
 import {
   predictPSuccessCheapTimed,
   resolvePSuccessWeights,
@@ -168,6 +173,9 @@ export interface PipelineOptions {
   /** Preloaded P(success) weights for tests; lazy-loads artifact when omitted (SP-105). */
   readonly pSuccessWeights?: PSuccessWeights;
   readonly pSuccessWeightsPath?: string;
+  /** Preloaded isotonic calibrator for tests; lazy-loads bundle when omitted (SP-133). */
+  readonly isotonicCalibrator?: IsotonicCalibratorArtifact | null;
+  readonly routingCalibrationPath?: string;
   /** SAAR pin policy (SP-123). Must match sessionPinner.saarConfig when enabled. */
   readonly saarConfig?: SaarConfig;
 }
@@ -194,11 +202,15 @@ export class RouterPipeline {
   private currentTierHintReasonCode: string | null = null;
   private currentLowIntensityScore: number | null = null;
   private currentPSuccessCheap: number | null = null;
+  private currentPSuccessRaw: number | null = null;
+  private currentPSuccessCalibrated: number | null = null;
   private currentPSuccessAlpha: number | null = null;
   private currentExpectedCostByTier: ExpectedCostBreakdown[] | null = null;
   private currentLocalEligibleReason: string | null = null;
   private pSuccessWeightsLoaded = false;
   private cachedPSuccessWeights: PSuccessWeights | null = null;
+  private isotonicCalibratorLoaded = false;
+  private cachedIsotonicCalibrator: IsotonicCalibratorArtifact | null = null;
   private currentContextFitRejected: readonly CandidateScore[] = [];
   private currentContextFitViableCount = 0;
   private contextOverflowPreferredProvider: string | null = null;
@@ -243,6 +255,8 @@ export class RouterPipeline {
     this.currentTierHintReasonCode = null;
     this.currentLowIntensityScore = null;
     this.currentPSuccessCheap = null;
+    this.currentPSuccessRaw = null;
+    this.currentPSuccessCalibrated = null;
     this.currentPSuccessAlpha = null;
     this.currentExpectedCostByTier = null;
     this.currentLocalEligibleReason = null;
@@ -341,6 +355,8 @@ export class RouterPipeline {
       tier_hint_reason_code: this.currentTierHintReasonCode,
       low_intensity_score: this.currentLowIntensityScore,
       p_success_cheap: this.currentPSuccessCheap,
+      p_success_raw: this.currentPSuccessRaw,
+      p_success_calibrated: this.currentPSuccessCalibrated,
       p_success_alpha: this.currentPSuccessAlpha,
       local_eligible_reason: this.currentLocalEligibleReason,
     };
@@ -1027,7 +1043,13 @@ export class RouterPipeline {
     const weights = this.resolvePSuccessWeights();
     const pFeatures = tierFeaturesToPSuccessFeatures(tierFeatures);
     const pResult = predictPSuccessCheapTimed(pFeatures, weights);
-    this.currentPSuccessCheap = pResult.probability;
+    const calibrator = this.resolveIsotonicCalibrator();
+    const calibratedResult = applyIsotonicCalibratorTimed(pResult.probability, calibrator);
+    const pSuccessForGate = calibratedResult.calibrated;
+
+    this.currentPSuccessRaw = pResult.probability;
+    this.currentPSuccessCalibrated = pSuccessForGate;
+    this.currentPSuccessCheap = pSuccessForGate;
 
     const structuralHint = this.resolveTierHint(
       score,
@@ -1041,10 +1063,14 @@ export class RouterPipeline {
       ? (() => {
           const selection = this.selectExpectedCostTierHint(
             request,
-            pResult.probability,
+            pSuccessForGate,
             alpha,
           );
-          this.logExpectedCostExplain(pResult.probability, alpha, selection);
+          this.logExpectedCostExplain(pSuccessForGate, alpha, selection, {
+            p_success_raw: pResult.probability,
+            p_success_calibrated: pSuccessForGate,
+            calibration_applied: calibratedResult.calibration_applied,
+          });
           return {
             tierHint: selection.tierHint,
             reasonCode: selection.reasonCode,
@@ -1106,10 +1132,18 @@ export class RouterPipeline {
       tierCosts: readonly ExpectedCostBreakdown[];
       rationale: string;
     },
+    calibration?: {
+      readonly p_success_raw: number;
+      readonly p_success_calibrated: number;
+      readonly calibration_applied: boolean;
+    },
   ): void {
     console.info('Expected-cost tier gate', {
       reason: selection.reasonCode,
       p_success_cheap: pSuccessCheap,
+      p_success_raw: calibration?.p_success_raw ?? pSuccessCheap,
+      p_success_calibrated: calibration?.p_success_calibrated ?? pSuccessCheap,
+      calibration_applied: calibration?.calibration_applied ?? false,
       alpha,
       chosen_tier: selection.tierHint,
       rationale: selection.rationale,
@@ -1140,6 +1174,23 @@ export class RouterPipeline {
     return this.cachedPSuccessWeights!;
   }
 
+  private resolveIsotonicCalibrator(): IsotonicCalibratorArtifact | null {
+    if (this.options.isotonicCalibrator !== undefined) {
+      return this.options.isotonicCalibrator;
+    }
+
+    if (!this.isotonicCalibratorLoaded) {
+      this.cachedIsotonicCalibrator = resolveIsotonicCalibrator({
+        ...(this.options.routingCalibrationPath !== undefined
+          ? { filePath: this.options.routingCalibrationPath }
+          : {}),
+      });
+      this.isotonicCalibratorLoaded = true;
+    }
+
+    return this.cachedIsotonicCalibrator;
+  }
+
   private resolveTierHint(
     score: number,
     highThreshold: number,

package/src/domain/routing/isotonic-calibrator.ts

@@ -0,0 +1,255 @@
+/**
+ * Online isotonic P(success) calibrator for low_intensity gate (SP-133).
+ *
+ * Loads monotonic knot tables from routing-calibration bundle at serve time.
+ * O(log n) binary search lookup with <5ms budget; falls back to raw logistic
+ * when the artifact is missing or under-trained.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { z } from 'zod';
+
+import { MIN_TRAINING_SAMPLES } from './p-success-classifier.js';
+
+export const ISOTONIC_CALIBRATOR_ARTIFACT_VERSION = 1 as const;
+export const ISOTONIC_LOOKUP_BUDGET_MS = 5;
+export const DEFAULT_ROUTING_CALIBRATION_PATH = resolve('config', 'routing-calibration.json');
+
+export interface IsotonicCalibratorArtifact {
+  readonly version: typeof ISOTONIC_CALIBRATOR_ARTIFACT_VERSION;
+  readonly min_training_samples: number;
+  readonly x_knots: readonly number[];
+  readonly y_knots: readonly number[];
+  readonly trained_sample_count: number;
+  readonly holdout_ece_raw: number | null;
+  readonly holdout_ece_calibrated: number | null;
+}
+
+export interface IsotonicCalibratorResult {
+  readonly calibrated: number;
+  readonly elapsed_ms: number;
+  readonly within_budget: boolean;
+  readonly calibration_applied: boolean;
+}
+
+export interface LoadIsotonicCalibratorOptions {
+  readonly filePath?: string;
+}
+
+export class IsotonicCalibratorLoaderError extends Error {
+  override readonly name = 'IsotonicCalibratorLoaderError';
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+const IsotonicCalibratorArtifactSchema = z.object({
+  version: z.literal(ISOTONIC_CALIBRATOR_ARTIFACT_VERSION),
+  min_training_samples: z.number().int().min(0),
+  x_knots: z.array(z.number().finite().min(0).max(1)).min(2),
+  y_knots: z.array(z.number().finite().min(0).max(1)).min(2),
+  trained_sample_count: z.number().int().min(0),
+  holdout_ece_raw: z.number().finite().min(0).max(1).nullable(),
+  holdout_ece_calibrated: z.number().finite().min(0).max(1).nullable(),
+});
+
+function clamp01(value: number): number {
+  if (value <= 0) return 0;
+  if (value >= 1) return 1;
+  return value;
+}
+
+function formatZodIssues(error: { issues: readonly { path: readonly PropertyKey[]; message: string }[] }): string {
+  return error.issues
+    .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+    .join('\n');
+}
+
+/** True when artifact has enough labeled samples for serve-time calibration. */
+export function isIsotonicCalibratorTrained(artifact: IsotonicCalibratorArtifact): boolean {
+  return artifact.trained_sample_count >= artifact.min_training_samples;
+}
+
+export function createDefaultIsotonicCalibratorArtifact(): IsotonicCalibratorArtifact {
+  return {
+    version: ISOTONIC_CALIBRATOR_ARTIFACT_VERSION,
+    min_training_samples: MIN_TRAINING_SAMPLES,
+    x_knots: [0, 1],
+    y_knots: [0, 1],
+    trained_sample_count: 0,
+    holdout_ece_raw: null,
+    holdout_ece_calibrated: null,
+  };
+}
+
+/** Piecewise-constant isotonic lookup with O(log n) binary search on knots. */
+export function applyIsotonicLookup(
+  rawScore: number,
+  xKnots: readonly number[],
+  yKnots: readonly number[],
+): number {
+  if (xKnots.length === 0 || yKnots.length === 0 || xKnots.length !== yKnots.length) {
+    return clamp01(rawScore);
+  }
+
+  const score = clamp01(rawScore);
+  if (score <= xKnots[0]!) {
+    return clamp01(yKnots[0]!);
+  }
+
+  const lastIndex = xKnots.length - 1;
+  if (score >= xKnots[lastIndex]!) {
+    return clamp01(yKnots[lastIndex]!);
+  }
+
+  let low = 0;
+  let high = lastIndex;
+  while (low < high) {
+    const mid = Math.floor((low + high + 1) / 2);
+    if (xKnots[mid]! <= score) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return clamp01(yKnots[low]!);
+}
+
+/**
+ * Apply isotonic calibration to a raw logistic P(success) score.
+ * Returns the raw score when the artifact is missing or under-trained.
+ */
+export function applyIsotonicCalibrator(
+  rawScore: number,
+  artifact: IsotonicCalibratorArtifact | null,
+): number {
+  if (artifact === null || !isIsotonicCalibratorTrained(artifact)) {
+    return clamp01(rawScore);
+  }
+
+  return applyIsotonicLookup(rawScore, artifact.x_knots, artifact.y_knots);
+}
+
+/** Apply isotonic calibration with elapsed timing guard for the online routing budget. */
+export function applyIsotonicCalibratorTimed(
+  rawScore: number,
+  artifact: IsotonicCalibratorArtifact | null,
+  budgetMs: number = ISOTONIC_LOOKUP_BUDGET_MS,
+): IsotonicCalibratorResult {
+  const start = performance.now();
+  const calibration_applied = artifact !== null && isIsotonicCalibratorTrained(artifact);
+  const calibrated = applyIsotonicCalibrator(rawScore, artifact);
+  const elapsed_ms = performance.now() - start;
+
+  if (elapsed_ms > budgetMs) {
+    console.warn('Isotonic P(success) lookup exceeded latency budget', {
+      elapsed_ms,
+      budget_ms: budgetMs,
+      knot_count: artifact?.x_knots.length ?? 0,
+    });
+  }
+
+  return {
+    calibrated,
+    elapsed_ms,
+    within_budget: elapsed_ms <= budgetMs,
+    calibration_applied,
+  };
+}
+
+/** Parse and validate an isotonic calibrator artifact from JSON text. */
+export function parseIsotonicCalibratorJson(raw: string): IsotonicCalibratorArtifact {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new IsotonicCalibratorLoaderError(`Failed to parse JSON: ${message}`, { cause: err });
+  }
+
+  const result = IsotonicCalibratorArtifactSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new IsotonicCalibratorLoaderError(
+      `Invalid isotonic calibrator artifact:\n${formatZodIssues(result.error)}`,
+      { cause: result.error },
+    );
+  }
+
+  return result.data;
+}
+
+/** Extract isotonic_calibrator from a routing-calibration bundle object. */
+export function parseIsotonicCalibratorFromBundle(parsed: unknown): IsotonicCalibratorArtifact {
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new IsotonicCalibratorLoaderError('Routing calibration bundle must be a JSON object');
+  }
+
+  const isotonic = (parsed as Record<string, unknown>).isotonic_calibrator;
+  if (isotonic === undefined) {
+    throw new IsotonicCalibratorLoaderError('Routing calibration bundle missing isotonic_calibrator');
+  }
+
+  const result = IsotonicCalibratorArtifactSchema.safeParse(isotonic);
+  if (!result.success) {
+    throw new IsotonicCalibratorLoaderError(
+      `Invalid isotonic_calibrator in routing calibration bundle:\n${formatZodIssues(result.error)}`,
+      { cause: result.error },
+    );
+  }
+
+  return result.data;
+}
+
+/**
+ * Load isotonic calibrator from routing-calibration bundle on disk.
+ * Returns null when the bundle file is missing.
+ */
+export function loadIsotonicCalibrator(
+  options?: LoadIsotonicCalibratorOptions,
+): IsotonicCalibratorArtifact | null {
+  const filePath = options?.filePath ?? DEFAULT_ROUTING_CALIBRATION_PATH;
+
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new IsotonicCalibratorLoaderError(`Failed to read routing calibration file: ${message}`, {
+      cause: err,
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new IsotonicCalibratorLoaderError(`Failed to parse routing calibration JSON: ${message}`, {
+      cause: err,
+    });
+  }
+
+  return parseIsotonicCalibratorFromBundle(parsed);
+}
+
+/** Resolve calibrator for online inference — missing or invalid artifacts fall back safely. */
+export function resolveIsotonicCalibrator(
+  options?: LoadIsotonicCalibratorOptions,
+): IsotonicCalibratorArtifact | null {
+  try {
+    return loadIsotonicCalibrator(options);
+  } catch (err: unknown) {
+    console.warn('Isotonic calibrator artifact invalid; using raw logistic fallback', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}