@klhapp/skillmux 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.2](https://github.com/klhq/skillmux/compare/v1.5.1...v1.5.2) (2026-08-17)
+
+
+### Changed
+
+* **calibration:** parallelize resumable evaluations ([#115](https://github.com/klhq/skillmux/issues/115)) ([49b3fba](https://github.com/klhq/skillmux/commit/49b3fba43961aa7a6648eda89c5c08d994c7433a))
+* **calibration:** report aggregate stage timings ([#119](https://github.com/klhq/skillmux/issues/119)) ([086128f](https://github.com/klhq/skillmux/commit/086128fdba8ded82ccf6a51d2e0117a18c2eea17))
+* **calibration:** reuse synchronized retrieval snapshot ([#117](https://github.com/klhq/skillmux/issues/117)) ([1fcf295](https://github.com/klhq/skillmux/commit/1fcf2959123b4f9ca6841a2978a3fa5552c23122))
+* **retrieval:** expose opt-in stage timings ([#118](https://github.com/klhq/skillmux/issues/118)) ([f459c90](https://github.com/klhq/skillmux/commit/f459c90f440834cea2ee008300bad3e15771949e))
+
 ## [1.5.1](https://github.com/klhq/skillmux/compare/v1.5.0...v1.5.1) (2026-08-17)
 
 

package/docs/calibration.md

@@ -30,9 +30,60 @@ skillmux calibrate apply RUN_ID
 ```
 
 Skillmux retrieves candidates and reranks exactly once for each evaluation
-query. It caches those observations, searches thresholds on the `tune` split,
-then certifies the selected policy on the frozen `test` split. Calibration
-starts only when an operator invokes `calibrate run`.
+query. It runs four queries at a time by default. Set a different positive
+worker limit with `--concurrency N`. The CLI writes completed-case progress to
+stderr without exposing query text.
+
+### Timing report
+
+Add `--timing` to any `calibrate run` invocation to write an aggregate
+performance report to **stderr** after the run finishes (with a completed or
+failed-gates result; a thrown error produces no report). Stdout remains valid
+JSON under `--json --timing`.
+
+```sh
+skillmux calibrate run --dataset ./eval/queries.json --timing
+```
+
+The report uses stable snake_case field names in milliseconds:
+
+| Field | Description |
+|---|---|
+| `cases_total` | Total dataset cases |
+| `cases_executed` | Cases retrieved in this invocation |
+| `cases_reused` | Cases loaded from a prior interrupted run (resume) |
+| `wall_ms` | Wall-clock duration of the full calibrateRun operation |
+| `vault_sync_ms` | One-time vault synchronization before retrieval |
+| `cumulative_embedding_ms` | Total worker time in embedding across all queries |
+| `cumulative_lexical_ms` | Total worker time in lexical search across all queries |
+| `cumulative_vector_ms` | Total worker time in vector search across all queries |
+| `cumulative_reranker_ms` | Total worker time in reranking across all queries |
+| `cumulative_checkpoint_ms` | Total worker time writing observation checkpoints |
+| `policy_evaluation_ms` | Threshold selection and test-split certification |
+
+**Cumulative vs wall time.** The cumulative fields (`cumulative_embedding_ms`,
+`cumulative_lexical_ms`, `cumulative_vector_ms`, `cumulative_reranker_ms`,
+`cumulative_checkpoint_ms`) are total _worker time_ summed across all concurrent
+query retrievals. Because multiple queries run at the same time, the sum of these
+fields typically exceeds `wall_ms`. They measure how much time each stage
+consumed across all workers, not how much wall-clock time each stage accounted
+for. `cases_executed + cases_reused = cases_total`.
+
+Timing collection is fully disabled when `--timing` is absent; it does not affect
+calibration results, resume behavior, checkpoint durability, or JSON schemas.
+Skillmux checkpoints each observation in the calibration evidence database.
+If inference fails or you interrupt the process, find the `running` run with
+`calibrate list` and resume it with the same dataset and certification flags:
+
+```sh
+skillmux calibrate run --dataset ./eval/queries.json --resume RUN_ID
+```
+
+Resume rejects changes to the dataset, corpus, inference models, recall
+settings, candidate limit, or certification gates. After all observations
+exist, Skillmux searches thresholds on the `tune` split and certifies the
+selected policy on the frozen `test` split. Calibration starts only when an
+operator invokes `calibrate run`.
 
 The operator owns the labels: supply or review the cases, start the run,
 inspect its evidence, and explicitly apply an acceptable result. A successful

package/docs/cli.md

@@ -298,9 +298,18 @@ certification gates, run evidence, reference values, and the complete operator
 lifecycle.
 
 ```sh
-# Run calibration on a dataset
+# Run calibration on a dataset with the default four workers
 skillmux calibrate run --dataset ./eval/queries.json
 
+# Set the bounded worker count
+skillmux calibrate run --dataset ./eval/queries.json --concurrency 6
+
+# Print aggregate performance timing to stderr
+skillmux calibrate run --dataset ./eval/queries.json --timing
+
+# Resume a running or interrupted attempt with the same inputs and gates
+skillmux calibrate run --dataset ./eval/queries.json --resume <run_id>
+
 # List stored calibration runs in the evidence store
 skillmux calibrate list
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/adapters.ts

@@ -1,6 +1,22 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { applyCalibrationRun, computeCorpusFingerprint, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
+import {
+  applyCalibrationRun,
+  computeCorpusFingerprint,
+  createInitialCalibrationRun,
+  finalizeCalibrationRun,
+  getCalibrationObservations,
+  getCalibrationRun,
+  insertCalibrationRun,
+  listCalibrationRuns,
+  loadDecisionCasesFromFile,
+  openCalibrateDb,
+  runCalibration,
+  saveCalibrationObservation,
+  summarizeDatasetProvenance,
+  type CalibrationResult,
+  type QueryObservation,
+} from "./calibrate";
 import { createClients } from "./clients";
 import { embeddingFingerprint, expandHome, loadConfig, rerankerFingerprint, resolveConfigPath } from "./config";
 import { openIndex } from "./db";
@@ -19,8 +35,13 @@ import {
   type SetConfigResult,
 } from "./config-service";
 import type { ResolvedTarget } from "./context";
-import { configure, retrieveAndRerank } from "./router-core";
-import type { Config } from "./types";
+import {
+  configure,
+  retrieveAndRerankSnapshot,
+  syncVaultIfNeeded,
+  type StageTiming,
+} from "./router-core";
+import type { Clients, Config } from "./types";
 
 export interface Capabilities {
   config_read: boolean;
@@ -34,6 +55,44 @@ export interface Capabilities {
 export interface TargetAdapterOptions {
   configPath?: string;
   allowInsecure?: boolean;
+  clients?: Clients;
+}
+
+/**
+ * Aggregate timing data collected during a single calibrateRun invocation.
+ *
+ * All durations are in milliseconds and are non-negative.
+ *
+ * Cumulative fields (cumulative_embedding_ms, cumulative_lexical_ms,
+ * cumulative_vector_ms, cumulative_reranker_ms, cumulative_checkpoint_ms)
+ * represent total worker time summed across all concurrent query retrievals
+ * or checkpoint writes. Because queries run concurrently, the sum of these
+ * cumulative fields may exceed wall_ms — they measure how much worker time
+ * each stage consumed, not how much wall-clock time it contributed.
+ */
+export interface CalibrationTimingSummary {
+  /** Total number of dataset cases. */
+  cases_total: number;
+  /** Cases actually retrieved in this invocation (not reused from a prior run). */
+  cases_executed: number;
+  /** Cases loaded from a prior interrupted run (resume observations). */
+  cases_reused: number;
+  /** Wall-clock duration of the full calibrateRun operation (ms). */
+  wall_ms: number;
+  /** Duration of the one-time vault synchronization before retrieval (ms). */
+  vault_sync_ms: number;
+  /** Cumulative worker time spent in embedding across all queries (ms). */
+  cumulative_embedding_ms: number;
+  /** Cumulative worker time spent in lexical search across all queries (ms). */
+  cumulative_lexical_ms: number;
+  /** Cumulative worker time spent in vector search across all queries (ms). */
+  cumulative_vector_ms: number;
+  /** Cumulative worker time spent in reranking across all queries (ms). */
+  cumulative_reranker_ms: number;
+  /** Cumulative worker time spent writing observation checkpoints (ms). */
+  cumulative_checkpoint_ms: number;
+  /** Duration of threshold selection and test-split certification (ms). */
+  policy_evaluation_ms: number;
 }
 
 export interface TargetAdapter {
@@ -50,6 +109,13 @@ export interface TargetAdapter {
     minRetrievalRecallAtK?: number;
     minDeliveredShortlistRecallAtK?: number;
     minAutoMatchCount?: number;
+    concurrency?: number;
+    resumeRunId?: string;
+    onProgress?: (completed: number, total: number) => void;
+    /** Opt-in timing collection. When true, onTimingSummary is called after a non-throwing result. */
+    timing?: boolean;
+    /** Called after calibration completes or fails-gates (not called on throws). */
+    onTimingSummary?: (summary: CalibrationTimingSummary) => void;
   }): Promise<{ run_id?: string; result?: CalibrationResult }>;
   calibrateList(): Promise<any[]>;
   calibrateShow(runId: string): Promise<any>;
@@ -68,9 +134,11 @@ export function isLoopbackHost(hostname: string): boolean {
 
 export class LocalAdapter implements TargetAdapter {
   private configPath: string;
+  private clients?: Clients;
 
   constructor(opts?: TargetAdapterOptions) {
     this.configPath = resolveConfigPath(opts?.configPath);
+    this.clients = opts?.clients;
   }
 
   async getCapabilities(): Promise<Capabilities> {
@@ -119,6 +187,7 @@ export class LocalAdapter implements TargetAdapter {
     if (caps.persistence === "externally_managed") {
       throw new CliError("Configuration is externally managed and cannot be modified", 4);
     }
+    validateDottedKey(key);
     return setDottedKey(key, rawValStr, {
       configPath: this.configPath,
       dryRun: opts?.dryRun,
@@ -136,10 +205,31 @@ export class LocalAdapter implements TargetAdapter {
     minRetrievalRecallAtK?: number;
     minDeliveredShortlistRecallAtK?: number;
     minAutoMatchCount?: number;
+    concurrency?: number;
+    resumeRunId?: string;
+    onProgress?: (completed: number, total: number) => void;
+    timing?: boolean;
+    onTimingSummary?: (summary: CalibrationTimingSummary) => void;
   }): Promise<{ run_id?: string; result?: CalibrationResult }> {
+    const collectTiming = opts?.timing === true;
+    const wallStart = collectTiming ? performance.now() : 0;
+
     const config = await loadConfig(this.configPath);
+    const clients = this.clients ?? createClients(config);
+    configure({ config, clients });
+
+    // Measure vault synchronization
+    let vault_sync_ms = 0;
+    if (collectTiming) {
+      const t0 = performance.now();
+      await syncVaultIfNeeded();
+      vault_sync_ms = Math.max(0, performance.now() - t0);
+    } else {
+      await syncVaultIfNeeded();
+    }
+
     const candidateLimit =
-      config.output?.ambiguous_candidate_limit ?? config.thresholds.candidate_limit ?? 5;
+      config.output?.ambiguous_candidate_limit ?? config.thresholds?.candidate_limit ?? 5;
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
     const indexDb = openIndex(expandHome(config.state_dir));
     let indexedSkills: Array<{ skill_id: string; content_sha256: string }>;
@@ -156,71 +246,222 @@ export class LocalAdapter implements TargetAdapter {
       datasetFile,
       indexedSkills.map((skill) => skill.skill_id),
     );
-    const clients = createClients(config);
-    configure({ config, clients });
-    const result = await runCalibration({
-      cases,
-      getRankedCandidates: async (query: string) => {
-        const result = await retrieveAndRerank({ query, forceLexical: false });
-        if (result.retrieval !== "reranked") {
-          throw new Error(
-            "Calibration requires successful hybrid retrieval and reranking for every query.",
-          );
-        }
-        return result.candidates.map((candidate) => ({
-          skill_id: candidate.skill_id,
-          score: candidate.score ?? 0,
-        }));
-      },
-      reranker: clients.rerank,
-      candidateLimit,
-      minAutoMatchPrecision: opts?.minAutoMatchPrecision,
-      minRetrievalRecallAtK: opts?.minRetrievalRecallAtK,
-      minDeliveredShortlistRecallAtK: opts?.minDeliveredShortlistRecallAtK,
-      minAutoMatchCount: opts?.minAutoMatchCount,
-    });
     const fingerprint = rerankerFingerprint(config);
     if (!fingerprint) {
       throw new Error("A configured remote reranker is required to record calibration.");
     }
     const datasetText = await Bun.file(datasetFile).text();
-    const runId = `run_${crypto.randomUUID()}`;
+    const datasetHash = createHash("sha256").update(datasetText).digest("hex");
+    const embedFp = embeddingFingerprint(config);
+    const recallSettings = {
+      k_lexical: config.recall.k_lexical,
+      k_vector: config.recall.k_vector,
+      k_rerank: config.recall.k_rerank ?? Math.min(10, config.recall.k_lexical + config.recall.k_vector),
+    };
+    const minAutoMatchPrecision = opts?.minAutoMatchPrecision ?? 0.99;
+    const minAutoMatchCount = opts?.minAutoMatchCount ?? 30;
+    const minDeliveredShortlistRecallAtK =
+      opts?.minDeliveredShortlistRecallAtK ??
+      opts?.minRetrievalRecallAtK ??
+      0.95;
+    const minShortlistRecallAt5 = opts?.minRetrievalRecallAtK ?? 0.95;
+    const concurrency = opts?.concurrency ?? 4;
+
     const db = openCalibrateDb(expandHome(config.state_dir));
+    let runId: string;
+    let initialObservations: Map<number, QueryObservation> | undefined = undefined;
+
+    // Cumulative timing accumulators (only used when collectTiming=true)
+    let cumulative_embedding_ms = 0;
+    let cumulative_lexical_ms = 0;
+    let cumulative_vector_ms = 0;
+    let cumulative_reranker_ms = 0;
+    let cumulative_checkpoint_ms = 0;
+
     try {
-      insertCalibrationRun(db, {
+      if (opts?.resumeRunId) {
+        runId = opts.resumeRunId;
+        const existingRun = getCalibrationRun(db, runId);
+        if (!existingRun) {
+          throw new Error(`Calibration run "${runId}" not found`);
+        }
+        if (existingRun.status !== "running") {
+          throw new Error(`Cannot resume completed calibration run "${runId}"`);
+        }
+        if (existingRun.dataset_hash !== datasetHash) {
+          throw new Error("Dataset hash mismatch: cannot resume run with a different dataset");
+        }
+        if (existingRun.corpus_fingerprint !== corpusFingerprint) {
+          throw new Error("Corpus fingerprint mismatch: cannot resume run with modified vault skills");
+        }
+        if (existingRun.embedding_fingerprint !== embedFp) {
+          throw new Error("Embedding fingerprint mismatch: cannot resume run with different embedding configuration");
+        }
+        if (existingRun.reranker_fingerprint !== fingerprint) {
+          throw new Error("Reranker fingerprint mismatch: cannot resume run with different reranker configuration");
+        }
+        if (existingRun.candidate_limit !== candidateLimit) {
+          throw new Error("Candidate limit mismatch: cannot resume run with different candidate limit");
+        }
+        if (
+          existingRun.recall_settings &&
+          JSON.stringify(existingRun.recall_settings) !== JSON.stringify(recallSettings)
+        ) {
+          throw new Error("Recall settings mismatch: cannot resume run with different recall parameters");
+        }
+        if (existingRun.min_auto_match_precision !== minAutoMatchPrecision) {
+          throw new Error("Certification gate mismatch: min_auto_match_precision differs from original run");
+        }
+        if ((existingRun.min_auto_match_count ?? 1) !== minAutoMatchCount) {
+          throw new Error("Certification gate mismatch: min_auto_match_count differs from original run");
+        }
+        if (
+          (existingRun.min_delivered_shortlist_recall_at_k ?? existingRun.min_shortlist_recall_at_5) !==
+          minDeliveredShortlistRecallAtK
+        ) {
+          throw new Error(
+            "Certification gate mismatch: min_delivered_shortlist_recall_at_k differs from original run",
+          );
+        }
+        if (existingRun.min_shortlist_recall_at_5 !== minShortlistRecallAt5) {
+          throw new Error("Certification gate mismatch: min_retrieval_recall_at_k differs from original run");
+        }
+
+        initialObservations = getCalibrationObservations(db, runId);
+        if (initialObservations.size === 0 && existingRun.observations && existingRun.observations.length > 0) {
+          existingRun.observations.forEach((obs, idx) => initialObservations!.set(idx, obs));
+        }
+      } else {
+        runId = `run_${crypto.randomUUID()}`;
+        createInitialCalibrationRun(db, {
+          run_id: runId,
+          created_at: new Date().toISOString(),
+          status: "running",
+          reranker_fingerprint: fingerprint,
+          embedding_fingerprint: embedFp,
+          corpus_fingerprint: corpusFingerprint,
+          dataset_hash: datasetHash,
+          dataset_provenance: summarizeDatasetProvenance(cases),
+          recall_settings: recallSettings,
+          candidate_limit: candidateLimit,
+          min_auto_match_precision: minAutoMatchPrecision,
+          min_auto_match_count: minAutoMatchCount,
+          min_delivered_shortlist_recall_at_k: minDeliveredShortlistRecallAtK,
+          min_shortlist_recall_at_5: minShortlistRecallAt5,
+        });
+      }
+
+      const casesReused = initialObservations?.size ?? 0;
+
+      const onProgress = opts?.onProgress ?? ((completed, total) => {
+        process.stderr.write(`Calibration observations: ${completed}/${total}\n`);
+      });
+
+      const retrievalTiming = collectTiming
+        ? {
+            onTiming: (timing: StageTiming) => {
+              cumulative_embedding_ms += timing.embedding_ms;
+              cumulative_lexical_ms += timing.lexical_ms;
+              cumulative_vector_ms += timing.vector_ms;
+              cumulative_reranker_ms += timing.reranker_ms;
+            },
+          }
+        : undefined;
+
+      const getRankedCandidates = async (query: string) => {
+        const res = await retrieveAndRerankSnapshot(
+          { query, forceLexical: false },
+          retrievalTiming,
+        );
+        if (res.retrieval !== "reranked") {
+          throw new Error(
+            "Calibration requires successful hybrid retrieval and reranking for every query.",
+          );
+        }
+        return res.candidates.map((candidate) => ({
+          skill_id: candidate.skill_id,
+          score: candidate.score ?? 0,
+        }));
+      };
+
+      let policyEvaluationStart = 0;
+
+      const result = await runCalibration({
+        cases,
+        getRankedCandidates,
+        reranker: clients.rerank,
+        candidateLimit,
+        minAutoMatchPrecision,
+        minRetrievalRecallAtK: minShortlistRecallAt5,
+        minDeliveredShortlistRecallAtK,
+        minAutoMatchCount,
+        concurrency,
+        initialObservations,
+        onProgress,
+        onObservation: collectTiming
+          ? (obs, caseIdx) => {
+              const t0 = performance.now();
+              saveCalibrationObservation(db, runId, caseIdx, obs);
+              const t1 = performance.now();
+              cumulative_checkpoint_ms += Math.max(0, t1 - t0);
+            }
+          : (obs, caseIdx) => {
+              saveCalibrationObservation(db, runId, caseIdx, obs);
+            },
+        onObservationsReady: collectTiming
+          ? () => {
+              policyEvaluationStart = performance.now();
+            }
+          : undefined,
+      });
+
+      // policy_evaluation_ms: threshold selection + certification duration
+      const policyEvalEnd = collectTiming ? performance.now() : 0;
+
+      finalizeCalibrationRun(db, {
         run_id: runId,
-        created_at: new Date().toISOString(),
         status: result.status,
-        reranker_fingerprint: fingerprint,
-        embedding_fingerprint: embeddingFingerprint(config),
-        corpus_fingerprint: corpusFingerprint,
-        dataset_hash: createHash("sha256").update(datasetText).digest("hex"),
-        dataset_provenance: summarizeDatasetProvenance(cases),
-        recall_settings: {
-          k_lexical: config.recall.k_lexical,
-          k_vector: config.recall.k_vector,
-          k_rerank: config.recall.k_rerank ?? Math.min(10, config.recall.k_lexical + config.recall.k_vector),
-        },
-        candidate_limit: candidateLimit,
-        min_auto_match_precision: opts?.minAutoMatchPrecision ?? 0.99,
-        min_auto_match_count: opts?.minAutoMatchCount ?? 30,
-        min_delivered_shortlist_recall_at_k:
-          opts?.minDeliveredShortlistRecallAtK ??
-          opts?.minRetrievalRecallAtK ??
-          0.95,
-        min_shortlist_recall_at_5: opts?.minRetrievalRecallAtK ?? 0.95,
         failed_reason: result.failed_reason,
         selected_thresholds: result.selected_thresholds,
         tune_metrics: result.tune_metrics,
         test_metrics: result.test_metrics,
         observations: result.observations,
       });
+
+      // Emit timing summary after a non-throwing result (completed or failed-gates).
+      // Never called when calibrateRun throws.
+      if (collectTiming && opts?.onTimingSummary) {
+        const wall_ms = Math.max(0, performance.now() - wallStart);
+        // policy_evaluation_ms covers threshold selection + test-split certification,
+        // the internal work runCalibration does after all observations are collected.
+        const policy_evaluation_ms = Math.max(0, policyEvalEnd - policyEvaluationStart);
+
+        const cases_reused = casesReused;
+        const cases_total = cases.length;
+        const cases_executed = cases_total - cases_reused;
+
+        opts.onTimingSummary({
+          cases_total,
+          cases_executed,
+          cases_reused,
+          wall_ms,
+          vault_sync_ms,
+          cumulative_embedding_ms,
+          cumulative_lexical_ms,
+          cumulative_vector_ms,
+          cumulative_reranker_ms,
+          cumulative_checkpoint_ms,
+          policy_evaluation_ms,
+        });
+      }
+
+      return { run_id: runId, result };
     } finally {
       db.close();
     }
-    return { run_id: runId, result };
   }
 
+
   async calibrateList(): Promise<any[]> {
     const config = await loadConfig(this.configPath);
     const db = openCalibrateDb(expandHome(config.state_dir));
@@ -429,11 +670,17 @@ export class RemoteAdapter implements TargetAdapter {
     minRetrievalRecallAtK?: number;
     minDeliveredShortlistRecallAtK?: number;
     minAutoMatchCount?: number;
+    concurrency?: number;
+    resumeRunId?: string;
+    onProgress?: (completed: number, total: number) => void;
+    timing?: boolean;
+    onTimingSummary?: (summary: CalibrationTimingSummary) => void;
   }): Promise<{ run_id?: string; result?: CalibrationResult }> {
     void opts;
     throw this.remoteCalibrationNotImplemented();
   }
 
+
   async calibrateList(): Promise<any[]> {
     throw this.remoteCalibrationNotImplemented();
   }

package/src/calibrate.ts

@@ -322,7 +322,7 @@ export interface CalibrationTestMetrics extends CalibrationMetrics {
   confusion_matrix: ConfusionMatrix;
 }
 
-export type CalibrationStatus = "completed" | "failed_gates";
+export type CalibrationStatus = "running" | "completed" | "failed_gates";
 export type CalibrationFailureReason =
   | "recall_precondition_failed"
   | "precision_floor_unreachable"
@@ -358,6 +358,17 @@ export interface RunCalibrationOptions {
   /** Default: 30 */
   minAutoMatchCount?: number;
   candidateLimit: number;
+  /** Default: 4 */
+  concurrency?: number;
+  initialObservations?: Map<number, QueryObservation> | QueryObservation[];
+  onProgress?: (completed: number, total: number) => void;
+  onObservation?: (
+    observation: QueryObservation,
+    caseIndex: number,
+    completedCount: number,
+    totalCount: number,
+  ) => void | Promise<void>;
+  onObservationsReady?: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -741,6 +752,40 @@ function selectThresholds(
 // Public API — runCalibration (AC2, AC3, AC4)
 // ---------------------------------------------------------------------------
 
+async function processWithConcurrency<T>(
+  items: readonly T[],
+  concurrency: number,
+  processItem: (item: T) => Promise<void>,
+): Promise<void> {
+  let nextItemPosition = 0;
+  let firstError: unknown;
+
+  const claimNextPosition = (): number | undefined => {
+    if (firstError !== undefined || nextItemPosition >= items.length) return undefined;
+    return nextItemPosition++;
+  };
+
+  const workerCount = Math.min(concurrency, items.length);
+  const workers = Array.from({ length: workerCount }, async () => {
+    for (
+      let itemPosition = claimNextPosition();
+      itemPosition !== undefined;
+      itemPosition = claimNextPosition()
+    ) {
+      try {
+        await processItem(items[itemPosition]!);
+      } catch (error) {
+        firstError ??= error;
+      }
+    }
+  });
+
+  // Drain work already in flight before propagating an error. Callers may close
+  // resources after rejection, so no worker may still be checkpointing then.
+  await Promise.all(workers);
+  if (firstError !== undefined) throw firstError;
+}
+
 /**
  * Run an in-memory calibration:
  *  1. Require a configured reranker (AC2)
@@ -759,8 +804,16 @@ export async function runCalibration(opts: RunCalibrationOptions): Promise<Calib
     minDeliveredShortlistRecallAtK = minRetrievalRecallAtK,
     minAutoMatchCount = 30,
     candidateLimit,
+    concurrency = 4,
+    initialObservations,
+    onProgress,
+    onObservation,
   } = opts;
 
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error("concurrency must be a positive integer");
+  }
+
   if (!getRankedCandidates && (!getCandidates || !reranker)) {
     throw new Error(
       "A configured reranker is required to run calibration. " +
@@ -769,8 +822,31 @@ export async function runCalibration(opts: RunCalibrationOptions): Promise<Calib
   }
 
   // --- Step 1: Cache observations (reranker called exactly once per query) ---
-  const observations: QueryObservation[] = [];
-  for (const c of cases) {
+  const obsMap = new Map<number, QueryObservation>();
+  if (initialObservations) {
+    if (Array.isArray(initialObservations)) {
+      initialObservations.forEach((obs, idx) => {
+        if (obs) obsMap.set(idx, obs);
+      });
+    } else {
+      for (const [idx, obs] of initialObservations.entries()) {
+        obsMap.set(idx, obs);
+      }
+    }
+  }
+
+  let completedCount = obsMap.size;
+  if (onProgress && completedCount > 0) {
+    onProgress(completedCount, cases.length);
+  }
+
+  const pendingIndices: number[] = [];
+  for (let i = 0; i < cases.length; i++) {
+    if (!obsMap.has(i)) pendingIndices.push(i);
+  }
+
+  await processWithConcurrency(pendingIndices, concurrency, async (caseIndex) => {
+    const c = cases[caseIndex]!;
     let ranked: Array<{ skill_id: string; score: number }>;
     if (getRankedCandidates) {
       ranked = await getRankedCandidates(c.query);
@@ -781,14 +857,25 @@ export async function runCalibration(opts: RunCalibrationOptions): Promise<Calib
         .map((d, i) => ({ skill_id: d.skill_id, score: scores[i] ?? 0 }))
         .sort((a, b) => b.score - a.score);
     }
-    observations.push({
+    const obs: QueryObservation = {
       query: c.query,
       split: c.split,
       expected_outcome: c.expected_outcome,
       relevant_skill_ids: c.relevant_skill_ids,
       ranked,
-    });
-  }
+    };
+    obsMap.set(caseIndex, obs);
+    if (onObservation) {
+      await onObservation(obs, caseIndex, completedCount + 1, cases.length);
+    }
+    const progressCount = ++completedCount;
+    if (onProgress) {
+      onProgress(progressCount, cases.length);
+    }
+  });
+
+  const observations: QueryObservation[] = cases.map((_, i) => obsMap.get(i)!);
+  opts.onObservationsReady?.();
 
   // --- Step 2: Select thresholds from tune split only ---
   const tuneObs = observations.filter((o) => o.split === "tune");
@@ -928,10 +1015,58 @@ export function openCalibrateDb(stateDir: string): Database {
   const db = new Database(join(stateDir, "calibrate.sqlite3"), { create: true });
   db.run("PRAGMA journal_mode = WAL");
   db.run("PRAGMA busy_timeout = 2000");
+
+  const tableDef = db
+    .query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'calibration_runs'")
+    .get() as { sql: string } | null;
+
+  if (
+    tableDef &&
+    tableDef.sql &&
+    tableDef.sql.includes("CHECK") &&
+    !tableDef.sql.includes("'running'")
+  ) {
+    const cols = db.query("PRAGMA table_info(calibration_runs)").all() as Array<{ name: string }>;
+    const colNames = cols.map((c) => c.name);
+    const selectCols = colNames.join(", ");
+
+    db.transaction(() => {
+      db.run(`CREATE TABLE calibration_runs_new (
+        run_id TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL,
+        status TEXT NOT NULL CHECK (status IN ('running', 'completed', 'failed_gates')),
+        reranker_fingerprint TEXT NOT NULL,
+        embedding_fingerprint TEXT NOT NULL,
+        corpus_fingerprint TEXT NOT NULL,
+        dataset_hash TEXT NOT NULL,
+        min_auto_match_precision REAL NOT NULL,
+        min_shortlist_recall_at_5 REAL NOT NULL,
+        selected_thresholds TEXT,
+        tune_metrics TEXT,
+        test_metrics TEXT,
+        observations TEXT NOT NULL,
+        candidate_limit INTEGER NOT NULL DEFAULT 5,
+        attempt_count INTEGER NOT NULL DEFAULT 1,
+        min_auto_match_count INTEGER NOT NULL DEFAULT 1,
+        min_delivered_shortlist_recall_at_k REAL NOT NULL DEFAULT 0.95,
+        failed_reason TEXT,
+        dataset_provenance TEXT NOT NULL DEFAULT '{}',
+        human_labelled_case_count INTEGER NOT NULL DEFAULT 0,
+        imported_labelled_case_count INTEGER NOT NULL DEFAULT 0,
+        recall_settings TEXT NOT NULL DEFAULT '{}'
+      )`);
+      db.run(
+        `INSERT INTO calibration_runs_new (${selectCols}) SELECT ${selectCols} FROM calibration_runs`,
+      );
+      db.run("DROP TABLE calibration_runs");
+      db.run("ALTER TABLE calibration_runs_new RENAME TO calibration_runs");
+    })();
+  }
+
   db.run(`CREATE TABLE IF NOT EXISTS calibration_runs (
     run_id TEXT PRIMARY KEY,
     created_at TEXT NOT NULL,
-    status TEXT NOT NULL CHECK (status IN ('completed', 'failed_gates')),
+    status TEXT NOT NULL CHECK (status IN ('running', 'completed', 'failed_gates')),
     reranker_fingerprint TEXT NOT NULL,
     embedding_fingerprint TEXT NOT NULL,
     corpus_fingerprint TEXT NOT NULL,
@@ -971,11 +1106,48 @@ export function openCalibrateDb(stateDir: string): Database {
   if (!columns.some((column) => column.name === "recall_settings")) {
     db.run("ALTER TABLE calibration_runs ADD COLUMN recall_settings TEXT NOT NULL DEFAULT '{}'");
   }
+
+  db.run(`CREATE TABLE IF NOT EXISTS calibration_observations (
+    run_id TEXT NOT NULL,
+    case_index INTEGER NOT NULL,
+    query TEXT NOT NULL,
+    split TEXT NOT NULL,
+    expected_outcome TEXT NOT NULL,
+    relevant_skill_ids TEXT NOT NULL,
+    ranked TEXT NOT NULL,
+    PRIMARY KEY (run_id, case_index),
+    FOREIGN KEY (run_id) REFERENCES calibration_runs(run_id) ON DELETE CASCADE
+  )`);
+
   return db;
 }
 
-/** Persist a calibration run (all fields) to the evidence store. */
-export function insertCalibrationRun(db: Database, run: CalibrationRunRecord): void {
+export interface CreateInitialCalibrationRunOptions {
+  run_id: string;
+  created_at: string;
+  status: "running";
+  reranker_fingerprint: string;
+  embedding_fingerprint: string;
+  corpus_fingerprint: string;
+  dataset_hash: string;
+  candidate_limit: number;
+  min_auto_match_precision: number;
+  min_auto_match_count?: number;
+  min_delivered_shortlist_recall_at_k?: number;
+  min_shortlist_recall_at_5: number;
+  dataset_provenance?: DatasetProvenanceSummary;
+  recall_settings?: {
+    k_lexical: number;
+    k_vector: number;
+    k_rerank: number;
+  };
+}
+
+/** Create an initial calibration run record with 'running' status before inference starts. */
+export function createInitialCalibrationRun(
+  db: Database,
+  run: CreateInitialCalibrationRunOptions,
+): void {
   const attemptCount = (
     db.query("SELECT COUNT(*) AS count FROM calibration_runs WHERE dataset_hash = ?")
       .get(run.dataset_hash) as { count: number }
@@ -1005,19 +1177,161 @@ export function insertCalibrationRun(db: Database, run: CalibrationRunRecord): v
       run.min_auto_match_count ?? 1,
       run.min_delivered_shortlist_recall_at_k ?? run.min_shortlist_recall_at_5,
       run.min_shortlist_recall_at_5,
+      null,
+      null,
+      null,
+      null,
+      "[]",
+      JSON.stringify(run.dataset_provenance ?? {}),
+      run.dataset_provenance?.human_labelled_case_count ?? 0,
+      run.dataset_provenance?.imported_labelled_case_count ?? 0,
+      JSON.stringify(run.recall_settings ?? {}),
+    ],
+  );
+}
+
+/** Save a single case observation incrementally. */
+export function saveCalibrationObservation(
+  db: Database,
+  runId: string,
+  caseIndex: number,
+  observation: QueryObservation,
+): void {
+  db.run(
+    `INSERT OR REPLACE INTO calibration_observations (
+      run_id, case_index, query, split, expected_outcome, relevant_skill_ids, ranked
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [
+      runId,
+      caseIndex,
+      observation.query,
+      observation.split,
+      observation.expected_outcome,
+      JSON.stringify(observation.relevant_skill_ids),
+      JSON.stringify(observation.ranked),
+    ],
+  );
+}
+
+/** Retrieve all completed observations for a run_id, keyed by case index. */
+export function getCalibrationObservations(
+  db: Database,
+  runId: string,
+): Map<number, QueryObservation> {
+  const rows = db
+    .query(
+      `SELECT case_index, query, split, expected_outcome, relevant_skill_ids, ranked
+       FROM calibration_observations WHERE run_id = ? ORDER BY case_index ASC`,
+    )
+    .all(runId) as Array<{
+      case_index: number;
+      query: string;
+      split: DecisionSplit;
+      expected_outcome: DecisionOutcome;
+      relevant_skill_ids: string;
+      ranked: string;
+    }>;
+  const map = new Map<number, QueryObservation>();
+  for (const r of rows) {
+    map.set(r.case_index, {
+      query: r.query,
+      split: r.split,
+      expected_outcome: r.expected_outcome,
+      relevant_skill_ids: JSON.parse(r.relevant_skill_ids) as string[],
+      ranked: JSON.parse(r.ranked) as Array<{ skill_id: string; score: number }>,
+    });
+  }
+  return map;
+}
+
+export interface FinalizeCalibrationRunOptions {
+  run_id: string;
+  status: CalibrationStatus;
+  failed_reason?: CalibrationFailureReason;
+  selected_thresholds?: SelectedThresholds;
+  tune_metrics?: CalibrationMetrics;
+  test_metrics?: CalibrationTestMetrics;
+  observations: QueryObservation[];
+}
+
+/** Finalize a calibration run record with its completion/failure status, metrics, and thresholds. */
+export function finalizeCalibrationRun(
+  db: Database,
+  run: FinalizeCalibrationRunOptions,
+): void {
+  db.run(
+    `UPDATE calibration_runs SET
+      status = ?,
+      failed_reason = ?,
+      selected_thresholds = ?,
+      tune_metrics = ?,
+      test_metrics = ?,
+      observations = ?
+     WHERE run_id = ?`,
+    [
+      run.status,
       run.failed_reason ?? null,
       run.selected_thresholds != null ? JSON.stringify(run.selected_thresholds) : null,
       run.tune_metrics != null ? JSON.stringify(run.tune_metrics) : null,
       run.test_metrics != null ? JSON.stringify(run.test_metrics) : null,
       JSON.stringify(run.observations),
-      JSON.stringify(run.dataset_provenance ?? {}),
-      run.dataset_provenance?.human_labelled_case_count ?? 0,
-      run.dataset_provenance?.imported_labelled_case_count ?? 0,
-      JSON.stringify(run.recall_settings ?? {}),
+      run.run_id,
     ],
   );
 }
 
+/** Persist a calibration run (all fields) to the evidence store. */
+export function insertCalibrationRun(db: Database, run: CalibrationRunRecord): void {
+  const attemptCount = (
+    db.query("SELECT COUNT(*) AS count FROM calibration_runs WHERE dataset_hash = ?")
+      .get(run.dataset_hash) as { count: number }
+  ).count + 1;
+  db.transaction(() => {
+    db.run(
+      `INSERT OR REPLACE INTO calibration_runs (
+        run_id, created_at, status,
+        reranker_fingerprint, embedding_fingerprint, corpus_fingerprint, dataset_hash,
+        candidate_limit,
+        attempt_count, min_auto_match_precision, min_auto_match_count,
+        min_delivered_shortlist_recall_at_k, min_shortlist_recall_at_5, failed_reason,
+        selected_thresholds, tune_metrics, test_metrics, observations,
+        dataset_provenance, human_labelled_case_count, imported_labelled_case_count,
+        recall_settings
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        run.run_id,
+        run.created_at,
+        run.status,
+        run.reranker_fingerprint,
+        run.embedding_fingerprint,
+        run.corpus_fingerprint,
+        run.dataset_hash,
+        run.candidate_limit,
+        attemptCount,
+        run.min_auto_match_precision,
+        run.min_auto_match_count ?? 1,
+        run.min_delivered_shortlist_recall_at_k ?? run.min_shortlist_recall_at_5,
+        run.min_shortlist_recall_at_5,
+        run.failed_reason ?? null,
+        run.selected_thresholds != null ? JSON.stringify(run.selected_thresholds) : null,
+        run.tune_metrics != null ? JSON.stringify(run.tune_metrics) : null,
+        run.test_metrics != null ? JSON.stringify(run.test_metrics) : null,
+        JSON.stringify(run.observations),
+        JSON.stringify(run.dataset_provenance ?? {}),
+        run.dataset_provenance?.human_labelled_case_count ?? 0,
+        run.dataset_provenance?.imported_labelled_case_count ?? 0,
+        JSON.stringify(run.recall_settings ?? {}),
+      ],
+    );
+    if (run.observations && run.observations.length > 0) {
+      for (let i = 0; i < run.observations.length; i++) {
+        const obs = run.observations[i]!;
+        saveCalibrationObservation(db, run.run_id, i, obs);
+      }
+    }
+  })();
+}
+
 interface RawCalibrationRow {
   run_id: string;
   created_at: string;
@@ -1111,7 +1425,16 @@ export function getCalibrationRun(db: Database, runId: string): CalibrationRunRe
   const row = db
     .query("SELECT * FROM calibration_runs WHERE run_id = ?")
     .get(runId) as RawCalibrationRow | null;
-  return row ? rowToRecord(row) : null;
+  if (!row) return null;
+  const record = rowToRecord(row);
+  if (record.observations.length === 0) {
+    const obsMap = getCalibrationObservations(db, runId);
+    if (obsMap.size > 0) {
+      const sortedIndices = Array.from(obsMap.keys()).sort((a, b) => a - b);
+      record.observations = sortedIndices.map((idx) => obsMap.get(idx)!);
+    }
+  }
+  return record;
 }
 
 /** List all runs ordered by created_at descending (excludes observations blob). */

package/src/cli.ts

@@ -475,6 +475,9 @@ async function handleCalibrateCommand(
     let minRetrievalRecallAtK: number | undefined;
     let minDeliveredShortlistRecallAtK: number | undefined;
     let minAutoMatchCount: number | undefined;
+    let concurrency: number | undefined;
+    let resumeRunId: string | undefined;
+    let timing = false;
     const readNumber = (flag: string, raw: string | undefined): number => {
       if (raw === undefined) throw new Error(`${flag} requires a value`);
       const value = Number(raw);
@@ -497,6 +500,19 @@ async function handleCalibrateCommand(
         if (!Number.isInteger(minAutoMatchCount) || minAutoMatchCount < 1) {
           throw new Error("--min-auto-match-count must be a positive integer");
         }
+      } else if (option === "--concurrency") {
+        const raw = args[++i];
+        if (raw === undefined) throw new Error("--concurrency requires a value");
+        const val = Number(raw);
+        if (!Number.isInteger(val) || val < 1) {
+          throw new Error("--concurrency must be a positive integer");
+        }
+        concurrency = val;
+      } else if (option === "--resume") {
+        resumeRunId = args[++i];
+        if (!resumeRunId) throw new Error("--resume requires a run_id value");
+      } else if (option === "--timing") {
+        timing = true;
       } else {
         throw new Error(`unknown calibrate run option: ${option}`);
       }
@@ -516,6 +532,34 @@ async function handleCalibrateCommand(
       minRetrievalRecallAtK,
       minDeliveredShortlistRecallAtK,
       minAutoMatchCount,
+      concurrency,
+      resumeRunId,
+      timing,
+      onTimingSummary: timing
+        ? (summary) => {
+            // Write timing report to stderr only — stdout remains valid JSON under --json.
+            // Cumulative fields are total worker time across concurrent queries and may
+            // exceed wall_ms. They do not sum to wall time.
+            process.stderr.write(
+              [
+                "--- calibrate run timing ---",
+                `cases_total:                ${summary.cases_total}`,
+                `cases_executed:             ${summary.cases_executed}  (retrieved in this invocation)`,
+                `cases_reused:               ${summary.cases_reused}  (loaded from prior interrupted run)`,
+                `wall_ms:                    ${summary.wall_ms.toFixed(1)}`,
+                `vault_sync_ms:              ${summary.vault_sync_ms.toFixed(1)}`,
+                "cumulative worker time (concurrent totals; may exceed wall_ms):",
+                `  cumulative_embedding_ms:  ${summary.cumulative_embedding_ms.toFixed(1)}`,
+                `  cumulative_lexical_ms:    ${summary.cumulative_lexical_ms.toFixed(1)}`,
+                `  cumulative_vector_ms:     ${summary.cumulative_vector_ms.toFixed(1)}`,
+                `  cumulative_reranker_ms:   ${summary.cumulative_reranker_ms.toFixed(1)}`,
+                `  cumulative_checkpoint_ms: ${summary.cumulative_checkpoint_ms.toFixed(1)}`,
+                `policy_evaluation_ms:       ${summary.policy_evaluation_ms.toFixed(1)}`,
+                "",
+              ].join("\n"),
+            );
+          }
+        : undefined,
     });
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderCalibrationTarget(ctx.target);
@@ -525,6 +569,7 @@ async function handleCalibrateCommand(
     return;
   }
 
+
   if (sub === "list") {
     const res = await adapter.calibrateList();
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
@@ -656,6 +701,11 @@ Setup:
   skillmux core <pin|unpin> <skill_id>... [--yes] [--dry-run] [--json]
   skillmux skill which <skill_id>
 
+Calibration:
+  skillmux calibrate run [--dataset <path>] [--concurrency <n>] [--resume <run_id>]
+                         [--timing] [--json]
+  skillmux calibrate <list|show|apply|generate-dataset>
+
 Init clients:
   claude-code, codex, gemini-cli, opencode, github-copilot, windsurf,
   antigravity, goose, hermes, skillmux-mcp

package/src/router-core.ts

@@ -530,18 +530,64 @@ export function classifyInferenceError(
   return stage === "embedding" ? "embedding_unavailable" : "reranker_unavailable";
 }
 
+export interface StageTiming {
+  embedding_ms: number;
+  lexical_ms: number;
+  vector_ms: number;
+  reranker_ms: number;
+}
+
+export interface RetrieveSnapshotOptions {
+  onTiming?: (timing: StageTiming) => void;
+}
+
 /**
  * Retrieve the full fused candidate set and rerank it once without applying
- * decision thresholds. Calibration uses this to avoid observing the policy it
- * is trying to replace.
+ * decision thresholds, synchronizing the vault before reading the index.
  */
 export async function retrieveAndRerank(
   input: ResolveSkillInput,
 ): Promise<RetrievalResult> {
-  const { config, db } = await getEnv();
   await syncVaultIfNeeded();
+  return retrieveAndRerankSnapshot(input);
+}
+
+/**
+ * Retrieve candidates against an already-synchronized index snapshot without
+ * triggering syncVaultIfNeeded(). Calibration uses this to avoid observing the
+ * policy it is trying to replace while keeping one corpus for the whole run.
+ */
+export async function retrieveAndRerankSnapshot(
+  input: ResolveSkillInput,
+  options?: RetrieveSnapshotOptions,
+): Promise<RetrievalResult> {
+  const { config, db } = await getEnv();
   const clients = getClients();
+  const measureTiming = options?.onTiming !== undefined;
+
+  let embedding_ms = 0;
+  let lexical_ms = 0;
+  let vector_ms = 0;
+  let reranker_ms = 0;
+
+  const tEmbed0 = measureTiming ? performance.now() : 0;
+  const embedPromise =
+    !input.forceLexical && clients.embed
+      ? clients.embed([input.query]).then(
+        (res) => {
+          if (measureTiming) embedding_ms = Math.max(0, performance.now() - tEmbed0);
+          return res;
+        },
+        (err) => {
+          if (measureTiming) embedding_ms = Math.max(0, performance.now() - tEmbed0);
+          return { error: err };
+        },
+      )
+      : null;
+
+  const tLex0 = measureTiming ? performance.now() : 0;
   const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
+  if (measureTiming) lexical_ms = Math.max(0, performance.now() - tLex0);
   const lexicalRanks = new Map(lexical.map((row, index) => [row.skill_id, index + 1]));
 
   let retrieval: RetrievalResult["retrieval"] = "lexical";
@@ -550,18 +596,12 @@ export async function retrieveAndRerank(
   let rows = lexical;
   let fusedRows: SkillRow[] | null = null;
 
-  if (!input.forceLexical) {
-    try {
-      const queryVec = (await clients.embed([input.query]))[0];
-      if (!queryVec) throw new Error("Embedding client returned no query vector.");
-      const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
-      rows = reciprocalRankFusion(lexical, nearest);
-      fusedRows = rows;
-      retrieval = "hybrid";
-    } catch (embedError) {
+  if (embedPromise) {
+    const embedRes = await embedPromise;
+    if (embedRes && typeof embedRes === "object" && "error" in embedRes) {
       retrieval = "lexical";
       degraded_from = clients.rerank ? "reranked" : "hybrid";
-      degradation_reason = classifyInferenceError("embedding", embedError);
+      degradation_reason = classifyInferenceError("embedding", embedRes.error);
       console.error(
         JSON.stringify({
           level: "warn",
@@ -570,6 +610,30 @@ export async function retrieveAndRerank(
           reason: degradation_reason,
         }),
       );
+    } else {
+      const tVec0 = measureTiming ? performance.now() : 0;
+      try {
+        const queryVec = (embedRes as Float32Array[])[0];
+        if (!queryVec) throw new Error("Embedding client returned no query vector.");
+        const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
+        if (measureTiming) vector_ms = Math.max(0, performance.now() - tVec0);
+        rows = reciprocalRankFusion(lexical, nearest);
+        fusedRows = rows;
+        retrieval = "hybrid";
+      } catch (embedError) {
+        if (measureTiming) vector_ms = Math.max(0, performance.now() - tVec0);
+        retrieval = "lexical";
+        degraded_from = clients.rerank ? "reranked" : "hybrid";
+        degradation_reason = classifyInferenceError("embedding", embedError);
+        console.error(
+          JSON.stringify({
+            level: "warn",
+            stage: "embedding",
+            degraded_from,
+            reason: degradation_reason,
+          }),
+        );
+      }
     }
   }
 
@@ -577,14 +641,17 @@ export async function retrieveAndRerank(
   if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
     const kRerank = config.recall.k_rerank ?? 10;
     const rerankCandidates = rows.slice(0, kRerank);
+    const tRerank0 = measureTiming ? performance.now() : 0;
     try {
       scores = await clients.rerank(
         input.query,
         rerankCandidates.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
       );
+      if (measureTiming) reranker_ms = Math.max(0, performance.now() - tRerank0);
       retrieval = "reranked";
       rows = rerankCandidates;
     } catch (rerankError) {
+      if (measureTiming) reranker_ms = Math.max(0, performance.now() - tRerank0);
       scores = null;
       degraded_from = "reranked";
       degradation_reason = classifyInferenceError("reranker", rerankError);
@@ -612,6 +679,13 @@ export async function retrieveAndRerank(
     : new Map<string, number>();
   const traceRows = fusedRows ?? rows;
 
+  options?.onTiming?.({
+    embedding_ms,
+    lexical_ms,
+    vector_ms,
+    reranker_ms,
+  });
+
   return {
     retrieval,
     ...(degraded_from ? { degraded_from, degradation_reason } : {}),