auto-model-router 0.32.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.32.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.32.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.
 
@@ -1426,6 +1436,35 @@ ignored rather than failing the turn. The decision trail records what the
 policy changed (`policy: …`), and `GET /v1/router/catalog?policy=…` shows what a
 policy admits, model by model, without routing a turn.
 
+## Per-turn upstream credentials
+
+The same front door can also send the credentials one turn dispatches with, in
+an `X-Omp-Upstream-Keys` header carrying JSON that maps an upstream id to a
+credential:
+
+```json
+{ "openrouter": "sk-or-v1-…", "azure-eu": "…" }
+```
+
+The ids are the ones the catalog and `/health` use: `openrouter`, `ollama`, or
+a named entry's `id`. An upstream named here dispatches with that credential
+for the whole turn — every retry, same-tier failover and tier escalation
+included — instead of its configured `apiKey`; one not named keeps the
+configured key. An upstream mapped to `""` has **no** credential this turn and
+is excluded from selection rather than dispatched keyless, so a turn that
+carries nothing usable for a provider simply routes elsewhere.
+
+Nothing is stored: the override lives on the parsed request and is read when a
+header is built, so the shared configuration is never written to and concurrent
+turns carrying different callers' keys cannot see each other's. The credential
+is a secret and is treated as one — it is never logged, never recorded in the
+ledger, and never repeated in an error or a decision reason. A malformed header
+is ignored like a malformed `X-Omp-Policy`, leaving the configured keys in
+force.
+
+This is what lets one router serve callers who bring their own keys — the team
+edition's per-user credentials — without a process per credential set.
+
 ## Data governance
 
 Two things an operator with a compliance obligation needs from a router: that

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.32.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/router/candidates.ts

