auto-model-router 0.1.4 → 0.2.0

package/test/exploration.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+
+import { normalizeCatalogModel } from "../src/catalog/openrouter-catalog.ts";
+import type { CatalogModel, CatalogSnapshot } from "../src/catalog/types.ts";
+import { loadConfig } from "../src/config/load.ts";
+import type { ExplorationConfig, ProfileConfig, RouterConfig } from "../src/config/types.ts";
+import { scoreHeuristic } from "../src/router/classify.ts";
+import { extractFeatures } from "../src/router/features.ts";
+import { select } from "../src/router/select.ts";
+import type { ClassificationSource, ConversationState, Tier } from "../src/router/types.ts";
+import { parseChatRequest } from "../src/wire/openai/request.ts";
+import type { NormRequest } from "../src/wire/types.ts";
+
+const FIXTURE = (await Bun.file("test/fixtures/openrouter-models.json").json()) as { data: unknown[] };
+const MODELS: CatalogModel[] = FIXTURE.data.map(normalizeCatalogModel).filter((m): m is CatalogModel => m !== null);
+const SNAPSHOT: CatalogSnapshot = { models: MODELS, fetchedAtMs: Date.now() };
+
+const BASE = loadConfig({});
+const PROFILE: ProfileConfig = {
+	id: "auto",
+	name: "Auto",
+	minTier: "trivial",
+	maxTier: "hard",
+	contextWindow: 400_000,
+	maxTokens: 32_000,
+};
+const NOW = Date.now();
+
+function request(userText: string): NormRequest {
+	return parseChatRequest(
+		{
+			model: "auto",
+			messages: [
+				{ role: "system", content: "You are a coding agent." },
+				{ role: "user", content: userText },
+			],
+		},
+		new Headers(),
+	);
+}
+
+function state(over: Partial<ConversationState> = {}): ConversationState {
+	return {
+		key: "abc123",
+		sessionId: "omp-abc123",
+		turn: 1,
+		currentSlug: null,
+		currentTier: null,
+		stickyUntilTurn: 0,
+		escalations: 0,
+		spentUsd: 0,
+		lastPromptTokens: 0,
+		cacheWarmSlug: null,
+		cacheWarmAtMs: 0,
+		updatedAtMs: NOW,
+		...over,
+	};
+}
+
+/** A hysteresis hold at the given tier, with the prompt cache warm or expired. */
+function heldState(held: Tier, cache: "warm" | "cold"): ConversationState {
+	return state({
+		turn: 1,
+		stickyUntilTurn: 5,
+		currentTier: held,
+		currentSlug: "vendor/model",
+		cacheWarmSlug: cache === "warm" ? "vendor/model" : null,
+		cacheWarmAtMs: cache === "warm" ? NOW : 0,
+	});
+}
+
+function withExploration(over: Partial<ExplorationConfig>): RouterConfig {
+	return { ...BASE, exploration: { ...BASE.exploration, ...over } };
+}
+
+function run(opts: {
+	userText?: string;
+	cfg?: RouterConfig;
+	st?: ConversationState;
+	tier?: Tier;
+	source?: ClassificationSource;
+	profile?: ProfileConfig;
+	excludeSlugs?: readonly string[];
+}) {
+	const cfg = opts.cfg ?? BASE;
+	const req = request(opts.userText ?? "tidy the retry helper");
+	const features = extractFeatures(req, 4000);
+	const heuristic = scoreHeuristic(features, cfg);
+	const classification = {
+		...heuristic,
+		...(opts.tier === undefined ? {} : { tier: opts.tier }),
+		...(opts.source === undefined ? {} : { source: opts.source }),
+	};
+	return select({
+		req,
+		features,
+		classification,
+		profile: opts.profile ?? PROFILE,
+		state: opts.st ?? state(),
+		snapshot: SNAPSHOT,
+		ledger: null,
+		cfg,
+		nowMs: NOW,
+		...(opts.excludeSlugs === undefined ? {} : { excludeSlugs: opts.excludeSlugs }),
+	});
+}
+
+const ALWAYS = { simple: 1, moderate: 1, hard: 1 };
+
+describe("exploration is opt-in", () => {
+	test("never fires under the shipped defaults", () => {
+		expect(BASE.exploration.enabled).toBe(false);
+		for (const tier of ["simple", "moderate", "hard"] as Tier[]) {
+			expect(run({ tier }).explored).toBeNull();
+		}
+	});
+
+	test("enabled with no rates configured still never fires", () => {
+		const cfg = withExploration({ enabled: true, rates: {} });
+		for (const tier of ["simple", "moderate", "hard"] as Tier[]) {
+			expect(run({ tier, cfg }).explored).toBeNull();
+		}
+	});
+});
+
+describe("per-tier rates", () => {
+	test("each tier is governed by its own rate, not one global one", () => {
+		const cfg = withExploration({ enabled: true, rates: { simple: 0, moderate: 0, hard: 1 } });
+		expect(run({ tier: "simple", cfg }).explored).toBeNull();
+		expect(run({ tier: "moderate", cfg }).explored).toBeNull();
+		expect(run({ tier: "hard", cfg }).explored).toEqual({ from: "hard", to: "moderate" });
+	});
+
+	test("a tier absent from the rates map is never explored", () => {
+		const cfg = withExploration({ enabled: true, rates: { hard: 1 } });
+		expect(run({ tier: "moderate", cfg }).explored).toBeNull();
+		expect(run({ tier: "hard", cfg }).explored).not.toBeNull();
+	});
+
+	test("the shipped defaults weight expensive tiers far above cheap ones", () => {
+		const r = BASE.exploration.rates;
+		expect(r.hard ?? 0).toBeGreaterThan(r.simple ?? 0);
+		expect(r.moderate ?? 0).toBeGreaterThan(r.simple ?? 0);
+	});
+});
+
+describe("exploration drops exactly one tier", () => {
+	const cfg = withExploration({ enabled: true, rates: ALWAYS });
+
+	test("moderate explores down to simple", () => {
+		expect(run({ tier: "moderate", cfg }).explored).toEqual({ from: "moderate", to: "simple" });
+	});
+
+	test("hard explores down to moderate, never further", () => {
+		expect(run({ tier: "hard", cfg }).explored).toEqual({ from: "hard", to: "moderate" });
+	});
+
+	test("trivial is the floor and cannot be explored below", () => {
+		expect(run({ tier: "trivial", cfg }).explored).toBeNull();
+	});
+
+	test("the decision trail says so out loud", () => {
+		expect(run({ tier: "moderate", cfg }).reasons.some((r) => r.startsWith("exploration:"))).toBe(true);
+	});
+});
+
+describe("hysteresis holds are explored only once the cache is cold", () => {
+	const cfg = withExploration({ enabled: true, rates: ALWAYS, stickyPolicy: "cold-cache" });
+
+	test("a held tier with a WARM cache is left alone", () => {
+		expect(run({ tier: "simple", cfg, st: heldState("hard", "warm") }).explored).toBeNull();
+	});
+
+	test("a held tier with a COLD cache is explorable", () => {
+		// This is the population that carries most of the spend: turns that
+		// reach hard by hold rather than by classification.
+		expect(run({ tier: "simple", cfg, st: heldState("hard", "cold") }).explored).toEqual({
+			from: "hard",
+			to: "moderate",
+		});
+	});
+
+	test("the reason names the hold and the cache state, for later analysis", () => {
+		const d = run({ tier: "simple", cfg, st: heldState("hard", "cold") });
+		expect(d.reasons.some((r) => r.includes("held tier (cold cache)"))).toBe(true);
+	});
+
+	test("stickyPolicy never leaves holds alone entirely", () => {
+		const off = withExploration({ enabled: true, rates: ALWAYS, stickyPolicy: "never" });
+		expect(run({ tier: "simple", cfg: off, st: heldState("hard", "cold") }).explored).toBeNull();
+		expect(run({ tier: "simple", cfg: off, st: heldState("hard", "warm") }).explored).toBeNull();
+	});
+
+	test("stickyPolicy always reaches held turns even with a live cache", () => {
+		// The only setting that samples the population carrying most of the
+		// spend, at the price of a forfeited cache read.
+		const always = withExploration({ enabled: true, rates: ALWAYS, stickyPolicy: "always" });
+		expect(run({ tier: "simple", cfg: always, st: heldState("hard", "warm") }).explored).toEqual({
+			from: "hard",
+			to: "moderate",
+		});
+		expect(
+			run({ tier: "simple", cfg: always, st: heldState("hard", "warm") }).reasons.some((r) =>
+				r.includes("held tier (warm cache)"),
+			),
+		).toBe(true);
+	});
+});
+
+describe("exploration respects the remaining guards", () => {
+	const cfg = withExploration({ enabled: true, rates: ALWAYS });
+
+	test("never routes below the profile floor", () => {
+		const floored: ProfileConfig = { ...PROFILE, minTier: "moderate" };
+		expect(run({ tier: "moderate", cfg, profile: floored }).explored).toBeNull();
+	});
+
+	test("skips forced escalations, which already proved the cheap tier failed", () => {
+		expect(run({ tier: "moderate", cfg, source: "escalation" }).explored).toBeNull();
+	});
+
+	test("skips failover retries so a second confound is not introduced", () => {
+		expect(run({ tier: "moderate", cfg, excludeSlugs: ["vendor/broken"] }).explored).toBeNull();
+	});
+});
+
+describe("exploration is deterministic", () => {
+	const cfg = withExploration({ enabled: true, rates: { simple: 0.5, moderate: 0.5, hard: 0.5 } });
+
+	test("the same turn always draws the same way, so explain can replay it", () => {
+		for (const text of ["alpha task", "beta task", "gamma task"]) {
+			const first = run({ userText: text, tier: "moderate", cfg });
+			for (let i = 0; i < 5; i++) {
+				expect(run({ userText: text, tier: "moderate", cfg }).explored).toEqual(first.explored);
+			}
+		}
+	});
+
+	test("the draw honours the configured rate across many turns", () => {
+		const cfg25 = withExploration({ enabled: true, rates: { moderate: 0.25 } });
+		let explored = 0;
+		const N = 400;
+		for (let i = 0; i < N; i++) {
+			if (run({ userText: "distinct task " + i, tier: "moderate", cfg: cfg25 }).explored !== null) explored++;
+		}
+		// Deterministic hash, so this cannot flake; the band is wide enough that
+		// only a genuinely biased draw would fail it.
+		expect(explored).toBeGreaterThan(N * 0.25 - 40);
+		expect(explored).toBeLessThan(N * 0.25 + 40);
+	});
+});

