auto-model-router 0.31.0 → 0.32.0

package/src/cost/views.ts

@@ -5,12 +5,13 @@
  * cost export by day, harness and model. Served by `/v1/router/spend`,
  * `GET /v1/router/feedback` and `/v1/router/export`, exported from lib.ts, and
  * behind `auto-model-router export`. All of them read only long-stable ledger
- * columns and accept a read-only database handle.
+ * columns, and they run on either engine through `util/sql.ts`: a front door
+ * may be reading a local file while the router writes a shared database.
  */
 
 import { providerOfSlug } from "./report.ts";
-import type { Database } from "bun:sqlite";
-import { toEntry, type LedgerRow } from "./ledger.ts";
+import { num, type SqlDb } from "../util/sql.ts";
+import { entriesOf } from "./ledger-sql.ts";
 import { harnessFilter } from "./report.ts";
 import type { LedgerEntry } from "./types.ts";
 
@@ -89,7 +90,7 @@ export interface DecisionFilter {
  * reasons, the classifier's view, the cost forecast against the bill, the escalation signal —
  * and the verdicts `/router good|bad` recorded against each turn ride along.
  */
-export function decisionEntries(db: Database, filter: DecisionFilter): DecisionEntry[] {
+export async function decisionEntries(db: SqlDb, filter: DecisionFilter): Promise<DecisionEntry[]> {
 	const s = scope(filter.harness, "harness_id");
 	if (s === null) return [];
 	const where = ["created_at_ms >= $since", ...s.sql];
@@ -107,20 +108,26 @@ export function decisionEntries(db: Database, filter: DecisionFilter): DecisionE
 		bind.$session = filter.ompSessionId;
 	}
 	const limit = Math.min(Math.max(filter.limit ?? 50, 1), 1_000);
-	const rows = db.query(`SELECT * FROM ledger WHERE ${where.join(" AND ")} ORDER BY created_at_ms DESC LIMIT ${limit}`).all(bind) as LedgerRow[];
-	const entries = rows.map(toEntry);
+	const rows = await db.query<unknown>(
+		`SELECT * FROM ledger WHERE ${where.join(" AND ")} ORDER BY created_at_ms DESC LIMIT ${limit}`,
+		bind,
+	);
+	const entries = entriesOf(rows);
 	if (entries.length === 0) return [];
 	// Verdicts, when the feedback table exists (it does not on a ledger no one has judged).
-	const hasFeedback = (db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'feedback'").get() as { name: string } | null) !== null;
 	const verdicts = new Map<string, DecisionEntry["feedback"]>();
-	if (hasFeedback) {
+	if (await db.tableExists("feedback")) {
 		const ids = entries.map((e) => e.id);
 		const marks = ids.map((_, i) => `$f${i}`).join(", ");
 		const fb: Record<string, string> = {};
 		ids.forEach((id, i) => (fb[`$f${i}`] = id));
-		for (const r of db.query(`SELECT ledger_id, verdict, note, created_at_ms FROM feedback WHERE ledger_id IN (${marks}) ORDER BY created_at_ms ASC`).all(fb) as { ledger_id: string; verdict: string; note: string; created_at_ms: number }[]) {
+		const rows = await db.query<{ ledger_id: string; verdict: string; note: string; created_at_ms: number }>(
+			`SELECT ledger_id, verdict, note, created_at_ms FROM feedback WHERE ledger_id IN (${marks}) ORDER BY created_at_ms ASC`,
+			fb,
+		);
+		for (const r of rows) {
 			const list = verdicts.get(r.ledger_id) ?? [];
-			list.push({ verdict: r.verdict === "good" ? "good" : "bad", note: r.note, createdAtMs: r.created_at_ms });
+			list.push({ verdict: r.verdict === "good" ? "good" : "bad", note: r.note, createdAtMs: num(r.created_at_ms) });
 			verdicts.set(r.ledger_id, list);
 		}
 	}
@@ -132,7 +139,7 @@ export function decisionEntries(db: Database, filter: DecisionFilter): DecisionE
  * as the ledger counts them. `contextScope`, when given, narrows to the turns that carried
  * exactly that agentdox scope — what a front door charges back to one project.
  */
-export function spendUsdSince(db: Database, sinceMs: number, harness: HarnessScope, contextScope?: string): number {
+export async function spendUsdSince(db: SqlDb, sinceMs: number, harness: HarnessScope, contextScope?: string): Promise<number> {
 	const s = scope(harness, "harness_id");
 	if (s === null) return 0;
 	const where = ["created_at_ms >= $since", ...s.sql];
@@ -141,36 +148,42 @@ export function spendUsdSince(db: Database, sinceMs: number, harness: HarnessSco
 		where.push("scope = $scope");
 		bind.$scope = contextScope;
 	}
-	const row = db.query(`SELECT COALESCE(SUM(${USD}), 0) AS usd FROM ledger WHERE ${where.join(" AND ")}`).get(bind) as { usd: number };
-	return row.usd;
+	const row = await db.one<{ usd: unknown }>(
+		`SELECT COALESCE(SUM(${USD}), 0) AS usd FROM ledger WHERE ${where.join(" AND ")}`,
+		bind,
+	);
+	return num(row?.usd);
 }
 
 /** Verdicts since `sinceMs`, by model and the most recent 200, joined to the ledger for the judging harness. */
-export function feedbackView(db: Database, sinceMs: number, harness: HarnessScope): FeedbackView {
-	const exists = (db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'feedback'").get() as { name: string } | null) !== null;
-	if (!exists) return { byModel: [], recent: [] };
+export async function feedbackView(db: SqlDb, sinceMs: number, harness: HarnessScope): Promise<FeedbackView> {
+	if (!(await db.tableExists("feedback"))) return { byModel: [], recent: [] };
 	const s = scope(harness, "l.harness_id");
 	if (s === null) return { byModel: [], recent: [] };
 	const where = ["f.created_at_ms >= $since", ...s.sql].join(" AND ");
 	const bind = { $since: sinceMs, ...s.bind };
 	const recent = (
-		db.query(`SELECT f.created_at_ms AS at_ms, f.slug, f.tier, f.verdict, f.note, COALESCE(l.harness_id, '') AS harness_id FROM feedback f LEFT JOIN ledger l ON l.id = f.ledger_id WHERE ${where} ORDER BY f.created_at_ms DESC LIMIT 200`).all(bind) as {
-			at_ms: number;
-			slug: string;
-			tier: string;
-			verdict: string;
-			note: string;
-			harness_id: string;
-		}[]
-	).map((r) => ({ atMs: r.at_ms, slug: r.slug, tier: r.tier, verdict: (r.verdict === "good" ? "good" : "bad") as "good" | "bad", note: r.note, harnessId: r.harness_id }));
+		await db.query<{ at_ms: number; slug: string; tier: string; verdict: string; note: string; harness_id: string }>(
+			`SELECT f.created_at_ms AS at_ms, f.slug, f.tier, f.verdict, f.note, COALESCE(l.harness_id, '') AS harness_id
+			 FROM feedback f LEFT JOIN ledger l ON l.id = f.ledger_id WHERE ${where} ORDER BY f.created_at_ms DESC LIMIT 200`,
+			bind,
+		)
+	).map((r) => ({
+		atMs: num(r.at_ms),
+		slug: r.slug,
+		tier: r.tier,
+		verdict: (r.verdict === "good" ? "good" : "bad") as "good" | "bad",
+		note: r.note,
+		harnessId: r.harness_id,
+	}));
 	const byModel = (
-		db
-			.query(
-				`SELECT f.slug, SUM(CASE WHEN f.verdict = 'good' THEN 1 ELSE 0 END) AS good, SUM(CASE WHEN f.verdict = 'bad' THEN 1 ELSE 0 END) AS bad, COUNT(DISTINCT COALESCE(l.harness_id, '')) AS judges
-				 FROM feedback f LEFT JOIN ledger l ON l.id = f.ledger_id WHERE ${where} GROUP BY f.slug ORDER BY bad DESC, good DESC, f.slug ASC`,
-			)
-			.all(bind) as { slug: string; good: number; bad: number; judges: number }[]
-	).map((r) => ({ slug: r.slug, good: r.good, bad: r.bad, judges: r.judges }));
+		await db.query<{ slug: string; good: unknown; bad: unknown; judges: unknown }>(
+			`SELECT f.slug, SUM(CASE WHEN f.verdict = 'good' THEN 1 ELSE 0 END) AS good, SUM(CASE WHEN f.verdict = 'bad' THEN 1 ELSE 0 END) AS bad,
+				COUNT(DISTINCT COALESCE(l.harness_id, '')) AS judges
+			 FROM feedback f LEFT JOIN ledger l ON l.id = f.ledger_id WHERE ${where} GROUP BY f.slug ORDER BY bad DESC, good DESC, f.slug ASC`,
+			bind,
+		)
+	).map((r) => ({ slug: r.slug, good: num(r.good), bad: num(r.bad), judges: num(r.judges) }));
 	return { byModel, recent };
 }
 
@@ -180,36 +193,53 @@ export function feedbackView(db: Database, sinceMs: number, harness: HarnessScop
  * can charge each project its own share; rows from before v18 (and turns that carried no
  * scope) group under "".
  */
-export function exportRows(db: Database, sinceMs: number, harness: HarnessScope): ExportRow[] {
+export async function exportRows(db: SqlDb, sinceMs: number, harness: HarnessScope): Promise<ExportRow[]> {
 	const s = scope(harness, "harness_id");
 	if (s === null) return [];
 	const where = ["created_at_ms >= $since", "requested_model <> 'digest'", ...s.sql].join(" AND ");
-	const rows = db
-		.query(
-			`SELECT strftime('%Y-%m-%d', created_at_ms / 1000, 'unixepoch') AS day, harness_id, COALESCE(served_slug, slug) AS slug, COALESCE(scope, '') AS scope,
+	// GROUP BY names the day expression rather than its alias: Postgres does not
+	// allow a select alias in GROUP BY, and repeating it keeps one statement for
+	// both engines.
+	const day = db.utcDay("created_at_ms");
+	const rows = await db.query<{
+		day: string;
+		harness_id: string;
+		slug: string;
+		scope: string;
+		dispatches: unknown;
+		prompt_tokens: unknown;
+		cached_tokens: unknown;
+		completion_tokens: unknown;
+		spend: unknown;
+		escalations: unknown;
+		errors: unknown;
+	}>(
+		`SELECT ${day} AS day, harness_id, COALESCE(served_slug, slug) AS slug, COALESCE(scope, '') AS scope,
 				COUNT(*) AS dispatches,
-				COALESCE(SUM(json_extract(usage, '$.promptTokens')), 0) AS prompt_tokens,
-				COALESCE(SUM(json_extract(usage, '$.cachedTokens')), 0) AS cached_tokens,
-				COALESCE(SUM(json_extract(usage, '$.completionTokens')), 0) AS completion_tokens,
+				COALESCE(SUM(${db.jsonNum("usage", "promptTokens")}), 0) AS prompt_tokens,
+				COALESCE(SUM(${db.jsonNum("usage", "cachedTokens")}), 0) AS cached_tokens,
+				COALESCE(SUM(${db.jsonNum("usage", "completionTokens")}), 0) AS completion_tokens,
 				COALESCE(SUM(${USD}), 0) AS spend,
 				SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END) AS escalations,
 				SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) AS errors
-			 FROM ledger WHERE ${where} GROUP BY day, harness_id, slug, scope ORDER BY day ASC, harness_id ASC, spend DESC`,
-		)
-		.all({ $since: sinceMs, ...s.bind }) as { day: string; harness_id: string; slug: string; scope: string; dispatches: number; prompt_tokens: number; cached_tokens: number; completion_tokens: number; spend: number; escalations: number; errors: number }[];
+			 FROM ledger WHERE ${where}
+			 GROUP BY ${day}, harness_id, COALESCE(served_slug, slug), COALESCE(scope, '')
+			 ORDER BY 1 ASC, harness_id ASC, spend DESC`,
+		{ $since: sinceMs, ...s.bind },
+	);
 	return rows.map((r) => ({
 		day: r.day,
 		harnessId: r.harness_id,
 		slug: r.slug,
 		scope: r.scope,
 		provider: providerOfSlug(r.slug),
-		dispatches: r.dispatches,
-		promptTokens: r.prompt_tokens,
-		cachedTokens: r.cached_tokens,
-		completionTokens: r.completion_tokens,
-		spendUsd: r.spend,
-		escalations: r.escalations,
-		errors: r.errors,
+		dispatches: num(r.dispatches),
+		promptTokens: num(r.prompt_tokens),
+		cachedTokens: num(r.cached_tokens),
+		completionTokens: num(r.completion_tokens),
+		spendUsd: num(r.spend),
+		escalations: num(r.escalations),
+		errors: num(r.errors),
 	}));
 }
 

package/src/lib.ts

@@ -25,14 +25,18 @@ export type { DeepPartial } from "./config/load.ts";
 export { buildUsageReport, renderUsageReport, type UsageReport, type ReportTotals } from "./cost/report.ts";
 export { buildDailySummary, renderDailySummary, type DailySummary } from "./cost/summary.ts";
 export { openDb } from "./util/sqlite.ts";
+// A front door reads the ledger through the engine-agnostic handle: the store
+// may be a file or a shared database, and the view functions take this.
+export { dialectOf, openSqlDb, num, numOrNull, type Dialect, type SqlDb } from "./util/sql.ts";
 export { spendUsdSince, feedbackView, exportRows, exportCsv, decisionEntries, harnessScopeParam, type HarnessScope, type ExportRow, type FeedbackRow, type FeedbackByModel, type FeedbackView, type DecisionEntry, type DecisionFilter } from "./cost/views.ts";
-export { createLedger } from "./cost/ledger.ts";
+export { createSqlLedger } from "./cost/ledger-sql.ts";
+export { migrateStore, STORE_TABLES } from "./util/schema.ts";
 export { createFeedbackStore, type FeedbackStore, type FeedbackRecord } from "./cost/feedback.ts";
 export { buildExecutable, collectPackageFiles, executableFileName, hostTarget, isExecutableTarget, EXECUTABLE_TARGETS, type ExecutableTarget, type BuildExecutableResult } from "./cli/build-executable.ts";
 export { parseSkillsBundle, type SkillsBundle } from "./cli/skills.ts";
 export type { RequestPolicy } from "./wire/types.ts";
 export type { CatalogView, CatalogViewModel } from "./server/catalog-view.ts";
-export type { Ledger, LedgerEntry, PruneResult } from "./cost/types.ts";
+export type { AsyncLedger, LedgerEntry, PruneResult } from "./cost/types.ts";
 // Retention: a front door asks through `POST /v1/router/prune` rather than
 // deleting from the ledger itself. The interval is exported so it can say when.
 export { RETENTION_INTERVAL_MS } from "./cost/retention.ts";

package/src/router/candidates.ts

@@ -7,7 +7,7 @@
 import type { CatalogModel, CatalogSnapshot } from "../catalog/types.ts";
 import type { FilterConfig, QualityAxis, RouterConfig } from "../config/types.ts";
 import { forecast, priceAt } from "../cost/forecast.ts";
-import type { Ledger, LedgerSignals, ModelLatency } from "../cost/types.ts";
+import type { LedgerSignals, ModelLatency } from "../cost/types.ts";
 import type { NormRequest } from "../wire/types.ts";
 import { effectivePriceCeiling, effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
 import type { Candidate, Features, Rejection, TaskType, Tier } from "./types.ts";
@@ -27,7 +27,6 @@ export interface BuildCandidatesArgs {
 	/** Task type; its config selects the axis, quality floor, and image filter. */
 	task: TaskType;
 	snapshot: CatalogSnapshot;
-	ledger: Ledger | null;
 	cfg: RouterConfig;
 	expectedCompletionTokens: number;
 	/** Slug whose prompt cache is warm this turn; wins score ties. */
@@ -154,7 +153,7 @@ function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig,
 }
 
 export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candidate[]; rejected: Rejection[] } {
-	const { req, features, tier, task, snapshot, ledger, cfg, expectedCompletionTokens, warmSlug, relaxLevel = 0 } = args;
+	const { req, features, tier, task, snapshot, cfg, expectedCompletionTokens, warmSlug, relaxLevel = 0 } = args;
 	// A Set only when non-empty: the common path allocates nothing.
 	const excluded = args.excludeSlugs === undefined || args.excludeSlugs.length === 0 ? null : new Set(args.excludeSlugs);
 	const tierCfg = cfg.tiers[tier];
@@ -318,14 +317,11 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
-		// Use pre-fetched signals when available (batch lookup, one query per
-		// signal kind for the entire candidate set instead of one per model).
-		// Falls back to per-slug calls when signals is not provided (e.g. tests).
+		// Signals are prefetched by `route` — one query per signal kind for the
+		// whole candidate set. Absent means "the ledger knows nothing about this
+		// model", which is what a cold start looks like and is handled below.
 		const signals = args.signals;
-		const trust =
-			signals?.get(slug)?.trust ??
-			ledger?.trust(slug, filters.trustScopedByHarness ? req.harnessId : undefined, filters.feedbackByTask ? task : undefined) ??
-			null;
+		const trust = signals?.get(slug)?.trust ?? null;
 		if (!relaxTrust && trust !== null && trust.attempts >= filters.minTrustSamples && trust.successRate < filters.minTrust) {
 			rejected.push({
 				slug,
@@ -342,11 +338,7 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// gate can. Only measured models are dropped, so a new model still gets its
 		// cold-start turns to accumulate samples. Relaxed with trust in rescue.
 		const needLatency = filters.latencyWeight > 0 || filters.maxExpectedWaitMs !== undefined;
-		const latency = needLatency
-			? (signals?.get(slug)?.latency ??
-				ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ??
-				null)
-			: null;
+		const latency = needLatency ? (signals?.get(slug)?.latency ?? null) : null;
 		if (
 			!relaxTrust &&
 			filters.maxExpectedWaitMs !== undefined &&

package/src/router/classify.ts

@@ -6,7 +6,7 @@
 import type { CatalogSource } from "../catalog/types.ts";
 import type { QualityAxis, RouterConfig } from "../config/types.ts";
 import { forecast } from "../cost/forecast.ts";
-import type { Ledger } from "../cost/types.ts";
+import type { AsyncLedger } from "../cost/types.ts";
 import { estimateTokens } from "../tokens/estimate.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
 import { sha256Hex } from "../util/hash.ts";
@@ -219,7 +219,7 @@ export function classifyTask(f: Features): TaskType {
 
 export interface ClassifyDeps {
 	upstream: UpstreamClient;
-	ledger: Ledger | null;
+	ledger: AsyncLedger | null;
 	catalog: CatalogSource | null;
 }
 
@@ -334,11 +334,13 @@ export async function classify(
 	}
 
 	// Cost guard: adjudication must be cheap relative to the turn it classifies.
-	const blend = deps.ledger?.blendedRate(cfg.ledger.blendWindowDays) ?? null;
+	const blend = (await deps.ledger?.blendedRate(cfg.ledger.blendWindowDays)) ?? null;
 	const inputRate = (blend?.inputPerMtok ?? cfg.ledger.fallbackBlend.inputPerMtok) / 1e6;
 	const outputRate = (blend?.outputPerMtok ?? cfg.ledger.fallbackBlend.outputPerMtok) / 1e6;
 	const judge = deps.catalog?.find(cc.model);
-	const digestTokens = estimateTokens(Buffer.byteLength(ADJUDICATOR_SYSTEM) + Buffer.byteLength(digest), "unknown", deps.ledger);
+	// The adjudicator prompt is short and its family unknown, so the default
+	// family ratio is as good as a measured one here.
+	const digestTokens = estimateTokens(Buffer.byteLength(ADJUDICATOR_SYSTEM) + Buffer.byteLength(digest), "unknown", null);
 	const adjudicatorUsd =
 		judge !== undefined
 			? forecast(judge, {

package/src/router/index.ts

@@ -10,23 +10,25 @@
  * real request without perturbing the conversation it belongs to.
  */
 
-import type { CatalogSource } from "../catalog/types.ts";
+import type { CatalogSnapshot, CatalogSource } from "../catalog/types.ts";
 import type { ProfileConfig, RouterConfig } from "../config/types.ts";
-import type { Ledger } from "../cost/types.ts";
+import { type AsyncLedger, type LedgerReader } from "../cost/types.ts";
 import { estimatePromptTokens } from "../tokens/estimate.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
+import { modelNotFound } from "../wire/openai/errors.ts";
 import type { NormRequest, RequestPolicy } from "../wire/types.ts";
 import { classify, classifyTask } from "./classify.ts";
 import { extractFeatures } from "./features.ts";
-import { select } from "./select.ts";
+import { monthStartMs, select, type TurnReads } from "./select.ts";
 import { TIER_ORDER, type Classification, type ConversationStore, type Decision, type Router, type Tier } from "./types.ts";
-
 export interface RouterDeps {
 	config: RouterConfig;
 	catalog: CatalogSource;
-	ledger: Ledger;
+	ledger: AsyncLedger;
 	conversations: ConversationStore;
 	upstream: UpstreamClient;
+	/** Async ledger reads; defaults to reading `ledger` directly. */
+	reader?: LedgerReader;
 }
 
 /**
@@ -90,20 +92,89 @@ export function resolveProfile(cfg: RouterConfig, requestedModel: string, isSuba
 	return fallback;
 }
 
+/**
+ * The `model` a client names is a profile id. When it is neither a profile nor
+ * a catalog slug, routing something else and reporting the asked-for name back
+ * is a silent substitution: the caller is billed for a model it never chose.
+ * A real slug becomes a pin (absolute, the way a session override is); anything
+ * else is refused.
+ *
+ * @param asked the client's `model` before the provider prefix was stripped.
+ * @returns the slug to pin, or undefined when a profile matched.
+ */
+export function pinForRequestedModel(
+	cfg: RouterConfig,
+	slugs: readonly string[],
+	requestedModel: string,
+	asked: string,
+): string | undefined {
+	if (cfg.profiles.some((p) => p.id === requestedModel)) return undefined;
+	if (slugs.includes(asked)) return asked;
+	throw modelNotFound(asked);
+}
+
+/**
+ * Reads the ledger for one turn, concurrently, before selection runs.
+ *
+ * Only what this turn's configuration actually consults is fetched: month and
+ * day spend are skipped when no such budget is set, and the escalation-cost
+ * term is skipped when its weight is 0. Empty catalog ⇒ no signal queries at
+ * all, which is what keeps the tests' fakes cheap.
+ */
+export async function prefetchTurnReads(
+	reader: LedgerReader | null,
+	req: NormRequest,
+	profile: ProfileConfig,
+	cfg: RouterConfig,
+	snapshot: CatalogSnapshot,
+	task: string,
+	nowMs: number = Date.now(),
+): Promise<TurnReads> {
+	if (reader === null) return {};
+	const slugs = snapshot.models.map((m) => m.slug);
+	const harness = cfg.filters.trustScopedByHarness ? req.harnessId : undefined;
+	const perMonthUsd = profile.budget?.perMonthUsd ?? cfg.budget.perMonthUsd;
+	const perDayUsd = profile.budget?.perDayUsd ?? cfg.budget.perDayUsd;
+	const [signals, cacheReliability, escalation, monthSpendUsd, daySpendUsd] = await Promise.all([
+		slugs.length > 0 ? reader.signals(slugs, harness, cfg.filters.feedbackByTask ? task : undefined) : undefined,
+		slugs.length > 0 && cfg.filters.cacheReliabilityMinSamples > 0 ? reader.cacheReliability(slugs) : undefined,
+		cfg.filters.escalationCostWeight > 0 ? reader.escalationCost(cfg.ledger.blendWindowDays) : undefined,
+		// Month pacing can tighten the daily ceiling, so month spend is needed
+		// whenever either budget is set.
+		perMonthUsd !== undefined ? reader.spendSince(monthStartMs(nowMs), req.harnessId) : undefined,
+		perDayUsd !== undefined || perMonthUsd !== undefined ? reader.spendSince(nowMs - 86_400_000, req.harnessId) : undefined,
+	]);
+	return {
+		...(signals === undefined ? {} : { signals }),
+		...(cacheReliability === undefined ? {} : { cacheReliability }),
+		...(escalation === undefined ? {} : { escalationUsdPerPromptToken: escalation?.usdPerPromptToken ?? null }),
+		...(monthSpendUsd === undefined ? {} : { monthSpendUsd }),
+		...(daySpendUsd === undefined ? {} : { daySpendUsd }),
+	};
+}
+
 export function createRouter(deps: RouterDeps): Router {
 	const { config, catalog, ledger, conversations, upstream } = deps;
+	// A Postgres ledger supplies its own reader; a local one is wrapped, so the
+	// prefetch path is identical for both.
+	// The unified ledger IS a reader: `LedgerReader` is the narrow half of it.
+	const reader = deps.reader ?? ledger;
 
 	return {
 		async route(
 			req: NormRequest,
 			opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[]; forceTier?: Tier; forceSlug?: string },
 		): Promise<Decision> {
-			const state = conversations.get(req.conversationKey) ?? conversations.load(req.conversationKey);
+			const state = (await conversations.get(req.conversationKey)) ?? (await conversations.load(req.conversationKey));
 			const snapshot = await catalog.get();
 
 			const priorTokenizer =
 				state.currentSlug === null ? undefined : catalog.find(state.currentSlug)?.tokenizer;
-			const promptTokens = estimatePromptTokens(req, priorTokenizer ?? NEUTRAL_TOKENIZER, ledger);
+			const tokenizer = priorTokenizer ?? NEUTRAL_TOKENIZER;
+			// One ratio, fetched before estimating: the estimate itself runs in
+			// synchronous code that a shared store cannot be read from.
+			const ratio = await ledger.tokenRatio(tokenizer);
+			const promptTokens = estimatePromptTokens(req, tokenizer, ratio);
 			const features = extractFeatures(req, promptTokens);
 
 			let classification: Classification;
@@ -136,7 +207,22 @@ export function createRouter(deps: RouterDeps): Router {
 				classification = await classify(req, features, config, { upstream, ledger, catalog });
 			}
 
-			const policed = applyRequestPolicy(resolveProfile(config, req.requestedModel, req.isSubagent), config, req.policy, opts.forceSlug);
+			const pinnedByModel = pinForRequestedModel(
+				config,
+				snapshot.models.map((m) => m.slug),
+				req.requestedModel,
+				req.requestedModelFull ?? req.requestedModel,
+			);
+			const policed = applyRequestPolicy(
+				resolveProfile(config, req.requestedModel, req.isSubagent),
+				config,
+				req.policy,
+				opts.forceSlug ?? pinnedByModel,
+			);
+			// Every ledger read this turn needs, fetched here rather than inside
+			// `select`: selection stays a synchronous pure function, and a ledger
+			// that can only be read asynchronously (Postgres) works unchanged.
+			const reads = await prefetchTurnReads(reader, req, policed.profile, policed.cfg, snapshot, classification.task);
 			const decision = select({
 				req,
 				features,
@@ -144,9 +230,9 @@ export function createRouter(deps: RouterDeps): Router {
 				profile: policed.profile,
 				state,
 				snapshot,
-				ledger,
 				cfg: policed.cfg,
 				nowMs: Date.now(),
+				reads,
 				...(opts.excludeSlugs === undefined ? {} : { excludeSlugs: opts.excludeSlugs }),
 				...(policed.forceSlug === undefined ? {} : { forceSlug: policed.forceSlug }),
 			});

package/src/router/select.ts

@@ -9,7 +9,7 @@
 import type { CatalogSnapshot } from "../catalog/types.ts";
 import type { ProfileConfig, RouterConfig } from "../config/types.ts";
 import { forecast, priceAt } from "../cost/forecast.ts";
-import type { Ledger } from "../cost/types.ts";
+import type { LedgerSignals, ModelCacheReliability } from "../cost/types.ts";
 import { explorationDraw } from "./explore.ts";
 import type { CompactionEdit, NormRequest, ReasoningLevel } from "../wire/types.ts";
 import { compactedBytes, planCompaction, validatePlan, type CompactionResult } from "./compaction.ts";
@@ -35,7 +35,6 @@ export interface SelectArgs {
 	profile: ProfileConfig;
 	state: ConversationState;
 	snapshot: CatalogSnapshot;
-	ledger: Ledger | null;
 	cfg: RouterConfig;
 	nowMs: number;
 	/**
@@ -49,6 +48,30 @@ export interface SelectArgs {
 	 * stay/switch comparison. Ignored when the catalog has no such model.
 	 */
 	forceSlug?: string;
+	/** Ledger reads already performed for this turn; see TurnReads. */
+	reads?: TurnReads;
+}
+
+/**
+ * Every ledger read a turn needs, fetched BEFORE selection.
+ *
+ * `select` is synchronous on purpose — it is a pure ranking function, and
+ * `explain` depends on being able to run it without side effects. A ledger on
+ * Postgres cannot be read synchronously, so the reads move up to `route`,
+ * which is already async, and arrive here as data. Absent ⇒ read through the
+ * absent reads degrade to no signals rather than reaching for the store.
+ */
+export interface TurnReads {
+	/** Trust and latency per candidate slug; one batch query per signal kind. */
+	signals?: Map<string, LedgerSignals>;
+	/** Observed warm-cache hit rate per slug. */
+	cacheReliability?: Map<string, ModelCacheReliability>;
+	/** What an escalated retry bills per prompt token; null ⇒ the term is inert. */
+	escalationUsdPerPromptToken?: number | null;
+	/** Spend since the start of the UTC month, scoped as the filters say. */
+	monthSpendUsd?: number;
+	/** Spend over the rolling 24h, scoped as the filters say. */
+	daySpendUsd?: number;
 }
 
 /**
@@ -67,7 +90,6 @@ export class BudgetExceededError extends Error {
 // Mid-range completion assumption for forecasts. Long generations amortize
 // into prompt-dominated cost anyway; precision here does not move rankings.
 const EXPECTED_COMPLETION_TOKENS = 1024;
-const DAY_MS = 86_400_000;
 
 /**
  * Authors known to accept replayed assistant reasoning over chat completions:
@@ -129,7 +151,7 @@ export function monthPace(nowMs: number, perMonthUsd: number, spentUsd: number):
 }
 
 export function select(args: SelectArgs): Decision {
-	const { req, features, classification, profile, state, snapshot, ledger, cfg, nowMs } = args;
+	const { req, features, classification, profile, state, snapshot, cfg, nowMs } = args;
 	const reasons: string[] = [];
 	const minI = tierIdx(profile.minTier);
 	const maxI = tierIdx(profile.maxTier);
@@ -351,29 +373,23 @@ export function select(args: SelectArgs): Decision {
 	const warmSlug = cacheWarm ? state.cacheWarmSlug : null;
 	// Expected cache hit for a model: its observed rate once enough warm-expected
 	// samples exist (filters.cacheReliabilityMinSamples), else a reliable 1.
+	const reads = args.reads;
 	const cacheHitExpectation = (slug: string): { rate: number; measured: boolean; samples: number } => {
 		const min = cfg.filters.cacheReliabilityMinSamples;
-		const rel = min > 0 ? (ledger?.cacheReliability?.(slug) ?? null) : null;
+		const rel = min > 0 ? (reads?.cacheReliability?.get(slug) ?? null) : null;
 		if (rel === null || rel.samples < min) return { rate: 1, measured: false, samples: rel?.samples ?? 0 };
 		return { rate: rel.hitRate, measured: true, samples: rel.samples };
 	};
-	// Pre-fetch trust/latency signals for all candidate slugs in one batch
-	// query per signal kind, instead of per-model individual lookups.
-	const candidateSignals =
-		ledger !== null && snapshot.models.length > 0
-			? ledger.signals?.(
-					snapshot.models.map((m) => m.slug),
-					cfg.filters.trustScopedByHarness ? req.harnessId : undefined,
-					cfg.filters.feedbackByTask ? classification.task : undefined,
-				)
-			: undefined;
+	// Trust and latency for every candidate, fetched by `route` before this ran.
+	// There is no fallback read here on purpose: selection is synchronous and the
+	// store may be a shared database, so a missing prefetch must degrade to
+	// "no signals" rather than silently reach for a handle it cannot await.
+	const candidateSignals = reads?.signals;
 	// What an escalated retry has actually been billing per prompt token, for
 	// the escalation-cost term in candidate scoring. Read once per turn; null
 	// (term inert) when the weight is 0 or the ledger has too few samples.
 	const escalationUsdPerPromptToken =
-		cfg.filters.escalationCostWeight > 0
-			? (ledger?.escalationCost?.(cfg.ledger.blendWindowDays)?.usdPerPromptToken ?? null)
-			: null;
+		cfg.filters.escalationCostWeight > 0 ? (reads?.escalationUsdPerPromptToken ?? null) : null;
 	// A pinned slug is admitted the way a config pin is: into the tier's pin
 	// list for this call only, so the quality floor cannot keep it out.
 	const pinSlug = args.forceSlug !== undefined && snapshot.models.some((m) => m.slug === args.forceSlug) ? args.forceSlug : undefined;
@@ -386,7 +402,6 @@ export function select(args: SelectArgs): Decision {
 			tier: t,
 			task: classification.task,
 			snapshot,
-			ledger,
 			cfg: buildCfg,
 			expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
 			warmSlug,
@@ -515,13 +530,15 @@ export function select(args: SelectArgs): Decision {
 	// left, becomes a daily ceiling that tightens as the month runs ahead.
 	let paceNote = "";
 	if (budget.perMonthUsd !== undefined) {
-		const pace = monthPace(nowMs, budget.perMonthUsd, ledger?.spendSince(monthStartMs(nowMs), req.harnessId) ?? 0);
+		const monthSpend = reads?.monthSpendUsd ?? 0;
+		const pace = monthPace(nowMs, budget.perMonthUsd, monthSpend);
 		if (budget.perDayUsd === undefined || pace.dailyCapUsd < budget.perDayUsd) {
 			budget.perDayUsd = pace.dailyCapUsd;
 			paceNote = ` (month pacing: $${pace.spentUsd.toFixed(2)} of $${budget.perMonthUsd} spent, $${pace.dailyCapUsd.toFixed(2)}/day for ${pace.daysLeft} more days)`;
 		}
 	}
-	const daySpend = budget.perDayUsd !== undefined ? (ledger?.spendSince(nowMs - DAY_MS, req.harnessId) ?? 0) : 0;
+	const daySpend =
+		budget.perDayUsd !== undefined ? (reads?.daySpendUsd ?? 0) : 0;
 	const breach = (c: Candidate): string | null => {
 		if (budget.perTurnUsd !== undefined && c.forecast.coldUsd > budget.perTurnUsd) {
 			return `cold forecast $${c.forecast.coldUsd.toFixed(4)} > per-turn budget $${budget.perTurnUsd}`;