auto-model-router 0.1.0

package/src/cost/blended.ts

@@ -0,0 +1,80 @@
+/**
+ * Blended rate: the spend-weighted average price per million tokens, over a
+ * rolling window, that omp displays as "what tokens cost through this router".
+ *
+ * The ledger stores each entry's REPORTED total and the component split its
+ * own model pricing implies (`cost_breakdown`). OpenRouter gives us no
+ * per-component reported prices, so each entry's reported dollars are
+ * apportioned across buckets in proportion to its predicted component split —
+ * exact when our pricing matches theirs, and self-correcting via the reported
+ * total when it does not.
+ */
+
+import type { Database } from "bun:sqlite";
+import type { RouterConfig } from "../config/types.ts";
+import type { BlendedRate, CostBreakdown, UsageCounts } from "./types.ts";
+
+interface BlendRow {
+	usage: string;
+	reported_usd: number;
+	cost_breakdown: string;
+}
+
+// Buckets with no window traffic still need a rate for the display; these are
+// the typical Anthropic-style relative prices, used only as display priors.
+const OUTPUT_TO_INPUT_PRIOR = 5;
+const CACHE_READ_TO_INPUT_PRIOR = 0.1;
+const CACHE_WRITE_TO_INPUT_PRIOR = 1.25;
+
+export function computeBlendedRate(db: Database, cfg: RouterConfig, windowDays: number): BlendedRate | null {
+	const sinceMs = Date.now() - windowDays * 86_400_000;
+	// We own the schema; row shape fixed by util/sqlite.ts and cost/ledger.ts.
+	const rows = db
+		.query(
+			`SELECT usage, reported_usd, cost_breakdown FROM ledger
+			 WHERE created_at_ms >= ? AND reported_usd IS NOT NULL AND cost_breakdown IS NOT NULL`,
+		)
+		.all(sinceMs) as BlendRow[];
+
+	let sampleCount = 0;
+	let inputUsd = 0;
+	let inputTokens = 0;
+	let outputUsd = 0;
+	let outputTokens = 0;
+	let cacheReadUsd = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteUsd = 0;
+	let cacheWriteTokens = 0;
+
+	for (const row of rows) {
+		const usage = JSON.parse(row.usage) as UsageCounts;
+		const split = JSON.parse(row.cost_breakdown) as CostBreakdown;
+		const tokenSplit = split.freshPrompt + split.cacheRead + split.cacheWrite + split.completion + split.reasoning;
+		// Entries whose usage produced no token-billed cost (pure image/request
+		// billing) carry no price signal per token; skip them.
+		if (tokenSplit <= 0) continue;
+		const freshTokens = Math.max(usage.promptTokens - usage.cachedTokens - usage.cacheWriteTokens, 0);
+
+		inputUsd += (row.reported_usd * split.freshPrompt) / tokenSplit;
+		inputTokens += freshTokens;
+		outputUsd += (row.reported_usd * (split.completion + split.reasoning)) / tokenSplit;
+		outputTokens += usage.completionTokens;
+		cacheReadUsd += (row.reported_usd * split.cacheRead) / tokenSplit;
+		cacheReadTokens += usage.cachedTokens;
+		cacheWriteUsd += (row.reported_usd * split.cacheWrite) / tokenSplit;
+		cacheWriteTokens += usage.cacheWriteTokens;
+		sampleCount += 1;
+	}
+
+	if (sampleCount < cfg.ledger.blendMinSamples) return null;
+
+	const inputPerMtok = inputTokens > 0 ? (inputUsd / inputTokens) * 1e6 : 0;
+	return {
+		inputPerMtok,
+		outputPerMtok: outputTokens > 0 ? (outputUsd / outputTokens) * 1e6 : inputPerMtok * OUTPUT_TO_INPUT_PRIOR,
+		cacheReadPerMtok: cacheReadTokens > 0 ? (cacheReadUsd / cacheReadTokens) * 1e6 : inputPerMtok * CACHE_READ_TO_INPUT_PRIOR,
+		cacheWritePerMtok: cacheWriteTokens > 0 ? (cacheWriteUsd / cacheWriteTokens) * 1e6 : inputPerMtok * CACHE_WRITE_TO_INPUT_PRIOR,
+		sampleCount,
+		windowDays,
+	};
+}

