@linxiraos/pi-catalog 1.4.6 → 1.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/CHANGELOG.md +6 -2
  2. package/README.md +3 -3
  3. package/dist/types/build.d.ts +12 -4
  4. package/dist/types/compat/auth-ids.d.ts +2 -2
  5. package/dist/types/compat/catalog-policy.d.ts +6 -4
  6. package/dist/types/compat/factory-droid.d.ts +7 -1
  7. package/dist/types/compat/provider-ids.d.ts +1 -1
  8. package/dist/types/compat/resolve.d.ts +1 -1
  9. package/dist/types/compat/revision.d.ts +2 -0
  10. package/dist/types/compat/server-side-fallback.d.ts +6 -4
  11. package/dist/types/compat/types.d.ts +6 -2
  12. package/dist/types/discovery/codex.d.ts +4 -5
  13. package/dist/types/discovery/cursor-proto.d.ts +8 -0
  14. package/dist/types/discovery/openai-compatible.d.ts +6 -0
  15. package/dist/types/model-cache.d.ts +8 -0
  16. package/dist/types/model-catalog-format.d.ts +37 -0
  17. package/dist/types/model-manager.d.ts +11 -1
  18. package/dist/types/model-thinking.d.ts +4 -0
  19. package/dist/types/models.d.ts +22 -3
  20. package/dist/types/pricing.d.ts +66 -6
  21. package/dist/types/provider-models/openai-compat.d.ts +18 -13
  22. package/dist/types/types.d.ts +14 -19
  23. package/dist/types/utils.d.ts +8 -0
  24. package/dist/types/wire/codex.d.ts +1 -1
  25. package/package.json +6 -10
  26. package/src/build.d.ts +12 -4
  27. package/src/build.ts +50 -3
  28. package/src/compat/auth-ids.ts +5 -0
  29. package/src/compat/axes.ts +27 -9
  30. package/src/compat/catalog-policy.d.ts +9 -0
  31. package/src/compat/catalog-policy.ts +14 -10
  32. package/src/compat/collapse.ts +1 -1
  33. package/src/compat/factory-droid.d.ts +7 -1
  34. package/src/compat/factory-droid.ts +9 -1
  35. package/src/compat/provider-ids.d.ts +1 -1
  36. package/src/compat/provider-ids.ts +2 -0
  37. package/src/compat/resolve.d.ts +1 -1
  38. package/src/compat/resolve.ts +4 -5
  39. package/src/compat/revision.d.ts +2 -0
  40. package/src/compat/revision.ts +10 -0
  41. package/src/compat/rules/README.md +14 -12
  42. package/src/compat/rules/auth/_order.kdl +1 -1
  43. package/src/compat/rules/auth/mistral.kdl +4 -0
  44. package/src/compat/rules/auth/modular.kdl +9 -0
  45. package/src/compat/rules/auth/scaleway.kdl +17 -0
  46. package/src/compat/rules/auth/typesafe.kdl +2 -1
  47. package/src/compat/rules/classes/anthropic.kdl +5 -0
  48. package/src/compat/rules/classes/deepseek.kdl +3 -2
  49. package/src/compat/rules/classes/gemini.kdl +1 -1
  50. package/src/compat/rules/classes/openai.kdl +2 -2
  51. package/src/compat/rules/classes/xai.kdl +1 -1
  52. package/src/compat/rules/providers/anthropic.kdl +8 -4
  53. package/src/compat/rules/providers/cursor.kdl +10 -0
  54. package/src/compat/rules/providers/deepseek.kdl +2 -2
  55. package/src/compat/rules/providers/factory-droid.kdl +243 -13
  56. package/src/compat/rules/providers/google-vertex.kdl +3 -0
  57. package/src/compat/rules/providers/kimi-code.kdl +6 -0
  58. package/src/compat/rules/providers/mistral.kdl +8 -0
  59. package/src/compat/rules/providers/modular.kdl +35 -0
  60. package/src/compat/rules/providers/openai-codex.kdl +1 -1
  61. package/src/compat/rules/providers/sambanova.kdl +2 -0
  62. package/src/compat/rules/providers/scaleway.kdl +179 -0
  63. package/src/compat/rules/runtime/behavior.kdl +22 -6
  64. package/src/compat/rules.json +1 -1
  65. package/src/compat/server-side-fallback.d.ts +9 -0
  66. package/src/compat/server-side-fallback.ts +7 -5
  67. package/src/compat/types.d.ts +6 -2
  68. package/src/compat/types.ts +6 -2
  69. package/src/discovery/codex.d.ts +4 -5
  70. package/src/discovery/codex.ts +7 -15
  71. package/src/discovery/cursor-proto.d.ts +8 -0
  72. package/src/discovery/cursor-proto.ts +12 -1
  73. package/src/discovery/factory-droid.ts +35 -11
  74. package/src/discovery/openai-compatible.d.ts +6 -0
  75. package/src/discovery/openai-compatible.ts +1 -1
  76. package/src/model-cache.d.ts +8 -0
  77. package/src/model-cache.ts +83 -61
  78. package/src/model-catalog-format.d.ts +37 -0
  79. package/src/model-catalog-format.ts +296 -0
  80. package/src/model-manager.d.ts +11 -1
  81. package/src/model-manager.ts +85 -143
  82. package/src/model-thinking.d.ts +4 -0
  83. package/src/model-thinking.ts +10 -0
  84. package/src/model-tokenizer.ts +13 -12
  85. package/src/models.d.ts +22 -3
  86. package/src/models.json +1 -1
  87. package/src/models.ts +48 -11
  88. package/src/pricing.d.ts +66 -6
  89. package/src/pricing.ts +59 -94
  90. package/src/provider-models/cache-provider-id.ts +23 -6
  91. package/src/provider-models/catalog-snapshot.json.zst +0 -0
  92. package/src/provider-models/catalog-snapshot.json.zst.d.ts +3 -0
  93. package/src/provider-models/descriptors.ts +2 -0
  94. package/src/provider-models/openai-compat.d.ts +18 -13
  95. package/src/provider-models/openai-compat.ts +203 -94
  96. package/src/provider-models/special.ts +5 -6
  97. package/src/types.d.ts +14 -19
  98. package/src/types.ts +11 -18
  99. package/src/utils.d.ts +8 -0
  100. package/src/utils.ts +18 -0
  101. package/src/wire/codex.d.ts +1 -1
  102. package/src/wire/codex.ts +1 -1
  103. package/src/wire/factory-droid.ts +4 -3
  104. package/src/models.json.d.ts +0 -9