package/test/failover.test.ts

@@ -29,6 +29,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 	return {
 		server: { host: "127.0.0.1", port: 8787 },
 		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0 },
+		benchmarks: { enabled: false, artificialAnalysisApiKey: "", benchlm: true, refreshMs: 86_400_000, timeoutMs: 30_000, useLocalScores: false },
 		tiers: {
 			trivial: { minQuality: 0, maxInputPerMtok: 0.3, qualityExponent: 0, pin: [] },
 			simple: { minQuality: 40, maxInputPerMtok: 1.5, qualityExponent: 0, pin: [] },
@@ -65,11 +66,13 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			...escalation,
 		},
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
+		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024 },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],
 		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
 		adaptiveTierFloors: true,
+		adaptivePriceCeilings: false,
 		logLevel: "silent",
 	};
 }
@@ -141,6 +144,7 @@ function mkDecision(tier: Tier, slug: string, probe: Partial<ProbePlan> = {}): D
 		considered: [],
 		rejected: [],
 		reasons: ["test decision"],
+		explored: null,
 		budgetDowngraded: false,
 	};
 }

package/test/hold-exploration.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from "bun:test";
+
+import { loadConfig } from "../src/config/load.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+import { explorationDraw, resolveHoldTurns } from "../src/router/explore.ts";
+
+const BASE = loadConfig({});
+
+function withHold(over: { enabled?: boolean; values?: number[] }, enabled = true): RouterConfig {
+	return {
+		...BASE,
+		exploration: {
+			...BASE.exploration,
+			enabled,
+			holdTurns: { enabled: over.enabled ?? true, values: over.values ?? [2, 3, 4] },
+		},
+	};
+}
+
+describe("hold exploration is opt-in", () => {
+	test("shipped defaults leave the hold alone", () => {
+		expect(BASE.exploration.holdTurns.enabled).toBe(false);
+		const got = resolveHoldTurns(BASE, "conv-1", true);
+		expect(got.turns).toBe(BASE.hysteresis.holdTurnsAfterEscalation);
+		expect(got.arm).toBeNull();
+	});
+
+	test("hold exploration stays off while exploration as a whole is off", () => {
+		const cfg = withHold({ values: [1] }, false);
+		const got = resolveHoldTurns(cfg, "conv-1", true);
+		expect(got.turns).toBe(BASE.hysteresis.holdTurnsAfterEscalation);
+		expect(got.arm).toBeNull();
+	});
+
+	test("an explicitly disabled hold experiment is inert", () => {
+		const cfg = withHold({ enabled: false, values: [1] });
+		expect(resolveHoldTurns(cfg, "conv-1", true).arm).toBeNull();
+	});
+});
+
+describe("only the post-escalation hold is randomised", () => {
+	const cfg = withHold({ values: [1] });
+
+	test("an escalated turn uses the drawn arm", () => {
+		expect(resolveHoldTurns(cfg, "conv-1", true).turns).toBe(1);
+	});
+
+	test("an ordinary turn keeps the configured hold", () => {
+		// The experiment targets the hold that governs expensive spend; leaving
+		// the ordinary hold fixed keeps the comparison narrow enough to read.
+		expect(resolveHoldTurns(cfg, "conv-1", false).turns).toBe(BASE.hysteresis.holdTurns);
+	});
+
+	test("but the arm is still recorded on non-escalated turns", () => {
+		// Intention-to-treat: arms are compared on whole-conversation cost, so
+		// every turn of an assigned conversation has to carry its arm.
+		expect(resolveHoldTurns(cfg, "conv-1", false).arm).toBe(1);
+	});
+});
+
+describe("assignment is per conversation", () => {
+	const cfg = withHold({ values: [2, 3, 4] });
+
+	test("the same conversation always draws the same arm", () => {
+		const first = resolveHoldTurns(cfg, "conv-stable", true).arm;
+		for (let i = 0; i < 20; i++) {
+			expect(resolveHoldTurns(cfg, "conv-stable", true).arm).toBe(first);
+		}
+	});
+
+	test("the arm never changes mid-hold, whatever the escalation state", () => {
+		const a: number | null = resolveHoldTurns(cfg, "conv-x", true).arm;
+		const b = resolveHoldTurns(cfg, "conv-x", false).arm;
+		expect(a).toEqual(b);
+	});
+
+	test("every drawn arm comes from the configured set", () => {
+		for (let i = 0; i < 200; i++) {
+			const arm = resolveHoldTurns(cfg, `conv-${i}`, true).arm;
+			expect(arm).not.toBeNull();
+			expect([2, 3, 4]).toContain(arm ?? -1);
+		}
+	});
+
+	test("arms are spread across conversations rather than collapsing to one", () => {
+		const counts = new Map<number, number>();
+		const N = 600;
+		for (let i = 0; i < N; i++) {
+			const arm = resolveHoldTurns(cfg, `spread-${i}`, true).arm ?? -1;
+			counts.set(arm, (counts.get(arm) ?? 0) + 1);
+		}
+		expect(counts.size).toBe(3);
+		// Deterministic hash, so this cannot flake. Each of 3 arms should land
+		// near N/3; the band is wide enough that only real bias would fail.
+		for (const [, n] of counts) {
+			expect(n).toBeGreaterThan(N / 3 - 60);
+			expect(n).toBeLessThan(N / 3 + 60);
+		}
+	});
+
+	test("a single-value set assigns everyone the same arm", () => {
+		const one = withHold({ values: [3] });
+		for (let i = 0; i < 20; i++) {
+			expect(resolveHoldTurns(one, `conv-${i}`, true).turns).toBe(3);
+		}
+	});
+});
+
+describe("the draw itself", () => {
+	test("is uniform in [0,1) and stable for a seed", () => {
+		expect(explorationDraw("seed-a")).toBe(explorationDraw("seed-a"));
+		expect(explorationDraw("seed-a")).not.toBe(explorationDraw("seed-b"));
+		for (const seed of ["a", "b", "c", "d", "e"]) {
+			const d = explorationDraw(seed);
+			expect(d).toBeGreaterThanOrEqual(0);
+			expect(d).toBeLessThan(1);
+		}
+	});
+
+	test("the tier draw and the hold draw are independent seeds", () => {
+		// Sharing a seed would correlate the two experiments and confound both.
+		expect(explorationDraw("hold:conv-1")).not.toBe(explorationDraw("explore:conv-1:1"));
+	});
+});

