A real changelog for the GenAI conventions

[JeremyFunk]

The GenAI registry had one snapshot, so it had no diffs, no release pages and no rows in the feed. It now has a history: every commit touching model/ is walked from ebe3d1f — the point at which it became a repository of its own — and 40 of them changed the model.

The floor is load-bearing. One commit earlier the filtered history still carries the 52 aws.* attributes the split dropped, so crossing it would report 52 removals the project never made. Everything older is already covered by the tagged semantic-conventions snapshots, which carried gen_ai.* until v1.44.0 deprecated it in place.

What had to be fixed for the walk to read well

• A candidate is kept only when the differ finds something in it. The old untagged gate compared normalized bytes, which is stricter than the diff: 7 of the 40 commits would have been published as release pages listing no changes at all.
• Same-day commits get their own version. A commit is dated, not numbered, and upstream merges several model changes on a busy day; the second one takes 2026-05-05.2 rather than overwriting the first snapshot. Four such collisions exist in the backfill.
• The differ never read usedBy. A commit whose whole content is a requirement level — "Relax gen_ai.provider.name on gen_ai.client.operation.duration to Conditionally Required" — diffed to nothing. It now reports levels that moved and references that appeared or disappeared, one change per attribute rather than one per signal.

That last one needed a normalizer fix underneath it: a group can reference an attribute twice — inherited through ref_group, then again in its own list to override the level — and keeping both wrote the attribute as required and conditionally_required on the same signal. Collapsing to the effective reference re-normalizes every semantic-conventions snapshot, which is why all 16 are touched here. Volume is small and mostly editorial: 0–16 requirement-level changes and 2–7 notable usage changes per release.

Site

• Release pages linked upstream through v${version}, which 404s for a dated source; they now use the commit SHA the record carries.
• BREAKING_BLURB was missing its genai key. tsc --noEmit does not check .astro, so typecheck now also runs astro check (currently 0 errors).
• Version labels, page titles and RSS titles no longer hardcode a v prefix.
• Editorial-only commits from an untagged source stay off the front page and the RSS feed — forty rows of reworded briefs would bury every tagged release. They keep their own pages and the prev/next navigation.
• An untagged release page shows the commit subject where a tagged one shows release-note bullets.
• Change lists can now link GenAI-only attributes, which have pages but were not in the linkable set.

Verification

• bun run ingest --force twice produces byte-identical data/ — the walk, the gate and the version numbering are deterministic. spec/ and proto/ are untouched by the normalizer change.
• An incremental bun run ingest genai fetches nothing and leaves the index byte-identical. The resume point is the newest snapshot's commit, not its date: ebe3d1f and 07bbdbe share a committer timestamp, and a date watermark would skip the second for good.
• bun run typecheck, bun run build, bun test — 50 pass, 0 fail. New tests cover the floor, the no-empty-release-page invariant, same-day versioning, the requirement-level relax, and the one-reference-per-group normalizer rule.
• Nothing in the GenAI history ranks breaking, as expected: the registry is development throughout.

Known follow-up

/api/diff/[source]/[pair] precomputes every ordered pair, so 40 GenAI snapshots add 780 files (11 MB of the 80 MB dist/). That grows quadratically with commit-granular history — worth capping before it approaches Cloudflare's 20k-asset limit, but not urgent at 3.1k files.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}