@@ -0,0 +1,296 @@
1
+ import type { Api, Model } from "./types";
2
+ import { isRecord } from "./utils";
3
+
4
+ // References are distinguished from JSON scalar values by their one-element array.
5
+ // -1 represents an explicitly present undefined value.
6
+ type EncodedValue = string | number | boolean | null | [number];
7
+ type ObjectNode = [0, EncodedValue[], number, number[]];
8
+ type ArrayNode = [1, EncodedValue[]];
9
+ type Node = ObjectNode | ArrayNode;
10
+ type CompatDelta = [number[], EncodedValue];
11
+ type ModelRow = [string, EncodedValue, CompatDelta?];
12
+ type ProviderRow = [string, EncodedValue, ModelRow[]];
13
+
14
+ interface CatalogData {
15
+ version: 1;
16
+ keys: string[];
17
+ booleanShapes: number[][];
18
+ nodes: Node[];
19
+ compat: [string, EncodedValue][];
20
+ providers: ProviderRow[];
21
+ }
22
+
23
+ /**
24
+ * Parsed compact catalog. Decoded nested objects and arrays can be shared by
25
+ * multiple models; callers must treat those values as immutable.
26
+ */
27
+ export interface ModelCatalog {
28
+ readonly data: CatalogData;
29
+ readonly values: unknown[];
30
+ readonly decoded: boolean[];
31
+ readonly providers: Map<string, Record<string, Model<Api>>>;
32
+ readonly compatBases: Map<string, EncodedValue>;
33
+ readonly compatValues: Map<string, Map<number, Map<string, Record<string, unknown>>>>;
34
+ }
35
+
36
+ // JSON serialization with sorted object keys gives both deterministic ordering
37
+ // and value-based interning, independent of the input objects' insertion order.
38
+ function canonical(value: unknown): string {
39
+ if (value === undefined) return "u";
40
+ if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
41
+ if (isRecord(value)) {
42
+ return `{${Object.keys(value)
43
+ .sort()
44
+ .map(key => `${JSON.stringify(key)}:${canonical(value[key])}`)
45
+ .join(",")}}`;
46
+ }
47
+ return JSON.stringify(value);
48
+ }
49
+
50
+ /** Encode a model catalog into a deterministic, compact JSON representation. */
51
+ export function encodeModelCatalog(models: Record<string, Record<string, Model<Api>>>): string {
52
+ // Match JSON's treatment of undefined and non-finite numbers in generated rows.
53
+ models = JSON.parse(JSON.stringify(models));
54
+ const keys: string[] = [];
55
+ const keyIds = new Map<string, number>();
56
+ const booleanShapes: number[][] = [];
57
+ const shapeIds = new Map<string, number>();
58
+ const nodes: Node[] = [];
59
+ const nodeIds = new Map<string, number>();
60
+ const keyId = (key: string): number => {
61
+ let id = keyIds.get(key);
62
+ if (id === undefined) {
63
+ id = keys.length;
64
+ keys.push(key);
65
+ keyIds.set(key, id);
66
+ }
67
+ return id;
68
+ };
69
+ const encode = (value: unknown): EncodedValue => {
70
+ if (value === undefined) return [-1];
71
+ if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
72
+ return value;
73
+ }
74
+ const signature = canonical(value);
75
+ const existing = nodeIds.get(signature);
76
+ if (existing !== undefined) return [existing];
77
+ let node: Node;
78
+ if (Array.isArray(value)) {
79
+ node = [1, value.map(encode)];
80
+ } else if (isRecord(value)) {
81
+ const properties: EncodedValue[] = [];
82
+ const boolKeys: number[] = [];
83
+ const masks: number[] = [];
84
+ for (const key of Object.keys(value).sort()) {
85
+ const entry = value[key];
86
+ if (typeof entry === "boolean") {
87
+ const bit = boolKeys.length;
88
+ boolKeys.push(keyId(key));
89
+ const word = Math.floor(bit / 32);
90
+ masks[word] ??= 0;
91
+ if (entry) masks[word] = (masks[word] | (1 << (bit % 32))) >>> 0;
92
+ } else {
93
+ properties.push(keyId(key), encode(entry));
94
+ }
95
+ }
96
+ const shape = boolKeys.join(",");
97
+ let shapeId = shapeIds.get(shape);
98
+ if (shapeId === undefined) {
99
+ shapeId = booleanShapes.length;
100
+ booleanShapes.push(boolKeys);
101
+ shapeIds.set(shape, shapeId);
102
+ }
103
+ node = [0, properties, shapeId, masks];
104
+ } else {
105
+ throw new TypeError("Model catalog values must be JSON-compatible");
106
+ }
107
+ const id = nodes.length;
108
+ nodes.push(node);
109
+ nodeIds.set(signature, id);
110
+ return [id];
111
+ };
112
+
113
+ // Select the most common complete compat object for each API. A row's
114
+ // delta records changed properties and explicitly removed base properties.
115
+ const compatCounts = new Map<string, Map<string, { value: Record<string, unknown>; count: number }>>();
116
+ for (const provider of Object.keys(models).sort()) {
117
+ for (const id of Object.keys(models[provider]).sort()) {
118
+ const model = models[provider][id];
119
+ if (typeof model.api !== "string" || !isRecord(model.compat)) continue;
120
+ let counts = compatCounts.get(model.api);
121
+ if (!counts) compatCounts.set(model.api, (counts = new Map()));
122
+ const signature = canonical(model.compat);
123
+ const entry = counts.get(signature);
124
+ if (entry) entry.count++;
125
+ else counts.set(signature, { value: model.compat, count: 1 });
126
+ }
127
+ }
128
+ const bases = new Map<string, Record<string, unknown>>();
129
+ for (const api of [...compatCounts.keys()].sort()) {
130
+ const choices = [...compatCounts.get(api)!.entries()].sort(
131
+ (a, b) => b[1].count - a[1].count || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0),
132
+ );
133
+ bases.set(api, choices[0][1].value);
134
+ }
135
+ const compat: [string, EncodedValue][] = [...bases].map(([api, value]) => [api, encode(value)]);
136
+ const providers: ProviderRow[] = [];
137
+ for (const provider of Object.keys(models).sort()) {
138
+ const entries = Object.entries(models[provider]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
139
+ const constants: Record<string, unknown> = Object.create(null);
140
+ if (entries.length) {
141
+ const first = entries[0][1] as unknown as Record<string, unknown>;
142
+ for (const key of Object.keys(first).sort()) {
143
+ const value = first[key];
144
+ if (key === "id" || key === "compat" || (value !== null && typeof value === "object")) continue;
145
+ if (
146
+ entries.every(
147
+ ([, model]) =>
148
+ Object.hasOwn(model, key) && (model as unknown as Record<string, unknown>)[key] === value,
149
+ )
150
+ ) {
151
+ constants[key] = value;
152
+ }
153
+ }
154
+ }
155
+ const encodedConstants = encode(constants);
156
+ const rows: ModelRow[] = [];
157
+ for (const [id, model] of entries) {
158
+ const rest: Record<string, unknown> = Object.create(null);
159
+ const source = model as unknown as Record<string, unknown>;
160
+ const base = typeof model.api === "string" ? bases.get(model.api) : undefined;
161
+ const useBase = base !== undefined && isRecord(model.compat);
162
+ for (const key of Object.keys(source).sort()) {
163
+ if (Object.hasOwn(constants, key) || (key === "id" && source.id === id) || (key === "compat" && useBase))
164
+ continue;
165
+ rest[key] = source[key];
166
+ }
167
+ const row: ModelRow = [id, encode(rest)];
168
+ if (useBase) {
169
+ const value = model.compat as Record<string, unknown>;
170
+ const removed = Object.keys(base)
171
+ .filter(key => !Object.hasOwn(value, key))
172
+ .sort()
173
+ .map(keyId);
174
+ const changed: Record<string, unknown> = Object.create(null);
175
+ for (const key of Object.keys(value).sort()) {
176
+ if (!Object.hasOwn(base, key) || canonical(value[key]) !== canonical(base[key]))
177
+ changed[key] = value[key];
178
+ }
179
+ row.push([removed, encode(changed)]);
180
+ }
181
+ rows.push(row);
182
+ }
183
+ providers.push([provider, encodedConstants, rows]);
184
+ }
185
+ return JSON.stringify({ version: 1, keys, booleanShapes, nodes, compat, providers } satisfies CatalogData);
186
+ }
187
+
188
+ /** Open a parsed catalog without materializing its provider models. */
189
+ export function openModelCatalog(value: unknown): ModelCatalog {
190
+ const data = value as CatalogData;
191
+ if (data.version !== 1) throw new Error("Unsupported model catalog version");
192
+ return {
193
+ data,
194
+ values: [],
195
+ decoded: [],
196
+ providers: new Map(),
197
+ compatBases: new Map(data.compat),
198
+ compatValues: new Map(),
199
+ };
200
+ }
201
+
202
+ // Assignment is safe for ordinary keys, but __proto__ must remain an own key.
203
+ function setProperty(object: Record<string, unknown>, key: string, value: unknown): void {
204
+ if (key === "__proto__") {
205
+ Object.defineProperty(object, key, { value, writable: true, enumerable: true, configurable: true });
206
+ } else {
207
+ object[key] = value;
208
+ }
209
+ }
210
+
211
+ function decodeObject(catalog: ModelCatalog, object: Record<string, unknown>, node: ObjectNode): void {
212
+ for (let i = 0; i < node[1].length; i += 2) {
213
+ setProperty(object, catalog.data.keys[node[1][i] as number], decode(catalog, node[1][i + 1]));
214
+ }
215
+ const shape = catalog.data.booleanShapes[node[2]];
216
+ for (let i = 0; i < shape.length; i++) {
217
+ setProperty(object, catalog.data.keys[shape[i]], ((node[3][i >>> 5] >>> (i % 32)) & 1) !== 0);
218
+ }
219
+ }
220
+
221
+ function decode(catalog: ModelCatalog, value: EncodedValue): unknown {
222
+ if (!Array.isArray(value)) return value;
223
+ const id = value[0];
224
+ if (id === -1) return undefined;
225
+ if (catalog.decoded[id]) return catalog.values[id];
226
+ const node = catalog.data.nodes[id];
227
+ let result: unknown;
228
+ if (node[0] === 1) {
229
+ result = node[1].map(entry => decode(catalog, entry));
230
+ } else {
231
+ const object: Record<string, unknown> = {};
232
+ decodeObject(catalog, object, node);
233
+ result = object;
234
+ }
235
+ catalog.values[id] = result;
236
+ catalog.decoded[id] = true;
237
+ return result;
238
+ }
239
+
240
+ /** List catalog provider keys in deterministic order. */
241
+ export function getCatalogProviders(catalog: ModelCatalog): string[] {
242
+ return catalog.data.providers.map(provider => provider[0]);
243
+ }
244
+
245
+ /** Materialize and cache one provider, or return undefined if it is absent. */
246
+ export function getCatalogProvider(catalog: ModelCatalog, provider: string): Record<string, Model<Api>> | undefined {
247
+ const cached = catalog.providers.get(provider);
248
+ if (cached) return cached;
249
+ const entry = catalog.data.providers.find(row => row[0] === provider);
250
+ if (!entry) return undefined;
251
+ const constants = decode(catalog, entry[1]) as Record<string, unknown>;
252
+ const models: Record<string, Model<Api>> = {};
253
+ for (const [id, encoded, delta] of entry[2]) {
254
+ if (!Array.isArray(encoded) || encoded[0] < 0) throw new Error("Invalid compact model row");
255
+ const row = catalog.data.nodes[encoded[0]];
256
+ if (!row || row[0] !== 0) throw new Error("Invalid compact model row");
257
+ const model: Record<string, unknown> = { id, ...constants };
258
+ decodeObject(catalog, model, row);
259
+ if (delta) {
260
+ const api = model.api as string;
261
+ const changeId = (delta[1] as [number])[0];
262
+ const changeNode = catalog.data.nodes[changeId] as ObjectNode;
263
+ const base = decode(catalog, catalog.compatBases.get(api)!) as Record<string, unknown>;
264
+ let compat: Record<string, unknown>;
265
+ if (
266
+ delta[0].length === 0 &&
267
+ changeNode[1].length === 0 &&
268
+ catalog.data.booleanShapes[changeNode[2]].length === 0
269
+ ) {
270
+ compat = base;
271
+ } else {
272
+ let byChange = catalog.compatValues.get(api);
273
+ if (!byChange) catalog.compatValues.set(api, (byChange = new Map()));
274
+ let byRemoved = byChange.get(changeId);
275
+ if (!byRemoved) byChange.set(changeId, (byRemoved = new Map()));
276
+ const removedKey = delta[0].join(",");
277
+ const cachedCompat = byRemoved.get(removedKey);
278
+ if (cachedCompat) {
279
+ compat = cachedCompat;
280
+ } else {
281
+ compat = { ...base };
282
+ for (const key of delta[0]) delete compat[catalog.data.keys[key]];
283
+ const changes = decode(catalog, delta[1]) as Record<string, unknown>;
284
+ for (const key in changes) {
285
+ if (Object.hasOwn(changes, key)) setProperty(compat, key, changes[key]);
286
+ }
287
+ byRemoved.set(removedKey, compat);
288
+ }
289
+ }
290
+ model.compat = compat;
291
+ }
292
+ setProperty(models as Record<string, unknown>, id, model);
293
+ }
294
+ catalog.providers.set(provider, models);
295
+ return models;
296
+ }
@@ -129,9 +129,19 @@ export declare function createModelManager<TApi extends Api = Api, TModelsDevPay
129
129
  * when at least one configured remote source did not refresh successfully.