package/src/cost/forecast.ts

@@ -0,0 +1,129 @@
+/**
+ * Cost arithmetic. This is the only place token counts become dollars, so
+ * the billing subtleties live here exactly once:
+ *
+ *  - `usage.promptTokens` INCLUDES cached tokens (OpenAI/OpenRouter
+ *    convention), so fresh tokens are what remains after subtracting cache
+ *    reads and writes.
+ *  - `usage.reasoningTokens` is a SUBSET of `completionTokens`; billing both
+ *    at full rate would double-count. When the model publishes no separate
+ *    reasoning rate, completion swallows reasoning at the completion price.
+ */
+
+import type { CatalogModel, Price } from "../catalog/types.ts";
+import type { CostBreakdown, CostForecast, UsageCounts } from "./types.ts";
+
+/** Highest override tier applicable at this prompt size; base price below every threshold. */
+export function priceAt(model: CatalogModel, promptTokens: number): Price {
+	// priceTiers is sorted ascending by minPromptTokens, so the last match wins.
+	let price = model.price;
+	for (const tier of model.priceTiers) {
+		if (tier.minPromptTokens <= promptTokens) price = tier.price;
+	}
+	return price;
+}
+
+function tierThresholdAt(model: CatalogModel, promptTokens: number): number {
+	let threshold = 0;
+	for (const tier of model.priceTiers) {
+		if (tier.minPromptTokens <= promptTokens) threshold = tier.minPromptTokens;
+	}
+	return threshold;
+}
+
+function clampCount(value: number, max: number): number {
+	return Math.min(Math.max(value, 0), max);
+}
+
+export function computeCost(model: CatalogModel, usage: UsageCounts): CostBreakdown {
+	const price = priceAt(model, usage.promptTokens);
+
+	const cachedTokens = clampCount(usage.cachedTokens, usage.promptTokens);
+	const cacheWriteTokens = clampCount(usage.cacheWriteTokens, usage.promptTokens - cachedTokens);
+	const freshTokens = Math.max(usage.promptTokens - cachedTokens - cacheWriteTokens, 0);
+	const reasoningTokens = clampCount(usage.reasoningTokens, usage.completionTokens);
+
+	const freshPrompt = freshTokens * price.prompt;
+	// Unpublished cache rates fall back to the full prompt price: absence of a
+	// published discount must never become a predicted discount.
+	const cacheRead = cachedTokens * (price.cacheRead ?? price.prompt);
+	const cacheWrite = cacheWriteTokens * (price.cacheWrite ?? price.prompt);
+
+	let completion: number;
+	let reasoning: number;
+	if (price.reasoning !== undefined) {
+		reasoning = reasoningTokens * price.reasoning;
+		completion = (usage.completionTokens - reasoningTokens) * price.completion;
+	} else {
+		reasoning = 0;
+		completion = usage.completionTokens * price.completion;
+	}
+
+	const images = usage.images * (price.image ?? 0);
+	const request = price.request ?? 0;
+
+	return {
+		freshPrompt,
+		cacheRead,
+		cacheWrite,
+		completion,
+		reasoning,
+		images,
+		request,
+		total: freshPrompt + cacheRead + cacheWrite + completion + reasoning + images + request,
+		tierAtPromptTokens: tierThresholdAt(model, usage.promptTokens),
+	};
+}
+
+export function forecast(
+	model: CatalogModel,
+	args: { promptTokens: number; completionTokens: number; cacheHitRate: number; images: number },
+): CostForecast {
+	const cacheHitRate = Math.min(Math.max(args.cacheHitRate, 0), 1);
+	const usage: UsageCounts = {
+		promptTokens: args.promptTokens,
+		cachedTokens: Math.round(args.promptTokens * cacheHitRate),
+		cacheWriteTokens: 0,
+		completionTokens: args.completionTokens,
+		reasoningTokens: 0,
+		images: args.images,
+	};
+	const breakdown = computeCost(model, usage);
+
+	// The worst case a budget guard must survive is a completely cold cache.
+	// That is the MAX of two computations: no cache activity at all, and a
+	// full first-time cache write. Taking the write case alone would understate
+	// models (several Geminis) whose published cache-write rate is BELOW their
+	// prompt rate; taking the no-cache case alone would understate Anthropic-
+	// style models whose write rate is a premium over prompt.
+	const coldNoCache = computeCost(model, {
+		promptTokens: args.promptTokens,
+		cachedTokens: 0,
+		cacheWriteTokens: 0,
+		completionTokens: args.completionTokens,
+		reasoningTokens: 0,
+		images: args.images,
+	});
+	let coldUsd = coldNoCache.total;
+	if (priceAt(model, args.promptTokens).cacheWrite !== undefined) {
+		const coldFullWrite = computeCost(model, {
+			promptTokens: args.promptTokens,
+			cachedTokens: 0,
+			cacheWriteTokens: args.promptTokens,
+			completionTokens: args.completionTokens,
+			reasoningTokens: 0,
+			images: args.images,
+		});
+		coldUsd = Math.max(coldUsd, coldFullWrite.total);
+	}
+
+	return {
+		slug: model.slug,
+		expectedUsd: breakdown.total,
+		coldUsd,
+		breakdown,
+		assumedPromptTokens: args.promptTokens,
+		assumedCompletionTokens: args.completionTokens,
+		assumedCacheHitRate: cacheHitRate,
+	};
+}

