auto-model-router 0.35.0 → 0.37.0

package/src/config/types.ts

@@ -7,6 +7,10 @@
  */
 
 import type { TaskType, Tier } from "../router/types.ts";
+// Type-only, and deliberately so: `benchmarks.extraScores` is the same row shape
+// the feeds produce, so there is one score vocabulary rather than two. The cycle
+// (benchmark-feeds imports RouterConfig) is erased at compile time.
+import type { FeedScore } from "../catalog/benchmark-feeds.ts";
 
 export type QualityAxis = "coding" | "agentic" | "intelligence";
 
@@ -173,6 +177,24 @@ export interface BenchmarksConfig {
 	 * e.g. after a data-collection window closes.
 	 */
 	useLocalScores: boolean;
+	/**
+	 * Scores supplied by the front door for axes the feeds leave empty. Applied by
+	 * the SAME fill-only-missing rule as the feeds, AFTER Artificial Analysis and
+	 * BenchLM and BEFORE `local`, so nothing a published source measured is ever
+	 * moved. Empty by default.
+	 *
+	 * Provenance is each entry's `source`, and only two values are accepted:
+	 * `neutral` (a benchmark's own leaderboard, taken as given) and `vendor` (a
+	 * self-reported model-card number, which the supplier discounts before sending
+	 * — the router never rescales a number it is handed). An entry claiming any
+	 * other source is dropped: config must not be able to impersonate a published
+	 * feed, nor write into the `local` lane that `useLocalScores` gates.
+	 *
+	 * Entries are sanitised on every use (`suppliedScores`), so a malformed one is
+	 * dropped with a warning rather than failing a refresh or zeroing a score, and
+	 * `key`/`creator` are normalised on the way in — the OpenRouter slug works.
+	 */
+	extraScores?: FeedScore[];
 }
 
 /** Quality/price envelope for one complexity tier. */