130
130
  */
131
131
  export declare function resolveProviderModels<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>, strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;
132
+ /**
133
+ * Merge policy that is part of a cache's identity in
134
+ * {@link fingerprintStaticModels}: `authoritative` when dynamic discovery owns
135
+ * the catalog, `additive` when the shared catalog may only add ids. The flags
136
+ * compose; snapshots written under different policies never match.
137
+ */
138
+ export interface StaticFingerprintPolicy {
139
+ authoritative?: boolean;
140
+ additive?: boolean;
141
+ }
132
142
  /**
133
143
  * Return the versioned content identity for a static provider slice. Callers
134
144
  * may mutate or freeze their arrays, so every call observes current content
135
145
  * and never attaches a stale sidecar fingerprint to caller-owned data.
136
146
  */
137
- export declare function fingerprintStaticModels<TApi extends Api>(models: readonly (ModelSpec<TApi> | Model<TApi>)[], dynamicModelsAuthoritative?: boolean): string;
147
+ export declare function fingerprintStaticModels<TApi extends Api>(models: readonly (ModelSpec<TApi> | Model<TApi>)[], policy?: StaticFingerprintPolicy): string;
@@ -1,19 +1,12 @@
1
+ import { type } from "@linxiraos/pi-omptype";
1
2
  import { logger, VERSION } from "@linxiraos/pi-utils";