package/src/cost/ledger.ts

@@ -0,0 +1,291 @@
+/**
+ * The spend ledger: one row per dispatched generation, plus the two derived
+ * signals the router consumes — per-model trust (Laplace-smoothed success) and
+ * per-tokenizer-family token calibration.
+ *
+ * `record` also persists the cost component split implied by the entry's own
+ * model pricing (`cost_breakdown`). The split needs catalog prices, which the
+ * ledger does not receive; it reads them back from the `catalog_cache` row the
+ * catalog slice already persists, re-normalized lazily and re-read only when
+ * the cache's `fetched_at_ms` changes. An entry recorded before the first
+ * catalog fetch simply stores NULL and is skipped by the blended rate.
+ */
+
+import type { Database } from "bun:sqlite";
+import { normalizeCatalogModel } from "../catalog/openrouter-catalog.ts";
+import type { CatalogModel } from "../catalog/types.ts";
+import type { RouterConfig } from "../config/types.ts";
+import { consumePendingEstimate } from "../tokens/estimate.ts";
+import { computeBlendedRate } from "./blended.ts";
+import { computeCost } from "./forecast.ts";
+import type { BlendedRate, Ledger, LedgerEntry, ModelTrust, UsageCounts } from "./types.ts";
+
+/** Estimates below this many samples are noise; the default ratio is better. */
+const MIN_CALIBRATION_SAMPLES = 20;
+
+// Row shapes below are fixed by our own schema in util/sqlite.ts.
+interface LedgerRow {
+	id: string;
+	created_at_ms: number;
+	conversation_key: string;
+	session_id: string;
+	turn: number;
+	requested_model: string;
+	harness_id: string;
+	slug: string;
+	served_slug: string | null;
+	tier: string;
+	classification_source: string;
+	reasons: string;
+	predicted_usd: number;
+	reported_usd: number | null;
+	usage: string;
+	cost_breakdown: string | null;
+	attempt: number;
+	escalation_signal: string | null;
+	latency_ms: number;
+	ttft_ms: number | null;
+	finish_reason: string | null;
+	wasted: number;
+	upstream_generation_id: string | null;
+	error: string | null;
+}
+
+interface TrustRow {
+	attempts: number;
+	escalations: number;
+	errors: number;
+	failures: number;
+	mean_cost_error: number | null;
+}
+
+interface CalibrationRow {
+	est_bytes: number;
+	actual_tokens: number;
+	samples: number;
+}
+
+/**
+ * Error kinds that say nothing about a MODEL's reliability, and so must not
+ * count against its trust:
+ *  - `aborted`: the client hung up (user pressed escape mid-turn).
+ *  - `auth`: credential, credit, or account-policy refusal (age confirmation,
+ *    prompt-injection blocking) — identical for every model on the key.
+ *  - `model_unavailable`: the guardrail or data policy excludes the endpoint;
+ *    an availability fact, not a quality one, and failover already handles it.
+ *
+ * Everything else (upstream_error, timeout, network, rate_limit, …) stays
+ * attributable. A NULL `error_kind` on a row that HAS an error is an
+ * unclassifiable legacy row and stays attributable, preserving the old,
+ * stricter behaviour rather than silently forgiving it.
+ */
+const UNATTRIBUTABLE_KINDS = "('aborted', 'auth', 'model_unavailable')";
+
+const ATTRIBUTABLE_ERROR = `error IS NOT NULL AND (error_kind IS NULL OR error_kind NOT IN ${UNATTRIBUTABLE_KINDS})`;
+
+const TRUST_SELECT = `COUNT(*) AS attempts,
+		COALESCE(SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END), 0) AS escalations,
+		COALESCE(SUM(CASE WHEN ${ATTRIBUTABLE_ERROR} THEN 1 ELSE 0 END), 0) AS errors,
+		COALESCE(SUM(CASE WHEN escalation_signal IS NOT NULL OR (${ATTRIBUTABLE_ERROR}) THEN 1 ELSE 0 END), 0) AS failures,
+		AVG(CASE WHEN reported_usd IS NOT NULL AND reported_usd > 0
+			THEN ABS(reported_usd - predicted_usd) / reported_usd END) AS mean_cost_error`;
+
+/**
+ * Recovers the `UpstreamErrorKind` from the text turn.ts stored.
+ *
+ * Errors are written as `"<kind>: <message>"`, except the abort path which
+ * writes the bare message. Returning null for anything unrecognised keeps that
+ * row model-attributable — the stricter reading — rather than quietly
+ * forgiving a failure we cannot classify.
+ */
+function errorKindOf(error: string | null): string | null {
+	if (error === null) return null;
+	if (error === "request aborted") return "aborted";
+	const sep = error.indexOf(": ");
+	if (sep <= 0) return null;
+	return error.slice(0, sep);
+}
+
+function toTrust(slug: string, row: TrustRow): ModelTrust {
+	// Laplace smoothing: an untried model scores a neutral 1/2, and a failure
+	// is an attempt superseded by an escalation or ended in an upstream error.
+	return {
+		slug,
+		attempts: row.attempts,
+		escalations: row.escalations,
+		errors: row.errors,
+		successRate: (row.attempts - row.failures + 1) / (row.attempts + 2),
+		meanCostError: row.mean_cost_error ?? 0,
+	};
+}
+
+function toEntry(row: LedgerRow): LedgerEntry {
+	return {
+		id: row.id,
+		createdAtMs: row.created_at_ms,
+		conversationKey: row.conversation_key,
+		sessionId: row.session_id,
+		turn: row.turn,
+		requestedModel: row.requested_model,
+		harnessId: row.harness_id,
+		slug: row.slug,
+		servedSlug: row.served_slug,
+		tier: row.tier,
+		classificationSource: row.classification_source,
+		reasons: JSON.parse(row.reasons) as string[],
+		predictedUsd: row.predicted_usd,
+		reportedUsd: row.reported_usd,
+		usage: JSON.parse(row.usage) as UsageCounts,
+		attempt: row.attempt,
+		escalationSignal: row.escalation_signal,
+		latencyMs: row.latency_ms,
+		ttftMs: row.ttft_ms,
+		finishReason: row.finish_reason,
+		wasted: row.wasted === 1,
+		upstreamGenerationId: row.upstream_generation_id,
+		error: row.error,
+	};
+}
+
+export function createLedger(db: Database, cfg: RouterConfig): Ledger {
+	// Prepared once: record() runs on every turn.
+	const insertStmt = db.query(
+		`INSERT INTO ledger (
+			id, created_at_ms, conversation_key, session_id, turn, requested_model, harness_id, slug, served_slug,
+			tier, classification_source, reasons, predicted_usd, reported_usd, usage, cost_breakdown,
+			attempt, escalation_signal, latency_ms, ttft_ms, finish_reason, wasted, upstream_generation_id, error,
+			error_kind
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+	);
+	const calibrationStmt = db.query(
+		`INSERT INTO token_calibration (tokenizer, est_bytes, actual_tokens, samples) VALUES (?, ?, ?, 1)
+		 ON CONFLICT(tokenizer) DO UPDATE SET
+			est_bytes = est_bytes + excluded.est_bytes,
+			actual_tokens = actual_tokens + excluded.actual_tokens,
+			samples = samples + 1`,
+	);
+	const spendByConversationStmt = db.query(
+		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE conversation_key = ?",
+	);
+	const spendSinceStmt = db.query(
+		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE created_at_ms >= ?",
+	);
+	const spendSinceHarnessStmt = db.query(
+		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE created_at_ms >= ? AND harness_id = ?",
+	);
+	const trustStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ?`);
+	const trustHarnessStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ? AND harness_id = ?`);
+	const allTrustStmt = db.query(`SELECT slug, ${TRUST_SELECT} FROM ledger GROUP BY slug`);
+	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
+	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
+	const cacheMetaStmt = db.query("SELECT fetched_at_ms FROM catalog_cache WHERE id = 1");
+	const cachePayloadStmt = db.query("SELECT payload FROM catalog_cache WHERE id = 1");
+
+	let indexFetchedAtMs = -1;
+	let modelBySlug: Map<string, CatalogModel> | null = null;
+
+	/** Slug → catalog model, rebuilt only when the catalog cache row changes. */
+	function priceIndex(): Map<string, CatalogModel> | null {
+		const meta = cacheMetaStmt.get() as { fetched_at_ms: number } | null;
+		if (meta === null) return null;
+		if (modelBySlug !== null && indexFetchedAtMs === meta.fetched_at_ms) return modelBySlug;
+		const row = cachePayloadStmt.get() as { payload: string } | null;
+		if (row === null) return null;
+		const payload: unknown = JSON.parse(row.payload);
+		if (!Array.isArray(payload)) return null;
+		const map = new Map<string, CatalogModel>();
+		for (const record of payload) {
+			const model = normalizeCatalogModel(record);
+			if (model !== null) map.set(model.slug, model);
+		}
+		modelBySlug = map;
+		indexFetchedAtMs = meta.fetched_at_ms;
+		return map;
+	}
+
+	return {
+		record(entry: LedgerEntry): void {
+			const models = priceIndex();
+			const model = (entry.servedSlug !== null ? models?.get(entry.servedSlug) : undefined) ?? models?.get(entry.slug) ?? null;
+			insertStmt.run(
+				entry.id,
+				entry.createdAtMs,
+				entry.conversationKey,
+				entry.sessionId,
+				entry.turn,
+				entry.requestedModel,
+				entry.harnessId,
+				entry.slug,
+				entry.servedSlug,
+				entry.tier,
+				entry.classificationSource,
+				JSON.stringify(entry.reasons),
+				entry.predictedUsd,
+				entry.reportedUsd,
+				JSON.stringify(entry.usage),
+				model !== null ? JSON.stringify(computeCost(model, entry.usage)) : null,
+				entry.attempt,
+				entry.escalationSignal,
+				entry.latencyMs,
+				entry.ttftMs,
+				entry.finishReason,
+				entry.wasted ? 1 : 0,
+				entry.upstreamGenerationId,
+				entry.error,
+				errorKindOf(entry.error),
+			);
+			// Always consume the pending estimate, even when the turn failed, so a
+			// dead turn's bytes can never pair with a later turn's tokens. Only
+			// actually-billed prompt tokens calibrate.
+			const pending = consumePendingEstimate(entry.conversationKey);
+			if (entry.usage.promptTokens > 0 && pending !== null) {
+				// The SERVED model's tokenizer produced the billing; the estimate-time
+				// family is the fallback when the model is unknown to the catalog.
+				const tokenizer = (model?.tokenizer ?? pending.tokenizer).trim().toLowerCase();
+				calibrationStmt.run(tokenizer, pending.bytes, entry.usage.promptTokens);
+			}
+		},
+
+		conversationSpend(conversationKey: string): number {
+			const row = spendByConversationStmt.get(conversationKey) as { total: number } | null;
+			return row?.total ?? 0;
+		},
+
+		spendSince(sinceMs: number, harnessId?: string): number {
+			const row =
+				harnessId !== undefined && harnessId !== ""
+					? (spendSinceHarnessStmt.get(sinceMs, harnessId) as { total: number } | null)
+					: (spendSinceStmt.get(sinceMs) as { total: number } | null);
+			return row?.total ?? 0;
+		},
+
+		blendedRate(windowDays: number): BlendedRate | null {
+			return computeBlendedRate(db, cfg, windowDays);
+		},
+
+		trust(slug: string, harnessId?: string): ModelTrust | null {
+			const row =
+				harnessId !== undefined && harnessId !== ""
+					? (trustHarnessStmt.get(slug, harnessId) as TrustRow | null)
+					: (trustStmt.get(slug) as TrustRow | null);
+			if (row === null || row.attempts === 0) return null;
+			return toTrust(slug, row);
+		},
+
+		allTrust(): ModelTrust[] {
+			const rows = allTrustStmt.all() as (TrustRow & { slug: string })[];
+			return rows.map((row) => toTrust(row.slug, row));
+		},
+
+		tokenRatio(tokenizer: string): number | null {
+			const row = ratioStmt.get(tokenizer.trim().toLowerCase()) as CalibrationRow | null;
+			if (row === null || row.samples < MIN_CALIBRATION_SAMPLES || row.actual_tokens <= 0) return null;
+			return row.est_bytes / row.actual_tokens;
+		},
+
+		recentEntries(limit: number): LedgerEntry[] {
+			const rows = recentStmt.all(limit) as LedgerRow[];
+			return rows.map(toEntry);
+		},
+	};
+}

package/src/cost/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Cost prediction, reconciliation, and the spend ledger.
+ *
+ * Two numbers exist for every request and they are never conflated:
+ *  - **predicted**: our arithmetic over the catalog, computed *before* dispatch.
+ *    Drives routing and budget enforcement.
+ *  - **reported**: `usage.cost` returned by OpenRouter, authoritative after the
+ *    fact. Drives the ledger, `stats`, and prediction-error calibration.
+ */
+
+/** Token counts for one upstream generation. */
+export interface UsageCounts {
+	/** Total prompt tokens, *including* `cachedTokens` (OpenAI/OpenRouter convention). */
+	promptTokens: number;
+	/** Prompt tokens served from cache (`prompt_tokens_details.cached_tokens`). */
+	cachedTokens: number;
+	/** Prompt tokens written to cache (`prompt_tokens_details.cache_write_tokens`). */
+	cacheWriteTokens: number;
+	completionTokens: number;
+	/** `completion_tokens_details.reasoning_tokens`. Subset of completion tokens. */
+	reasoningTokens: number;
+	/** Images in the prompt, for per-image surcharges. */
+	images: number;
+}
+
+export const EMPTY_USAGE: UsageCounts = {
+	promptTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+	completionTokens: 0,
+	reasoningTokens: 0,
+	images: 0,
+};
+
+/** Per-component cost decomposition, USD. Components sum to `total`. */
+export interface CostBreakdown {
+	freshPrompt: number;
+	cacheRead: number;
+	cacheWrite: number;
+	completion: number;
+	reasoning: number;
+	images: number;
+	request: number;
+	total: number;
+	/** Which price tier was applied (`minPromptTokens` of the winning tier, 0 = base). */
+	tierAtPromptTokens: number;
+}
+
+/** What a candidate model is expected to cost for a pending request. */
+export interface CostForecast {
+	slug: string;
+	/** Expected total, USD. */
+	expectedUsd: number;
+	/** Forecast assuming zero cache hits — the worst case a budget guard must survive. */
+	coldUsd: number;
+	breakdown: CostBreakdown;
+	/** Prompt tokens the forecast assumed. */
+	assumedPromptTokens: number;
+	/** Completion tokens the forecast assumed. */
+	assumedCompletionTokens: number;
+	/** Fraction of prompt tokens assumed to hit cache, 0-1. */
+	assumedCacheHitRate: number;
+}
+
+/** One dispatched upstream generation, successful or not. */
+export interface LedgerEntry {
+	id: string;
+	createdAtMs: number;
+	conversationKey: string;
+	sessionId: string;
+	/** Turn index within the conversation, 1-based. */
+	turn: number;
+	/** Virtual model omp asked for, e.g. `auto`. */
+	requestedModel: string;
+	/** Harness id from the request header; empty for the default harness. */
+	harnessId: string;
+	/** Concrete slug we dispatched to. */
+	slug: string;
+	/** Slug that actually served it, per the response `model` field. */
+	servedSlug: string | null;
+	tier: string;
+	classificationSource: string;
+	/** Human-readable decision trail. */
+	reasons: string[];
+	predictedUsd: number;
+	reportedUsd: number | null;
+	usage: UsageCounts;
+	/** Attempt index within this turn; >0 means this was an escalation retry. */
+	attempt: number;
+	/** Why this attempt was superseded, if it was. */
+	escalationSignal: string | null;
+	/** Wall-clock ms from dispatch to final chunk. */
+	latencyMs: number;
+	/** Time to first content token, ms. */
+	ttftMs: number | null;
+	finishReason: string | null;
+	/** Tokens billed but discarded because the attempt was aborted and retried. */
+	wasted: boolean;
+	upstreamGenerationId: string | null;
+	error: string | null;
+}
+
+/** Rolling blended rate used to keep omp's cost display honest. */
+export interface BlendedRate {
+	/** USD per million prompt tokens, spend-weighted over the window. */
+	inputPerMtok: number;
+	/** USD per million completion tokens, spend-weighted over the window. */
+	outputPerMtok: number;
+	/** USD per million cached prompt tokens. */
+	cacheReadPerMtok: number;
+	/** USD per million cache-write tokens. */
+	cacheWritePerMtok: number;
+	/** Requests the blend is based on. Low counts ⇒ fall back to a config default. */
+	sampleCount: number;
+	windowDays: number;
+}
+
+/** Per-model reliability learned from our own traffic. Feeds candidate scoring. */
+export interface ModelTrust {
+	slug: string;
+	attempts: number;
+	/** Attempts superseded by an escalation. */
+	escalations: number;
+	/** Attempts that ended in an upstream error. */
+	errors: number;
+	/** Laplace-smoothed success rate, 0-1. */
+	successRate: number;
+	/** Mean absolute relative prediction error, for forecast calibration. */
+	meanCostError: number;
+}
+
+export interface Ledger {
+	record(entry: LedgerEntry): void;
+	/** Total reported (or predicted, when reported is null) spend for a conversation. */
+	conversationSpend(conversationKey: string): number;
+	/**
+	 * Total spend since a wall-clock instant. When `harnessId` is non-empty,
+	 * scoped to that harness only; empty ⇒ all harnesses (global).
+	 */
+	spendSince(sinceMs: number, harnessId?: string): number;
+	blendedRate(windowDays: number): BlendedRate | null;
+	/** Per-model reliability over the ledger, optionally scoped to a harness. */
+	trust(slug: string, harnessId?: string): ModelTrust | null;
+	allTrust(): ModelTrust[];
+	/** Observed chars-per-token ratio for a tokenizer family; null until calibrated. */
+	tokenRatio(tokenizer: string): number | null;
+	recentEntries(limit: number): LedgerEntry[];
+}