package/test/tier-plan.test.ts

@@ -5,7 +5,7 @@ import type { CatalogModel, CatalogSnapshot } from "../src/catalog/types.ts";
 import { loadConfig } from "../src/config/load.ts";
 import { buildCandidates } from "../src/router/candidates.ts";
 import { extractFeatures } from "../src/router/features.ts";
-import { computeTierPlan, effectiveQualityFloor, tierPlanFor } from "../src/router/tier-plan.ts";
+import { computeTierPlan, effectivePriceCeiling, effectiveQualityFloor, tierPlanFor } from "../src/router/tier-plan.ts";
 import { TIER_ORDER } from "../src/router/types.ts";
 import { parseChatRequest } from "../src/wire/openai/request.ts";
 
@@ -300,3 +300,57 @@ describe("adaptive floors in candidate selection", () => {
 		expect(rejected.some((r) => r.slug === target && r.reason === "failed_this_turn")).toBe(true);
 	});
 });
+
+describe("adaptive price ceilings", () => {
+	const priced = models([
+		["a/1", 80, 1],
+		["a/2", 80, 2],
+		["a/3", 80, 3],
+		["a/4", 80, 4],
+	]);
+	const req = parseChatRequest(
+		{
+			model: "auto",
+			tools: [{ type: "function", function: { name: "read", description: "Read", parameters: { type: "object", properties: {} } } }],
+			messages: [{ role: "user", content: "refactor the auth module" }],
+		},
+		new Headers(),
+	);
+	const features = extractFeatures(req, 100);
+
+	test("computeTierPlan derives per-tier price bands from the catalog", () => {
+		const plan = computeTierPlan(priced, BASE);
+		expect(plan.priceCeilings).toEqual({ trivial: 1, simple: 2, moderate: 3, hard: 4 });
+	});
+
+	test("effectivePriceCeiling: band when on, tighter of config/band, config when off", () => {
+		const plan = computeTierPlan(priced, BASE);
+		expect(effectivePriceCeiling(undefined, "moderate", plan, true)).toBe(3); // band
+		expect(effectivePriceCeiling(2, "moderate", plan, true)).toBe(2); // config tightens
+		expect(effectivePriceCeiling(10, "moderate", plan, true)).toBe(3); // band tightens
+		expect(effectivePriceCeiling(2, "moderate", plan, false)).toBe(2); // off ⇒ config
+		expect(effectivePriceCeiling(undefined, "hard", plan, false)).toBeUndefined();
+	});
+
+	test("a model above the adaptive band is dropped in candidate selection", () => {
+		const snap = snapshot(priced);
+		const run = (adaptivePriceCeilings: boolean) =>
+			buildCandidates({
+				req,
+				features,
+				tier: "moderate",
+				task: "coding",
+				snapshot: snap,
+				ledger: null,
+				cfg: { ...BASE, adaptivePriceCeilings },
+				expectedCompletionTokens: 512,
+				warmSlug: null,
+			});
+		// Off: the fixed moderate ceiling ($4) admits a/4 at $4.
+		expect(run(false).candidates.map((c) => c.model.slug)).toContain("a/4");
+		// On: the catalog band tightens moderate to $3, so a/4 is over-ceiling.
+		const on = run(true);
+		expect(on.candidates.map((c) => c.model.slug)).not.toContain("a/4");
+		expect(on.rejected.some((r) => r.slug === "a/4" && r.reason === "over_price_ceiling")).toBe(true);
+	});
+});