2
3
  import { buildModel } from "./build";
3
4
  import { collapseBuiltVariants } from "./compat/collapse";
4
5
  import { applyCatalogMetrics, CatalogMetricsIndex } from "./identity/metrics";
5
6
  import { readModelCache, writeModelCache } from "./model-cache";
6
7
  import { type GeneratedProvider, getBundledModels } from "./models";
7
- import { isTimeBasedCost } from "./pricing";
8
- import {
9
- type Api,
10
- type Model,
11
- type ModelCost,
12
- modelKind,
13
- type ModelSpec,
14
- type Provider,
15
- type TokenCost,
16
- } from "./types";
8
+ import { TimeBasedCostShape } from "./pricing";
9
+ import { type Api, type Model, modelKind, type ModelSpec, type Provider } from "./types";
17
10
  import { isRecord } from "./utils";
18
11
 
19
12
  const DEFAULT_CACHE_TTL_MS = 2 * 60 * 60 * 1000;
@@ -267,7 +260,6 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
267
260
  const cache = readModelCache<TApi>(cacheProviderId, ttlMs, now, dbPath);
268
261
  const dynamicModelsAuthoritative = options.dynamicModelsAuthoritative ?? false;
269
262
  const isAuthoritativeDynamicCache = dynamicModelsAuthoritative && (cache?.payloadAuthoritative ?? false);
