auto-model-router 0.33.0 → 0.34.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.33.0",
+    "version": "0.34.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.33.0",
+      "version": "0.34.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1192,6 +1192,16 @@ it lands on the other (`cache: keeping warm …`), and a replica that has served
 nothing refuses with `402 budget_exceeded` once the shared spend is past its
 cap — where the same cap against an empty store serves.
 
+On Postgres the `ledger` table is partitioned by UTC day
+(`PARTITION BY RANGE (created_at_ms)`), so `ledger.retentionDays` drops whole
+days as partitions instead of deleting rows — at the write rates a shared store
+is for, a bulk `DELETE` competes for I/O with the inserts it is making room
+for. Partitions are provisioned a few days ahead on every boot and created on
+demand if a turn arrives for a day nobody provisioned, so a write never fails
+for a missing partition. A Postgres ledger created before this is left exactly
+as it is (Postgres cannot convert a populated table in place) and logs how to
+convert; see [Data governance](docs/data-governance.md).
+
 A SQLite deployment is unchanged: the file is still migrated in place through
 the nineteen shipped versions, and both halves live in the one file.
 

package/docs/data-governance.md

@@ -166,7 +166,12 @@ one a library default should make for them. (Before v0.21.0 the default was
    because the subquery needs the rows that are about to be deleted.
 2. `ollama_meter_samples` past the cutoff. They only calibrate the ledger's own
    Ollama estimate, so they age out with the rows they calibrate.
-3. `ledger` rows past the cutoff.
+3. `ledger` rows past the cutoff. On Postgres the ledger is partitioned by UTC
+   day, so every day the cutoff covers *completely* is dropped as a partition —
+   a metadata operation — and only the boundary day the cutoff falls inside is
+   deleted row by row. `deleted` still counts ROWS: each partition is counted
+   before it is dropped, so the number means turns, not tables. SQLite has no
+   declarative partitioning and deletes rows as it always has.
 
 Then, when anything was deleted, `PRAGMA incremental_vacuum` hands freed pages
 back to the filesystem and `PRAGMA wal_checkpoint(TRUNCATE)` folds the WAL so
@@ -182,6 +187,42 @@ behaviour and is fine.
 honest answer to "how far back does this ledger go now", which is what the
 question was actually about, and it is reported even when nothing was deleted.
 
+### Partitions, on Postgres
+
+A ledger row is ~2.6 kB, and a thousand-tenant deployment writes 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. So on Postgres `ledger` is `PARTITION BY RANGE (created_at_ms)`, one
+partition per UTC day, and retention becomes a `DROP TABLE` per day.
+
+The bounds are the ms-epoch integers the column already holds, not a derived
+timestamp, so every existing query (`created_at_ms >= ?`) prunes partitions on
+its own: no read — export, spend, the caps, the decision trail — knows the
+table is partitioned. The one visible consequence is the primary key, which a
+partitioned table requires to include the partition key: it is
+`(id, created_at_ms)` there. Ids are per-row UUIDs and a re-recorded entry
+carries the same instant, so the `ON CONFLICT DO NOTHING` guard still collapses
+a duplicate write.
+
+`migrateStore` provisions yesterday through three days ahead on every boot. A
+row for a day nobody provisioned is not an error either: the insert is retried
+once after `ensureLedgerPartitions` creates that day (and the next few), so a
+turn is never lost because a partition was late.
+
+A Postgres ledger created before this shipped **stays exactly as it is**.
+Postgres cannot convert a populated table to a partitioned one in place, and
+copying a billing table at boot is not a failure mode a ledger can have — there
+is no second copy of it. The router logs one line saying retention will keep
+deleting rows there, with the conversion an operator can run deliberately, with
+the router stopped:
+
+```sql
+ALTER TABLE ledger RENAME TO ledger_legacy;      -- then start the router:
+                                                 -- boot recreates it partitioned
+INSERT INTO ledger SELECT * FROM ledger_legacy;  -- verify the counts, then
+DROP TABLE ledger_legacy;
+```
+
 ### The schedule, and the route
 
 `createRetentionRunner` (`src/cost/retention.ts`) owns the once-an-hour floor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cost/ledger-sql.ts

@@ -22,6 +22,7 @@
 import type { CatalogModel } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { consumePendingEstimate } from "../tokens/estimate.ts";
+import { droppableLedgerPartitions, ensureLedgerPartitions } from "../util/schema.ts";
 import { jsonParam, jsonValue, num, numOrNull, type SqlDb } from "../util/sql.ts";
 import { foldBlendSamples, type BlendSample } from "./blended.ts";
 import { computeCost } from "./forecast.ts";
@@ -290,7 +291,12 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 				deps.findModel(entry.slug) ??
 				null;
 			const breakdown = model !== null ? computeCost(model, entry.usage) : null;
-			await sql`
+			// No conflict target: on Postgres the ledger is partitioned by day, so
+			// its unique index has to include `created_at_ms` and `(id)` alone is
+			// not an arbiter. A re-recorded entry carries the same instant, which
+			// is the case this guard exists for.
+			const insert = async (): Promise<void> => {
+				await sql`
 				INSERT INTO ledger (
 					id, created_at_ms, conversation_key, session_id, turn, requested_model, harness_id, omp_session_id,
 					slug, served_slug, tier, classification_source, reasons, predicted_usd, reported_usd, usage,
@@ -309,7 +315,22 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 					${entry.promptTokensSaved},
 					${entry.scope === undefined || entry.scope === "" ? null : entry.scope}, ${entry.redactions ?? null}
 				)
-				ON CONFLICT (id) DO NOTHING`;
+				ON CONFLICT DO NOTHING`;
+			};
+			try {
+				await insert();
+			} catch (err) {
+				// A day nobody provisioned: Postgres refuses the row with 23514
+				// ("no partition of relation ledger found for row"). The ledger has
+				// no CHECK constraints of its own, so on this statement that code
+				// can only mean partition routing. Create the day — and the next
+				// few, so this happens once rather than daily — and write again. A
+				// turn is never lost because a partition was late.
+				const code = err !== null && typeof err === "object" && "errno" in err ? String(err.errno) : "";
+				if (code !== "23514") throw err;
+				await ensureLedgerPartitions(db, entry.createdAtMs);
+				await insert();
+			}
 			// 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.
 			const pending = consumePendingEstimate(entry.conversationKey);
