auto-model-router 0.33.0 → 0.35.0

package/src/util/schema.ts

@@ -8,19 +8,137 @@
  * has no history to migrate, and on an already-migrated file every statement
  * here is a no-op.
  *
+ * On Postgres the ledger is additionally PARTITIONED BY RANGE over
+ * `created_at_ms`, one partition per UTC day. Retention is then a metadata
+ * DROP rather than a bulk DELETE, which matters at the sizes this store is
+ * built for: a ledger row is ~2.6 kB, and 10k-50k users write 33-165 GB a day
+ * at 440-2200 writes a second. Deleting that competes for I/O with the inserts
+ * it is trying to make room for, and leaves bloat autovacuum has to chase.
+ *
+ * Every read is unchanged: the bounds ARE ms-epoch integers, so a
+ * `created_at_ms >= x` filter prunes partitions on its own and no query needs
+ * to know the table is partitioned. SQLite has no declarative partitioning and
+ * keeps exactly the shape it always had.
+ *
  * The two must agree, so the definitions below are transcribed from
  * `util/sqlite.ts` with its incremental columns folded in, and
  * `test/schema.test.ts` compares the two engine-by-engine rather than trusting
  * that they were copied correctly.
  */
 
+import type { Logger } from "./log.ts";
 import type { SqlDb } from "./sql.ts";
 
+const DAY_MS = 86_400_000;
+
+/**
+ * Days of ledger partitions provisioned ahead of today. A turn at 23:59:59
+ * must not depend on a partition created at 00:00:00, and a process that runs
+ * for days without rebooting still has runway.
+ */
+const LEDGER_PARTITION_AHEAD_DAYS = 3;
+
+/** The start of the UTC day an ms-epoch instant falls in — a partition bound. */
+export function ledgerDayStart(ms: number): number {
+	return Math.floor(ms / DAY_MS) * DAY_MS;
+}
+
+/** The partition holding the UTC day that starts at `dayStartMs`, e.g. `ledger_p20260914`. */
+export function ledgerPartitionName(dayStartMs: number): string {
+	return `ledger_p${new Date(dayStartMs).toISOString().slice(0, 10).replaceAll("-", "")}`;
+}
+
+/**
+ * `IF NOT EXISTS` is not atomic on Postgres: two replicas booting against a
+ * fresh database both pass the existence check and the loser fails on the
+ * unique index over pg_type (23505), or on the table name itself (42P07 /
+ * 42710). Measured: one of two replicas started together died with
+ * "duplicate key value violates unique constraint pg_type_typname_nsp_index".
+ * The condition those errors report is the condition the statement asked to
+ * tolerate, so they are the success case arriving from the other replica.
+ */
+const RACED = new Set(["23505", "42P07", "42710"]);
+
+async function createIfAbsent(db: SqlDb, statement: string): Promise<void> {
+	try {
+		await db.sql.unsafe(statement);
+	} catch (err) {
+		const code = err !== null && typeof err === "object" && "errno" in err ? String(err.errno) : "";
+		if (!RACED.has(code)) throw err;
+	}
+}
+
+/**
+ * How this store holds the ledger.
+ *
+ * `plain` is SQLite, and also a Postgres ledger created before partitioning
+ * shipped: Postgres cannot convert a populated table to a partitioned one in
+ * place, so an existing deployment keeps the table it has (see `migrateStore`).
+ */
+export async function ledgerLayout(db: SqlDb): Promise<"partitioned" | "plain" | "absent"> {
+	if (db.dialect !== "postgres") return (await db.tableExists("ledger")) ? "plain" : "absent";
+	const rows = await db.query<{ relkind: string }>("SELECT relkind FROM pg_class WHERE oid = to_regclass('ledger')");
+	const kind = rows[0]?.relkind;
+	if (kind === "p") return "partitioned";
+	return kind === undefined ? "absent" : "plain";
+}
+
+/**
+ * Creates the day partitions around `aroundMs` — yesterday through
+ * `aheadDays` — so the write path never meets a day nobody provisioned.
+ * Idempotent and a no-op on any store whose ledger is not partitioned.
+ *
+ * Yesterday is included because a row's `created_at_ms` is the instant the turn
+ * STARTED: a boot just after midnight, or a replica whose clock trails the one
+ * that provisioned, can still present the previous day.
+ */
+export async function ensureLedgerPartitions(db: SqlDb, aroundMs = Date.now(), aheadDays = LEDGER_PARTITION_AHEAD_DAYS): Promise<void> {
+	if ((await ledgerLayout(db)) !== "partitioned") return;
+	const today = ledgerDayStart(aroundMs);
+	for (let start = today - DAY_MS; start <= today + aheadDays * DAY_MS; start += DAY_MS) {
+		await createIfAbsent(
+			db,
+			`CREATE TABLE IF NOT EXISTS ${ledgerPartitionName(start)} PARTITION OF ledger FOR VALUES FROM (${start}) TO (${start + DAY_MS})`,
+		);
+	}
+}
+
+/**
+ * Ledger partitions whose whole range ends at or before `upToMs`, oldest
+ * first: the ones a retention cutoff covers completely.
+ *
+ * Bounds are read from the catalog rather than parsed out of the partition's
+ * name, so a partition an operator attached by hand is judged on what it
+ * actually holds, and one with an unreadable or DEFAULT bound is skipped
+ * rather than guessed at — the rows in it are then pruned by the row-wise
+ * DELETE, which is slower but never drops a day it did not verify.
+ */
+export async function droppableLedgerPartitions(db: SqlDb, upToMs: number): Promise<string[]> {
+	if ((await ledgerLayout(db)) !== "partitioned") return [];
+	const rows = await db.query<{ name: string; bound: string | null }>(
+		`SELECT c.relname AS name, pg_get_expr(c.relpartbound, c.oid) AS bound
+		 FROM pg_class c JOIN pg_inherits i ON i.inhrelid = c.oid
+		 WHERE i.inhparent = to_regclass('ledger')`,
+	);
+	const covered: { name: string; endMs: number }[] = [];
+	for (const row of rows) {
+		const upper = /TO \('?(-?\d+)'?\)/.exec(row.bound ?? "");
+		if (upper === null) continue;
+		const endMs = Number(upper[1]);
+		if (endMs <= upToMs) covered.push({ name: row.name, endMs });
+	}
+	covered.sort((a, b) => a.endMs - b.endMs);
+	return covered.map((p) => p.name);
+}
+
 /**
  * Creates every table and index the router uses. Idempotent, so boot order
  * never matters — the property the SQLite bootstrap has always had.
  */