270
- const cacheAdditiveStaticModelIds = isAuthoritativeDynamicCache ? undefined : modelsDevAdditiveStaticModelIds;
271
263
  const restoredCache = restoreCachedModelHeaders(
272
264
  cache?.models ?? [],
273
265
  staticModels,
@@ -286,7 +278,12 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
286
278
  staticNames: options.keepStaticNames ? new Map(staticModels.map(model => [model.id, model.name])) : undefined,
287
279
  };
288
280
  const cacheDropIds = options.dropCachedModelIdsOnStaticMismatch;
289
- const staticCatalogFingerprint = fingerprintStaticModels(staticModels, dynamicModelsAuthoritative);
281
+ // Additive mode is cache identity: a snapshot written while shared-catalog
282
+ // rows could replace bundled metadata must not match an additive resolver.
283
+ const staticCatalogFingerprint = fingerprintStaticModels(staticModels, {
284
+ authoritative: dynamicModelsAuthoritative,
285
+ additive: modelsDevAdditiveStaticModelIds !== undefined,
286
+ });
290
287
  // Endpoint-migration policy is cache identity: adding an id must invalidate
291
288
  // matching-static-catalog caches written by the prior resolver.
292
289
  const staticFingerprint =
@@ -294,6 +291,13 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
294
291
  ? `${staticCatalogFingerprint}:drop:${Bun.hash(cacheDropIds.join("\0")).toString(36)}`
295
292
  : staticCatalogFingerprint;
296
293
  const cacheFingerprintMatches = cache?.staticFingerprint === staticFingerprint && staticFingerprint.length > 0;
294
+ // A matching cache was written against this static catalog under the same
295
+ // additive policy, so its same-id rows are live discovery merged over the
296
+ // bundled rows, never shared-catalog overrides (#17481). Strip them only on
297
+ // a mismatch: a static-catalog upgrade or a cache written before additive
298
+ // semantics were enabled.
299
+ const cacheAdditiveStaticModelIds =
300
+ isAuthoritativeDynamicCache || cacheFingerprintMatches ? undefined : modelsDevAdditiveStaticModelIds;
297
301
  const cacheNeedsModelMigration =
298
302
  !cacheFingerprintMatches &&