@@ -226,6 +248,15 @@ export interface FilterConfig {
 	allow: string[];
 	/** Glob patterns; matching models are dropped. Applied after `allow`. */
 	deny: string[];
+	/**
+	 * Model-glob → provider-glob. A model matching a key may only dispatch
+	 * through a provider whose id matches the value, so a team can keep a
+	 * subscription's models on that subscription instead of its OpenRouter
+	 * twins (`{"anthropic/*": "anthropic-subscription"}`). Applied before
+	 * ranking; a model matching several locks must satisfy each. An empty
+	 * object locks nothing.
+	 */
+	providerLocks: Record<string, string>;
 	/** Consider zero-price models. Off by default: rate limits make them expensive in retries. */
 	includeFree: boolean;
 	/** Require `supported_parameters` to include `tools` whenever the request offers tools. */

package/src/cost/ledger-sql.ts

@@ -302,7 +302,7 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 					slug, served_slug, tier, classification_source, reasons, predicted_usd, reported_usd, usage,
 					cost_breakdown, attempt, escalation_signal, latency_ms, ttft_ms, finish_reason, wasted,
 					upstream_generation_id, error, error_kind, features, score, confidence, task, classifier_reasons,
-					explored_from, hold_arm, prompt_tokens_saved, scope, redactions
+					explored_from, hold_arm, prompt_tokens_saved, scope, redactions, request_id
 				) VALUES (
 					${entry.id}, ${entry.createdAtMs}, ${entry.conversationKey}, ${entry.sessionId}, ${entry.turn},
 					${entry.requestedModel}, ${entry.harnessId}, ${entry.ompSessionId}, ${entry.slug}, ${entry.servedSlug},
@@ -313,7 +313,8 @@ export function createSqlLedger(db: SqlDb, cfg: RouterConfig, deps: LedgerDeps):
 					${jsonParam(db, entry.features)}, ${entry.score}, ${entry.confidence}, ${entry.task},
 					${jsonParam(db, entry.classifierReasons)}, ${entry.exploredFrom}, ${entry.holdArm},
 					${entry.promptTokensSaved},
-					${entry.scope === undefined || entry.scope === "" ? null : entry.scope}, ${entry.redactions ?? null}
+					${entry.scope === undefined || entry.scope === "" ? null : entry.scope}, ${entry.redactions ?? null},
+					${entry.requestId === undefined || entry.requestId === "" ? null : entry.requestId}
 				)
 				ON CONFLICT DO NOTHING`;
 			};

package/src/cost/ledger.ts

@@ -82,6 +82,7 @@ export interface LedgerRow {
 	prompt_tokens_saved: number | null;
 	scope: string | null;
 	redactions: number | null;
+	request_id: string | null;
 }
 
 interface TrustRow {
@@ -257,6 +258,9 @@ export function toEntry(row: LedgerRow): LedgerEntry {
 		// Likewise a row from before v19, or a turn with redaction off: absent,
 		// which is a different fact from 0 (the rules ran and matched nothing).
 		...(row.redactions === null || row.redactions === undefined ? {} : { redactions: row.redactions }),
+		// A row from before v20, or one the router wrote for a caller that named
+		// no request: absent, and never guessed at from anything else.
+		...(row.request_id === null || row.request_id === undefined ? {} : { requestId: row.request_id }),
 		// A row recorded before pricing, or one whose model could not be priced,
 		// stores NULL; absent is the front door's cue to fall back to the blend.
 		...(row.cost_breakdown === null || row.cost_breakdown === undefined ? {} : { costBreakdown: JSON.parse(row.cost_breakdown) as CostBreakdown }),

package/src/cost/types.ts

@@ -161,6 +161,18 @@ export interface LedgerEntry {
 	 * on every row written before v19; 0 means the rules ran and matched nothing.
 	 */
 	redactions?: number;
+	/**
+	 * The id of the HTTP request this row belongs to: the `X-Request-Id` the
+	 * caller sent, or the one the router minted for a caller that sent none
+	 * (prefixed `amr-`, so the two are never confused — see
+	 * `util/requestid.ts`). An escalated turn writes several rows under one id.
+	 *
+	 * This is what turns "my request id was abc123" into exactly this turn. A
+	 * front door that had to guess from member and time can stop guessing.
+	 * Absent on every row written before v20, and on the router's own side
+	 * calls whose caller named no request.
+	 */
+	requestId?: string;
 	/**
 	 * The catalog model that served, for the cost split. The ledger can price
 	 * OpenRouter slugs from its own cached catalog payload; a model from another

package/src/cost/views.ts

@@ -82,6 +82,13 @@ export interface DecisionFilter {
 	tier?: string;
 	/** Only one omp session (`/router why`). */
 	ompSessionId?: string;
+	/**
+	 * Only the rows written for one request id — the `x-request-id` a customer
+	 * quotes. Every attempt of an escalated turn shares it, so this is the
+	 * whole turn rather than one dispatch. Exact: an id nothing was recorded
+	 * under returns nothing, which is a different answer from a guess.
+	 */
+	requestId?: string;
 }
 
 /**
@@ -107,6 +114,11 @@ export async function decisionEntries(db: SqlDb, filter: DecisionFilter): Promis
 		where.push("omp_session_id = $session");
 		bind.$session = filter.ompSessionId;
 	}
+	if (filter.requestId !== undefined && filter.requestId !== "") {
+		// Indexed, and the only exact way in: `idx_ledger_request`.
+		where.push("request_id = $requestId");
+		bind.$requestId = filter.requestId;
+	}
 	const limit = Math.min(Math.max(filter.limit ?? 50, 1), 1_000);
 	const rows = await db.query<unknown>(
 		`SELECT * FROM ledger WHERE ${where.join(" AND ")} ORDER BY created_at_ms DESC LIMIT ${limit}`,

package/src/lib.ts

@@ -20,6 +20,14 @@ export type { RedactionConfig, RedactionRule, RouterConfig, UpstreamEntry, Upstr
 // the same guard the router refuses it with, before the rule is ever saved.
 export { validateRedactionPattern, validateRedactionRule, defaultReplacement, MAX_REDACTION_RULES } from "./config/redaction.ts";
 export { RESERVED_UPSTREAM_IDS } from "./config/schema.ts";
+// `benchmarks.extraScores`: a front door supplies scores for axes the feeds leave
+// empty. The row shape and the two provenances config may claim are exported so
+// it can build and check the table against the same rules the router applies —
+// including the cap, past which the excess is dropped. There is deliberately no
+// writer for `local_scores` here: that table belongs to the eval runner and is
+// gated by `benchmarks.useLocalScores`, and a front door writing into it would
+// make the router's own switch a lie.
+export { MAX_EXTRA_SCORES, SUPPLIED_SOURCES, FILL_ORDER, type FeedScore, type FeedSource } from "./catalog/benchmark-feeds.ts";
 export { setKnownUpstreamIds, providerOfSlug } from "./cost/report.ts";
 export type { DeepPartial } from "./config/load.ts";
 export { buildUsageReport, renderUsageReport, type UsageReport, type ReportTotals } from "./cost/report.ts";
@@ -40,3 +48,7 @@ export type { AsyncLedger, LedgerEntry, PruneResult } from "./cost/types.ts";
 // Retention: a front door asks through `POST /v1/router/prune` rather than
 // deleting from the ledger itself. The interval is exported so it can say when.
 export { RETENTION_INTERVAL_MS } from "./cost/retention.ts";
+// Request ids. A front door that stamps `x-request-id` and then looks a turn up
+// by it judges an id with the SAME rules the router carried it under, and tells
+// a minted id from one its own edge assigned — rather than reimplementing either.
+export { acceptRequestId, isRequestId, isMintedRequestId, mintRequestId, requestIdFor, MINTED_REQUEST_ID_PREFIX, REQUEST_ID_MAX_LENGTH } from "./util/requestid.ts";

package/src/router/candidates.ts

@@ -164,6 +164,12 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 	const relaxTrust = relaxLevel >= 3;
 	const allowRes = filters.allow.map(globToRe);
 	const denyRes = filters.deny.map(globToRe);
+	// Compiled once per turn: pairs of [model glob, provider glob] regexes.
+	// Null when there are no locks, so the common path allocates nothing.
+	const lockRes =
+		filters.providerLocks && Object.keys(filters.providerLocks).length > 0
+			? Object.entries(filters.providerLocks).map(([m, p]) => [globToRe(m), globToRe(p)] as const)
+			: null;
 	const needTools = req.tools.length > 0 && filters.requireToolSupport;
 	const minContext = Math.ceil(features.promptTokens * filters.contextHeadroom) + expectedCompletionTokens;
 	// Task selects the quality axis and capability filters; the tier still
@@ -237,6 +243,17 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			rejected.push({ slug, reason: "denylisted", detail: "filters.deny" });
 			continue;
 		}
+		// Provider locks: where a model may be served from. Checked like a
+		// filter (a lock the model cannot satisfy drops it before ranking)
+		// rather than at dispatch, so the catalog view, the rejection list and
+		// the turn all agree on what was available.
+		if (lockRes !== null) {
+			const violated = lockRes.find(([modelRe, providerRe]) => modelRe.test(slug) && !providerRe.test(model.provider));
+			if (violated !== undefined) {
+				rejected.push({ slug, reason: "provider_locked", detail: `${slug} is locked to providers matching "${violated[1].source}"` });
+				continue;
+			}
+		}
 		if (model.isFree && !filters.includeFree) {
 			rejected.push({ slug, reason: "free_tier_excluded" });
 			continue;

package/src/router/index.ts

@@ -65,6 +65,10 @@ export function applyRequestPolicy(
 	const outProfile = narrowed ? { ...profile, id: `${profile.id}+policy`, minTier, maxTier } : profile;
 	if (narrowed) reasons.push(`policy: tiers narrowed to [${minTier}..${maxTier}]`);
 	let outCfg = cfg;
+	if (policy.providerLocks !== undefined) {
+		outCfg = { ...cfg, filters: { ...cfg.filters, providerLocks: { ...cfg.filters.providerLocks, ...policy.providerLocks } } };
+		reasons.push(`policy: provider locks ${Object.entries(policy.providerLocks).map(([m, p]) => `${m}→${p}`).join(" ")}`);
+	}
 	if (policy.allow !== undefined || policy.deny !== undefined) {
 		outCfg = { ...cfg, filters: { ...cfg.filters, ...(policy.allow === undefined ? {} : { allow: policy.allow }), ...(policy.deny === undefined ? {} : { deny: [...cfg.filters.deny, ...policy.deny] }) } };
 		reasons.push(`policy: ${policy.allow === undefined ? "" : `allow ${policy.allow.join("|")} `}${policy.deny === undefined ? "" : `deny ${policy.deny.join("|")}`}`.trim());

package/src/router/types.ts

@@ -162,6 +162,8 @@ export type RejectionReason =
 	| "denylisted"
 	| "not_allowlisted"
 	| "free_tier_excluded"
+	/** filters.providerLocks: the model matches a lock whose provider glob excludes its upstream. */
+	| "provider_locked"
 	| "reasoning_mandatory"
 	| "untrusted"
 	/** The turn's `X-Omp-Upstream-Keys` names this model's upstream with an empty credential: it cannot be dispatched to. */

package/src/server/catalog-view.ts

@@ -49,7 +49,7 @@ export interface CatalogView {
 }
 
 /** The filters a turn routes under: the configured ones, or those `applyRequestPolicy` merged a policy into. */
-export type AdmissionFilters = Pick<FilterConfig, "allow" | "deny" | "includeFree" | "requireToolSupport">;
+export type AdmissionFilters = Pick<FilterConfig, "allow" | "deny" | "providerLocks" | "includeFree" | "requireToolSupport">;
 
 export interface CatalogViewArgs {
 	models: readonly CatalogModel[];
@@ -84,11 +84,17 @@ function filterReason(model: CatalogModel, filters: AdmissionFilters, allowRes:
 	if (allowRes.length > 0 && !allowRes.some((re) => re.test(model.slug))) return "not in the allow list";
 	const denied = denyRes.findIndex((re) => re.test(model.slug));
 	if (denied !== -1) return `denied by ${filters.deny[denied]}`;
+	if (filters.providerLocks) {
+		for (const [modelGlob, providerGlob] of Object.entries(filters.providerLocks)) {
+			if (globToRe(modelGlob).test(model.slug) && !globToRe(providerGlob).test(model.provider)) {
+				return `locked to providers matching ${providerGlob} (filters.providerLocks)`;
+			}
+		}
+	}
 	if (model.isFree && !filters.includeFree) return "free models excluded (filters.includeFree)";
 	if (filters.requireToolSupport && !model.supportsTools) return "no tool support (filters.requireToolSupport)";
 	return null;
 }
-
 export function catalogView(args: CatalogViewArgs): CatalogView {
 	const sorted = [...args.models].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
 	const verdict = args.verdict;

package/src/server/compaction-digest.ts

@@ -107,6 +107,9 @@ export async function digestCompactionEdits(args: DigestCompactionArgs): Promise
 					query,
 					tier,
 					source: "compaction",
+					// The turn's own request id: the digest row and the turn row are
+					// then one request, which is how they are read in support.
+					...(req.requestId === undefined ? {} : { requestId: req.requestId }),
 				});
 				return { edit: e, result };
 			} catch (err) {

package/src/server/digest.ts

@@ -48,6 +48,14 @@ export interface DigestRequest {
 	 * and is gated on `compaction.digestToolResults` instead.
 	 */
 	source?: "tool_result" | "compaction";
+	/**
+	 * The HTTP request this digest belongs to, recorded on its ledger row. A
+	 * digest taken DURING a turn carries that turn's id, so the cheap side call
+	 * and the turn it saved money on answer to one request id; a standalone
+	 * digest carries whatever its own caller sent, and nothing when it sent
+	 * none (a side call is not a turn, so none is minted for it).
+	 */
+	requestId?: string;
 }
 
 export type DigestResult =
@@ -260,6 +268,9 @@ export function createDigester(deps: DigesterDeps): Digester {
 				upstreamGenerationId: null,
 				error,
 				promptTokensSaved: 0,
+				// The request this digest served, when it has one: inside a turn that
+				// is the turn's id, so both rows answer to what a customer quotes.
+				...(req.requestId === undefined || req.requestId === "" ? {} : { requestId: req.requestId }),
 				priceModel: model,
 			};
 			try {

package/src/server/http.ts

@@ -41,6 +41,7 @@ import { PINNED_CONFIG_PATHS, watchConfig } from "../config/hot-reload.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { createLogger } from "../util/log.ts";
 import { openDb } from "../util/sqlite.ts";
+import { acceptRequestId, isRequestId } from "../util/requestid.ts";
 import { dialectOf, openSqlDb } from "../util/sql.ts";
 import { migrateStore } from "../util/schema.ts";
 import { WireErrorException, renderErrorEnvelope } from "../wire/openai/errors.ts";
@@ -275,7 +276,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	const postgres = dialectOf(storePath) === "postgres";
 	const cachePath = postgres ? join(routerHome(), "cache.db") : storePath;
 	mkdirSync(dirname(cachePath), { recursive: true });
-	// `openDb` is the migration path for a SQLite file: nineteen versions, in
+	// `openDb` is the migration path for a SQLite file: twenty versions, in
 	// order, on whatever an older release left behind.
 	const db = openDb(cachePath);
 	const sqlDb = openSqlDb(storePath);
@@ -510,7 +511,25 @@ export function startServer(cfg: RouterConfig): StartedServer {
 				releaseTurn();
 			});
 
-		return response;
+		// The id this turn's ledger rows are filed under, echoed so the caller
+		// holds it: a front door that sent one gets its own value back
+		// unchanged, and a direct caller that sent none learns the minted id it
+		// would otherwise never see. Set on the response object the wire just
+		// built (a fresh `new Response`, so its headers are still mutable) —
+		// for a buffered turn that is a promise, awaited here as it was before.
+		const stamp = async (r: Response | Promise<Response>): Promise<Response> => {
+			const res = await r;
+			if (normReq.requestId !== undefined) {
+				try {
+					res.headers.set("x-request-id", normReq.requestId);
+				} catch {
+					// An immutable response: the id still reached the ledger, which is
+					// what support reads. Never fail a served turn over a header.
+				}
+			}
+			return res;
+		};
+		return stamp(response);
 	};
 
 	const server: Server<undefined> = Bun.serve({
@@ -692,13 +711,26 @@ export function startServer(cfg: RouterConfig): StartedServer {
 				if (req.method === "GET" && url.pathname === "/v1/router/decisions") {
 					// The decision trail, newest first. ?session=<omp session id> narrows to one
 					// session (/router why); ?harness=a,b to a harness set (a team's user or group),
-					// ?since=<ms> or ?days=N to a window, ?slug= and ?tier= to a model or a tier.
+					// ?since=<ms> or ?days=N to a window, ?slug= and ?tier= to a model or a tier,
+					// and ?requestId= to the rows of ONE request — the id a customer quotes,
+					// which an escalated turn's every attempt shares. That last one is
+					// exact: an id nothing was recorded under answers with no entries
+					// rather than with the nearest turn in time.
 					const rawLimit = url.searchParams.get("limit");
 					const parsed = rawLimit === null ? 50 : Number.parseInt(rawLimit, 10);
 					const limit = Number.isInteger(parsed) ? Math.min(Math.max(parsed, 1), 1_000) : 50;
 					const sinceRaw = Number.parseInt(url.searchParams.get("since") ?? "", 10);
 					const daysRaw = url.searchParams.get("days");
 					const sinceMs = Number.isFinite(sinceRaw) ? sinceRaw : daysRaw === null ? 0 : Date.now() - clampDays(daysRaw, 30) * 86_400_000;
+					// A lookup accepts a MINTED id as readily as a caller's — the header
+					// refuses the prefix so nobody can claim to have minted one, but
+					// asking about one the router minted is the ordinary case. An id
+					// this router could never have recorded is a mangled paste, and
+					// saying so beats silently answering with the whole trail.
+					const askedRequestId = (url.searchParams.get("requestId") ?? "").trim();
+					if (askedRequestId !== "" && !isRequestId(askedRequestId)) {
+						return wireErrorResponse({ status: 400, code: "invalid_request_error", message: "requestId is not a request id this router records" });
+					}
 					const entries = await decisionEntries(sqlDb, {
 						sinceMs,
 						harness: harnessScopeParam(url.searchParams.get("harness")),
@@ -706,6 +738,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 						slug: url.searchParams.get("slug") ?? "",
 						tier: url.searchParams.get("tier") ?? "",
 						ompSessionId: url.searchParams.get("session") ?? "",
+						requestId: askedRequestId,
 					});
 					return json({ entries });
 				}
@@ -757,6 +790,10 @@ export function startServer(cfg: RouterConfig): StartedServer {
 							input: typeof body.input === "object" && body.input !== null ? (body.input as Record<string, unknown>) : {},
 							content: body.content,
 							query: typeof body.query === "string" ? body.query : "",
+							// The caller's own request id when it sent one. None is minted
+							// here: a digest is a side call, and an id invented for it would
+							// address a row no client could ever ask about.
+							...(acceptRequestId(req.headers.get("x-request-id")) === "" ? {} : { requestId: acceptRequestId(req.headers.get("x-request-id")) }),
 						}),
 					);
 				}
@@ -923,7 +960,12 @@ export function startServer(cfg: RouterConfig): StartedServer {
 						// `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"],
