@linxiraos/pi-catalog 1.1.7 → 1.1.8

package/src/compat/behavior.ts

@@ -0,0 +1,207 @@
+/**
+ * Typed accessors over the compiled runtime-behavior vocabulary
+ * (`rules/runtime/behavior.kdl`): provider/model heuristics that run before
+ * or outside exact bundled-model lookup — responses routing, API routing,
+ * quota tiers, plan requirements, model limits, roster exclusions, hosted
+ * defaults, and pricing peers.
+ */
+import { globMatch } from "./cascade";
+import rules from "./rules.json";
+import type { CompiledMatchList } from "./types";
+
+const behavior = rules.behavior;
+
+function matchesList(match: CompiledMatchList, model: string, modelLower: string): boolean {
+	if (match.exact?.some(candidate => candidate === model)) return true;
+	if (match.prefix?.some(prefix => model.startsWith(prefix))) return true;
+	if (match.substring?.some(sub => model.includes(sub))) return true;
+	if (match.token !== undefined) {
+		const parts = modelLower.split(/[^a-z0-9]+/);
+		if (match.token.some(token => parts.includes(token))) return true;
+	}
+	if (match.glob?.some(pattern => globMatch(pattern, modelLower))) return true;
+	return false;
+}
+
+/**
+ * Conservative heuristic for a normalized, lowercase discovered model id with
+ * no exact bundled record: whether it likely rides the OpenAI Responses API.
+ */
+export function isLikelyOpenAIResponsesId(model: string): boolean {
+	const rule = behavior.openaiResponsesHeuristic;
+	if (!rule) return false;
+	if (rule.excludePrefixes.some(prefix => model.startsWith(prefix))) return false;
+	if (rule.excludeSubstrings.some(sub => model.includes(sub))) return false;
+	return rule.includePrefixes.some(prefix => model.startsWith(prefix));
+}
+
+/**
+ * Additional catalog-declared operations for a discovered provider/model pair
+ * (e.g. `generate_image`), augmenting provider discovery metadata.
+ */
+export function modelOperationOverrides(provider: string, model: string): readonly string[] {
+	const lower = model.toLowerCase();
+	const out: string[] = [];
+	for (const rule of behavior.modelOperations) {
+		if (rule.provider !== provider || !matchesList(rule.models, lower, lower)) continue;
+		for (const operation of rule.operations) {
+			if (!out.includes(operation)) out.push(operation);
+		}
+	}
+	return out;
+}
+
+/**
+ * Splits a Cursor effort-suffixed OpenAI sibling id into its base id and
+ * declared effort tier. The family gate requires the declared marker
+ * (`gpt-`) followed immediately by an ASCII digit; matching stays
+ * case-sensitive to preserve Cursor wire-id behavior.
+ */
+export function cursorEffortSuffix(model: string): { base: string; tier: string } | undefined {
+	const rule = behavior.cursorEffort;
+	if (!rule) return undefined;
+	for (const tier of rule.tiers) {
+		if (!model.endsWith(tier)) continue;
+		const prefix = model.slice(0, model.length - tier.length);
+		if (!prefix.endsWith("-")) continue;
+		const base = prefix.slice(0, -1);
+		let family = false;
+		let index = base.indexOf(rule.familyMarker);
+		while (index !== -1) {
+			const next = base.charCodeAt(index + rule.familyMarker.length);
+			if (next >= 48 && next <= 57) {
+				family = true;
+				break;
+			}
+			index = base.indexOf(rule.familyMarker, index + 1);
+		}
+		if (!family) return undefined;
+		return { base, tier };
+	}
+	return undefined;
+}
+
+/** Fixed Cursor `requestedModel` parameters declared for an exact wire model. */
+export function cursorModelParameters(model: string): readonly { id: string; value: string }[] {
+	return behavior.cursorParameters.filter(parameter => parameter.model === model);
+}
+
+/**
+ * The catalog-declared quota scope or display tier for a provider model id.
+ * Exact authored memberships win; provider-authored substring fallbacks
+ * preserve quota semantics for newly discovered ids.
+ */
+export function quotaTierFor(provider: string, model: string): string | undefined {
+	const rule = behavior.quotaTiers.find(candidate => candidate.provider === provider);
+	if (!rule) return undefined;
+	for (const tier of rule.tiers) {
+		if (tier.models.includes(model)) return tier.label;
+	}
+	for (const fallback of rule.fallbacks) {
+		if (model.includes(fallback.substring)) return fallback.label;
+	}
+	return undefined;
+}
+
+/** Whether a provider has catalog-authored model quota scopes. */
+export function hasQuotaTierPolicy(provider: string): boolean {
+	return behavior.quotaTiers.some(rule => rule.provider === provider);
+}
+
+/** The provider-default wire model for a model-less hosted operation. */
+export function hostedDefaultModel(provider: string): string | undefined {
+	return behavior.hostedDefaults.find(entry => entry.provider === provider)?.model;
+}
+
+/** One resolved API route for a provider model id. */
+export interface ApiRouteMatch {
+	/** Transport API the id rides. */
+	api: string;
+	/** Wire id after prefix stripping, when the route declares `strip-prefix`. */
+	requestModelId?: string;
+}
+
+/**
+ * Resolves the declared API route for a provider model id. Routes match in
+ * declaration order; a `strip-prefix` route with a prefix matcher strips the
+ * matched prefix off the wire id. Falls back to the node's `default` API.
+ */
+export function apiRouteFor(provider: string, model: string): ApiRouteMatch | undefined {
+	const table = behavior.apiRoutes.find(candidate => candidate.provider === provider);
+	if (!table) return undefined;
+	const lower = model.toLowerCase();
+	for (const route of table.routes) {
+		if (!matchesList(route.match, model, lower)) continue;
+		const out: ApiRouteMatch = { api: route.api };
+		if (route.stripPrefix) {
+			const prefix = route.match.prefix?.find(candidate => model.startsWith(candidate));
+			if (prefix) out.requestModelId = model.slice(prefix.length);
+		}
+		return out;
+	}
+	return table.default !== undefined ? { api: table.default } : undefined;
+}
+
+/** Exact model ids named by a provider's api-routes rules (cache-migration drop lists). */
+export function apiRouteExactModelIds(provider: string): string[] {
+	const table = behavior.apiRoutes.find(candidate => candidate.provider === provider);
+	if (!table) return [];
+	const ids: string[] = [];
+	for (const route of table.routes) {
+		for (const id of route.match.exact ?? []) {
+			if (!ids.includes(id)) ids.push(id);
+		}
+	}
+	return ids;
+}
+
+/** Declared context-window / max-token pins for a provider model id. */
+export function modelLimitsFor(provider: string, model: string): { context?: number; maxTokens?: number } | undefined {
+	for (const table of behavior.modelLimits) {
+		if (table.provider !== provider) continue;
+		const limit = table.limits.find(entry => entry.model === model);
+		if (limit) {
+			const out: { context?: number; maxTokens?: number } = {};
+			if (limit.context !== undefined) out.context = limit.context;
+			if (limit.maxTokens !== undefined) out.maxTokens = limit.maxTokens;
+			return out;
+		}
+	}
+	return undefined;
+}
+
+/** Whether a provider roster entry is a declared non-chat/unsupported SKU. */
+export function isExcludedModel(provider: string, model: string): boolean {
+	const lower = model.toLowerCase();
+	return behavior.excludeModels.some(rule => rule.provider === provider && matchesList(rule.match, lower, lower));
+}
+
+/**
+ * Whether a provider is retired: its entire roster is excluded from the
+ * generated bundle and must never be resurrected from the previous snapshot.
+ */
+export function isRetiredProvider(provider: string): boolean {
+	return behavior.retiredProviders.includes(provider);
+}
+
+/** The declared subscription tier required to use a provider model id, if any. */
+export function planRequirementFor(provider: string, model: string): string | undefined {
+	const rule = behavior.planRequirements.find(candidate => candidate.provider === provider);
+	if (!rule) return undefined;
+	const lower = model.toLowerCase();
+	for (const tier of rule.tiers) {
+		if (matchesList(tier.match, model, lower)) return tier.tier;
+	}
+	return undefined;
+}
+
+/** Cross-provider pricing-peer resolution for one provider model id. */
+export function pricingPeerFor(
+	provider: string,
+	model: string,
+): { peers: readonly string[]; peerId: string } | undefined {
+	const rule = behavior.pricingPeers.find(candidate => candidate.provider === provider);
+	if (!rule) return undefined;
+	const alias = rule.aliases.find(candidate => candidate.model === model);
+	return { peers: rule.peers, peerId: alias?.peerId ?? model };
+}