299
303
  cacheDropIds !== undefined &&
@@ -315,8 +319,8 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
315
319
  // Cold-start fast path: when a fresh, authoritative cache exists, the network
316
320
  // fetch is skipped, AND the static catalog slice is byte-identical to what
317
321
  // was merged in last time, the cache row IS the authoritative merge result.
318
- // Additive caches still need same-id rows stripped because an older binary
319
- // may have written the snapshot before additive semantics were enabled.
322
+ // A mismatched additive cache never reaches here; its same-id rows are
323
+ // stripped below.
320
324
  if (
321
325
  !shouldFetchFromNetwork &&
322
326
  cache?.fresh &&
@@ -324,18 +328,9 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
324
328
  cacheFingerprintMatches &&
325
329
  !cacheHasUnresolvedHeaders
326
330
  ) {
327
- const cacheContribution = cacheAdditiveStaticModelIds
328
- ? restoredCache.models.filter(model => !cacheAdditiveStaticModelIds.has(model.id))
329
- : restoredCache.models;
330
- const cachedModels = cacheAdditiveStaticModelIds
331
- ? mergeCatalogMetrics(
332
- mergeDynamicModels(staticModels, cacheContribution, mergeAuthority),
333
- restoredCache.models,
334
- )
335
- : restoredCache.models;
336
- const source: ModelResolutionSource = cacheContribution.length > 0 ? "cache" : "bundled";
331
+ const source: ModelResolutionSource = restoredCache.models.length > 0 ? "cache" : "bundled";
337
332
  return {
338
- models: collapseBuiltVariants(cachedModels),
333
+ models: collapseBuiltVariants(restoredCache.models),
339
334
  stale: false,
340
335
  source,
341
336
  ...(source === "cache" ? { updatedAt: cache.updatedAt } : {}),
@@ -382,7 +377,10 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
382
377
  dynamicModels.length > 0 &&
383
378
  (dynamicModelsAuthoritative || !hasModelsDevFetcher || modelsDevFetchSucceeded)
384
379
  : modelsDevFetchSucceeded;
385
- const mergedWithCache = mergeDynamicModels(staticModels, cacheModels, mergeAuthority);
380
+ const mergedWithCache = mergeCachedModels(staticModels, cacheModels, {
381
+ authority: mergeAuthority,
382
+ matchesStatic: cacheFingerprintMatches,
383
+ });
386
384
  const mergedWithModelsDev = mergeDynamicModels(
387
385
  mergedWithCache,
388
386
  modelsDevModels,
@@ -455,7 +453,10 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
455
453
  ? preparedLatestCacheModels.filter(model => !cacheAdditiveStaticModelIds.has(model.id))
456
454
  : preparedLatestCacheModels;
457
455
  const mergedFallbackModels = mergeDynamicModels(
458
- mergeDynamicModels(staticModels, latestCacheModels, mergeAuthority),
456
+ mergeCachedModels(staticModels, latestCacheModels, {
457
+ authority: mergeAuthority,
458
+ matchesStatic: cacheFingerprintMatches,
459
+ }),
459
460
  modelsDevModels,
460
461
  mergeAuthority,
461
462
  );
@@ -631,6 +632,24 @@ function mergeDynamicModels<TApi extends Api>(
631
632
  return Array.from(merged.values());
632
633
  }
633
634
 
635
+ /**
636
+ * Lays cached rows over the static catalog. A snapshot written against this
637
+ * static catalog (`matchesStatic`) is already that catalog merged with live
638
+ * discovery, so its rows replace same-id static rows verbatim; re-merging would
639
+ * only rebuild them and churn the persisted payload. A snapshot from another
640
+ * static catalog re-merges so upgraded bundled metadata applies.
641
+ */
642
+ function mergeCachedModels<TApi extends Api>(
643
+ staticModels: readonly Model<TApi>[],
644
+ cacheModels: readonly Model<TApi>[],
645
+ options: { authority: DynamicMergeAuthority; matchesStatic: boolean },
646
+ ): Model<TApi>[] {
647
+ if (!options.matchesStatic) return mergeDynamicModels(staticModels, cacheModels, options.authority);
648
+ const merged = new Map<string, Model<TApi>>(staticModels.map(model => [model.id, model]));
649
+ for (const cachedModel of cacheModels) merged.set(cachedModel.id, cachedModel);
650
+ return Array.from(merged.values());
651
+ }
652
+
634
653
  function retainModelIds<TApi extends Api>(
635
654
  models: readonly Model<TApi>[],
636
655
  retainedModels: readonly Model<TApi>[],
@@ -642,6 +661,17 @@ function retainModelIds<TApi extends Api>(
642
661
 
643
662
  const MODEL_CACHE_FINGERPRINT_VERSION = `merge-v5:${VERSION}`;
644
663
 
664
+ /**
665
+ * Merge policy that is part of a cache's identity in
666
+ * {@link fingerprintStaticModels}: `authoritative` when dynamic discovery owns
667
+ * the catalog, `additive` when the shared catalog may only add ids. The flags
668
+ * compose; snapshots written under different policies never match.
669
+ */
670
+ export interface StaticFingerprintPolicy {
671
+ authoritative?: boolean;
672
+ additive?: boolean;
673
+ }
674
+
645
675
  /**
646
676
  * Return the versioned content identity for a static provider slice. Callers
647
677
  * may mutate or freeze their arrays, so every call observes current content
@@ -649,12 +679,11 @@ const MODEL_CACHE_FINGERPRINT_VERSION = `merge-v5:${VERSION}`;
649
679
  */
650
680
  export function fingerprintStaticModels<TApi extends Api>(
651
681
  models: readonly (ModelSpec<TApi> | Model<TApi>)[],
652
- dynamicModelsAuthoritative = false,
682
+ policy: StaticFingerprintPolicy = {},
653
683
  ): string {
654
- if (models.length === 0) return `${MODEL_CACHE_FINGERPRINT_VERSION}:empty`;
655
- if (dynamicModelsAuthoritative)
656
- return `${MODEL_CACHE_FINGERPRINT_VERSION}:authoritative:${fingerprintStaticModels(models)}`;
657
- return `${MODEL_CACHE_FINGERPRINT_VERSION}:${Bun.hash(JSON.stringify(models)).toString(36)}`;
684
+ const policyKey = `${policy.authoritative ? ":authoritative" : ""}${policy.additive ? ":additive" : ""}`;
685
+ if (models.length === 0) return `${MODEL_CACHE_FINGERPRINT_VERSION}${policyKey}:empty`;
686
+ return `${MODEL_CACHE_FINGERPRINT_VERSION}${policyKey}:${Bun.hash(JSON.stringify(models)).toString(36)}`;
658
687
  }
659
688
 
660
689
  function mergeDynamicModel<TApi extends Api>(
@@ -782,18 +811,19 @@ function preferDiscoveryLimit(discoveryLimit: number | null, fallbackLimit: numb
782
811
  * caller treats the source as failed (cache/static fallback) rather than as an
783
812
  * intentionally empty catalog that an authoritative provider would prune to.
784
813
  */
785
- function buildDiscoveredModelSpecs<TApi extends Api>(value: unknown): DiscoveredModelSet<TApi> {
814
+ function buildDiscoveredModelSpecs<TApi extends Api>(values: unknown): DiscoveredModelSet<TApi> {
786
815
  const models: Model<TApi>[] = [];
787
816
  const explicitKindModels = new Set<Model<TApi>>();
788
- if (!Array.isArray(value)) {
817
+ if (!Array.isArray(values)) {
789
818
  return { models, explicitKindModels };
790
819
  }
791
820
  const failures: unknown[] = [];
792
- for (const item of value) {
793
- if (!isModelLike(item)) continue;
821
+ for (const value of values) {
822
+ if (!ModelSpecShape.allows(value)) continue;
823
+ const item = value as ModelSpec<TApi>;
794
824
  let model: Model<TApi>;
795
825
  try {
796
- model = buildModel(item as ModelSpec<TApi>);
826
+ model = buildModel(item);
797
827
  } catch (error) {
798
828
  failures.push(error);
799
829
  logger.warn("model discovery skipped a model that failed to build", {
@@ -810,109 +840,21 @@ function buildDiscoveredModelSpecs<TApi extends Api>(value: unknown): Discovered
810
840
  return { models, explicitKindModels };
811
841
  }
812
842
 
813
- function isModelLike(value: unknown): value is ModelSpec<Api> {
814
- if (!isRecord(value)) {
815
- return false;
816
- }
817
- const v = value as {
818
- id?: unknown;
819
- name?: unknown;
820
- api?: unknown;
821
- provider?: unknown;
822
- baseUrl?: unknown;
823
- reasoning?: unknown;
824
- input?: unknown;
825
- cost?: unknown;
826
- contextWindow?: unknown;
827
- maxTokens?: unknown;
828
- };
829
- if (typeof v.id !== "string" || v.id.length === 0) {
830
- return false;
831
- }
832
- if (typeof v.name !== "string" || v.name.length === 0) {
833
- return false;
834
- }
835
- if (typeof v.api !== "string" || v.api.length === 0) {
836
- return false;
837
- }
838
- if (typeof v.provider !== "string" || v.provider.length === 0) {
839
- return false;
840
- }
841
- if (typeof v.baseUrl !== "string" || v.baseUrl.length === 0) {
842
- return false;
843
- }
844
- if (typeof v.reasoning !== "boolean") {
845
- return false;
846
- }
847
- if (!isModelInputArray(v.input)) {
848
- return false;
849
- }
850
- if (!isModelCost(v.cost)) {
851
- return false;
852
- }
853
- // Finite positive: NaN > 0 is false, +Infinity < Infinity is false.
854
- const cw = v.contextWindow;
855
- if (cw !== null && (typeof cw !== "number" || !(cw > 0 && cw < Infinity))) {
856
- return false;
857
- }
858
- const mt = v.maxTokens;
859
- if (mt !== null && (typeof mt !== "number" || !(mt > 0 && mt < Infinity))) {
860
- return false;
861
- }
862
- return true;
863
- }
864
-
865
- function isModelInputArray(value: unknown): value is ("text" | "image")[] {
866
- if (!Array.isArray(value) || value.length === 0) {
867
- return false;
868
- }
869
- for (let i = 0; i < value.length; i++) {
870
- const item = value[i];
871
- if (item !== "text" && item !== "image") {
872
- return false;
873
- }
874
- }
875
- return true;
876
- }
877
-
878
- function isTokenCost(value: unknown): value is TokenCost {
879
- if (!isRecord(value)) {
880
- return false;
881
- }
882
- const c = value as {
883
- input?: unknown;
884
- output?: unknown;
885
- cacheRead?: unknown;
886
- cacheWrite?: unknown;
887
- };
888
- // Finite (NaN-safe): -Infinity < x < Infinity rejects NaN and both infinities.
889
- // Preserves original behavior: 0 and negatives remain valid.
890
- const ci = c.input;
891
- if (typeof ci !== "number" || !(ci > -Infinity && ci < Infinity)) {
892
- return false;
893
- }
894
- const co = c.output;
895
- if (typeof co !== "number" || !(co > -Infinity && co < Infinity)) {
896
- return false;
897
- }
898
- const cr = c.cacheRead;
899
- if (typeof cr !== "number" || !(cr > -Infinity && cr < Infinity)) {
900
- return false;
901
- }
902
- const cw = c.cacheWrite;
903
- if (typeof cw !== "number" || !(cw > -Infinity && cw < Infinity)) {
904
- return false;
905
- }
906
- return true;
907
- }
908
-
909
- function isModelCost(value: unknown): value is ModelCost {
910
- if (!isTokenCost(value)) return false;
911
- const cost = value as TokenCost & { longContext?: unknown; timeBased?: unknown };
912
- if (cost.timeBased !== undefined && !isTimeBasedCost(cost.timeBased)) return false;
913
- const longContext = cost.longContext;
914
- if (longContext === undefined) return true;
915
- if (!isTokenCost(longContext) || !isRecord(longContext)) return false;
916
- const threshold = longContext.inputThreshold;
917
- return typeof threshold === "number" && threshold > 0 && threshold < Infinity;
918
- }
843
+ /** Finite rates; 0 and negatives stay valid. */
844
+ const FiniteTokenCost = type({ input: "number", output: "number", cacheRead: "number", cacheWrite: "number" });
845
+ /** Discovery output is built in memory, so optional fields may be present as `undefined`. */
846
+ const ModelSpecShape = type({
847
+ id: "string > 0",
848
+ name: "string > 0",
849
+ api: "string > 0",
850
+ provider: "string > 0",
851
+ baseUrl: "string > 0",
852
+ reasoning: "boolean",
853
+ input: "('text' | 'image')[] > 0",
854
+ cost: FiniteTokenCost.and({
855
+ "timeBased?": TimeBasedCostShape.or("undefined"),
856
+ "longContext?": FiniteTokenCost.and({ inputThreshold: "number > 0" }).or("undefined"),
857
+ }),
858
+ contextWindow: "number > 0 | null",
859
+ maxTokens: "number > 0 | null",
860
+ });
@@ -32,6 +32,10 @@ export declare function withoutUnverifiedThinking<T extends {
32
32
  /**
33
33
  * Clamps a requested thinking level against explicit model metadata.
34
34
  *
35
+ * An unserved level first follows `thinking.effortMap` when the map sends it to
36
+ * a served tier that reaches the wire unchanged (a gateway answering `medium`
37
+ * as `high`); otherwise it climbs down to the nearest lower tier.
38
+ *
35
39
  * Non-reasoning models always resolve to `undefined`.
36
40
  */
37
41
  export declare function clampThinkingLevelForModel<TApi extends Api>(model: ApiModel<TApi> | undefined, requested: Effort | undefined): Effort | undefined;
@@ -42,6 +42,10 @@ export function withoutUnverifiedThinking<T extends { reasoning: boolean; thinki
42
42
  /**
43
43
  * Clamps a requested thinking level against explicit model metadata.
44
44
  *
45
+ * An unserved level first follows `thinking.effortMap` when the map sends it to
46
+ * a served tier that reaches the wire unchanged (a gateway answering `medium`
47
+ * as `high`); otherwise it climbs down to the nearest lower tier.
48
+ *
45
49
  * Non-reasoning models always resolve to `undefined`.
46
50
  */
47
51
  export function clampThinkingLevelForModel<TApi extends Api>(
@@ -60,6 +64,12 @@ export function clampThinkingLevelForModel<TApi extends Api>(
60
64
  return requested;
61
65
  }
62
66
 
67
+ const effortMap = model.thinking?.effortMap;
68
+ const aliased = effortMap?.[requested] as Effort | undefined;
69
+ if (aliased !== undefined && levels.includes(aliased) && (effortMap![aliased] ?? aliased) === aliased) {
70
+ return aliased;
71
+ }
72
+
63
73
  const requestedIndex = THINKING_EFFORTS.indexOf(requested);
64
74
  if (requestedIndex === -1) {
65
75
  return undefined;