@danypops/jittor 0.17.0 → 0.18.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Just-in-Time Token Optimization Router for Pi -- token and context observability with optimization policies",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
-  "keywords": ["pi-package", "llm-router", "token-budget"],
+  "keywords": ["llm-router", "token-budget"],
   "bin": {
     "jittor": "src/cli.ts"
   },
@@ -15,6 +15,17 @@
     "serve": "bun src/cli.ts serve",
     "service:install": "bun src/cli.ts service install"
   },
+  "packed": {
+    "daemonService": {
+      "name": "jittor",
+      "displayName": "Jittor",
+      "binPath": "src/cli.ts",
+      "args": ["serve"],
+      "handleFilename": "daemon.json",
+      "restartOnFailure": true,
+      "restartSec": 2
+    }
+  },
   "dependencies": {
     "@danypops/vehicle-core": "^0.12.1",
     "@danypops/vehicle-server": "^0.17.0",

package/src/cli-commands/cache.ts

@@ -0,0 +1,120 @@
+import type {
+	CacheEconomicsAggregateTotals,
+	CacheEconomicsModelSummary,
+	CacheEconomicsStablePrefixPoint,
+	CacheEconomicsSummary,
+	CacheEconomicsTaskSummary,
+	CacheEconomicsUnattributedActivity,
+} from "../observability/cache-economics.ts";
+import { type CliDependencies, callAndPrint, humanField } from "./support.ts";
+
+export const CACHE_USAGE_LINES = ["  cache economics --since <ms> --until <ms> [--json]"];
+
+interface CacheEconomicsArgs {
+	since: number;
+	until: number;
+	json: boolean;
+}
+
+function parseCacheArgs(action: string | undefined, args: string[]): CacheEconomicsArgs | null {
+	if (action !== "economics") return null;
+	let json = false;
+	let since: number | undefined;
+	let until: number | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") {
+			json = true;
+			continue;
+		}
+		if (argument !== "--since" && argument !== "--until") return null;
+		const raw = args[++index];
+		const value = raw === undefined ? Number.NaN : Number(raw);
+		if (!Number.isSafeInteger(value) || value < 0) return null;
+		if (argument === "--since") since = value;
+		else until = value;
+	}
+	if (since === undefined || until === undefined || until < since) return null;
+	return { since, until, json };
+}
+
+function formatUsdAmount(amount: number): string {
+	return `$${amount.toFixed(Math.abs(amount) < 0.01 && amount !== 0 ? 4 : 2)}`;
+}
+
+function basisSuffix(basis: "provider-reported" | "catalog-estimate" | "unknown"): string {
+	return basis === "provider-reported" ? "" : basis === "catalog-estimate" ? " (catalog estimate)" : "";
+}
+
+function formatCostField(amountUsd: number | null, basis: "provider-reported" | "catalog-estimate" | "unknown"): string {
+	return amountUsd === null ? "unknown" : `${formatUsdAmount(amountUsd)}${basisSuffix(basis)}`;
+}
+
+function formatAggregateFields(totals: CacheEconomicsAggregateTotals): string {
+	const payback = totals.paybackAchieved === null ? "n/a" : totals.paybackAchieved ? "yes" : "not yet";
+	return [
+		`read ${totals.cacheReadTokens.toLocaleString()} tok (${formatCostField(totals.cacheReadCostUsd, totals.cacheReadCostBasis)})`,
+		`write ${totals.cacheWriteTokens.toLocaleString()} tok (${formatCostField(totals.cacheWriteCostUsd, totals.cacheWriteCostBasis)})`,
+		`savings ${totals.savingsUsd === null ? "unknown" : formatUsdAmount(totals.savingsUsd)}`,
+		`premium ${totals.cacheWritePremiumUsd === null ? "unknown" : formatUsdAmount(totals.cacheWritePremiumUsd)}`,
+		`break-even ${totals.breakEvenReadTokens === null ? "unknown" : `${totals.breakEvenReadTokens.toLocaleString()} tok`}`,
+		`payback ${payback}`,
+	].join(" · ");
+}
+
+function formatFreshnessSuffix(catalogFreshness: "fresh" | "stale" | null): string {
+	return catalogFreshness === "stale" ? " (stale catalog snapshot used for the estimate(s) above)" : "";
+}
+
+function formatModelLine(model: CacheEconomicsModelSummary): string {
+	return `- ${humanField(model.provider)}/${humanField(model.model)}: ${formatAggregateFields(model)}${formatFreshnessSuffix(model.catalogFreshness)}`;
+}
+
+function formatTaskLine(task: CacheEconomicsTaskSummary): string {
+	return `- ${humanField(task.taskId)}: ${formatAggregateFields(task)}${formatFreshnessSuffix(task.catalogFreshness)}`;
+}
+
+function formatUnattributedLine(activity: CacheEconomicsUnattributedActivity): string {
+	return [
+		`Unattributed cache activity (no Papyrus task focused):`,
+		`read ${activity.cacheReadTokens.toLocaleString()} tok (${formatCostField(activity.cacheReadCostUsd, activity.cacheReadCostBasis)})`,
+		`write ${activity.cacheWriteTokens.toLocaleString()} tok (${formatCostField(activity.cacheWriteCostUsd, activity.cacheWriteCostBasis)})`,
+	].join(" · ");
+}
+
+function formatChurnPoint(point: CacheEconomicsStablePrefixPoint): string {
+	return `- ${new Date(point.observedAt).toISOString()} session ${humanField(point.sessionId)}: ${point.stablePrefixTokens.toLocaleString()} tok${point.resetReason === null ? "" : ` (${point.resetReason} reset)`}`;
+}
+
+export function formatCacheEconomics(summary: CacheEconomicsSummary): string {
+	const lines = [
+		`Cache economics: ${summary.models.length.toLocaleString()} model(s)${summary.truncated ? " (query limit reached; totals are a lower bound)" : ""}`,
+		...summary.models.map(formatModelLine),
+		`By task: ${summary.tasks.length.toLocaleString()} task(s)`,
+		...summary.tasks.map(formatTaskLine),
+		formatUnattributedLine(summary.unattributedCacheActivity),
+		...(summary.stablePrefixChurn.length > 0
+			? [
+					`Stable-prefix churn (${summary.stablePrefixChurn.length.toLocaleString()} snapshot(s), oldest first):`,
+					...summary.stablePrefixChurn.map(formatChurnPoint),
+				]
+			: []),
+		`Candidate missed-cache opportunities: ${summary.missedOpportunities.length.toLocaleString()}`,
+		...summary.missedOpportunities.map(
+			(candidate) =>
+				`- session ${humanField(candidate.sessionId)}: ${candidate.resetReason} reset, then ${candidate.cacheWriteTokens.toLocaleString()} cache-write tok${candidate.cacheWriteCostUsd === null ? "" : ` (${formatUsdAmount(candidate.cacheWriteCostUsd)})`} -- ${candidate.note}`,
+		),
+	];
+	return lines.join("\n");
+}
+
+export async function runCacheCommand(
+	action: string | undefined,
+	rest: string[],
+	deps: CliDependencies,
+	usage: () => number,
+): Promise<number> {
+	const parsed = parseCacheArgs(action, rest);
+	if (!parsed) return usage();
+	return callAndPrint(deps, "cache.economics", { since: parsed.since, until: parsed.until }, parsed.json, formatCacheEconomics);
+}

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from "node:url";
 import { BACKFILL_USAGE_LINES, formatUsageImportResult, formatUsageImportStatus, runBackfillCommand } from "./cli-commands/backfill.ts";
 import { BENCHMARKS_USAGE_LINES, runBenchmarksCommand } from "./cli-commands/benchmarks.ts";
