@oh-my-pi/pi-catalog 18.4.4 → 18.4.6

package/src/compat/axes.ts

@@ -11,6 +11,7 @@
  */
 import type { Effort } from "../effort";
 import { MODEL_KINDS, type ThinkingControlMode } from "../types";
+import { FACTORY_DROID_UPSTREAMS } from "../wire/factory-droid";
 
 /** Value shape a directive accepts (see `rules/README.md`). */
 export type AxisShape = "scalar" | "array" | "object";
@@ -19,7 +20,7 @@ export type AxisShape = "scalar" | "array" | "object";
 export type AxisSet = "wire" | "thinking" | "catalog";
 
 /** Resolved compat record families a wire axis may be assigned onto. */
-export type CompatRecordName = "openai" | "openai-responses" | "anthropic" | "bedrock" | "devin" | "google";
+export type CompatRecordName = "openai" | "openai-responses" | "anthropic" | "bedrock" | "devin" | "google" | "request";
 
 /** One axis definition: resolved key, namespace, shape, and applicability. */
 export interface AxisDef {
@@ -37,6 +38,8 @@ export interface AxisDef {
 	 * that compile to camelCase resolved keys.
 	 */
 	verbatimKeys?: true;
+	/** Array axes only: a bare directive assigns an empty list (an explicit "none"). */
+	emptyArray?: true;
 }
 
 const OAI = ["openai", "openai-responses"] as const;
@@ -86,6 +89,34 @@ function wire(
  * blocks.
  */
 export const AXES: Readonly<Record<string, AxisDef>> = {
+	// Selected-route request shaping, resolved alongside shared adapter compat.
+	"completions-reasoning-mode": wire("completionsReasoningMode", ["request"], "scalar", [
+		"none",
+		"effort",
+		"opt-in",
+		"forced-on",
+	]),
+	"completions-reasoning-history": wire("completionsReasoningHistory", ["request"], "scalar", [
+		"omit",
+		"preserved",
+		"interleaved",
+	]),
+	"anthropic-thinking": wire("anthropicThinking", ["request"], "scalar", [
+		"adaptive",
+		"adaptive-summarized",
+		"budget-interleaved",
+		"budget-effort",
+	]),
+	"anthropic-tool-streaming-beta": wire("anthropicToolStreamingBeta", ["request"]),
+	"openai-platform-header": wire("openaiPlatformHeader", ["request"]),
+	"responses-cache-retention": wire("responsesCacheRetention", ["request"]),
+	"responses-verbosity": wire("responsesVerbosity", ["request"], "scalar", ["low"]),
+	"responses-service-tier": wire("responsesServiceTier", ["request"], "scalar", ["priority"]),
+	"responses-parallel-tool-calls": wire("responsesParallelToolCalls", ["request"]),
+	"responses-safety-identifier": wire("responsesSafetyIdentifier", ["request"]),
+	"responses-tool-choice-auto": wire("responsesToolChoiceAuto", ["request"]),
+	"routing-session-lock": wire("routingSessionLock", ["request"]),
+	"google-thinking": wire("googleThinking", ["request"], "scalar", ["level", "level-medium"]),
 	// ── wire: OpenAI-compatible surfaces (chat completions + Responses) ──
 	"allows-synthetic-reasoning-content-for-tool-calls": wire("allowsSyntheticReasoningContentForToolCalls", OAI),
 	"always-send-max-tokens": wire("alwaysSendMaxTokens", OAI),
@@ -101,6 +132,7 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"include-encrypted-reasoning": wire("includeEncryptedReasoning", OAI),
 	"kimi-api-format": wire("kimiApiFormat", ["openai"], "scalar", ["openai", "anthropic"]),
 	"max-tokens-field": wire("maxTokensField", ["openai"], "scalar", ["max_completion_tokens", "max_tokens"]),
+	"mistral-reasoning-content-parts": wire("mistralReasoningContentParts", ["openai"]),
 	"native-kimi-k3-reasoning": wire("nativeKimiK3Reasoning", ["openai"]),
 	"omit-reasoning-effort": wire("omitReasoningEffort", OAI),
 	"prompt-cache-breakpoint-ttl": wire("promptCacheBreakpointTtl", OAI, "scalar", ["30m"]),
@@ -128,6 +160,7 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	]),
 	"reasoning-effort-map": wire("reasoningEffortMap", OAI, "object"),
 	"replay-reasoning-content": wire("replayReasoningContent", ["openai"]),
+	"synthetic-reasoning-content-fallback": wire("syntheticReasoningContentFallback", ["openai"]),
 	"requires-assistant-after-tool-result": wire("requiresAssistantAfterToolResult", ["openai"]),
 	"requires-assistant-content-for-tool-calls": wire("requiresAssistantContentForToolCalls", OAI),
 	"requires-mistral-tool-ids": wire("requiresMistralToolIds", ["openai"]),
@@ -194,7 +227,10 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"allow-anthropic-header-overrides": wire("allowAnthropicHeaderOverrides", ["anthropic"]),
 	"disable-adaptive-thinking": wire("disableAdaptiveThinking", ["anthropic"]),
 	"disable-strict-tools": wire("disableStrictTools", ["anthropic"]),
+	"disabled-thinking": wire("disabledThinking", ["anthropic"], "scalar", ["omit", "disabled", "adaptive"]),
+	"effort-beta": wire("effortBeta", ["anthropic"]),
 	"escape-builtin-tool-names": wire("escapeBuiltinToolNames", ["anthropic"]),
+	"fast-mode": wire("fastMode", ["anthropic"]),
 	"first-party-provider": wire("firstPartyProvider", ["anthropic"]),
 	"inject-claude-code-instruction": wire("injectClaudeCodeInstruction", ["anthropic"]),
 	"official-endpoint": wire("officialEndpoint", ["anthropic", "openai-responses"]),
@@ -202,6 +238,7 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"requires-thinking-enabled": wire("requiresThinkingEnabled", ["anthropic"]),
 	"requires-tool-result-id": wire("requiresToolResultId", ["anthropic"]),
 	"signing-endpoint": wire("signingEndpoint", ["anthropic"]),
+	"strip-thinking-history": wire("stripThinkingHistory", ["anthropic"]),
 	"supports-context-management": wire("supportsContextManagement", ["anthropic"]),
 	"supports-output-effort": wire("supportsOutputEffort", ["anthropic"]),
 	"supports-eager-tool-input-streaming": wire("supportsEagerToolInputStreaming", ["anthropic"]),
@@ -255,7 +292,7 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"stream-first-event-timeout-ms": wire("streamFirstEventTimeoutMs", [...OAI, "google"]),
 	"stream-idle-timeout-ms": wire("streamIdleTimeoutMs", [...OAI, "anthropic", "bedrock", "google"]),
 	"strip-image-input": wire("stripImageInput", [...OAI, "anthropic", "google"]),
-	"supports-forced-tool-choice": wire("supportsForcedToolChoice", [...OAI, "anthropic"]),
+	"supports-forced-tool-choice": wire("supportsForcedToolChoice", [...OAI, "anthropic", "bedrock"]),
 	"supports-sampling-params": wire("supportsSamplingParams", [...OAI, "anthropic"]),
 	"thinking-loop-guard": wire("thinkingLoopGuard", [...OAI, "anthropic", "google"], "scalar", [
 		"gemini",
@@ -321,6 +358,12 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"clamp-context-override": { key: "clampContextOverride", set: "catalog", shape: "scalar" },
 	"context-promotion-target": { key: "contextPromotionTarget", set: "catalog", shape: "scalar" },
 	"context-window-floor": { key: "contextWindowFloor", set: "catalog", shape: "scalar" },
+	"context-window-authoritative": {
+		key: "contextWindowAuthoritative",
+		set: "catalog",
+		shape: "scalar",
+		values: [true, false],
+	},
 	"cost-patch": { key: "costPatch", set: "catalog", shape: "object" },
 	"cost-fallback": { key: "costFallback", set: "catalog", shape: "object" },
 	/**
@@ -353,6 +396,12 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"prompt-cache": { key: "promptCache", set: "catalog", shape: "object" },
 	"long-usage-limit-fallback": { key: "longUsageLimitFallback", set: "catalog", shape: "scalar" },
 	"max-context-window": { key: "maxContextWindow", set: "catalog", shape: "scalar" },
+	"pricing-status": {
+		key: "pricingStatus",
+		set: "catalog",
+		shape: "scalar",
+		values: ["free", "included", "variable", "unknown"],
+	},
 	"requires-cursor-tool-schema-projection": {
 		key: "requiresCursorToolSchemaProjection",
 		set: "catalog",
@@ -379,6 +428,68 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	priority: { key: "priority", set: "catalog", shape: "scalar" },
 	"service-tier-cost": { key: "serviceTierCost", set: "catalog", shape: "object" },
 	"time-based-cost": { key: "timeBased", set: "catalog", shape: "object" },
+
+	// ── catalog: routed-subscription registry ──
+	// A gateway whose proxy fans one model out to several upstreams (Factory
+	// Droid). Consumed through `./factory-droid`; `api-routes` picks the wire
+	// and `quota-tiers` the billing pool.
+	/** Ordered upstream rotation; the first entry is the default `x-api-provider`. */
+	"upstream-rotation": { key: "upstreamRotation", set: "catalog", shape: "array", values: FACTORY_DROID_UPSTREAMS },
+	/**
+	 * Upstreams eligible to serve one inference region. The provider-wide rule
+	 * is the upstream serving table; a model rule replaces it (the native
+	 * region override), and a bare directive means the region never serves it.
+	 */
+	"region-upstreams-global": {
+		key: "regionUpstreamsGlobal",
+		set: "catalog",
+		shape: "array",
+		values: FACTORY_DROID_UPSTREAMS,
+		emptyArray: true,
+	},
+	"region-upstreams-us": {
+		key: "regionUpstreamsUs",
+		set: "catalog",
+		shape: "array",
+		values: FACTORY_DROID_UPSTREAMS,
+		emptyArray: true,
+	},
+	"region-upstreams-eu": {
+		key: "regionUpstreamsEu",
+		set: "catalog",
+		shape: "array",
+		values: FACTORY_DROID_UPSTREAMS,
+		emptyArray: true,
+	},
+	/** EU inference limits (`context-window`, `max-tokens`) where the region narrows the default. */
+	"region-limits-eu": { key: "regionLimitsEu", set: "catalog", shape: "object" },
+	/**
+	 * Subscription credit rates: `input` is the per-token credit weight shown
+	 * as the model's multiplier; `output` and `cache-read` multiply it.
+	 */
+	"credit-rates": { key: "creditRates", set: "catalog", shape: "object" },
+	/**
+	 * List price borrowed from a bundled catalog row: provider id, then the
+	 * row id when it differs from the model's own. Absent means no list price.
+	 */
+	"list-price-from": { key: "listPriceFrom", set: "catalog", shape: "array" },
+	/** Provider family whose live routing defaults apply to the model. */
+	"routing-family": {
+		key: "routingFamily",
+		set: "catalog",
+		shape: "scalar",
+		values: ["anthropic", "openai", "google", "factory", "xai"],
+	},
+	/** Other ids organization policy may use for the model. */
+	"policy-aliases": { key: "policyAliases", set: "catalog", shape: "array" },
+	/**
+	 * Account gates: `feature-flag` must be on to list the model,
+	 * `deprecation-flag` hides it once on, `requires-explicit-opt-in` hides it
+	 * without an org policy, and `base-variant` marks a fast tier of that model.
+	 */
+	entitlement: { key: "entitlement", set: "catalog", shape: "object" },
+	/** The native default when the caller picks no effort is thinking off. */
+	"default-reasoning-off": { key: "defaultReasoningOff", set: "catalog", shape: "scalar", values: [true, false] },
 };
 
 /** Records applicable to each API family; used by `resolve.ts` when applying wire axes. */

package/src/compat/cascade.ts

@@ -3,7 +3,7 @@
  * for one structured model target from the compiled rule tree.
  *
  * Faithful port of the o2 reference resolver (`cascade.rs`): rules are
- * conjunctions over `(class, provider, api, family, revision, models)`; per axis
+ * conjunctions over `(class, provider, api, upstream, family, revision, models)`; per axis
  * the matching rule with the greatest `(model-selector exactness,
  * constrained-dimension count, priority)` tuple wins, and an equal-tuple
  * same-axis contest throws {@link AmbiguousOverlapError}. Declaration and
@@ -129,6 +129,7 @@ function buildRuleIndex(cascade: CompiledCascade): RuleIndex {
 				Number(compiled.class !== undefined) +
 				Number(compiled.providers !== undefined) +
 				Number(compiled.apis !== undefined) +
+				Number(compiled.upstreams !== undefined) +
 				Number(compiled.family !== undefined) +
 				Number(compiled.revision !== undefined) +
 				Number(compiled.models !== undefined),
@@ -215,6 +216,11 @@ function rankRule(rule: IndexedRule, prepared: PreparedTarget): readonly [number
 	const { compiled } = rule;
 	const { target } = prepared;
 	if (compiled.apis !== undefined && !compiled.apis.includes(target.api)) return undefined;
+	if (
+		compiled.upstreams !== undefined &&
+		(target.upstream === undefined || !compiled.upstreams.includes(target.upstream))
+	)
+		return undefined;
 	if (compiled.family !== undefined && compiled.family !== target.family) return undefined;
 	if (rule.revision !== undefined && (!prepared.revision || !revisionSatisfies(prepared.revision, rule.revision))) {
 		return undefined;
@@ -292,6 +298,7 @@ function targetKey(target: ResolveTarget): string {
 	return (
 		keyPart(target.provider) +
 		keyPart(target.api) +
+		keyPart(target.upstream) +
 		keyPart(target.class) +
 		keyPart(target.family) +
 		keyPart(target.revision) +

package/src/compat/collapse.ts

@@ -937,6 +937,9 @@ function collapseWithTable<TSpec extends VariantSpecLike>(
 			...(cursorMaxMode === undefined ? {} : { cursorMaxMode }),
 			...(cursorMaxModeRoutes === undefined ? {} : { cursorMaxModeRoutes }),
 		};
+		if (memberSpecs.some(spec => spec.isProviderDefault === true)) {
+			collapsed.isProviderDefault = true;
+		}
 		// The default wire id is the family's declared `defaultMember` when live,
 		// else the highest-priority live member. Omitted when it equals the
 		// logical id (bare/thinking pairs) — `resolveWireModelId` falls back.

package/src/compat/factory-droid.ts

@@ -0,0 +1,170 @@
+/**
+ * Factory Droid registry policy read from KDL: the roster seed and per-model
+ * catalog axes in `rules/providers/factory-droid.kdl`, plus each model's wire
+ * (`api-routes`) in `rules/runtime/behavior.kdl`. Discovery builds
+ * account-scoped specs from it and the pi-ai provider re-reads it per request
+ * to bind a model to the account serving it.
+ */
+import { isRecord, once } from "@oh-my-pi/pi-utils";
+import type { Api, ModelSpec } from "../types";
+import { FACTORY_DROID_WIRES, type FactoryDroidRegion, type FactoryDroidWire } from "../wire/factory-droid";
+import { apiRouteFor } from "./behavior";
+import { seedModels } from "./providers";
+import { resolveCatalogAxes } from "./resolve";
+
+const PROVIDER = "factory-droid";
+
+/** Native token limits for one inference region. */
+export interface FactoryDroidLimits {
+	contextWindow: number | null;
+	maxTokens: number | null;
+}
+
+/** Standard Credits rates: `input` is the per-token weight; `output` and `cacheRead` multiply it. */
+export interface FactoryDroidCreditRates {
+	input: number;
+	output?: number;
+	cacheRead?: number;
+}
+
+/** Account gates on one registry model (the `entitlement` axis). */
+export interface FactoryDroidEntitlement {
+	/** Feature flag that must be on for the account to see the model. */
+	featureFlag?: string;
+	/** Hard deprecation flag; when on, first-party clients hide the model. */
+	deprecationFlag?: string;
+	/** Hidden unless an org policy is known and does not require consent. */
+	requiresExplicitOptIn: boolean;
+	/** Base model this entry is the fast tier of; org policy can withdraw fast tiers as a class. */
+	baseVariant?: string;
+}
+
+/** Registry facts for one Factory model. */
+export interface FactoryDroidModelPolicy {
+	wire: FactoryDroidWire;
+	/** Registry upstream order; the first entry is the default `x-api-provider`. */
+	rotation: readonly string[];
+	/** Upstreams eligible per inference region; empty means the region does not serve the model. */
+	regionUpstreams: Readonly<Record<FactoryDroidRegion, readonly string[]>>;
+	/** Registry limits; EU entries override them where the region narrows the model. */
+	limits: FactoryDroidLimits;
+	euLimits: Partial<FactoryDroidLimits>;
+	creditRates?: FactoryDroidCreditRates;
+	/** Bundled catalog row whose list price the model shows. */
+	listPriceFrom?: { provider: string; modelId: string };
+	/** Provider family whose live routing defaults apply. */
+	routingFamily?: string;
+	/** Other ids organization policy may use for the model. */
+	policyAliases: readonly string[];
+	entitlement: FactoryDroidEntitlement;
+	/** Native default with no caller effort is thinking off. */
+	defaultReasoningOff: boolean;
+}
+
+/** One registry model: its roster row and resolved policy. */
+export interface FactoryDroidRegistryModel {
+	spec: ModelSpec<"factory-droid-agent">;
+	policy: FactoryDroidModelPolicy;
+}
+
+function stringList(value: unknown): readonly string[] | undefined {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : undefined;
+}
+
+function numberField(source: Record<string, unknown>, key: string): number | undefined {
+	const value = source[key];
+	return typeof value === "number" ? value : undefined;
+}
+
+function stringField(source: Record<string, unknown>, key: string): string | undefined {
+	const value = source[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function readPolicy(spec: ModelSpec<"factory-droid-agent">): FactoryDroidModelPolicy {
+	const catalog = resolveCatalogAxes(spec);
+	const routedApi = apiRouteFor(PROVIDER, spec.id)?.api;
+	const euLimits = isRecord(catalog.regionLimitsEu) ? catalog.regionLimitsEu : {};
+	const credits = isRecord(catalog.creditRates) ? catalog.creditRates : {};
+	const entitlement = isRecord(catalog.entitlement) ? catalog.entitlement : {};
+	const creditInput = numberField(credits, "input");
+	const [priceProvider, priceModelId] = stringList(catalog.listPriceFrom) ?? [];
+	const euContextWindow = numberField(euLimits, "contextWindow");
+	const euMaxTokens = numberField(euLimits, "maxTokens");
+	const creditOutput = numberField(credits, "output");
+	const creditCacheRead = numberField(credits, "cacheRead");
+	const featureFlag = stringField(entitlement, "featureFlag");
+	const deprecationFlag = stringField(entitlement, "deprecationFlag");
+	const baseVariant = stringField(entitlement, "baseVariant");
+	return {
+		wire: FACTORY_DROID_WIRES.find(wire => wire === routedApi) ?? "openai-completions",
+		rotation: stringList(catalog.upstreamRotation) ?? [],
+		regionUpstreams: {
+			global: stringList(catalog.regionUpstreamsGlobal) ?? [],
+			us: stringList(catalog.regionUpstreamsUs) ?? [],
+			eu: stringList(catalog.regionUpstreamsEu) ?? [],
+		},
+		limits: { contextWindow: spec.contextWindow, maxTokens: spec.maxTokens },
+		euLimits: {
+			...(euContextWindow !== undefined && { contextWindow: euContextWindow }),
+			...(euMaxTokens !== undefined && { maxTokens: euMaxTokens }),
+		},
+		...(creditInput !== undefined && {
+			creditRates: {
+				input: creditInput,
+				...(creditOutput !== undefined && { output: creditOutput }),
+				...(creditCacheRead !== undefined && { cacheRead: creditCacheRead }),
+			},
+		}),
+		...(priceProvider !== undefined && {
+			listPriceFrom: { provider: priceProvider, modelId: priceModelId ?? spec.id },
+		}),
+		...(typeof catalog.routingFamily === "string" && { routingFamily: catalog.routingFamily }),
+		policyAliases: stringList(catalog.policyAliases) ?? [],
+		entitlement: {
+			...(featureFlag !== undefined && { featureFlag }),
+			...(deprecationFlag !== undefined && { deprecationFlag }),
+			requiresExplicitOptIn: entitlement.requiresExplicitOptIn === true,
+			...(baseVariant !== undefined && { baseVariant }),
+		},
+		defaultReasoningOff: catalog.defaultReasoningOff === true,
+	};
+}
+
+/** The registry roster in declaration order, each row with its resolved policy. */
+export const factoryDroidRegistry = once((): readonly FactoryDroidRegistryModel[] =>
+	seedModels<"factory-droid-agent">(PROVIDER).map(spec => ({ spec, policy: readPolicy(spec) })),
+);
+
+/** Registry policy for a model (by its request id); undefined for ids outside the registry. */
+export function resolveFactoryDroidPolicy(
+	model: Pick<ModelSpec<Api>, "id" | "requestModelId">,
+): FactoryDroidModelPolicy | undefined {
+	const id = model.requestModelId ?? model.id;
+	return factoryDroidRegistry().find(entry => entry.spec.id === id)?.policy;
+}
+
+/**
+ * Effective upstream rotation for an inference region: the registry order,
+ * narrowed to the upstreams that region serves (or the model's own region
+ * override). An empty result means the region cannot serve the model.
+ */
+export function resolveFactoryDroidRotation(
+	policy: FactoryDroidModelPolicy,
+	region: string | undefined,
+): readonly string[] {
+	const eligible = policy.regionUpstreams[region === "eu" || region === "us" ? region : "global"];
+	return policy.rotation.filter(upstream => eligible.includes(upstream));
+}
+
+/** Native limits for an inference region; EU overrides fall back to the registry defaults. */
+export function factoryDroidRegionalLimits(
+	policy: FactoryDroidModelPolicy,
+	region: string | undefined,
+): FactoryDroidLimits {
+	if (region !== "eu") return policy.limits;
+	return {
+		contextWindow: policy.euLimits.contextWindow ?? policy.limits.contextWindow,
+		maxTokens: policy.euLimits.maxTokens ?? policy.limits.maxTokens,
+	};
+}

package/src/compat/provider-ids.ts

@@ -23,6 +23,7 @@ export type KnownProvider =
 	| "deepinfra"
 	| "deepseek"
 	| "devin"
+	| "factory-droid"
 	| "firepass"
 	| "fireworks"
 	| "github-copilot"
@@ -34,6 +35,7 @@ export type KnownProvider =
 	| "google-gemini-cli"
 	| "google-vertex"
 	| "groq"
+	| "helmcode"
 	| "huggingface"
 	| "kilo"
 	| "kimi-code"

package/src/compat/resolve.ts

@@ -42,7 +42,7 @@ import { API_COMPAT_RECORDS, AXES, type CompatRecordName } from "./axes";
 import { hasModelScopedEffortsRule, resolveCascade } from "./cascade";
 import { compareRevision, parseRevision, type Revision } from "./revision";
 import { classifyModel, stripThinkingVariantSuffix } from "./taxonomy";
-import type { ModelIdentity, ResolvedAxes, ResolveTarget } from "./types";
+import type { ModelIdentity, RequestPolicy, ResolvedAxes, ResolveTarget } from "./types";
 
 /** Result of resolving one model spec through the compat engine. */
 export interface ResolvedModelPolicy<TApi extends Api = Api> {
@@ -51,6 +51,25 @@ export interface ResolvedModelPolicy<TApi extends Api = Api> {
 	thinking: ThinkingConfig | undefined;
 	/** Catalog-data axis assignments (longContext, priority, …) for generation. */
 	catalog: Record<string, unknown>;
+	/** Request-shaping directives for the selected upstream. */
+	request: RequestPolicy;
+}
+
+/** Request routing context is separate from model identity and deployment. */
+export interface ResolveRoute {
+	upstream?: string;
+}
+
+const REQUEST_AXIS_KEYS = Object.values(AXES)
+	.filter(axis => axis.records?.includes("request"))
+	.map(axis => axis.key);
+
+function resolveRequestPolicy(axes: ResolvedAxes): RequestPolicy {
+	const policy: Record<string, unknown> = {};
+	for (const key of REQUEST_AXIS_KEYS) {
+		if (key in axes.wire) policy[key] = axes.wire[key];
+	}
+	return policy as RequestPolicy;
 }
 
 // ---------------------------------------------------------------------------
@@ -516,6 +535,7 @@ function detectOpenAICompat(
 		filterReasoningHistory: d.isOpenRouter && isAnthropicModel,
 		thinkingKeep: usesMoonshotKimiPreservedThinking ? "all" : undefined,
 		reasoningContentField: d.isClinePass ? "reasoning" : "reasoning_content",
+		mistralReasoningContentParts: undefined,
 		requiresReasoningContentForToolCalls:
 			(facts.is("kimi") && !d.isOpenCodeProvider) ||
 			(isDeepseekFamily && reasoningCapable) ||
@@ -524,6 +544,8 @@ function detectOpenAICompat(
 		requiresReasoningContentForAllAssistantTurns:
 			((isDeepseekFamily && reasoningCapable) || d.isXiaomiMimo) && !d.isOpenRouter,
 		allowsSyntheticReasoningContentForToolCalls: (!isDeepseekFamily || !reasoningCapable) && !d.isXiaomiMimo,
+		// Keep the typed sparse override key present for DeepSeek proxy replay.
+		syntheticReasoningContentFallback: undefined,
 		replayReasoningContent: d.isLocalOpenAICompatBackend,
 		qwenPreserveThinking:
 			(thinkingFormat === "qwen" || thinkingFormat === "qwen-chat-template") && d.isLocalOpenAICompatBackend,
@@ -756,6 +778,7 @@ function resolveOpenAIResponsesPolicy(
 			reasoningCapable,
 		requiresReasoningContentForAllAssistantTurns: isDeepseekFamily && reasoningCapable && !isOpenRouter,
 		allowsSyntheticReasoningContentForToolCalls: !isDeepseekFamily || !reasoningCapable,
+		syntheticReasoningContentFallback: undefined,
 		replayReasoningContent: false,
 		qwenPreserveThinking: false,
 		qwenTemplateReasoningEffort: false,
@@ -892,6 +915,9 @@ function resolveAnthropicPolicy(
 		injectClaudeCodeInstruction: true,
 		stripImageInput: false,
 		thinkingLoopGuard: undefined,
+		// Present as keys so models.yml `compat` can set them; unset unless a rule assigns them.
+		stripThinkingHistory: undefined,
+		fastMode: undefined,
 		streamIdleTimeoutMs: spec.compat?.streamIdleTimeoutMs,
 	};
 	applyWireAxes(compat, axes.wire, "anthropic-messages");
@@ -909,6 +935,7 @@ function resolveBedrockPolicy(spec: ModelSpec<"bedrock-converse-stream">, axes:
 		supportsLongPromptCacheRetention: false,
 		promptCacheMinimumTokens: 0,
 		promptCacheMaximumCheckpoints: 0,
+		supportsForcedToolChoice: true,
 	};
 	// Reasoning capability is a mechanism gate; adaptive-lineage duration is rule-owned.
 	compat.streamIdleTimeoutMs = compatReasoning(spec, axes) ? BEDROCK_REASONING_STREAM_IDLE_TIMEOUT_MS : undefined;
@@ -1207,7 +1234,15 @@ function fillExplicitThinking<TApi extends Api>(
 			(impliesMandatoryReasoning(facts, spec.id) || isQwenTemplateReasoningEffortCompat(compat)));
 	const needsDefaultLevel = thinking.defaultLevel === undefined && rule.defaultLevel !== undefined;
 	const needsPrefixBinding = thinking.prefixBinding === undefined && rule.prefixBinding === true;
-	if (effortMap === undefined && !needsDisplay && !needsRequiresEffort && !needsDefaultLevel && !needsPrefixBinding) {
+	const needsEffortBudgets = thinking.effortBudgets === undefined && rule.effortBudgets !== undefined;
+	if (
+		effortMap === undefined &&
+		!needsDisplay &&
+		!needsRequiresEffort &&
+		!needsDefaultLevel &&
+		!needsPrefixBinding &&
+		!needsEffortBudgets
+	) {
 		return thinking;
 	}
 	const filled: ThinkingConfig = { ...thinking };
@@ -1216,6 +1251,7 @@ function fillExplicitThinking<TApi extends Api>(
 	if (needsDefaultLevel && rule.defaultLevel !== undefined) filled.defaultLevel = rule.defaultLevel;
 	if (needsRequiresEffort) filled.requiresEffort = true;
 	if (needsPrefixBinding) filled.prefixBinding = true;
+	if (needsEffortBudgets) filled.effortBudgets = rule.effortBudgets;
 	return filled;
 }
 
@@ -1264,11 +1300,16 @@ export function resolveCatalogAxes(spec: ModelSpec<Api>): Record<string, unknown
  * Resolves the full policy surface for one model spec: structured identity,
  * complete compat record, thinking metadata, and catalog-data corrections.
  */
-export function resolveModelPolicy<TApi extends Api>(spec: ModelSpec<TApi>): ResolvedModelPolicy<TApi>;
-export function resolveModelPolicy(spec: ModelSpec<Api>): ResolvedModelPolicy<Api> {
+export function resolveModelPolicy<TApi extends Api>(
+	spec: ModelSpec<TApi>,
+	route?: ResolveRoute,
+): ResolvedModelPolicy<TApi>;
+export function resolveModelPolicy(spec: ModelSpec<Api>, route?: ResolveRoute): ResolvedModelPolicy<Api> {
 	const identity = resolveIdentity(spec);
 	const facts = new IdentityFacts(identity);
-	const axes = resolveCascade(buildResolveTarget(spec, identity));
+	const target = buildResolveTarget(spec, identity);
+	target.upstream = route?.upstream;
+	const axes = resolveCascade(target);
 	let compat: CompatOf<Api>;
 	if (specUsesApi(spec, "openrouter")) {
 		const chat = resolveOpenAICompletionsPolicy(spec, facts, axes);
@@ -1302,6 +1343,7 @@ export function resolveModelPolicy(spec: ModelSpec<Api>): ResolvedModelPolicy<Ap
 		compat,
 		thinking: resolveThinkingPolicy(spec, facts, axes, compat),
 		catalog: axes.catalog,
+		request: resolveRequestPolicy(axes),
 	};
 }
 

package/src/compat/rules/README.md

@@ -152,7 +152,7 @@ discovery {
 
 ## Cascade grammar
 
-A cascade document starts with `class`, `provider`, or `on-api`. Root `on-api` declares a transport contract independent of model identity and provider name. Every selector adds a conjunct to the current rule. `on` scopes by deployment provider; `on-api` scopes by request adapter, including custom provider names. Axis directives may appear directly in any permitted scope, and nested selector blocks may appear alongside them.
+A cascade document starts with `class`, `provider`, or `on-api`. Root `on-api` declares a transport contract independent of model identity and provider name. Every selector adds a conjunct to the current rule. `on` scopes by deployment provider; `on-api` scopes by request adapter, including custom provider names; `on-upstream` scopes by the actual upstream selected behind that deployment. An upstream never changes the deployment provider or imports that upstream's direct-host rules. Axis directives may appear directly in any permitted scope, and nested selector blocks may appear alongside them.
 
 ```kdl
 class "gemini" {
@@ -182,14 +182,17 @@ provider "openrouter" {
 | Selector   | Form                                     | Matching semantics                                                                                                                                                             |
 | ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `class`    | `class "id" { ... }`                     | Exact class ID. At document root it may contain `on`, `on-api`, `family`, `revision`, and `models`. Under `provider` it may contain `family`, `revision`, and `models`.        |
-| `provider` | `provider "id" { ... }`                  | Exact provider ID. It is root-only and may contain `class` and `models`.                                                                                                       |
-| `on`       | `on "provider-a" "provider-b" { ... }`   | One or more provider IDs, combined as OR. It is allowed only under a root `class`, and may contain `family`, `revision`, and `models`.                                         |
-| `on-api`   | `on-api "adapter-a" "adapter-b" { ... }` | One or more request adapter IDs, combined as OR. At document root it may contain `class` and `models`; under a root `class` it may contain `family`, `revision`, and `models`. |
+| `provider` | `provider "id" { ... }`                  | Exact provider ID. It is root-only and may contain `class`, `on-api`, and `models`.                                                                                           |
+| `on`       | `on "provider-a" "provider-b" { ... }`   | One or more provider IDs, combined as OR. It is allowed under a root `class`, and may contain `on-api` to conjoin an API scope plus `family`, `revision`, and `models`. |
+| `on-api`   | `on-api "adapter-a" "adapter-b" { ... }` | One or more request adapter IDs, combined as OR. At document root it may contain `class` and `models`; under a root `class` (directly or nested inside `on`) or `provider` it may contain `family`, `revision`, and `models`. |
 | `family`   | `family "id" { ... }`                    | Exact classified family ID. It may contain `revision` and `models`. A target with no family does not match.                                                                    |
 | `revision` | `revision ">=2.5 <4" { ... }`            | A non-empty, whitespace-separated conjunction of comparisons. It may contain `models`. A target with no revision does not match.                                               |
-| `models`   | `models "id" "vendor/*" { ... }`         | One or more alternatives, combined as OR. It cannot contain another selector. `token="name"` matches an ASCII-case-insensitive token bounded by non-alphanumerics.             |
+| `models`   | `models "id" "vendor/*" { ... }`         | One or more alternatives, combined as OR. It may contain only `on-upstream`. `token="name"` matches an ASCII-case-insensitive token bounded by non-alphanumerics.                 |
+| `on-upstream` | `on-upstream "a" "b" { ... }`        | Exact selected upstream IDs, combined as OR. Allowed inside any selector scope once; preserves the containing scope's other permitted children. Absent upstream never matches. |
 
-Class, provider/`on`, `on-api`, and family selector values are compared exactly and case-sensitively to the structured resolve target. Revision operators are `>=`, `>`, `<=`, `<`, and `=`; operands have one to three dot-separated unsigned 8-bit components, omitted components zero.
+Every selector scope may additionally contain `on-upstream`; it cannot replace an already constrained upstream. Class, provider/`on`, `on-api`, `on-upstream`, and family values are compared exactly and case-sensitively to the structured resolve target. Revision operators are `>=`, `>`, `<=`, `<`, and `=`; operands have one to three dot-separated unsigned 8-bit components, omitted components zero.
+
+An `on-api` nested inside `on` under a class requires both the selected provider and request adapter; values within each selector remain alternatives.
 
 A `models` string without `*` is an exact, case-sensitive match against the provider-relative model identifier. A string containing `*` is an anchored, ASCII-case-insensitive wildcard match. Prefer taxonomy ranks; retain exact/glob lists only when they isolate the census member set exactly, and keep a `// residue:` comment explaining why ranks do not.
 
@@ -197,6 +200,8 @@ A `models` string without `*` is an exact, case-sensitive match against the prov
 
 `buildDiscoveredModel(spec, providerType)` resolves the catalog `discovery-api` axis before materializing compatibility. It preserves the credential-bearing provider ID and records `providerType` as the backend used for provider selectors on subsequent rebuilds. Ordinary `buildModel` preserves its input API. This lets custom-named llama.cpp deployments reuse the same rules without model-specific discovery code.
 
+`resolveModelPolicy(spec, { upstream })` resolves the selected route without mutating the model identity. Call it again when retry routing selects another upstream. Its typed `request` record carries request-shaping axes (reasoning history, disabled-effort semantics, Anthropic thinking mode, Responses options, and Google thinking dialect); shared transport fields remain in `compat`. Both records use the same per-axis cascade, precedence, ambiguity checks, and upstream-aware cache key. Request fields have the `request` applicability record in `axes.ts`, so they do not leak into shared transport compat objects. See [`providers/factory-droid.kdl`](providers/factory-droid.kdl) for the upstream-scoped consumer.
+
 ### Axis vocabulary and value shapes
 
 The directive vocabulary is closed and lives in **`src/compat/axes.ts`** — one table mapping each kebab-case directive to its resolved camelCase field, namespace (`wire` / `thinking` / `catalog`), value shape, applicable compat records, and (for enums) accepted values. The compiler rejects unknown directives and out-of-vocabulary values against that table; consult it rather than a duplicated table here.
@@ -204,12 +209,16 @@ The directive vocabulary is closed and lives in **`src/compat/axes.ts`** — one
 The three value shapes are:
 
 - **Scalar**: exactly one KDL boolean, integer, float, or string argument and no children. `#null` is rejected.
-- **Array**: one or more scalar arguments and no children; it resolves to a JSON array.
+- **Array**: one or more scalar arguments and no children; it resolves to a JSON array. Axes marked `emptyArray` in `axes.ts` also accept a bare directive, which assigns an explicit empty list (`region-upstreams-eu` with no arguments: the region never serves the model).
 - **Object**: no arguments and a child block, including an empty block. Child names are kebab-case: an axis-directive spelling compiles to its resolved axis key (`template-reasoning-effort` → `qwenTemplateReasoningEffort`), anything else converts mechanically (`input-threshold` → `inputThreshold`); camelCase names are a compile error. `extra-body` payloads (top-level or nested) are the exception — their child names are literal wire JSON keys copied verbatim (`enable_thinking`). Each child is either one scalar or another object; arrays are not representable inside an object payload.
 
 A rule cannot assign the same resolved axis twice in one block.
 One object axis carries a computed form: `long-context-cost` accepts either the absolute rates (`input-threshold` + `input`/`output`/`cache-read`/`cache-write`) or `input-threshold` + `multiplier` (with optional `input-threshold-inclusive`), which derives the tier from the row's live base price at build time so the rule tracks upstream list-price updates (xAI's SuperGrok 200K tier). Rows without a token price carry no tier.
 
+`context-window-authoritative #true` preserves a host's supplied context window through runtime model selection instead of applying inferred expansion or reference-price-tier caps. Explicit user context overrides still apply afterward. It applies to rows materialized through `buildModel` (discovery and regenerated bundles). See [`providers/factory-droid.kdl`](providers/factory-droid.kdl).
+
+The routed-subscription registry axes (`upstream-rotation`, `region-upstreams-global|us|eu`, `region-limits-eu`, `credit-rates`, `list-price-from`, `routing-family`, `policy-aliases`, `entitlement`, `default-reasoning-off`) describe a gateway whose proxy fans one model out to several upstreams. They are read through `src/compat/factory-droid.ts` by Factory Droid discovery and its request provider, not materialized by `buildModel`. A provider-wide `region-upstreams-*` rule is the upstream serving table and a model rule replaces it for that region. `list-price-from "<provider>" ["<id>"]` shows a bundled row's list price beside the subscription's own billing; unlike seed values it is resolved at runtime and degrades to the seed's zero cost when the row is gone. See [`providers/factory-droid.kdl`](providers/factory-droid.kdl), whose wire and billing pool per model are `api-routes` and `quota-tiers` rules in `runtime/behavior.kdl`.
+
 ### Time-based pricing
 
 The catalog object axis `time-based-cost` materializes into `ModelCost.timeBased`. It uses **named child objects**, not KDL arrays or repeated anonymous windows. For example, inside a matching provider/model scope:
@@ -258,7 +267,7 @@ Rules resolve independently per axis. A matching rule is ranked by:
 The tuple is compared lexicographically, greatest first:
 
 - model exactness is `2` when any matching `models` selector is exact, `1` when the best matching selector is a glob or token, and `0` when the rule has no `models` selector;
-- dimension count is the number of present dimensions among class, provider/`on`, API/`on-api`, family, revision, and models;
+- dimension count is the number of present dimensions among class, provider/`on`, API/`on-api`, upstream/`on-upstream`, family, revision, and models;
 - priority is the local block's `priority`, defaulting to `0`.
 
 The highest-ranked matching assignment wins for that axis. Two distinct rules that tie on all three components and assign the same axis are an ambiguity error even if their values are equal. File and declaration order never resolve the tie; add an explicit priority only after confirming the overlap is intentional.
@@ -417,6 +426,7 @@ A `seed` _defines_ bundled rows for providers whose catalog cannot be discovered
 | `always`   | Every regeneration. Same-id upstream/discovery rows win dedup.            |
 | `fallback` | Only when the provider's authoritative catalog discovery did not succeed. |
 | `empty`    | Only when no other source produced a row for the provider.                |
+| `never`    | Never; the provider's runtime model manager is the only consumer.         |
 
 `precedence="seed"` prepends the rows after the previous-snapshot merge and cross-provider reference fills, so the authored row wins dedup and same-id rows on other hosts never overwrite its name or capabilities (QwenCloud Token Plan, Meta). The default `upstream` precedence appends before the snapshot merge, so the current seed — not a stale snapshot copy — is the fallback row.