Skip to content
Source
Sign inSign up
TanStack/schemas

Link alias rows to the model they resolve to #720

Mergedtombeckenhammerged 3 commits intomain fromfeat/709-alias-linksmerged by tombeckenham View on GitHub

tombeckenhamcommented

Field 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_of and index models_providerId_rawId_idx (migration 0019; 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, with factSources.aliasOf as 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 serves aliasOf: null with the evidence kept, and the source is hidden with it, as sameAs does.
  • The target row's aliases lists the alias, with factSources.aliases. An alias may now be a row of its own (Mistral, OpenAI, Gemini already did this for gemini-flash-latest). Lookup by an id that is a row still returns that row.
  • aliasOf, aliasOfSource and aliasesSource are compared on each poll, so a link change, or a newly stated silence, emits model.updated and is written.
  • path: 'unstated' is a stated silence (the source was read and names no target for this id). It is stored provenance like cacheRead: 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.

    1. tombeckenham pusheda39203e

    2. tombeckenham pushed149f514

    3. tombeckenham merged this751d289

    4. tombeckenham closed this

Sign in to join this conversation.