+import { CACHE_USAGE_LINES, formatCacheEconomics, runCacheCommand } from "./cli-commands/cache.ts";
 import { CATALOG_USAGE_LINES, formatCatalogQuery, formatCatalogStatus, runCatalogCommand } from "./cli-commands/catalog.ts";
 import { runCompactionCommand } from "./cli-commands/compaction.ts";
 import { CONTEXT_USAGE_LINES, formatContextAssessment, formatContextDelta, runContextCommand } from "./cli-commands/context.ts";
@@ -19,6 +20,7 @@ import { connectJittorClient } from "./vehicle/client.ts";
 // directly from cli.ts rather than reaching into src/cli-commands/*.
 export type { CliDependencies };
 export {
+	formatCacheEconomics,
 	formatCatalogQuery,
 	formatCatalogStatus,
 	formatContextAssessment,
@@ -54,6 +56,7 @@ function usage(stderr: (line: string) => void): number {
 			...CONTEXT_USAGE_LINES,
 			...BENCHMARKS_USAGE_LINES,
 			...CATALOG_USAGE_LINES,
+			...CACHE_USAGE_LINES,
 			...METRICS_USAGE_LINES,
 			...ROUTER_USAGE_LINES,
 			...SESSION_USAGE_LINES,
@@ -96,6 +99,8 @@ export async function runCli(args: string[], deps: CliDependencies = DEFAULT_DEP
 			return runBenchmarksCommand(action, rest, deps, fail);
 		case "catalog":
 			return runCatalogCommand(action, rest, deps, fail);
+		case "cache":
+			return runCacheCommand(action, rest, deps, fail);
 		case "context":
 			return runContextCommand(action, rest, deps, fail);
 		case "service":

package/src/constants.ts

@@ -69,6 +69,19 @@ export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
 export const TASK_FOCUS_EVENT_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
 export const TASK_FOCUS_ID_MAX_LENGTH = 200;
 export const TASK_COST_QUERY_LIMIT = 10_000;
+export const CACHE_ECONOMICS_QUERY_LIMIT = 10_000;
+export const CACHE_ECONOMICS_MAX_MODEL_GROUPS = 500;
+/** Bounds the per-task rollup the same way CACHE_ECONOMICS_MAX_MODEL_GROUPS bounds the per-model one -- applied post-hoc (sorted by activity, then sliced) rather than at row-intake time, since realistic task cardinality in one window is small. */
+export const CACHE_ECONOMICS_MAX_TASK_GROUPS = 500;
+/** Bounds the stable-prefix-churn time series; the most recent points are kept (oldest dropped first) since a trend view cares most about what's recent. */
+export const CACHE_ECONOMICS_MAX_STABLE_PREFIX_POINTS = 500;
+export const CACHE_ECONOMICS_MAX_MISSED_OPPORTUNITIES = 100;
+/** How soon after a context-prefix reset (session/provider/model change) a same-session cache-write still counts as a candidate cache-loss consequence of that reset, not an unrelated later write. */
+export const CACHE_ECONOMICS_LOSS_CORRELATION_WINDOW_MS = 5 * MILLISECONDS_PER_MINUTE;
+/** models.dev (and Jittor's catalog) quote pricing per one million tokens; catalog-estimate math divides by this to get a per-token rate. */
+export const CATALOG_PRICE_TOKEN_UNIT = 1_000_000;
+/** models.dev's own long-context pricing convention: a request whose context exceeds this many tokens uses ModelCatalogPricing.contextOver200k instead of the flat/tiered rate. */
+export const CATALOG_LONG_CONTEXT_THRESHOLD_TOKENS = 200_000;
 /** A `metrics prune --before` cutoff newer than this must pass `force: true`. Guards against accidentally wiping recent/live data with a too-recent cutoff (e.g. "now"), while still allowing routine cleanup of genuinely old rows without ceremony. */
 export const PRUNE_MIN_AGE_MS = 24 * MILLISECONDS_PER_HOUR;
 export const CONTEXT_OBSERVATION_MAX_CHARACTERS = 10_000_000;

package/src/index.ts

@@ -15,6 +15,20 @@ export {
 	type GoogleVertexMetricSource,
 	googleVertexFailureMetrics,
 } from "./google-vertex/failures.ts";
+export {
+	buildCacheEconomicsSummary,
+	type CacheCostBasis,
+	type CacheEconomicsAggregateTotals,
+	type CacheEconomicsMissedOpportunity,
+	type CacheEconomicsModelSummary,
+	type CacheEconomicsPricing,
+	type CacheEconomicsPricingLookup,
+	type CacheEconomicsStablePrefixPoint,
+	type CacheEconomicsSummary,
+	type CacheEconomicsSummaryOptions,
+	type CacheEconomicsTaskSummary,
+	type CacheEconomicsUnattributedActivity,
+} from "./observability/cache-economics.ts";
 export {
 	CONTEXT_SEGMENT_SOURCES,
 	CONTEXT_SEGMENT_STATES,

package/src/observability/cache-economics.ts

@@ -0,0 +1,623 @@
+import {
+	CACHE_ECONOMICS_LOSS_CORRELATION_WINDOW_MS,
+	CACHE_ECONOMICS_MAX_MISSED_OPPORTUNITIES,
+	CACHE_ECONOMICS_MAX_MODEL_GROUPS,
+	CACHE_ECONOMICS_MAX_STABLE_PREFIX_POINTS,
+	CACHE_ECONOMICS_MAX_TASK_GROUPS,
+	CATALOG_PRICE_TOKEN_UNIT,
+} from "../constants.ts";
+import type { ContextPrefixResetReason } from "./context-delta.ts";
+import type { StoredMetricObservation } from "./metric.ts";
+
+/**
+ * How much authority a cache-cost figure carries. `provider-reported` comes straight from the
+ * provider's own per-turn `usage.cost.*` breakdown (or is trivially true, e.g. zero tokens cost
+ * zero dollars); `catalog-estimate` is derived from models.dev catalog pricing when the provider
+ * never itemizes cache cost; `unknown` means neither exists and the figure must stay null rather
+ * than being fabricated.
+ */
+export type CacheCostBasis = "provider-reported" | "catalog-estimate" | "unknown";
+
+/** Flat (already tier-resolved, if applicable) per-token-million catalog prices for one provider/model at one particular request size. */
+export interface CacheEconomicsPricing {
+	input?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	/** Whether the catalog snapshot this price was resolved from was still fresh at query time. Only meaningful when this pricing is actually used for a catalog-estimate figure; the lookup may omit it (e.g. a fake with no notion of freshness). */
+	freshness?: "fresh" | "stale";
+}
+
+/**
+ * Best-effort catalog pricing lookup; returns null when the catalog has no snapshot or no
+ * matching model, never throws. `contextSizeTokens` is the specific request/run's own real size
+ * (input + cache-read + cache-write tokens) -- the lookup is free to resolve a tiered or
+ * long-context ("contextOver200k") price against it instead of a single flat rate; the domain
+ * layer here never assumes which it did.
+ */
+export interface CacheEconomicsPricingLookup {
+	priceFor(provider: string, model: string, contextSizeTokens: number): CacheEconomicsPricing | null;
+}
+
+/**
+ * Every derived economics figure this domain produces, independent of which dimension (model,
+ * task) it's grouped by -- see CacheEconomicsModelSummary/CacheEconomicsTaskSummary, which each add
+ * only their own grouping key on top of this.
+ */
+export interface CacheEconomicsAggregateTotals {
+	inputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	/** Real dollars actually paid for cache reads in-window, or a catalog estimate, or null when neither is known. */
+	cacheReadCostUsd: number | null;
+	cacheReadCostBasis: CacheCostBasis;
+	/** Real dollars actually paid for cache writes in-window, or a catalog estimate, or null when neither is known. */
+	cacheWriteCostUsd: number | null;
+	cacheWriteCostBasis: CacheCostBasis;
+	/** sum(provider-reported input cost) / sum(input tokens) within the window -- a real per-token rate derived only from provider-reported dollar/token figures, not a catalog guess. Null when the provider never reported itemized input cost in-window. */
+	effectiveInputRateUsdPerToken: number | null;
+	/** What the cache-read tokens would have cost had they been billed as ordinary input, at the best available rate. */
+	counterfactualNoCacheCostUsd: number | null;
+	counterfactualBasis: CacheCostBasis;
+	/** counterfactualNoCacheCostUsd minus the actual cache-read cost -- the real economic benefit of caching, when derivable. */
+	savingsUsd: number | null;
+	/** The premium actually paid for cache-write tokens over what plain input billing would have cost. */
+	cacheWritePremiumUsd: number | null;
+	/** How many cache-read tokens, at the observed/estimated read rate, would be needed to offset the write premium. Zero when no premium was paid; null when undeterminable. An aggregate approximation over the whole window/group, not resolved per run. */
+	breakEvenReadTokens: number | null;
+	/** Whether observed savings already met or exceeded the write premium. Null when there was no cache write to evaluate, or the comparison is undeterminable. */
+	paybackAchieved: boolean | null;
+	/** Worst ("stale" wins) freshness among every catalog-estimate figure this group actually used. Null when no catalog estimate was used at all -- everything was provider-reported, or nothing was derivable. Never set from a catalog price that was resolved but ended up unused (e.g. provider-reported cost took precedence). */
+	catalogFreshness: "fresh" | "stale" | null;
+}
+
+export interface CacheEconomicsModelSummary extends CacheEconomicsAggregateTotals {
+	provider: string;
+	model: string;
+}
+
+/**
+ * The same figures as CacheEconomicsModelSummary, rolled up by the Papyrus task focused when each
+ * row was recorded instead of by provider/model -- mirrors task-cost.ts's own attributes.taskId
+ * grouping for token/cost metrics. A task that stayed on one model gets the same tiered-catalog
+ * pricing precision as the model-level rollup; a task that spanned several models still sums
+ * correctly (each run was already priced against its own real context size before this rollup ever
+ * runs) but skips the single extra break-even catalog lookup that only makes sense for one model.
+ */
+export interface CacheEconomicsTaskSummary extends CacheEconomicsAggregateTotals {
+	taskId: string;
+}
+
+/**
+ * Cache activity recorded with no Papyrus task focused. Real spend/activity, just not attributable
+ * to any task -- reported separately (mirroring task-cost.ts's own unattributedCostUsd) rather than
+ * silently dropped or folded into a fabricated "unknown task" bucket.
+ */
+export interface CacheEconomicsUnattributedActivity {
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	cacheReadCostUsd: number | null;
+	cacheReadCostBasis: CacheCostBasis;
+	cacheWriteCostUsd: number | null;
+	cacheWriteCostBasis: CacheCostBasis;
+	catalogFreshness: "fresh" | "stale" | null;
+}
+
+/**
+ * One snapshot's own stable-prefix-token measurement at one point in time -- the same raw evidence
+ * findMissedOpportunities correlates internally, made directly visible instead of only ever feeding
+ * a derived diagnostic. A sharp drop, especially alongside a non-null resetReason, is what a missed
+ * cache write actually looks like in this series; still just evidence, not a causal claim.
+ */
+export interface CacheEconomicsStablePrefixPoint {
+	sessionId: string;
+	observedAt: number;
+	stablePrefixTokens: number;
+	resetReason: ContextPrefixResetReason;
+}
+
+/** A context-prefix reset (session/provider/model change) followed shortly by a same-session cache-write is *evidence*, not proof, that the reset forced a cache rewrite -- correlation, never asserted causality. */
+export interface CacheEconomicsMissedOpportunity {
+	sessionId: string;
+	occurredAt: number;
+	resetReason: Exclude<ContextPrefixResetReason, null>;
+	cacheWriteTokens: number;
+	cacheWriteCostUsd: number | null;
+	note: string;
+}
+
+export interface CacheEconomicsSummary {
+	since: number;
+	until: number;
+	models: CacheEconomicsModelSummary[];
+	tasks: CacheEconomicsTaskSummary[];
+	unattributedCacheActivity: CacheEconomicsUnattributedActivity;
+	missedOpportunities: CacheEconomicsMissedOpportunity[];
+	/** Chronological (oldest first), bounded to the most recent CACHE_ECONOMICS_MAX_STABLE_PREFIX_POINTS. */
+	stablePrefixChurn: CacheEconomicsStablePrefixPoint[];
+	/** True when the model-group list, the task-group list, the stable-prefix-churn series, or the missed-opportunity list was cut off at its bound. */
+	truncated: boolean;
+}
+
+export interface CacheEconomicsSummaryOptions {
+	since: number;
+	until: number;
+}
+
+const RESET_REASONS = new Set<Exclude<ContextPrefixResetReason, null>>(["initial", "session-changed", "provider-changed", "model-changed"]);
+
+function attributeText(attributes: Record<string, unknown>, key: string): string {
+	return typeof attributes[key] === "string" && attributes[key].length > 0 ? (attributes[key] as string) : "unknown";
+}
+
+/** A turn's own runId when present, else its shared observedAt timestamp -- rows recorded before runId tagging existed still group correctly as long as they were sent (and therefore timestamped) together. */
+function runKeyFor(row: StoredMetricObservation): string {
+	const runId = row.attributes.runId;
+	if (typeof runId === "string" && runId.length > 0) return runId;
+	return `observedAt:${row.observedAt}`;
+}
+
+/** One turn's own token/cost totals -- the unit pricing (including any tiered/long-context catalog rate) is resolved against. */
+interface RunAccumulator {
+	provider: string;
+	model: string;
+	/** The Papyrus task focused when this turn's rows were recorded, or undefined when nothing was focused -- undefined is a real, distinct state from any task id string, never coerced to "unknown". */
+	taskId: string | undefined;
+	inputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	inputCostUsd: number;
+	sawInputCost: boolean;
+	cacheReadCostUsd: number;
+	sawCacheReadCost: boolean;
+	cacheWriteCostUsd: number;
+	sawCacheWriteCost: boolean;
+}
+
+function newRunAccumulator(provider: string, model: string, taskId: string | undefined): RunAccumulator {
+	return {
+		provider,
+		model,
+		taskId,
+		inputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		inputCostUsd: 0,
+		sawInputCost: false,
+		cacheReadCostUsd: 0,
+		sawCacheReadCost: false,
+		cacheWriteCostUsd: 0,
+		sawCacheWriteCost: false,
+	};
+}
+
+function combineBasis(left: CacheCostBasis, right: CacheCostBasis): CacheCostBasis {
+	if (left === "unknown" || right === "unknown") return "unknown";
+	if (left === "catalog-estimate" || right === "catalog-estimate") return "catalog-estimate";
+	return "provider-reported";
+}
+
+/** Sums basis-tagged dollar amounts; a single unknown amount makes the whole sum unknown rather than silently partial. */
+function combineDollarField(entries: Array<{ amount: number | null; basis: CacheCostBasis }>): {
+	amount: number | null;
+	basis: CacheCostBasis;
+} {
+	let total = 0;
+	let basis: CacheCostBasis = "provider-reported";
+	for (const entry of entries) {
+		if (entry.amount === null) return { amount: null, basis: "unknown" };
+		total += entry.amount;
+		basis = combineBasis(basis, entry.basis);
+	}
+	return { amount: total, basis };
+}
+
+function combineNullableSum(values: Array<number | null>): number | null {
+	let total = 0;
+	for (const value of values) {
+		if (value === null) return null;
+		total += value;
+	}
+	return total;
+}
+
+/** "stale" outvotes "fresh"; both outvote "never used a catalog estimate at all" (null). */
+function combineFreshness(values: Array<"fresh" | "stale" | undefined>): "fresh" | "stale" | null {
+	let result: "fresh" | "stale" | null = null;
+	for (const value of values) {
+		if (value === undefined) continue;
+		if (value === "stale") return "stale";
+		result = "fresh";
+	}
+	return result;
+}
+
+function actualCost(
+	tokens: number,
+	sawCost: boolean,
+	costUsd: number,
+	catalogPricePerMillion: number | undefined,
+): { costUsd: number | null; basis: CacheCostBasis } {
+	if (tokens === 0) return { costUsd: 0, basis: "provider-reported" };
+	if (sawCost) return { costUsd, basis: "provider-reported" };
+	if (catalogPricePerMillion !== undefined)
+		return { costUsd: (tokens * catalogPricePerMillion) / CATALOG_PRICE_TOKEN_UNIT, basis: "catalog-estimate" };
+	return { costUsd: null, basis: "unknown" };
+}
+
+interface RunPricingResult {
+	provider: string;
+	model: string;
+	taskId: string | undefined;
+	inputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	inputCostUsd: number;
+	sawInputCost: boolean;
+	cacheReadCostUsd: number | null;
+	cacheReadCostBasis: CacheCostBasis;
+	cacheWriteCostUsd: number | null;
+	cacheWriteCostBasis: CacheCostBasis;
+	counterfactualNoCacheCostUsd: number | null;
+	counterfactualBasis: CacheCostBasis;
+	cacheWritePremiumUsd: number | null;
+	/** This run's own catalog freshness, only when a catalog-estimate price actually ended up used for one of this run's figures; undefined otherwise (never fabricated from an unused lookup result). */
+	catalogFreshness: "fresh" | "stale" | undefined;
+}
+
+/**
+ * Prices exactly one turn, against that turn's own real context size (input + cache-read +
+ * cache-write tokens) -- the only level at which a tiered/long-context catalog price can honestly
+ * be resolved. Never sums across turns; that happens once, afterward, in aggregateRuns.
+ */
+function priceRun(run: RunAccumulator, pricing: CacheEconomicsPricingLookup): RunPricingResult {
+	const contextSizeTokens = run.inputTokens + run.cacheReadTokens + run.cacheWriteTokens;
+	const catalogPrices = pricing.priceFor(run.provider, run.model, contextSizeTokens);
+	const read = actualCost(run.cacheReadTokens, run.sawCacheReadCost, run.cacheReadCostUsd, catalogPrices?.cacheRead);
+	const write = actualCost(run.cacheWriteTokens, run.sawCacheWriteCost, run.cacheWriteCostUsd, catalogPrices?.cacheWrite);
+
+	let baselineRate: number | null = null;
+	let baselineBasis: CacheCostBasis = "unknown";
+	if (run.sawInputCost && run.inputTokens > 0) {
+		baselineRate = run.inputCostUsd / run.inputTokens;
+		baselineBasis = "provider-reported";
+	} else if (catalogPrices?.input !== undefined) {
+		baselineRate = catalogPrices.input / CATALOG_PRICE_TOKEN_UNIT;
+		baselineBasis = "catalog-estimate";
+	}
+
+	let counterfactualNoCacheCostUsd: number | null = null;
+	let counterfactualBasis: CacheCostBasis = "unknown";
+	if (run.cacheReadTokens === 0) {
+		counterfactualNoCacheCostUsd = 0;
+		counterfactualBasis = "provider-reported";
+	} else if (baselineRate !== null) {
+		counterfactualNoCacheCostUsd = run.cacheReadTokens * baselineRate;
+		counterfactualBasis = baselineBasis;
+	}
+
+	let cacheWritePremiumUsd: number | null = null;
+	if (run.cacheWriteTokens === 0) cacheWritePremiumUsd = 0;
+	else if (baselineRate !== null && write.costUsd !== null) cacheWritePremiumUsd = write.costUsd - run.cacheWriteTokens * baselineRate;
+
+	const finalCounterfactualBasis = run.cacheReadTokens === 0 ? "provider-reported" : combineBasis(baselineBasis, counterfactualBasis);
+	const usedCatalog =
+		read.basis === "catalog-estimate" || write.basis === "catalog-estimate" || finalCounterfactualBasis === "catalog-estimate";
+
+	return {
+		provider: run.provider,
+		model: run.model,
+		taskId: run.taskId,
+		inputTokens: run.inputTokens,
+		cacheReadTokens: run.cacheReadTokens,
+		cacheWriteTokens: run.cacheWriteTokens,
+		inputCostUsd: run.inputCostUsd,
+		sawInputCost: run.sawInputCost,
+		cacheReadCostUsd: read.costUsd,
+		cacheReadCostBasis: read.basis,
+		cacheWriteCostUsd: write.costUsd,
+		cacheWriteCostBasis: write.basis,
+		counterfactualNoCacheCostUsd,
+		counterfactualBasis: finalCounterfactualBasis,
+		cacheWritePremiumUsd,
+		catalogFreshness: usedCatalog ? catalogPrices?.freshness : undefined,
+	};
+}
+
+/**
+ * A single provider/model to resolve one extra, approximate whole-window catalog lookup against
+ * for the break-even projection below -- only meaningful when every run being aggregated actually
+ * shares this same provider/model (a per-model rollup always does; a per-task rollup only does when
+ * that task stayed on one model the whole time). Pass null to skip that refinement rather than
+ * guessing which of several different models' rates should stand in for the blend.
+ */
+interface SingleModelPricingContext {
+	provider: string;
+	model: string;
+	pricing: CacheEconomicsPricingLookup;
+}
+
+/**
+ * Sums already-run-priced dollar figures into one group's (model's, or task's) window totals, then
+ * derives break-even/payback from those totals plus -- when catalogContext identifies a single real
+ * provider/model to resolve against -- one whole-window catalog lookup. This is an intentional,
+ * documented approximation: unlike the dollar totals above (correctly tiered per run), a single
+ * "how many more read tokens would it take" projection over a blended window has no one real
+ * request size to resolve a tier against either.
+ */
+function aggregateRunTotals(runs: RunPricingResult[], catalogContext: SingleModelPricingContext | null): CacheEconomicsAggregateTotals {
+	const inputTokens = runs.reduce((sum, run) => sum + run.inputTokens, 0);
+	const cacheReadTokens = runs.reduce((sum, run) => sum + run.cacheReadTokens, 0);
+	const cacheWriteTokens = runs.reduce((sum, run) => sum + run.cacheWriteTokens, 0);
+	const read = combineDollarField(runs.map((run) => ({ amount: run.cacheReadCostUsd, basis: run.cacheReadCostBasis })));
+	const write = combineDollarField(runs.map((run) => ({ amount: run.cacheWriteCostUsd, basis: run.cacheWriteCostBasis })));
+	const counterfactual = combineDollarField(
+		runs.map((run) => ({ amount: run.counterfactualNoCacheCostUsd, basis: run.counterfactualBasis })),
+	);
+	const savingsUsd = counterfactual.amount !== null && read.amount !== null ? counterfactual.amount - read.amount : null;
+	const cacheWritePremiumUsd = combineNullableSum(runs.map((run) => run.cacheWritePremiumUsd));
+
+	const reportingRuns = runs.filter((run) => run.sawInputCost && run.inputTokens > 0);
+	const effectiveInputRateUsdPerToken =
+		reportingRuns.length > 0
+			? reportingRuns.reduce((sum, run) => sum + run.inputCostUsd, 0) / reportingRuns.reduce((sum, run) => sum + run.inputTokens, 0)
+			: null;
+
+	let breakEvenReadTokens: number | null = null;
+	if (cacheWriteTokens === 0) breakEvenReadTokens = 0;
+	else if (cacheWritePremiumUsd !== null) {
+		const catalogPrices = catalogContext?.pricing.priceFor(
+			catalogContext.provider,
+			catalogContext.model,
+			inputTokens + cacheReadTokens + cacheWriteTokens,
+		);
+		const baselineRate =
+			effectiveInputRateUsdPerToken ?? (catalogPrices?.input !== undefined ? catalogPrices.input / CATALOG_PRICE_TOKEN_UNIT : null);
+		const readRate =
+			cacheReadTokens > 0 && read.amount !== null
+				? read.amount / cacheReadTokens
+				: (catalogPrices?.cacheRead ?? undefined) !== undefined
+					? catalogPrices!.cacheRead! / CATALOG_PRICE_TOKEN_UNIT
+					: null;
+		const perTokenSavings = baselineRate !== null && readRate !== null ? baselineRate - readRate : null;
+		if (cacheWritePremiumUsd <= 0) breakEvenReadTokens = 0;
+		else if (perTokenSavings !== null && perTokenSavings > 0) breakEvenReadTokens = Math.ceil(cacheWritePremiumUsd / perTokenSavings);
+	}
+
+	const paybackAchieved =
+		cacheWriteTokens === 0 ? null : savingsUsd !== null && cacheWritePremiumUsd !== null ? savingsUsd >= cacheWritePremiumUsd : null;
+
+	return {
+		inputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		cacheReadCostUsd: read.amount,
+		cacheReadCostBasis: read.basis,
+		cacheWriteCostUsd: write.amount,
+		cacheWriteCostBasis: write.basis,
+		effectiveInputRateUsdPerToken,
+		counterfactualNoCacheCostUsd: counterfactual.amount,
+		counterfactualBasis: counterfactual.basis,
+		savingsUsd,
+		cacheWritePremiumUsd,
+		breakEvenReadTokens,
+		paybackAchieved,
+		catalogFreshness: combineFreshness(runs.map((run) => run.catalogFreshness)),
+	};
+}
+
+function buildModelSummary(
+	provider: string,
+	model: string,
+	runs: RunPricingResult[],
+	pricing: CacheEconomicsPricingLookup,
+): CacheEconomicsModelSummary {
+	return { provider, model, ...aggregateRunTotals(runs, { provider, model, pricing }) };
+}
+
+/** A single-model catalog context only when every run in this task's group really did share one provider/model -- never guesses a representative model for a task that switched partway through. */
+function buildTaskSummary(taskId: string, runs: RunPricingResult[], pricing: CacheEconomicsPricingLookup): CacheEconomicsTaskSummary {
+	const firstRun = runs[0]!;
+	const singleModel = runs.every((run) => run.provider === firstRun.provider && run.model === firstRun.model);
+	const catalogContext = singleModel ? { provider: firstRun.provider, model: firstRun.model, pricing } : null;
+	return { taskId, ...aggregateRunTotals(runs, catalogContext) };
+}
+
+interface ResetEvent {
+	sessionId: string;
+	occurredAt: number;
+	resetReason: Exclude<ContextPrefixResetReason, null>;
+}
+
+function resetEventFromRow(row: StoredMetricObservation): ResetEvent | null {
+	const resetReason = row.attributes.resetReason;
+	if (resetReason === null || resetReason === undefined || !RESET_REASONS.has(resetReason as Exclude<ContextPrefixResetReason, null>))
+		return null;
+	if (typeof row.scope !== "string" || row.scope.length === 0) return null;
+	return { sessionId: row.scope, occurredAt: row.observedAt, resetReason: resetReason as Exclude<ContextPrefixResetReason, null> };
+}
+
+function stablePrefixChurnFrom(snapshotRows: StoredMetricObservation[]): CacheEconomicsStablePrefixPoint[] {
+	return snapshotRows
+		.filter(
+			(row): row is StoredMetricObservation =>
+				row.source === "pi-context-snapshot" &&
+				row.metric === "snapshot" &&
+				typeof row.value === "number" &&
+				typeof row.scope === "string" &&
+				row.scope.length > 0,
+		)
+		.map((row) => ({
+			sessionId: row.scope as string,
+			observedAt: row.observedAt,
+			stablePrefixTokens: row.value as number,
+			resetReason: (row.attributes.resetReason ?? null) as ContextPrefixResetReason,
+		}))
+		.sort((left, right) => left.observedAt - right.observedAt);
+}
+
+function findMissedOpportunities(
+	usageRows: StoredMetricObservation[],
+	snapshotRows: StoredMetricObservation[],
+): CacheEconomicsMissedOpportunity[] {
+	const resets = snapshotRows
+		.filter((row) => row.source === "pi-context-snapshot" && row.metric === "snapshot")
+		.map(resetEventFromRow)
+		.filter((event): event is ResetEvent => event !== null);
+	if (resets.length === 0) return [];
+	const writes = usageRows.filter(
+		(row) => row.source === "pi" && row.metric === "cache-write-tokens" && typeof row.value === "number" && row.value > 0,
+	);
+	const found: CacheEconomicsMissedOpportunity[] = [];
+	for (const reset of resets) {
+		const match = writes
+			.filter((row) => attributeText(row.attributes, "sessionId") === reset.sessionId)
+			.filter(
+				(row) => row.observedAt >= reset.occurredAt && row.observedAt - reset.occurredAt <= CACHE_ECONOMICS_LOSS_CORRELATION_WINDOW_MS,
+			)
+			.sort((left, right) => left.observedAt - right.observedAt)[0];
+		if (!match) continue;
+		const costRow = usageRows.find(
+			(row) =>
+				row.source === "pi" &&
+				row.metric === "cache-write-cost" &&
+				attributeText(row.attributes, "sessionId") === reset.sessionId &&
+				row.observedAt === match.observedAt,
+		);
+		found.push({
+			sessionId: reset.sessionId,
+			occurredAt: match.observedAt,
+			resetReason: reset.resetReason,
+			cacheWriteTokens: match.value as number,
+			cacheWriteCostUsd: typeof costRow?.value === "number" ? costRow.value : null,
+			note: `Candidate missed-cache opportunity: a ${reset.resetReason} context-prefix reset was followed by a cache write in the same session within the correlation window. This is a correlated pattern, not a proven cause.`,
+		});
+	}
+	return found;
+}
+
+/**
+ * Pure aggregation over already-fetched, already-bounded rows -- the operation layer owns querying
+ * MetricStore and the model catalog; this function only ever combines what it is given. Rows are
+ * first grouped into per-turn runs (see runKeyFor) and priced against each run's own real context
+ * size, so a tiered/long-context catalog price is resolved honestly instead of guessed against a
+ * blended window-wide sum; run-level dollar figures are only summed together afterward. Every
+ * derived (non-trivial) dollar figure is explicitly basis-tagged; nothing is fabricated when
+ * evidence is absent.
+ */
+export function buildCacheEconomicsSummary(
+	usageRows: StoredMetricObservation[],
+	snapshotRows: StoredMetricObservation[],
+	pricing: CacheEconomicsPricingLookup,
+	options: CacheEconomicsSummaryOptions,
+): CacheEconomicsSummary {
+	const byRun = new Map<string, RunAccumulator>();
+	const admittedModels = new Set<string>();
+	let modelGroupsTruncated = false;
+	for (const row of usageRows) {
+		if (row.source !== "pi" || typeof row.value !== "number" || !Number.isFinite(row.value) || row.value < 0) continue;
+		if (row.observedAt < options.since || row.observedAt > options.until) continue;
+		const provider = attributeText(row.attributes, "provider");
+		const model = attributeText(row.attributes, "model");
+		const modelKey = `${provider}\u0000${model}`;
+		if (!admittedModels.has(modelKey)) {
+			if (admittedModels.size >= CACHE_ECONOMICS_MAX_MODEL_GROUPS) {
+				modelGroupsTruncated = true;
+				continue;
+			}
+			admittedModels.add(modelKey);
+		}
+		const taskId = typeof row.attributes.taskId === "string" && row.attributes.taskId.length > 0 ? row.attributes.taskId : undefined;
+		const runKey = `${modelKey}\u0000${runKeyFor(row)}`;
+		const run = byRun.get(runKey) ?? newRunAccumulator(provider, model, taskId);
+		byRun.set(runKey, run);
+		if (row.metric === "input-tokens" && row.unit === "tokens") run.inputTokens += row.value;
+		else if (row.metric === "cache-read-tokens" && row.unit === "tokens") run.cacheReadTokens += row.value;
+		else if (row.metric === "cache-write-tokens" && row.unit === "tokens") run.cacheWriteTokens += row.value;
+		else if (row.metric === "input-cost" && row.unit === "usd") {
+			run.inputCostUsd += row.value;
+			run.sawInputCost = true;
+		} else if (row.metric === "cache-read-cost" && row.unit === "usd") {
+			run.cacheReadCostUsd += row.value;
+			run.sawCacheReadCost = true;
+		} else if (row.metric === "cache-write-cost" && row.unit === "usd") {
+			run.cacheWriteCostUsd += row.value;
+			run.sawCacheWriteCost = true;
+		}
+	}
+
+	const allPriced = [...byRun.values()].map((run) => priceRun(run, pricing));
+
+	const runsByModel = new Map<string, { provider: string; model: string; runs: RunPricingResult[] }>();
+	const runsByTask = new Map<string, RunPricingResult[]>();
+	const unattributedRuns: RunPricingResult[] = [];
+	for (const priced of allPriced) {
+		const modelKey = `${priced.provider}\u0000${priced.model}`;
+		const existingModel = runsByModel.get(modelKey);
+		if (existingModel) existingModel.runs.push(priced);
+		else runsByModel.set(modelKey, { provider: priced.provider, model: priced.model, runs: [priced] });
+
+		if (priced.taskId === undefined) {
+			unattributedRuns.push(priced);
+			continue;
+		}
+		const existingTask = runsByTask.get(priced.taskId);
+		if (existingTask) existingTask.push(priced);
+		else runsByTask.set(priced.taskId, [priced]);
+	}
+	const models = [...runsByModel.values()]
+		.map(({ provider, model, runs }) => buildModelSummary(provider, model, runs, pricing))
+		.sort(
+			(left, right) =>
+				right.cacheReadTokens + right.cacheWriteTokens - (left.cacheReadTokens + left.cacheWriteTokens) ||
+				left.model.localeCompare(right.model),
+		);
+
+	const allTasks = [...runsByTask.entries()]
+		.map(([taskId, runs]) => buildTaskSummary(taskId, runs, pricing))
+		.sort(
+			(left, right) =>
+				right.cacheReadTokens + right.cacheWriteTokens - (left.cacheReadTokens + left.cacheWriteTokens) ||
+				left.taskId.localeCompare(right.taskId),
+		);
+	const taskGroupsTruncated = allTasks.length > CACHE_ECONOMICS_MAX_TASK_GROUPS;
+	const tasks = allTasks.slice(0, CACHE_ECONOMICS_MAX_TASK_GROUPS);
+
+	const unattributedCacheRead = combineDollarField(
+		unattributedRuns.map((run) => ({ amount: run.cacheReadCostUsd, basis: run.cacheReadCostBasis })),
+	);
+	const unattributedCacheWrite = combineDollarField(
+		unattributedRuns.map((run) => ({ amount: run.cacheWriteCostUsd, basis: run.cacheWriteCostBasis })),
+	);
+	const unattributedCacheActivity: CacheEconomicsUnattributedActivity = {
+		cacheReadTokens: unattributedRuns.reduce((sum, run) => sum + run.cacheReadTokens, 0),
+		cacheWriteTokens: unattributedRuns.reduce((sum, run) => sum + run.cacheWriteTokens, 0),
+		cacheReadCostUsd: unattributedCacheRead.amount,
+		cacheReadCostBasis: unattributedCacheRead.basis,
+		cacheWriteCostUsd: unattributedCacheWrite.amount,
+		cacheWriteCostBasis: unattributedCacheWrite.basis,
+		catalogFreshness: combineFreshness(unattributedRuns.map((run) => run.catalogFreshness)),
+	};
+
+	const windowedSnapshotRows = snapshotRows.filter((row) => row.observedAt >= options.since && row.observedAt <= options.until);
+	const allMissed = findMissedOpportunities(
+		usageRows.filter((row) => row.observedAt >= options.since && row.observedAt <= options.until),
+		windowedSnapshotRows,
+	);
+	const missedTruncated = allMissed.length > CACHE_ECONOMICS_MAX_MISSED_OPPORTUNITIES;
+	const missedOpportunities = allMissed.slice(0, CACHE_ECONOMICS_MAX_MISSED_OPPORTUNITIES);
+
+	const allChurn = stablePrefixChurnFrom(windowedSnapshotRows);
+	const churnTruncated = allChurn.length > CACHE_ECONOMICS_MAX_STABLE_PREFIX_POINTS;
+	const stablePrefixChurn = allChurn.slice(-CACHE_ECONOMICS_MAX_STABLE_PREFIX_POINTS);
+
+	return {
+		since: options.since,
+		until: options.until,
+		models,
+		tasks,
+		unattributedCacheActivity,
+		missedOpportunities,
+		stablePrefixChurn,
+		truncated: modelGroupsTruncated || taskGroupsTruncated || missedTruncated || churnTruncated,
+	};
+}

package/src/vehicle/cache-operations.ts

@@ -0,0 +1,95 @@
+import { CACHE_ECONOMICS_QUERY_LIMIT, CATALOG_LONG_CONTEXT_THRESHOLD_TOKENS } from "../constants.ts";
+import {
+	buildCacheEconomicsSummary,
+	type CacheEconomicsPricing,
+	type CacheEconomicsPricingLookup,
+} from "../observability/cache-economics.ts";
+import type { MetricStore } from "../observability/store.ts";
+import type { ModelCatalogController, ModelCatalogPriceTier, ModelCatalogPricing } from "../optimization/model-selection/catalog.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
+
+function mergeWithBase(
+	base: ModelCatalogPricing,
+	override: Partial<Pick<ModelCatalogPricing, "input" | "cacheRead" | "cacheWrite">>,
+): CacheEconomicsPricing {
+	return {
+		input: override.input ?? base.input,
+		cacheRead: override.cacheRead ?? base.cacheRead,
+		cacheWrite: override.cacheWrite ?? base.cacheWrite,
+	};
+}
+
+/**
+ * Resolves one flat price for one real request size, honoring models.dev's own long-context and
+ * tiered pricing shapes -- the only place tiering can be resolved honestly, since it needs a
+ * single request's real context size (see cache-economics.ts's per-run pricing).
+ *
+ * `contextOver200k` takes priority over `tiers` when both are present (mirrors models.dev's own
+ * convention: it is a distinct override for the specific >200k-token case, not one more tier).
+ * A field a tier/override omits falls back to the base flat price, never to `undefined`-as-unknown
+ * silently -- a tier that only republishes input/output pricing still inherits the model's real
+ * cache prices instead of losing them.
+ */
+export function resolveTieredCatalogPrice(pricing: ModelCatalogPricing, contextSizeTokens: number): CacheEconomicsPricing {
+	if (pricing.contextOver200k && contextSizeTokens > CATALOG_LONG_CONTEXT_THRESHOLD_TOKENS) {
+		return mergeWithBase(pricing, pricing.contextOver200k);
+	}
+	if (pricing.tiers && pricing.tiers.length > 0) {
+		const ascending = [...pricing.tiers].sort((left, right) => left.contextSize - right.contextSize);
+		const tier: ModelCatalogPriceTier = ascending.find((candidate) => candidate.contextSize >= contextSizeTokens) ?? ascending.at(-1)!;
+		return mergeWithBase(pricing, tier);
+	}
+	return { input: pricing.input, cacheRead: pricing.cacheRead, cacheWrite: pricing.cacheWrite };
+}
+
+/**
+ * Best-effort catalog-backed pricing lookup: an unconfigured/unavailable catalog, or a model the
+ * catalog doesn't carry, returns null rather than throwing -- cache economics degrades that
+ * model's pricing to "unknown" instead of failing the whole query.
+ */
+class CatalogCacheEconomicsPricing implements CacheEconomicsPricingLookup {
+	constructor(private readonly catalog: ModelCatalogController) {}
+
+	priceFor(provider: string, model: string, contextSizeTokens: number): CacheEconomicsPricing | null {
+		try {
+			const result = this.catalog.query({ provider, model, limit: 1 });
+			const entry = result.entries[0];
+			if (!entry?.pricing) return null;
+			return { ...resolveTieredCatalogPrice(entry.pricing, contextSizeTokens), freshness: result.freshness };
+		} catch {
+			return null;
+		}
+	}
+}
+
+/** cache.economics -- the only operation that combines the metric store's "pi"/"pi-context-snapshot" rows with catalog pricing. */
+export function cacheEconomicsOperations(metrics: MetricStore, catalog: ModelCatalogController): OperationHandlerMap {
+	const pricing = new CatalogCacheEconomicsPricing(catalog);
+	return {
+		"cache.economics": (input) => {
+			const since = input.since;
+			const until = input.until;
+			if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+				throw new Error("cache economics requires non-negative ordered integer bounds");
+			}
+			const usageRows = metrics.query({
+				source: "pi",
+				since: since as number,
+				until: until as number,
+				order: "desc",
+				limit: CACHE_ECONOMICS_QUERY_LIMIT,
+			});
+			const snapshotRows = metrics.query({
+				source: "pi-context-snapshot",
+				metric: "snapshot",
+				since: since as number,
+				until: until as number,
+				order: "desc",
+				limit: CACHE_ECONOMICS_QUERY_LIMIT,
+			});
+			const summary = buildCacheEconomicsSummary(usageRows, snapshotRows, pricing, { since: since as number, until: until as number });
+			const rowsTruncated = usageRows.length >= CACHE_ECONOMICS_QUERY_LIMIT || snapshotRows.length >= CACHE_ECONOMICS_QUERY_LIMIT;
+			return { ...summary, truncated: summary.truncated || rowsTruncated };
+		},
+	};
+}

package/src/vehicle/registration.ts

@@ -73,6 +73,8 @@ const WRITE: VehicleIdempotency = { mode: "unsafe" };
  *   available_routes: local-write (every one is a real router.set (or
  *   pause/resume) call, despite router.current_route's read-sounding name
  *   -- confirmed directly against router-operations.ts).
+ * - cache.economics: read (a pure projection over already-recorded metric
+ *   rows plus catalog pricing; never mutates anything).
  */
 const OPERATION_META: Record<OperationName, OperationMeta> = {
 	"metrics.record": { description: "Records one metric observation.", effect: "local-write" },
@@ -113,6 +115,11 @@ const OPERATION_META: Record<OperationName, OperationMeta> = {
 	"router.clear_override": { description: "Clears a manual route override.", effect: "local-write" },
 	"router.current_route": { description: "Sets the router's currently-active route.", effect: "local-write" },
 	"router.available_routes": { description: "Sets the router's currently-available routes.", effect: "local-write" },
+	"cache.economics": {
+		description:
+			"Reports prompt-cache economics (read/write cost, savings, break-even) and candidate missed-cache opportunities within a bounded time window.",
+		effect: "read",
+	},
 };
 
 /** Read effects need only jittor:read; every other effect needs both (writes commonly also read first). */

package/src/vehicle/service.ts

@@ -2,6 +2,7 @@ import { VehicleRegistry } from "@danypops/vehicle-server";
 import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import { errorResponse, healthResponse, readyResponse, requireBearerToken } from "@danypops/vehicle-server/rpc-http";
 import { SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES } from "../constants.ts";
+import type { CacheEconomicsSummary } from "../observability/cache-economics.ts";
 import type { ContextDelta, ContextSnapshot } from "../observability/context-delta.ts";
 import { type ContextSnapshotHistory, MetricContextSnapshotHistory } from "../observability/context-snapshot-history.ts";
 import type { CompactionDurationEstimate, ContextAssessment } from "../observability/context-telemetry.ts";
@@ -27,6 +28,7 @@ import { routerMutationAuthorizer } from "../sessions/router-authorization.ts";
 import { DisabledObservationExporter, type ObservationExporter, type ObservationExportStatus } from "../telemetry-export/exporter.ts";
 import { VERSION } from "../version.ts";
 import { benchmarkOperations } from "./benchmark-operations.ts";
+import { cacheEconomicsOperations } from "./cache-operations.ts";
 import { catalogOperations } from "./catalog-operations.ts";
 import { contextOperations } from "./context-operations.ts";
 import { exportOperations } from "./export-operations.ts";
@@ -74,6 +76,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"router.clear_override",
 	"router.current_route",
 	"router.available_routes",
+	"cache.economics",
 ] as const;
 
 export type OperationName = (typeof EXPECTED_OPERATION_NAMES)[number];
@@ -117,6 +120,7 @@ export interface OperationInputs {
 	"router.clear_override": RouterScopeInput;
 	"router.current_route": Route & RouterScopeInput;
 	"router.available_routes": { routes: Route[] } & RouterScopeInput;
+	"cache.economics": { since: number; until: number };
 }
 export interface OperationOutputs {
 	"session.register": RegisterSessionIdentityResult;
@@ -154,6 +158,7 @@ export interface OperationOutputs {
 	"router.clear_override": RouterStatus;
 	"router.current_route": RouterStatus;
 	"router.available_routes": RouterStatus;
+	"cache.economics": CacheEconomicsSummary;
 }
 
 export class UnknownOperationError extends Error {}
@@ -286,6 +291,7 @@ export class JittorService {
 			...routerOperations(router, authorize),
 			...modelRankingOperations(modelRanker, router, authorize),
 			...sessionIdentityOperations(sessionIdentity),
+			...cacheEconomicsOperations(metrics, catalog),
 		};
 		this.vehicleRegistry = new VehicleRegistry({
 			name: "jittor",