-export async function migrateStore(db: SqlDb): Promise<void> {
+export async function migrateStore(db: SqlDb, log?: Logger): Promise<void> {
+	// Postgres partitions the ledger by day; SQLite has no declarative
+	// partitioning, so it keeps the single table it always had.
+	const partitioned = db.dialect === "postgres" && (await ledgerLayout(db)) !== "plain";
 	const json = db.type("json");
 	const float = db.type("float");
 	const big = db.type("bigint");
@@ -41,8 +159,14 @@ export async function migrateStore(db: SqlDb): Promise<void> {
 
 		// One row per dispatched upstream generation. The columns nineteen
 		// migrations added are declared here as they finally stand.
+		//
+		// Partitioned by day on Postgres, which forces the primary key to
+		// include the partition key — a unique index on a partitioned table has
+		// to. `id` alone stays unique in practice (it is a fresh UUID per entry),
+		// and a re-recorded entry carries the same `created_at_ms`, so the
+		// ON CONFLICT guard in `record` still collapses it.
 		`CREATE TABLE IF NOT EXISTS ledger (
-			id TEXT PRIMARY KEY,
+			id TEXT${partitioned ? "" : " PRIMARY KEY"},
 			created_at_ms ${big} NOT NULL,
 			conversation_key TEXT NOT NULL,
 			session_id TEXT NOT NULL,
@@ -77,8 +201,11 @@ export async function migrateStore(db: SqlDb): Promise<void> {
 			hold_arm INTEGER,
 			prompt_tokens_saved INTEGER,
 			scope TEXT,
-			redactions INTEGER
-		)`,
+			redactions INTEGER${partitioned ? ",\n\t\t\tPRIMARY KEY (id, created_at_ms)" : ""}
+		)${partitioned ? " PARTITION BY RANGE (created_at_ms)" : ""}`,
+		// The composite key above cannot serve a lookup by `id` alone, which is
+		// what the feedback join and `markWasted` do.
+		...(partitioned ? ["CREATE INDEX IF NOT EXISTS idx_ledger_id ON ledger (id)"] : []),
 		"CREATE INDEX IF NOT EXISTS idx_ledger_conversation ON ledger (conversation_key)",
 		"CREATE INDEX IF NOT EXISTS idx_ledger_created ON ledger (created_at_ms)",
 		"CREATE INDEX IF NOT EXISTS idx_ledger_slug ON ledger (slug)",
@@ -166,22 +293,24 @@ export async function migrateStore(db: SqlDb): Promise<void> {
 		)`,
 	];
 
-	// `IF NOT EXISTS` is not atomic on Postgres: two replicas booting against a
-	// fresh database both pass the existence check and the loser fails on the
-	// unique index over pg_type (23505), or on the table name itself (42P07 /
-	// 42710). Measured: one of two replicas started together died with
-	// "duplicate key value violates unique constraint pg_type_typname_nsp_index".
-	// The condition those errors report is the condition the statement asked to
-	// tolerate, so they are the success case arriving from the other replica.
-	const RACED = new Set(["23505", "42P07", "42710"]);
-	for (const statement of statements) {
-		try {
-			await db.sql.unsafe(statement);
-		} catch (err) {
-			const code = (err as { errno?: unknown }).errno;
-			if (!RACED.has(String(code))) throw err;
-		}
+	for (const statement of statements) await createIfAbsent(db, statement);
+
+	if (db.dialect !== "postgres") return;
+	if (partitioned) {
+		// Ahead of need: the write path must never be the thing that discovers a
+		// day has no partition (it recovers, but a bill should not depend on that).
+		await ensureLedgerPartitions(db);
+		return;
 	}
+	// A Postgres ledger from before this shipped. Postgres cannot convert a
+	// populated table to a partitioned one in place, and copying a billing table
+	// at boot is the one failure mode the ledger must not have, so the existing
+	// table is left exactly as it is and retention keeps deleting rows. The
+	// conversion is an operator's decision, taken with the router stopped.
+	log?.warn("ledger is not partitioned by day, so retention will delete rows instead of dropping partitions; partitioning applies to new deployments", {
+		convert:
+			"stop every replica, then: ALTER TABLE ledger RENAME TO ledger_legacy; start the router (it recreates ledger partitioned); INSERT INTO ledger SELECT * FROM ledger_legacy; verify the counts match; DROP TABLE ledger_legacy",
+	});
 }
 
 /** Every table `migrateStore` creates, for tests and for teardown. */

package/test/failover.test.ts

@@ -31,7 +31,7 @@ import type {
 function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 	return {
 		server: { host: "127.0.0.1", port: 8787, maxConcurrentTurns: 24, subagentProfile: "auto-sub" },
-		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0 },
+		openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "", title: "test", timeoutMs: 30_000, catalogTtlMs: 3_600_000, catalogRefreshMs: 0, minCreditsUsd: 0, usagePollMs: 0 },
 		ollama: { enabled: false, baseUrl: "http://127.0.0.1:11434/v1", apiKey: "", timeoutMs: 30_000, catalogTtlMs: 300_000, includeLocal: false, prices: {}, twins: {}, costBias: 1, biasUntilUsage: 0.9, usagePollMs: 0, quotaCooldownMs: 0, rateLimitCooldownMs: 0, planCreditsUsd: 0 },
 		upstreams: [],
 		benchmarks: { enabled: false, artificialAnalysisApiKey: "", benchlm: true, refreshMs: 86_400_000, timeoutMs: 30_000, useLocalScores: false },
@@ -380,6 +380,33 @@ describe("same-tier failover", () => {
 		expect(finishes[0]!.attempts).toBe(2);
 	});
 
+	test("a Kimi credit 429 fails over to another provider's model in the SAME turn", async () => {
+		// Moonshot's balance wording misclassified as rate_limit used to let the
+		// raw 429 (Retry-After 30 min) reach the client. Quota is retryable
+		// elsewhere: the retry re-routes with the failed slug excluded.
+		const { router, calls } = mkRouter([mkDecision("moderate", "kimi/kimi-k3"), mkDecision("moderate", "openrouter/grok-4")]);
+		const { upstream, calls: dispatches } = mkUpstream([
+			{ kind: "fail", error: new UpstreamError("quota", 429, "This request would exceed your available credits given your current in-flight requests", true) },
+			{ kind: "chunks", chunks: okChunks("openrouter/grok-4") },
+		]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors, finishes } = mkSink();
+
+		await runTurn(mkReq(), sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog, context: createDisabledBridge() }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(finishes).toHaveLength(1);
+		expect(calls).toHaveLength(2);
+		expect(calls[1]).toEqual({ attempt: 1, excludeSlugs: ["kimi/kimi-k3"] });
+		expect(dispatches.map((d) => d.body.model)).toEqual(["kimi/kimi-k3", "openrouter/grok-4"]);
+		expect(entries[0]!.error).toContain("available credits");
+		expect(entries[0]!.wasted).toBe(true);
+		expect(entries[1]!.wasted).toBe(false);
+		expect(finishes[0]!.servedSlug).toBe("openrouter/grok-4");
+		expect(finishes[0]!.escalated).toBe(false);
+	});
+
 	test("a 403 moderation block fails over to a different model in the same tier", async () => {
 		const { router, calls } = mkRouter([mkDecision("trivial", "a/model"), mkDecision("trivial", "b/model")]);
 		const { upstream, calls: dispatches } = mkUpstream([
@@ -664,6 +691,7 @@ describe("same-tier failover", () => {
 
 });
 
+
 describe("400 classification (review 2026-09-05 follow-up)", () => {
 	test("a 400 naming a model capability limit is retryable, so failover picks a sibling", async () => {
 		const e = classifyUpstreamStatus(400, { error: { message: "This model only supports single tool-calls at once!" } });
@@ -677,6 +705,19 @@ describe("400 classification (review 2026-09-05 follow-up)", () => {
 		expect(e.retryable).toBe(false);
 	});
 
+	test("an OpenRouter 402 naming in-flight requests is a concurrency throttle, retryable like a rate limit", async () => {
+		// OpenRouter reserves credits per in-flight request: a burst can exhaust
+		// the UNRESERVED balance on an account with plenty left. It clears when
+		// the streams settle — fail over, never surface to the client.
+		const e = classifyUpstreamStatus(402, { error: { message: "This request would exceed your available credits given your current in-flight requests. Retry after in-flight requests settle, or add credits." } });
+		expect(e.kind).toBe("rate_limit");
+		expect(e.retryable).toBe(true);
+		// A plain 402 (balance actually gone) stays final.
+		const broke = classifyUpstreamStatus(402, { error: { message: "Insufficient credits" } });
+		expect(broke.kind).toBe("auth");
+		expect(broke.retryable).toBe(false);
+	});
+
 	test("a 400 for context overflow is still context_length", async () => {
 		const e = classifyUpstreamStatus(400, { error: { message: "This endpoint's maximum context length is 131072 tokens" } });
 		expect(e.kind).toBe("context_length");

package/test/ledger-partitions.test.ts

@@ -0,0 +1,321 @@
+/**
+ * The ledger's day partitions, on every engine it claims to support.
+ *
+ * SQLite runs always (a temp file) and MUST be unchanged by any of this: it has
+ * no declarative partitioning, so every assertion below has to hold on the
+ * single table it always had. Postgres runs when AMR_ROUTER_TEST_PG points at
+ * one, following this repo's convention for store tests.
+ *
+ * What is actually being defended: retention on a store taking 33-165 GB a day
+ * cannot be a bulk DELETE, and the conversion to something cheaper must not
+ * change a single figure a bill is read from — nor lose a row on a deployment
+ * that upgrades into it.
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+import { createSqlLedger } from "../src/cost/ledger-sql.ts";
+import { exportRows, spendUsdSince } from "../src/cost/views.ts";
+import { EMPTY_USAGE, type AsyncLedger, type LedgerEntry } from "../src/cost/types.ts";
+import type { Logger } from "../src/util/log.ts";
+import {
+	droppableLedgerPartitions,
+	ensureLedgerPartitions,
+	ledgerDayStart,
+	ledgerLayout,
+	ledgerPartitionName,
+	migrateStore,
+} from "../src/util/schema.ts";
+import { num, openSqlDb, type SqlDb } from "../src/util/sql.ts";
+
+const DAY = 86_400_000;
+const PG = process.env.AMR_ROUTER_TEST_PG;
+
+const engines: { name: string; url: string; partitions: boolean }[] = [
+	{ name: "sqlite", url: `sqlite://${join(tmpdir(), `ledger-part-${process.pid}-${Date.now()}.db`)}`, partitions: false },
+	...(PG === undefined ? [] : [{ name: "postgres", url: PG, partitions: true }]),
+];
+
+function entry(over: Partial<LedgerEntry> & { id: string }): LedgerEntry {
+	return {
+		createdAtMs: Date.now(),
+		conversationKey: `conv-${over.id}`,
+		sessionId: `sess-${over.id}`,
+		turn: 1,
+		requestedModel: "auto",
+		harnessId: "hp",
+		ompSessionId: `omp-${over.id}`,
+		slug: "x/model",
+		servedSlug: "x/model",
+		tier: "simple",
+		classificationSource: "heuristic",
+		reasons: ["cheapest"],
+		predictedUsd: 0.001,
+		reportedUsd: 0.002,
+		usage: { ...EMPTY_USAGE, promptTokens: 100, completionTokens: 10 },
+		attempt: 0,
+		escalationSignal: null,
+		latencyMs: 10,
+		ttftMs: 5,
+		finishReason: "stop",
+		wasted: false,
+		upstreamGenerationId: null,
+		error: null,
+		features: null,
+		score: null,
+		confidence: null,
+		task: null,
+		classifierReasons: null,
+		exploredFrom: null,
+		holdArm: null,
+		promptTokensSaved: null,
+		scope: "team/proj",
+		redactions: null,
+		...over,
+	} as unknown as LedgerEntry;
+}
+
+/** Live day partitions of the ledger, by name; empty on an unpartitioned store. */
+async function partitionsOf(db: SqlDb): Promise<string[]> {
+	if ((await ledgerLayout(db)) !== "partitioned") return [];
+	const rows = await db.query<{ name: string }>(
+		"SELECT c.relname AS name FROM pg_class c JOIN pg_inherits i ON i.inhrelid = c.oid WHERE i.inhparent = to_regclass('ledger') ORDER BY 1",
+	);
+	return rows.map((r) => r.name);
+}
+
+for (const engine of engines) {
+	describe(`ledger partitioning on ${engine.name}`, () => {
+		let db: SqlDb;
+		const cfg: RouterConfig = { ...structuredClone(DEFAULT_CONFIG), ledger: { ...DEFAULT_CONFIG.ledger, path: engine.url } };
+		let ledger: AsyncLedger;
+
+		/** A fresh store: what a NEW deployment boots into, not what an old one upgraded to. */
+		const fresh = async (): Promise<void> => {
+			if (db.dialect === "postgres") await db.sql.unsafe("DROP TABLE IF EXISTS ledger");
+			await migrateStore(db);
+		};
+
+		beforeAll(async () => {
+			db = openSqlDb(engine.url);
+			await fresh();
+			ledger = createSqlLedger(db, cfg, { findModel: () => null });
+		});
+
+		afterAll(async () => {
+			// Leave the shared database in the shape a fresh boot produces, whatever
+			// the legacy test below did to it.
+			await fresh();
+			await db.close();
+		});
+
+		beforeEach(async () => {
+			await db.sql.unsafe("DELETE FROM ledger");
+			await db.sql.unsafe("DELETE FROM feedback");
+		});
+
+		test("a fresh store partitions by day on postgres and not on sqlite, and a turn writes and reads back", async () => {
+			expect(await ledgerLayout(db)).toBe(engine.partitions ? "partitioned" : "plain");
+			// Ahead of need: today's partition exists before any turn arrives, and
+			// so do the next few days, so a turn at 23:59:59 cannot be the first to
+			// need tomorrow's.
+			const today = ledgerDayStart(Date.now());
+			const expected = engine.partitions
+				? [-1, 0, 1, 2, 3].map((d) => ledgerPartitionName(today + d * DAY))
+				: [];
+			expect(await partitionsOf(db)).toEqual(expected);
+
+			await ledger.record(entry({ id: "t1", reportedUsd: 0.5 }));
+			const recent = await ledger.recentEntries(10);
+			expect(recent.map((e) => e.id)).toEqual(["t1"]);
+			// The JSON columns and the money survive the trip through a partition.
+			expect(recent[0]?.usage.promptTokens).toBe(100);
+			expect(recent[0]?.reasons).toEqual(["cheapest"]);
+			expect(await ledger.spendSince(0, "hp")).toBeCloseTo(0.5, 9);
+			expect((await ledger.latestForSession("omp-t1"))?.id).toBe("t1");
+		});
+
+		test("a turn for a day nobody provisioned still records, and the day exists afterwards", async () => {
+			// 40 days back is outside every partition `migrateStore` created. On
+			// Postgres the insert is refused once, the day is created, and the row
+			// lands — the caller never sees a failure, because a ledger row is a
+			// bill and there is no second copy of it.
+			const backdated = Date.now() - 40 * DAY;
+			await ledger.record(entry({ id: "late", createdAtMs: backdated, reportedUsd: 0.25 }));
+			// And forwards: a process that has been up for a week.
+			const ahead = Date.now() + 9 * DAY;
+			await ledger.record(entry({ id: "ahead", createdAtMs: ahead, reportedUsd: 0.75 }));
+
+			expect((await ledger.recentEntries(10)).map((e) => e.id).sort()).toEqual(["ahead", "late"]);
+			expect(await ledger.spendSince(0, "hp")).toBeCloseTo(1, 9);
+			if (!engine.partitions) return;
+			const live = await partitionsOf(db);
+			expect(live).toContain(ledgerPartitionName(ledgerDayStart(backdated)));
+			expect(live).toContain(ledgerPartitionName(ledgerDayStart(ahead)));
+		});
+
+		test("prune drops whole days, keeps the recent window, and counts rows rather than partitions", async () => {
+			// One instant for both the rows and the cutoff: `oldestKeptMs` is an
+			// exact row timestamp, so a second Date.now() would be milliseconds off.
+			const nowMs = Date.now();
+			for (const age of [400, 200, 1]) {
+				await ledger.record(entry({ id: `p${age}`, createdAtMs: nowMs - age * DAY }));
+			}
+			expect(await ledger.prune(365, nowMs)).toEqual({ deleted: 1, oldestKeptMs: expect.any(Number) });
+			expect((await ledger.recentEntries(10)).map((e) => e.id).sort()).toEqual(["p1", "p200"]);
+			if (engine.partitions) {
+				// The dropped day is gone as a table, not just as rows.
+				expect(await partitionsOf(db)).not.toContain(ledgerPartitionName(ledgerDayStart(nowMs - 400 * DAY)));
+				expect(await partitionsOf(db)).toContain(ledgerPartitionName(ledgerDayStart(nowMs - 200 * DAY)));
+			}
+			expect((await ledger.prune(30, nowMs)).deleted).toBe(1);
+			expect((await ledger.recentEntries(10)).map((e) => e.id)).toEqual(["p1"]);
+			// Nothing left to remove, and the window is reported from real rows.
+			expect(await ledger.prune(30, nowMs)).toEqual({ deleted: 0, oldestKeptMs: nowMs - DAY });
+		});
+
+		test("the boundary day the cutoff falls inside is pruned row by row, so the count stays honest", async () => {
+			// The cutoff at noon splits a day: its partition holds rows on both
+			// sides of it and must not be dropped, while the day before it goes
+			// whole. `deleted` has to count both kinds of row and nothing else.
+			const cutoff = ledgerDayStart(Date.now()) + 12 * 3_600_000;
+			const nowMs = cutoff + DAY;
+			await ledger.record(entry({ id: "b_before", createdAtMs: cutoff - 60_000 }));
+			await ledger.record(entry({ id: "b_after", createdAtMs: cutoff + 60_000 }));
+			await ledger.record(entry({ id: "b_whole", createdAtMs: cutoff - 2 * DAY }));
+
+			expect((await ledger.prune(1, nowMs)).deleted).toBe(2);
+			expect((await ledger.recentEntries(10)).map((e) => e.id)).toEqual(["b_after"]);
+			if (!engine.partitions) return;
+			const live = await partitionsOf(db);
+			expect(live).toContain(ledgerPartitionName(ledgerDayStart(cutoff)));
+			expect(live).not.toContain(ledgerPartitionName(ledgerDayStart(cutoff - 2 * DAY)));
+			// And the partial day was not covered by a drop: the helper only ever
+			// offers partitions whose whole range is behind the cutoff.
+			expect(await droppableLedgerPartitions(db, cutoff)).not.toContain(ledgerPartitionName(ledgerDayStart(cutoff)));
+		});
+
+		test("export, spend and cap reads see exactly what they saw before partitioning", async () => {
+			const day = ledgerDayStart(Date.now()) + 3_600_000;
+			await ledger.record(entry({ id: "v1", createdAtMs: day, reportedUsd: 1 }));
+			await ledger.record(entry({ id: "v2", createdAtMs: day + 60_000, reportedUsd: 2, harnessId: "other" }));
+			await ledger.record(entry({ id: "v3", createdAtMs: day - 2 * DAY, reportedUsd: 4 }));
+
+			const rows = await exportRows(db, 0, null);
+			expect(rows.map((r) => [r.day, r.harnessId, r.dispatches, r.spendUsd])).toEqual([
+				[new Date(day - 2 * DAY).toISOString().slice(0, 10), "hp", 1, 4],
+				[new Date(day).toISOString().slice(0, 10), "hp", 1, 1],
+				[new Date(day).toISOString().slice(0, 10), "other", 1, 2],
+			]);
+			expect(rows.every((r) => r.scope === "team/proj")).toBe(true);
+			// The cap reads: whole ledger, one harness, one window, one project.
+			expect(await spendUsdSince(db, 0, null)).toBeCloseTo(7, 9);
+			expect(await spendUsdSince(db, 0, ["hp"])).toBeCloseTo(5, 9);
+			expect(await spendUsdSince(db, day, null)).toBeCloseTo(3, 9);
+			expect(await spendUsdSince(db, 0, null, "team/proj")).toBeCloseTo(7, 9);
+			expect(await ledger.spendSince(day - DAY, "hp")).toBeCloseTo(1, 9);
+			expect(await ledger.conversationSpend("conv-v3")).toBeCloseTo(4, 9);
+			expect((await ledger.trust("x/model", "hp"))?.attempts).toBe(2);
+		});
+
+		test("ensuring partitions is idempotent and never touches an unpartitioned store", async () => {
+			const before = await partitionsOf(db);
+			await ensureLedgerPartitions(db);
+			await ensureLedgerPartitions(db);
+			expect(await partitionsOf(db)).toEqual(before);
+			expect(await ledgerLayout(db)).toBe(engine.partitions ? "partitioned" : "plain");
+		});
+	});
+}
+
+/**
+ * The upgrade path. A deployment with a populated, unpartitioned `ledger` is
+ * holding billing history with no second copy, and Postgres cannot convert a
+ * table to a partitioned one in place — so the chosen behaviour is to leave it
+ * exactly as it is, say so once, and keep working.
+ */
+describe.skipIf(PG === undefined)("a legacy unpartitioned postgres ledger", () => {
+	let db: SqlDb;
+	const cfg: RouterConfig = { ...structuredClone(DEFAULT_CONFIG), ledger: { ...DEFAULT_CONFIG.ledger, path: PG ?? "" } };
+	const warnings: string[] = [];
+	const capture: Logger = {
+		error: () => {},
+		warn: (msg) => warnings.push(msg),
+		info: () => {},
+		debug: () => {},
+	};
+
+	beforeAll(async () => {
+		db = openSqlDb(PG as string);
+		await db.sql.unsafe("DROP TABLE IF EXISTS ledger");
+		await migrateStore(db);
+		// Reshape it into what an older release left behind: the same columns, one
+		// plain table. `LIKE` copies the column list off the partitioned parent,
+		// so this fixture cannot drift from the real schema.
+		await db.sql.unsafe("DROP TABLE IF EXISTS ledger_legacy_fixture");
+		await db.sql.unsafe("CREATE TABLE ledger_legacy_fixture (LIKE ledger INCLUDING DEFAULTS)");
+		await db.sql.unsafe("DROP TABLE ledger");
+		await db.sql.unsafe("ALTER TABLE ledger_legacy_fixture RENAME TO ledger");
+		await db.sql.unsafe("ALTER TABLE ledger ADD PRIMARY KEY (id)");
+	});
+
+	afterAll(async () => {
+		await db.sql.unsafe("DROP TABLE IF EXISTS ledger");
+		await migrateStore(db);
+		await db.close();
+	});
+
+	test("it is left alone, its rows are kept, and the operator is told once how to convert", async () => {
+		const ledger = createSqlLedger(db, cfg, { findModel: () => null });
+		await ledger.record(entry({ id: "legacy1", createdAtMs: Date.now() - 400 * DAY, reportedUsd: 3 }));
+		warnings.length = 0;
+
+		await migrateStore(db, capture);
+
+		expect(await ledgerLayout(db)).toBe("plain");
+		expect(num((await db.one<{ n: unknown }>("SELECT COUNT(*) AS n FROM ledger"))?.n)).toBe(1);
+		expect(warnings.filter((w) => w.includes("not partitioned"))).toHaveLength(1);
+		// Still a working ledger, and retention still applies — row-wise, which is
+		// the cost of not converting.
+		await ledger.record(entry({ id: "legacy2", reportedUsd: 5 }));
+		expect(await ledger.spendSince(0, "hp")).toBeCloseTo(8, 9);
+		expect(await droppableLedgerPartitions(db, Date.now())).toEqual([]);
+		expect((await ledger.prune(365)).deleted).toBe(1);
+		expect((await ledger.recentEntries(10)).map((e) => e.id)).toEqual(["legacy2"]);
+	});
+
+	test("every read returns the same figures on the partitioned table as on the legacy one", async () => {
+		// The same three turns, read twice: once through the table a deployment
+		// already has, once through the partitioned one a fresh boot creates. Any
+		// difference here is a bill that changed because of a storage decision.
+		const rows = [
+			entry({ id: "same1", createdAtMs: ledgerDayStart(Date.now()) + 3_600_000, reportedUsd: 1 }),
+			entry({ id: "same2", createdAtMs: ledgerDayStart(Date.now()) + 7_200_000, reportedUsd: 2, harnessId: "other" }),
+			entry({ id: "same3", createdAtMs: ledgerDayStart(Date.now()) - 5 * DAY, reportedUsd: 4 }),
+		];
+		const read = async (): Promise<unknown> => {
+			const ledger = createSqlLedger(db, cfg, { findModel: () => null });
+			await db.sql.unsafe("DELETE FROM ledger");
+			for (const row of rows) await ledger.record(row);
+			return {
+				exported: await exportRows(db, 0, null),
+				all: await spendUsdSince(db, 0, null),
+				scoped: await spendUsdSince(db, 0, ["hp"]),
+				project: await spendUsdSince(db, 0, null, "team/proj"),
+				trust: await ledger.trust("x/model"),
+				entries: (await ledger.recentEntries(10)).map((e) => e.id),
+			};
+		};
+
+		expect(await ledgerLayout(db)).toBe("plain");
+		const legacy = await read();
+
+		await db.sql.unsafe("DROP TABLE ledger");
+		await migrateStore(db);
+		expect(await ledgerLayout(db)).toBe("partitioned");
+		expect(await read()).toEqual(legacy);
+	});
+});

package/test/openrouter-usage.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { createOpenRouterUsageSource, NO_OPENROUTER_USAGE, openRouterServing, type OpenRouterCredits } from "../src/upstream/openrouter-usage.ts";
+import { createLogger } from "../src/util/log.ts";
+
+const log = createLogger("error");
+
+function credits(remaining: number | null): OpenRouterCredits | null {
+	return remaining === null ? null : { remainingUsd: remaining, totalCreditsUsd: 100, totalUsageUsd: 100 - remaining, fetchedAtMs: 1 };
+}
+
+describe("openRouterServing", () => {
+	test("serves above the floor and stops at/below it", () => {
+		expect(openRouterServing(credits(5.01), 5)).toBe(true);
+		expect(openRouterServing(credits(5), 5)).toBe(false);
+		expect(openRouterServing(credits(0), 5)).toBe(false);
+	});
+
+	test("fails open on unknown balance and when the gate is off", () => {
+		expect(openRouterServing(null, 5)).toBe(true);
+		expect(openRouterServing(credits(0), 0)).toBe(true);
+	});
+});
+
+describe("createOpenRouterUsageSource", () => {
+	test("returns null without a key and parses the credits payload", async () => {
+		const unkeyed = createOpenRouterUsageSource({ apiKey: () => "", pollMs: 1000, timeoutMs: 100, log, root: "https://x/v1" });
+		expect(await unkeyed.get()).toBe(null);
+		expect(NO_OPENROUTER_USAGE.peek()).toBe(null);
+
+		let calls = 0;
+		const src = createOpenRouterUsageSource({
+			apiKey: () => "k",
+			pollMs: 1000,
+			timeoutMs: 100,
+			log,
+			root: "https://x/v1",
+			fetchImpl: async () => {
+				calls++;
+				return new Response(JSON.stringify({ data: { total_credits: 20, total_usage: 13.5 } }), { status: 200 });
+			},
+		});
+		const v = await src.get();
+		expect(calls).toBe(1);
+		expect(v?.remainingUsd).toBe(6.5);
+		expect(src.peek()?.totalUsageUsd).toBe(13.5);
+
+		// A failed poll keeps the last good reading instead of hiding the provider.
+		const failing = createOpenRouterUsageSource({
+			apiKey: () => "k",
+			pollMs: 0,
+			timeoutMs: 100,
+			log,
+			root: "https://x/v1",
+			fetchImpl: async () => new Response("nope", { status: 500 }),
+		});
+		await failing.get();
+		expect(failing.peek()).toBe(null); // never had a reading; gate stays open on unknown
+	});
+});