Link alias rows to the model they resolve to #720
main fromfeat/709-alias-links·merged by tombeckenham View on GitHubField decision#
sameAs keeps its one meaning: a reseller row linking to the maker's row at another provider (evidence in upstream_*, resolved by reconcileSameAs). Within-provider alias links use aliases, the field #112 built, plus one new pointer on the alias row, because nothing pointed from an alias row to its target.
- New column
models.alias_ofand indexmodels_providerId_rawId_idx(migration0019; the join below uses the index for both sides): the raw id the provider states this alias resolves to. It is evidence, written by the poll, withfactSources.aliasOfas its source. - The catalog resolves it at read time with an exact-id join (provider + raw id + live row), the first tier of
reconcileSameAs. The fuzzy tiers are not needed here: the provider names its own id. No stored link can go stale. A target that is gone or not yet listed servesaliasOf: nullwith the evidence kept, and the source is hidden with it, assameAsdoes. - The target row's
aliaseslists the alias, withfactSources.aliases. An alias may now be a row of its own (Mistral, OpenAI, Gemini already did this forgemini-flash-latest). Lookup by an id that is a row still returns that row. aliasOf,aliasOfSourceandaliasesSourceare compared on each poll, so a link change, or a newly stated silence, emitsmodel.updatedand is written.path: 'unstated'is a stated silence (the source was read and names no target for this id). It is stored provenance likecacheRead: not-offered, not a ledger entry: the source-silent ledger is chat-only and tied to gap-report scoring, and several of these rows are audio and OCR.
No alias table is written in code. Every link is parsed from a source at poll time. Id shapes (date suffix, -latest) are never the evidence.
Per provider#
Mistral (GET https://api.mistral.ai/v1/models, checked 2026-11-21, trimmed fixture mistral-models-aliases.json). Each member of an alias group lists the others in aliases: group membership is stated, direction is not. The listing's name is an undescribed display string, so it is not read as a target. All 18 -latest rows, and every other grouped row, are linked to their counterparts through aliases, with aliasOf: null and factSources.aliasOf path unstated. No Mistral row links through aliasOf.
OpenAI (model pages, for example https://developers.openai.com/api/docs/models/gpt-4o.md, trimmed fixture openai-gpt-4o.md.txt). A page's Model ID resolves to its Default snapshot. Read from the cached parse (ids[0], the other priced id), so no parser output changed and no docs cache bump is needed. Against the live listing, 35 dated rows: 29 linked (gpt-4o → gpt-4o-2024-08-06), 3 listed on a page's Snapshots list with no alias resolving to them (gpt-4o-2024-11-20, gpt-4o-mini-transcribe-2025-03-20, gpt-4o-mini-tts-2025-03-20; factSources.aliases path Snapshots), and 3 that no page names (gpt-5-search-api-2025-10-14, tts-1-1106, tts-1-hd-1106; path unstated). A failed page marks aliases and aliasOf unavailable, so the stored links are kept.
Gemini (https://aistudio.google.com/docs/changelog.md, through the existing tryDocs load). A changelog line sets the alias row's aliasOf even while the target is not listed. gemini-flash-latest → gemini-3-flash-preview links. gemini-pro-latest → gemini-3-pro-preview is stored, but that row is deprecated, so it serves null. gemini-flash-lite-latest and the other -latest rows no line names get unstated. A failed changelog marks aliases (every row) and aliasOf (-latest rows) unavailable. Before this change, a failed read silently dropped the stored target aliases.
Other change#
emptySources counted only a fixed list of keys, so a row whose only kept source was aliasOf (or cacheRead, sameAs...) had its sources dropped by resolveAbsent. It now counts every key.
API shape#
MODEL_ROW_SHAPE v10: rows gain aliasOf: string | null, and factSources gains aliases and aliasOf. aliases can now name ids that are rows. Noted in docs/api-changes.md and README ("Aliases at the same provider"), with a @modelschemas/client minor changeset. Migrate D1 (0019) before the deploy.