+						// `request-id`: this router reads `X-Request-Id` on a turn and
+						// records it on the ledger row, so a front door can stop matching
+						// its own request log against the ledger by member and time and
+						// read the id off the row instead. One without the name still
+						// serves every turn; its front door keeps the approximate join.
+						features: ["upstream-keys", "request-id"],
 						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

@@ -349,6 +349,11 @@ export async function runTurn(
 				// row back to a project. The resolved one the bridge used, header or
 				// configured default; "" stores as NULL.
 				scope: doxScope,
+				// The HTTP request this turn is answering, so a request id quoted in
+				// a ticket names the turn exactly rather than by member and time. The
+				// wire has already decided it: the caller's header, or a minted one.
+				// Every attempt of the turn is recorded under the same id.
+				...(req.requestId === undefined ? {} : { requestId: req.requestId }),
 				ompSessionId: req.ompSessionId,
 				slug: decision.slug,
 				servedSlug,

package/src/util/requestid.ts

@@ -0,0 +1,77 @@
+/**
+ * The request id a turn carries, end to end.
+ *
+ * A front door (the team edition, a proxy, an edge) stamps `x-request-id` on
+ * the response a customer sees, and that is what they quote in a ticket. Until
+ * the router recorded it, placing that id on a ROUTED TURN was a time-window
+ * join — "the same member at the same instant" — which can only ever answer
+ * "probably this one", and answers nothing at all when two turns overlap. The
+ * ledger records the id instead, so the answer is exact.
+ *
+ * The value comes from outside, so it is validated rather than trusted:
+ *
+ *  - **Bounded.** 128 characters covers every id in circulation (a UUID is 36,
+ *    a ULID 26, a W3C `traceparent` 55, the team edition's own 12) with room
+ *    to spare, and nothing unbounded reaches a column, a log line or a JSON
+ *    body.
+ *  - **Safe characters only.** Letters, digits, and `. _ - : + =`. That is
+ *    every id shape a caller actually sends, and it excludes by construction
+ *    the things that make an opaque string dangerous downstream: control
+ *    characters and newlines (log injection — a log line must stay one line),
+ *    quotes and angle brackets (a front door rendering the id in HTML), and
+ *    whitespace.
+ *  - **Rejected, never repaired.** A value outside the rules is treated as
+ *    absent, not truncated or stripped. A truncated id looks valid and matches
+ *    nothing, which is worse than a fresh one that at least addresses the row.
+ *
+ * When the caller sends nothing usable the router MINTS one, so every turn it
+ * records is addressable — a direct user of the router gets the capability the
+ * team edition's members get, without a front door in between. A minted id
+ * carries a fixed prefix so it is never confused with one a caller chose, and
+ * a caller-supplied id that wears the prefix is refused for the same reason:
+ * nobody but this router may claim to have minted an id.
+ */
+
+/** The longest id accepted from a caller, and the length of a minted one's body. */
+export const REQUEST_ID_MAX_LENGTH = 128;
+
+/**
+ * What every id this router mints starts with. Chosen to survive a front door's
+ * own id rules: it stays inside `[A-Za-z0-9._-]`, so an operator can paste a
+ * minted id into the team edition's support search unchanged.
+ */
+export const MINTED_REQUEST_ID_PREFIX = "amr-";
+
+const SHAPE = new RegExp(`^[A-Za-z0-9._:+=-]{1,${REQUEST_ID_MAX_LENGTH}}$`);
+
+/** Whether a string is an acceptable request id at all (shape and length only). */
+export function isRequestId(value: string): boolean {
+	return SHAPE.test(value);
+}
+
+/** Whether this router minted the id, rather than a caller supplying it. */
+export function isMintedRequestId(value: string): boolean {
+	return value.startsWith(MINTED_REQUEST_ID_PREFIX);
+}
+
+/** A fresh id for a turn whose caller supplied none: the prefix plus 32 hex characters. */
+export function mintRequestId(): string {
+	return `${MINTED_REQUEST_ID_PREFIX}${crypto.randomUUID().replaceAll("-", "")}`;
+}
+
+/**
+ * The id to trust from a request header: the caller's, or `""` for anything
+ * this router will not carry — absent, empty, too long, the wrong characters,
+ * or wearing the minted prefix.
+ */
+export function acceptRequestId(raw: string | null | undefined): string {
+	const s = (raw ?? "").trim();
+	if (!isRequestId(s)) return "";
+	return isMintedRequestId(s) ? "" : s;
+}
+
+/** The id a turn carries: the caller's when it passes, otherwise a minted one. */
+export function requestIdFor(raw: string | null | undefined): string {
+	const given = acceptRequestId(raw);
+	return given === "" ? mintRequestId() : given;
+}

package/src/util/schema.ts

@@ -2,7 +2,7 @@
  * The store's schema, for either engine.
  *
  * `util/sqlite.ts` remains the migration path for a SQLite FILE that already
- * exists: nineteen versions have shipped, and an old file still needs its
+ * exists: twenty versions have shipped, and an old file still needs its
  * `ALTER TABLE`s applied in order. This module declares the FINAL shape of
  * every table instead, which is what a fresh store needs — a Postgres database
  * has no history to migrate, and on an already-migrated file every statement
@@ -68,6 +68,34 @@ async function createIfAbsent(db: SqlDb, statement: string): Promise<void> {
 	}
 }
 