package/test/tokens.test.ts

@@ -24,6 +24,13 @@ function entry(over: Partial<LedgerEntry>): LedgerEntry {
 		tier: "simple",
 		classificationSource: "heuristic",
 		reasons: [],
+		features: null,
+		score: null,
+		confidence: null,
+		task: null,
+		classifierReasons: null,
+		exploredFrom: null,
+		holdArm: null,
 		predictedUsd: 0.001,
 		reportedUsd: 0.001,
 		usage: EMPTY_USAGE,

package/test/trust-attribution.test.ts

@@ -22,6 +22,13 @@ function entry(over: Partial<LedgerEntry>): LedgerEntry {
 		tier: "simple",
 		classificationSource: "heuristic",
 		reasons: [],
+		features: null,
+		score: null,
+		confidence: null,
+		task: null,
+		classifierReasons: null,
+		exploredFrom: null,
+		holdArm: null,
 		predictedUsd: 0.001,
 		reportedUsd: 0.001,
 		usage: EMPTY_USAGE,
@@ -164,11 +171,11 @@ describe("v4 migration", () => {
 		}
 	});
 
-	test("schema is at user_version 5", () => {
+	test("schema is at user_version 10", () => {
 		const db = openDb(":memory:");
 		try {
 			const row = db.query("PRAGMA user_version").get() as { user_version: number };
-			expect(row.user_version).toBe(5);
+			expect(row.user_version).toBe(10);
 		} finally {
 			db.close();
 		}
@@ -187,3 +194,90 @@ describe("v4 migration", () => {
 		}
 	});
 });
+
+describe("v6 classifier instrumentation", () => {
+	const FEATURES = {
+		promptTokens: 1234,
+		isToolResultContinuation: true,
+		toolLoopDepth: 3,
+		complexityKeywords: ["race", "debug"],
+	};
+
+	test("round-trips the feature vector and classifier outputs", () => {
+		const db = openDb(":memory:");
+		try {
+			const ledger = createLedger(db, cfg);
+			ledger.record(
+				entry({
+					features: FEATURES,
+					score: 0.42,
+					confidence: 0.75,
+					task: "coding",
+					classifierReasons: ["-0.28 tool-result continuation"],
+				}),
+			);
+
+			const got = ledger.recentEntries(1)[0];
+			expect(got?.features).toEqual(FEATURES);
+			expect(got?.score).toBe(0.42);
+			expect(got?.confidence).toBe(0.75);
+			expect(got?.task).toBe("coding");
+			expect(got?.classifierReasons).toEqual(["-0.28 tool-result continuation"]);
+		} finally {
+			db.close();
+		}
+	});
+
+	test("an uninstrumented row reads back as null, not as invented data", () => {
+		const db = openDb(":memory:");
+		try {
+			const ledger = createLedger(db, cfg);
+			ledger.record(entry({}));
+			const got = ledger.recentEntries(1)[0];
+			expect(got?.features).toBeNull();
+			expect(got?.score).toBeNull();
+			expect(got?.confidence).toBeNull();
+			expect(got?.task).toBeNull();
+			expect(got?.classifierReasons).toBeNull();
+		} finally {
+			db.close();
+		}
+	});
+
+	test("records which tier exploration dropped from, and NULL otherwise", () => {
+		const db = openDb(":memory:");
+		try {
+			const ledger = createLedger(db, cfg);
+			ledger.record(entry({ tier: "simple", exploredFrom: "moderate" }));
+			ledger.record(entry({ tier: "moderate" }));
+
+			const got = ledger.recentEntries(10);
+			expect(got.map((e) => e.exploredFrom).sort()).toEqual(["moderate", null] as unknown as string[]);
+
+			// The counterfactual query this whole column exists to make possible:
+			// of the turns we deliberately under-routed, how many had to escalate?
+			const counted = db
+				.query("SELECT COUNT(*) n FROM ledger WHERE explored_from IS NOT NULL")
+				.get() as { n: number };
+			expect(counted.n).toBe(1);
+		} finally {
+			db.close();
+		}
+	});
+	test("features land in the column as queryable JSON", () => {
+		const db = openDb(":memory:");
+		try {
+			const ledger = createLedger(db, cfg);
+			ledger.record(entry({ features: FEATURES, score: 0.9, confidence: 0.1, task: "vision" }));
+			// SQLite json_extract proves the blob is real JSON, not a stringified object.
+			const row = db
+				.query("SELECT json_extract(features, '$.toolLoopDepth') AS depth, score, task FROM ledger")
+				.get() as { depth: number; score: number; task: string };
+			expect(row.depth).toBe(3);
+			expect(row.score).toBe(0.9);
+			expect(row.task).toBe("vision");
+		} finally {
+			db.close();
+		}
+	});
+});

package/test/turn.test.ts

@@ -29,6 +29,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 	return {
 		server: { host: "127.0.0.1", port: 8787 },
 		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0 },
+		benchmarks: { enabled: false, artificialAnalysisApiKey: "", benchlm: true, refreshMs: 86_400_000, timeoutMs: 30_000, useLocalScores: false },
 		tiers: {
 			trivial: { minQuality: 0, maxInputPerMtok: 0.3, qualityExponent: 0, pin: [] },
 			simple: { minQuality: 40, maxInputPerMtok: 1.5, qualityExponent: 0, pin: [] },
@@ -65,11 +66,13 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			...escalation,
 		},
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
+		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024 },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],
 		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
 		adaptiveTierFloors: true,