package/src/compat/cascade.ts

@@ -0,0 +1,230 @@
+/**
+ * Runtime compat cascade: resolves per-axis wire/thinking/catalog assignments
+ * 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, 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
+ * file order are never semantic.
+ */
+import { parseRevision, type Revision, type RevisionTerm, revisionSatisfies } from "./revision";
+import rules from "./rules.json";
+import type { CompiledCascade, CompiledRule, CompiledSelector, ResolvedAxes, ResolveTarget } from "./types";
+
+/**
+ * Two equal-rank rules contest one axis for a target. CI-time for bundled
+ * targets (the parity sweep exercises every catalog row); fix with an
+ * explicit `priority=` in the KDL, never in code.
+ */
+export class AmbiguousOverlapError extends Error {
+	constructor(
+		readonly provider: string,
+		readonly model: string,
+		readonly axis: string,
+		readonly first: string,
+		readonly second: string,
+	) {
+		super(
+			`ambiguous overlap for \`${provider}/${model}\` on axis \`${axis}\`: rules \`${first}\` and \`${second}\` tie; add an explicit priority`,
+		);
+		this.name = "AmbiguousOverlapError";
+	}
+}
+
+/**
+ * Anchored `*`-wildcard match; both sides must be pre-lowercased. `*` spans
+ * any substring; non-wildcard text stays anchored in order.
+ */
+export function globMatch(pattern: string, value: string): boolean {
+	const segments = pattern.split("*");
+	if (segments.length === 1) return value === pattern;
+	const head = segments[0];
+	if (!value.startsWith(head)) return false;
+	let remainder = value.slice(head.length);
+	for (let i = 1; i < segments.length - 1; i++) {
+		const segment = segments[i];
+		if (!segment) continue;
+		const found = remainder.indexOf(segment);
+		if (found === -1) return false;
+		remainder = remainder.slice(found + segment.length);
+	}
+	const last = segments[segments.length - 1];
+	return last === "" || remainder.endsWith(last);
+}
+
+interface IndexedRule {
+	compiled: CompiledRule;
+	revision?: RevisionTerm[];
+	priority: number;
+	dimensions: number;
+	hasExactEffortsRule: boolean;
+}
+
+let ruleIndex: IndexedRule[] | undefined;
+
+function buildRuleIndex(cascade: CompiledCascade): IndexedRule[] {
+	return cascade.rules.map(compiled => {
+		const revision = compiled.revision?.map(term => {
+			const parsed = parseRevision(term.revision);
+			if (!parsed) throw new Error(`invalid compiled revision term in ${compiled.source}`);
+			return { op: term.op, revision: parsed } satisfies RevisionTerm;
+		});
+		const dimensions =
+			Number(compiled.class !== undefined) +
+			Number(compiled.providers !== undefined) +
+			Number(compiled.family !== undefined) +
+			Number(compiled.revision !== undefined) +
+			Number(compiled.models !== undefined);
+		return {
+			compiled,
+			revision,
+			priority: compiled.priority ?? 0,
+			dimensions,
+			hasExactEffortsRule: compiled.thinking !== undefined && "efforts" in compiled.thinking,
+		};
+	});
+}
+
+function getRuleIndex(): IndexedRule[] {
+	ruleIndex ??= buildRuleIndex(rules.cascade);
+	return ruleIndex;
+}
+
+function selectorMatches(selector: CompiledSelector, model: string, modelLower: string): boolean {
+	switch (selector.kind) {
+		case "exact":
+			return selector.value === model;
+		case "glob":
+			return globMatch(selector.value, modelLower);
+		case "token": {
+			for (const part of modelLower.split(/[^a-z0-9]+/)) {
+				if (part === selector.value) return true;
+			}
+			return false;
+		}
+	}
+}
+
+/** `(exactness, dimensions, priority)` when the rule matches, else undefined. */
+function rankRule(
+	rule: IndexedRule,
+	target: ResolveTarget,
+	revision: Revision | undefined,
+	modelLower: string,
+): readonly [number, number, number] | undefined {
+	const { compiled } = rule;
+	if (compiled.class !== undefined && compiled.class !== target.class) return undefined;
+	if (compiled.providers !== undefined && !compiled.providers.includes(target.provider)) return undefined;
+	if (compiled.family !== undefined && compiled.family !== target.family) return undefined;
+	if (rule.revision !== undefined && (!revision || !revisionSatisfies(revision, rule.revision))) return undefined;
+	let exactness = 0;
+	if (compiled.models !== undefined) {
+		let best = -1;
+		for (const selector of compiled.models) {
+			if (!selectorMatches(selector, target.model, modelLower)) continue;
+			const value = selector.kind === "exact" ? 2 : 1;
+			if (value > best) best = value;
+		}
+		if (best < 0) return undefined;
+		exactness = best;
+	}
+	return [exactness, rule.dimensions, rule.priority];
+}
+
+type WinnerTable = Record<string, { rank: readonly [number, number, number]; rule: IndexedRule }>;
+
+function rankCompare(a: readonly [number, number, number], b: readonly [number, number, number]): number {
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+function contest(
+	winners: WinnerTable,
+	axes: Record<string, unknown> | undefined,
+	rank: readonly [number, number, number],
+	rule: IndexedRule,
+	target: ResolveTarget,
+): void {
+	if (!axes) return;
+	for (const axis in axes) {
+		const held = winners[axis];
+		if (held) {
+			const order = rankCompare(held.rank, rank);
+			if (order === 0) {
+				throw new AmbiguousOverlapError(
+					target.provider,
+					target.model,
+					axis,
+					held.rule.compiled.source,
+					rule.compiled.source,
+				);
+			}
+			if (order > 0) continue;
+		}
+		winners[axis] = { rank, rule };
+	}
+}
+
+function collect(winners: WinnerTable, pick: (rule: CompiledRule) => Record<string, unknown> | undefined) {
+	const out: Record<string, unknown> = {};
+	for (const axis in winners) {
+		out[axis] = pick(winners[axis].rule.compiled)?.[axis];
+	}
+	return out;
+}
+
+/**
+ * Resolves wire, thinking, and catalog assignments for one structured target.
+ *
+ * Thinking axes are gated on `target.reasoning`, except that an exact model
+ * selector declaring `thinking-efforts` upgrades the target (a reviewed
+ * correction to stale capability metadata). Family and revision selectors
+ * never match targets missing that identity rank. Unmatched targets resolve
+ * to empty maps.
+ *
+ * @throws AmbiguousOverlapError when two equal-rank rules contest one axis.
+ */
+export function resolveCascade(target: ResolveTarget): ResolvedAxes {
+	return resolveOverIndex(getRuleIndex(), target);
+}
+
+/**
+ * Resolves a target against an arbitrary compiled cascade (test seam and
+ * scratch evaluations); `resolveCascade` delegates here with the bundled
+ * rule index.
+ */
+export function resolveCascadeRules(cascade: CompiledCascade, target: ResolveTarget): ResolvedAxes {
+	return resolveOverIndex(buildRuleIndex(cascade), target);
+}
+
+function resolveOverIndex(index: IndexedRule[], target: ResolveTarget): ResolvedAxes {
+	const modelLower = target.model.toLowerCase();
+	const revision = target.revision === undefined ? undefined : parseRevision(target.revision);
+	const wire: WinnerTable = {};
+	const thinking: WinnerTable = {};
+	const catalog: WinnerTable = {};
+	let reasoning = target.reasoning;
+	if (!reasoning) {
+		for (const rule of index) {
+			if (!rule.hasExactEffortsRule) continue;
+			const rank = rankRule(rule, target, revision, modelLower);
+			if (rank && rank[0] === 2) {
+				reasoning = true;
+				break;
+			}
+		}
+	}
+	for (const rule of index) {
+		const rank = rankRule(rule, target, revision, modelLower);
+		if (!rank) continue;
+		contest(wire, rule.compiled.wire, rank, rule, target);
+		contest(catalog, rule.compiled.catalog, rank, rule, target);
+		if (reasoning) contest(thinking, rule.compiled.thinking, rank, rule, target);
+	}
+	return {
+		wire: collect(wire, rule => rule.wire),
+		thinking: collect(thinking, rule => rule.thinking),
+		catalog: collect(catalog, rule => rule.catalog),
+	};
+}