+/**
+ * Columns added to `ledger` AFTER this shim shipped, as `<name> <type>`.
+ *
+ * `CREATE TABLE IF NOT EXISTS` declares the final shape for a store that does
+ * not exist yet and does exactly nothing for one that does — so a Postgres
+ * deployment that has been running since before a column was added would never
+ * grow it, and the very next turn would fail its INSERT on an unknown column.
+ * SQLite reaches the same place through `util/sqlite.ts`'s guarded ALTERs;
+ * this is that path for the other engine, and it stays a list rather than a
+ * version counter because `ADD COLUMN IF NOT EXISTS` is already the guard.
+ *
+ * On a partitioned ledger the ALTER applies to the parent and every partition
+ * with it, which is what keeps a day's table from diverging from its parent.
+ */
+const PG_LEDGER_COLUMNS = ["request_id TEXT"] as const;
+
+/** `42701` is "column already exists": another replica added it between the check and the ALTER. */
+const ADDED_ALREADY = new Set([...RACED, "42701"]);
+
+async function addColumnIfAbsent(db: SqlDb, table: string, column: string): Promise<void> {
+	try {
+		await db.sql.unsafe(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${column}`);
+	} catch (err) {
+		const code = err !== null && typeof err === "object" && "errno" in err ? String(err.errno) : "";
+		if (!ADDED_ALREADY.has(code)) throw err;
+	}
+}
+
 /**
  * How this store holds the ledger.
  *
@@ -157,7 +185,7 @@ export async function migrateStore(db: SqlDb, log?: Logger): Promise<void> {
 		singleton("benchmark_cache"),
 		singleton("local_scores"),
 
-		// One row per dispatched upstream generation. The columns nineteen
+		// One row per dispatched upstream generation. The columns twenty
 		// migrations added are declared here as they finally stand.
 		//
 		// Partitioned by day on Postgres, which forces the primary key to
@@ -201,7 +229,8 @@ export async function migrateStore(db: SqlDb, log?: Logger): Promise<void> {
 			hold_arm INTEGER,
 			prompt_tokens_saved INTEGER,
 			scope TEXT,
-			redactions INTEGER${partitioned ? ",\n\t\t\tPRIMARY KEY (id, created_at_ms)" : ""}
+			redactions INTEGER,
+			request_id TEXT${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.
@@ -216,6 +245,9 @@ export async function migrateStore(db: SqlDb, log?: Logger): Promise<void> {
 		"CREATE INDEX IF NOT EXISTS idx_ledger_harness_created ON ledger (harness_id, created_at_ms DESC)",
 		"CREATE INDEX IF NOT EXISTS idx_ledger_slug_harness_created ON ledger (slug, harness_id, created_at_ms DESC)",
 		"CREATE INDEX IF NOT EXISTS idx_ledger_session ON ledger (omp_session_id, created_at_ms DESC)",
+		// One request id straight to its rows: what support does with an id a
+		// customer quoted, and an escalated turn files several rows under it.
+		"CREATE INDEX IF NOT EXISTS idx_ledger_request ON ledger (request_id)",
 
 		`CREATE TABLE IF NOT EXISTS token_calibration (
 			tokenizer TEXT PRIMARY KEY,
@@ -293,6 +325,13 @@ export async function migrateStore(db: SqlDb, log?: Logger): Promise<void> {
 		)`,
 	];
 
+	// Before the statements, so the indexes below can name a column an existing
+	// deployment is only now growing. A store that has no ledger yet gets the
+	// whole shape from the CREATE TABLE and needs no top-up.
+	if (db.dialect === "postgres" && (await db.tableExists("ledger"))) {
+		for (const column of PG_LEDGER_COLUMNS) await addColumnIfAbsent(db, "ledger", column);
+	}
+
 	for (const statement of statements) await createIfAbsent(db, statement);
 
 	if (db.dialect !== "postgres") return;

package/src/util/sqlite.ts

@@ -18,7 +18,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Bump when a migration is added; guarded below so reopening never regresses it. */
-const USER_VERSION = 19;
+const USER_VERSION = 20;
 
 const MIGRATIONS = `
 CREATE TABLE IF NOT EXISTS catalog_cache (
@@ -306,6 +306,24 @@ const MIGRATE_V19 = `
 ALTER TABLE ledger ADD COLUMN redactions INTEGER;
 `;
 
+// v20: ledger records the id of the HTTP request the turn answered — the
+// `X-Request-Id` a front door stamps on the response a customer sees, or one
+// the router minted for a caller that sent none (`util/requestid.ts`). Without
+// it, placing a quoted request id on a turn was a join on member and time,
+// which can only answer "probably this one" and answers nothing when two turns
+// of one member overlap.
+//
+// Indexed because that lookup — one id, straight to its rows — is the whole
+// point of the column, and an escalated turn writes several rows under the
+// same id. NULL on every row written before this, and on the router's own side
+// calls (a standalone digest whose caller named no request); there is nothing
+// to backfill from, and a time-window guess written into the column would be
+// indistinguishable from a fact.
+const MIGRATE_V20 = `
+ALTER TABLE ledger ADD COLUMN request_id TEXT;
+CREATE INDEX IF NOT EXISTS idx_ledger_request ON ledger (request_id);
+`;
+
 // v9: benchmark_cache holds the external benchmark feeds (Artificial Analysis,
 // BenchLM) that backfill quality scores OpenRouter leaves unpublished. It is a
 // whole new table, created idempotently by the MIGRATIONS block above, so there
@@ -360,6 +378,7 @@ export function openDb(path: string): Database {
 		if (!ledgerCols.some((c) => c.name === "prompt_tokens_saved")) db.exec(MIGRATE_V12);
 		if (!ledgerCols.some((c) => c.name === "scope")) db.exec(MIGRATE_V18);
 		if (!ledgerCols.some((c) => c.name === "redactions")) db.exec(MIGRATE_V19);
+		if (!ledgerCols.some((c) => c.name === "request_id")) db.exec(MIGRATE_V20);
 		const convCols = db.query("PRAGMA table_info(conversations)").all() as { name: string }[];
 		if (!convCols.some((c) => c.name === "context_version")) db.exec(MIGRATE_V11);
 		if (!convCols.some((c) => c.name === "compaction_plan")) db.exec(MIGRATE_V13);

package/src/wire/openai/request.ts

@@ -11,6 +11,7 @@ import type {
 	UpstreamMutations,
 } from "../types.ts";
 import { conversationKeyOf } from "../../util/hash.ts";
+import { requestIdFor } from "../../util/requestid.ts";
 import { invalidRequest, modelNotFound } from "./errors.ts";
 
 const ROLES: Record<string, true> = { system: true, developer: true, user: true, assistant: true, tool: true };
@@ -374,6 +375,12 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 	// Subagent marker from the embed extension (sessions without a UI).
 	const isSubagent = (headers.get("x-omp-subagent") ?? "").trim() === "1";
 
+	// The id of the request this turn answers, recorded on every ledger row the
+	// turn writes. A front door's `X-Request-Id` when it passes the rules
+	// (bounded, safe characters, not wearing the minted prefix); otherwise one
+	// minted here, so a turn is addressable whether or not a caller named it.
+	const requestId = requestIdFor(headers.get("x-request-id"));
+
 	// Per-request routing policy (team edition): JSON in X-Omp-Policy.
 	const policy = parsePolicyHeader(headers.get("x-omp-policy"));
 
@@ -444,6 +451,7 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 		agentdoxPersonal,
 		agentdoxOrigin,
 		isSubagent,
+		requestId,
 		...(policy === undefined ? {} : { policy }),
 		...(upstreamKeys === undefined ? {} : { upstreamKeys }),
 		requestedModel,