+		adaptivePriceCeilings: false,
 		logLevel: "silent",
 	};
 }
@@ -141,6 +144,7 @@ function mkDecision(tier: Tier, slug: string, probe: Partial<ProbePlan> = {}): D
 		considered: [],
 		rejected: [],
 		reasons: ["test decision"],
+		explored: null,
 		budgetDowngraded: false,
 	};
 }
@@ -497,3 +501,44 @@ describe("runTurn", () => {
 		expect(errors).toHaveLength(0);
 	});
 });
+
+describe("exploration reaches the ledger", () => {
+	test("an explored turn records the tier it was dropped from", async () => {
+		const explored = { ...mkDecision("simple", "cheap/model"), explored: { from: "moderate" as Tier, to: "simple" as Tier } };
+		const { router } = mkRouter([explored]);
+		const { upstream } = mkUpstream([
+			{
+				kind: "chunks",
+				chunks: [startChunk("cheap/model"), textChunk("ok"), finishChunk("stop"), usageChunk({ promptTokens: 10, completionTokens: 2 }, 0.0001)],
+			},
+		]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		const { sink } = mkSink();
+
+		await runTurn(mkReq(), sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog }, new AbortController().signal);
+
+		expect(entries).toHaveLength(1);
+		// The counterfactual pair: what the classifier wanted, and what actually ran.
+		expect(entries[0]?.exploredFrom).toBe("moderate");
+		expect(entries[0]?.tier).toBe("simple");
+	});
+
+	test("a normally routed turn leaves it null", async () => {
+		const { router } = mkRouter([mkDecision("simple", "cheap/model")]);
+		const { upstream } = mkUpstream([
+			{
+				kind: "chunks",
+				chunks: [startChunk("cheap/model"), textChunk("ok"), finishChunk("stop"), usageChunk({ promptTokens: 10, completionTokens: 2 }, 0.0001)],
+			},
+		]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		const { sink } = mkSink();
+
+		await runTurn(mkReq(), sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog }, new AbortController().signal);
+
+		expect(entries).toHaveLength(1);
+		expect(entries[0]?.exploredFrom).toBeNull();
+	});
+});

package/tools/smoke.ts

@@ -160,6 +160,8 @@ cfg.ledger.path = join(home, "router.db");
 cfg.logLevel = "warn";
 // The adjudicator would call the mock and obscure which tier the heuristic chose.
 cfg.classifier.ambiguityThreshold = 0;
+// External benchmark feeds hit the real internet; keep the smoke test hermetic.
+cfg.benchmarks.enabled = false;
 
 const app = startServer(cfg);
 const base = `http://127.0.0.1:${app.server.port}`;