@@ -214,6 +214,15 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
+		// A per-turn credential map that names this model's upstream with an
+		// empty string says the turn HAS no key for it: dispatching would 401,
+		// so it is not a candidate this turn (and is a candidate again on the
+		// next turn that does carry one).
+		if (req.upstreamKeys?.[model.provider] === "") {
+			rejected.push({ slug, reason: "no_credential", detail: `upstream ${model.provider} has no credential on this turn` });
+			continue;
+		}
+
 		// Hard-coded denials, before any user configuration.
 		const builtIn = builtInDenial(model);
 		if (builtIn !== null) {

package/src/router/types.ts

@@ -164,6 +164,8 @@ export type RejectionReason =
 	| "free_tier_excluded"
 	| "reasoning_mandatory"
 	| "untrusted"
+	/** The turn's `X-Omp-Upstream-Keys` names this model's upstream with an empty credential: it cannot be dispatched to. */
+	| "no_credential"
 	/** Already failed on this turn; excluded so failover picks a different model. */
 	| "failed_this_turn";
 

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.
@@ -918,6 +918,12 @@ export function startServer(cfg: RouterConfig): StartedServer {
 					const snap = catalog.peek();
 					return json({
 						status: "ok",
+						// What a front door may rely on, by name rather than by version: a
+						// team edition that sends per-turn credentials to a router without
+						// `upstream-keys` would have them ignored, and its tenants served on
+						// the deployment's own credential — a silent cross-charge. A name it
+						// can check turns that into a refusal it can explain.
+						features: ["upstream-keys"],
 						apiKeyConfigured: cfg.openrouter.apiKey !== "",
 						// Which upstreams turns can actually be served from: OpenRouter needs
 						// its key; Ollama needs to be on and out of cooldown.

package/src/server/turn.ts

@@ -472,7 +472,9 @@ export async function runTurn(
 		let streamEnded = false;
 
 		try {
-			dispatch = await upstream.dispatch({ body, sessionId: decision.sessionId, signal: attemptSignal });
+			// Inside the attempt loop, so a retry, a same-tier failover and a tier
+			// escalation all dispatch with the same per-turn credentials.
+			dispatch = await upstream.dispatch({ body, sessionId: decision.sessionId, signal: attemptSignal, ...(req.upstreamKeys === undefined ? {} : { upstreamKeys: req.upstreamKeys }) });
 		} catch (err) {
 			streamError = err;
 		}

package/src/upstream/anthropic.ts

@@ -410,13 +410,13 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 		if (caller && timeout) return AbortSignal.any([caller, timeout]);
 		return caller ?? timeout;
 	}
-	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined): Promise<Response> {
+	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined, apiKey: string = e.apiKey): Promise<Response> {
 		const headers: Record<string, string> = { "content-type": "application/json", "anthropic-version": ANTHROPIC_VERSION, ...e.headers };
 		if (e.auth === "oauth-bearer") {
 			// A Claude Pro/Max subscription token: Bearer auth at the first-party API, with the OAuth beta. No per-token cost is reported.
-			headers["authorization"] = `Bearer ${e.apiKey}`;
+			headers["authorization"] = `Bearer ${apiKey}`;
 			headers["anthropic-beta"] = e.headers["anthropic-beta"] ?? "oauth-2025-04-20,claude-code-20250219";
-		} else if (e.apiKey !== "") headers["x-api-key"] = e.apiKey;
+		} else if (apiKey !== "") headers["x-api-key"] = apiKey;
 		try {
 			return await fetchImpl(`${e.baseUrl.replace(/\/+$/, "")}/v1/messages`, { method: "POST", headers, body: JSON.stringify(body), signal: composeSignal(e, signal) });
 		} catch (err) {
@@ -444,7 +444,8 @@ export function createAnthropicClient(cfg: RouterConfig, id: string, fetchImpl:
 		async dispatch(opts: DispatchOptions): Promise<Dispatch> {
 			const e = entry();
 			const { rendered, servedSlug } = render(e, { ...opts.body, stream: true });
-			const res = await post(e, rendered, opts.signal);
+			// A per-turn credential for this upstream wins for this dispatch only; the shared entry is never touched.
+			const res = await post(e, rendered, opts.signal, opts.upstreamKeys?.[id] ?? e.apiKey);
 			if (!res.ok) throw await httpError(res);
 			if (!res.body) throw new UpstreamError("upstream_error", res.status, "response had no body", true);
 			const translator = createAnthropicTranslator(servedSlug);

package/src/upstream/compat.ts

@@ -113,15 +113,20 @@ function transportError(id: string, err: unknown): UpstreamError {
 	return new UpstreamError("network", 0, err instanceof Error ? err.message : String(err), true);
 }
 
-/** The chat-completions URL and auth for an entry: Azure names the deployment in the path and keys with `api-key`. */
-export function compatEndpoint(entry: UpstreamEntry, modelId: string): { url: string; headers: Record<string, string> } {
+/**
+ * The chat-completions URL and auth for an entry: Azure names the deployment in the path and keys with `api-key`.
+ *
+ * `apiKey` overrides the entry's own credential for one dispatch (a per-turn
+ * key from the front door). The entry itself is never written to.
+ */
+export function compatEndpoint(entry: UpstreamEntry, modelId: string, apiKey: string = entry.apiKey): { url: string; headers: Record<string, string> } {
 	const base = entry.baseUrl.replace(/\/+$/, "");
 	const headers: Record<string, string> = { "content-type": "application/json", ...entry.headers };
 	if (entry.kind === "azure") {
-		if (entry.apiKey !== "") headers["api-key"] = entry.apiKey;
+		if (apiKey !== "") headers["api-key"] = apiKey;
 		return { url: `${base}/openai/deployments/${encodeURIComponent(modelId)}/chat/completions?api-version=${encodeURIComponent(entry.apiVersion)}`, headers };
 	}
-	if (entry.apiKey !== "") headers.authorization = `Bearer ${entry.apiKey}`;
+	if (apiKey !== "") headers.authorization = `Bearer ${apiKey}`;
 	return { url: `${base}/chat/completions`, headers };
 }
 
@@ -195,8 +200,8 @@ export function createCompatClient(cfg: RouterConfig, id: string, fetchImpl: Fet
 		return err;
 	}
 
-	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined): Promise<Response> {
-		const { url, headers } = compatEndpoint(e, typeof body.model === "string" ? body.model : "");
+	async function post(e: UpstreamEntry, body: Record<string, unknown>, signal: AbortSignal | undefined, apiKey: string = e.apiKey): Promise<Response> {
+		const { url, headers } = compatEndpoint(e, typeof body.model === "string" ? body.model : "", apiKey);
 		try {
 			return await fetchImpl(url, { method: "POST", headers, body: JSON.stringify(body), signal: composeSignal(e, signal) });
 		} catch (err) {
@@ -212,7 +217,8 @@ export function createCompatClient(cfg: RouterConfig, id: string, fetchImpl: Fet
 
 		async dispatch(opts: DispatchOptions): Promise<Dispatch> {
 			const e = entry();
-			const res = await post(e, toCompatBody(id, { ...opts.body, stream: true }), opts.signal);
+			// A per-turn credential for this upstream wins for this dispatch only; the shared entry is never touched.
+			const res = await post(e, toCompatBody(id, { ...opts.body, stream: true }), opts.signal, opts.upstreamKeys?.[id] ?? e.apiKey);
 			if (!res.ok) throw await httpError(res);
 			if (!res.body) throw new UpstreamError("upstream_error", res.status, "response had no body", true);
 			const parsed = parseSse(res.body, (msg, fields) => log.warn(msg, fields));

package/src/upstream/ollama.ts

@@ -146,9 +146,9 @@ export function createOllamaClient(cfg: RouterConfig, fetchImpl: FetchLike = fet
 		log.warn("ollama cloud unavailable; routing around it", { kind: err.kind, cooldownMs: ms, message: err.message });
 	};
 
-	function headers(extra: Record<string, string> = {}): Record<string, string> {
+	function headers(extra: Record<string, string> = {}, apiKey: string = o.apiKey): Record<string, string> {
 		const h: Record<string, string> = { "content-type": "application/json", ...extra };
-		if (o.apiKey !== "") h.authorization = `Bearer ${o.apiKey}`;
+		if (apiKey !== "") h.authorization = `Bearer ${apiKey}`;
 		return h;
 	}
 
@@ -195,7 +195,8 @@ export function createOllamaClient(cfg: RouterConfig, fetchImpl: FetchLike = fet
 			try {
 				res = await fetchImpl(`${baseUrl()}/chat/completions`, {
 					method: "POST",
-					headers: headers(),
+					// A per-turn credential wins for this dispatch only; cfg is never written to.
+					headers: headers({}, opts.upstreamKeys?.ollama ?? o.apiKey),
 					body: JSON.stringify(body),
 					signal: composeSignal(opts.signal),
 				});

package/src/upstream/openrouter.ts

@@ -114,14 +114,14 @@ export function createOpenRouterClient(cfg: RouterConfig): UpstreamClient {
 		return caller ?? timeout;
 	}
 
-	function headers(extra: Record<string, string>): Record<string, string> {
+	function headers(extra: Record<string, string>, apiKey: string = cfg.openrouter.apiKey): Record<string, string> {
 		const h: Record<string, string> = {
 			"content-type": "application/json",
 			"x-title": cfg.openrouter.title,
 			...extra,
 		};
 		// /models is public; an empty key must not produce a broken Bearer header.
-		if (cfg.openrouter.apiKey !== "") h.authorization = `Bearer ${cfg.openrouter.apiKey}`;
+		if (apiKey !== "") h.authorization = `Bearer ${apiKey}`;
 		if (cfg.openrouter.referer) h["http-referer"] = cfg.openrouter.referer;
 		return h;
 	}
@@ -139,7 +139,8 @@ export function createOpenRouterClient(cfg: RouterConfig): UpstreamClient {
 			try {
 				res = await fetch(`${baseUrl}/chat/completions`, {
 					method: "POST",
-					headers: headers({ "x-session-id": opts.sessionId }),
+					// A per-turn credential wins for this dispatch only; cfg is never written to.
+					headers: headers({ "x-session-id": opts.sessionId }, opts.upstreamKeys?.openrouter ?? cfg.openrouter.apiKey),
 					body: JSON.stringify(body),
 					signal,
 				});

package/src/upstream/types.ts

@@ -43,6 +43,13 @@ export interface DispatchOptions {
 	body: Record<string, unknown>;
 	/** Forwarded as the `x-session-id` header, mirroring body `session_id`. */
 	sessionId: string;
+	/**
+	 * Per-turn credentials by upstream id (`NormRequest.upstreamKeys`). The
+	 * client dispatching this body prefers its own entry over the configured
+	 * `apiKey`, without ever writing to the shared config: concurrent turns
+	 * carry different tenants' keys over the same `UpstreamEntry`.
+	 */
+	upstreamKeys?: Readonly<Record<string, string>>;
 	signal: AbortSignal;
 }
 

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. */