@@ -520,8 +541,25 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 			// swept up too.
 			await sql`DELETE FROM feedback WHERE created_at_ms < ${cutoff} OR ledger_id IN (SELECT id FROM ledger WHERE created_at_ms < ${cutoff})`;
 			await sql`DELETE FROM ollama_meter_samples WHERE at_ms < ${cutoff}`;
+			// Whole days the cutoff covers go as metadata: a DROP of a day's
+			// partition is O(1) where deleting its rows is hours of I/O competing
+			// with the inserts it is making room for. Counted before the drop, so
+			// `deleted` still means rows, not partitions.
+			//
+			// ponytail: an exact COUNT(*) scans each doomed day once — a fraction of
+			// what deleting it costs, but not free. If that scan ever matters, read
+			// pg_class.reltuples instead and report the count as an estimate.
+			let dropped = 0;
+			for (const partition of await droppableLedgerPartitions(db, cutoff)) {
+				const rows = (await sql.unsafe(`SELECT COUNT(*) AS n FROM ${partition}`)) as { n: unknown }[];
+				dropped += num(rows[0]?.n);
+				await sql.unsafe(`DROP TABLE ${partition}`);
+			}
+			// What the drops could not cover: the boundary day the cutoff falls
+			// inside (a partial day, so row-wise), anything in a partition whose
+			// bounds could not be read, and every row on SQLite.
 			const deleted = (await sql`DELETE FROM ledger WHERE created_at_ms < ${cutoff} RETURNING id`) as { id: string }[];
-			return { deleted: deleted.length, oldestKeptMs: await oldest() };
+			return { deleted: dropped + deleted.length, oldestKeptMs: await oldest() };
 		},
 
 		async markWasted(id: string): Promise<void> {

package/src/server/http.ts

@@ -282,7 +282,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	// A Postgres store has no bootstrap of its own to run synchronously, so the
 	// shape is created on the way up and every entry point waits for it once.
 	// Resolved already on SQLite, where `openDb` just did it.
-	const storeReady = postgres ? migrateStore(sqlDb) : Promise.resolve();
+	const storeReady = postgres ? migrateStore(sqlDb, log) : Promise.resolve();
 	// The ledger reads and writes through the engine-agnostic handle. `findModel`
 	// closes over the catalog built just below: a shared store has no catalog
 	// cache of its own to price a row from.

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/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);
+	});
+});