[jagguji]

Fixes #90.

Problem

The finalization pass (stabilizeNames) gives a genuinely-colliding shape — same base name, same home, distinct shape — a content-hash suffix instead of an encounter-order counter, so a byte-identical shape should keep its name. But the hash was seeded from entrySig/recordSig, which encode a field's referenced type as its entry key — and keys are 'id:' + type.id. The checker assigns type.id in encounter order, so:

• an unrelated upstream edit (adds/removes a sibling type) renumbers it, and
• a compiler-version bump (e.g. TS 5.9 → 6.0) renumbers it too,

→ the "stable" hash changes and a byte-identical shape gets a different name (fooConfig3 ⇄ fooConfig). That's source-breaking churn for every downstream consumer who annotated the old name, with zero semantic change upstream — exactly what a typed-API generator must not do.

Fix

A new structuralSig seeds the hash from structure only: field names + optionality, and recursively the shapes of referenced types (not their id-keys), cycle- and diamond-guarded by an add-only seen set (linear on deep DAGs — blend's ~2600-node --webapi graph is fine). The id-based entrySig/recordSig are untouched for dedup and the merge, where type.id is correct within a run. The change is one line in stabilizeNames — swapping the hash seed.

Guarantee

Identical shape ⇒ identical name, across compiler versions and unrelated upstream edits. Only a real shape change changes a name.

Verified three ways:

• Compiler-version stability: blend@0.0.36 generates byte-identical type names (1749 of them) on TypeScript 5.9.3 and 6.0.3 — before this, they churned.
• Unrelated-edit stability: adding several unrelated types upstream (renumbering every subsequent type.id) no longer renames the unchanged SizeToken shapes.
• Smoke guard: a renumber-invariance check builds the same shape (incl. a self-ref cycle) under two totally different key-numberings and asserts the hash is identical; a different shape still hashes differently.

One-time cost

Because the hash function changes, the currently hash-suffixed names rename once in this release (the golden + benchmark-baseline diff — portalStyleQn0e4 → portalStyleV1dkur, byte-identical shapes). This is the last forced rename; ship it with a version bump and a consumer note. All metrics are unchanged (name-only, equal-or-better on all 9 benchmark packages).

Verification

• smoke (2 new Structural type names churn across versions when shape is unchanged (numbered suffixes shift on unrelated upstream edits) #90 guards), all 93 goldens match + compile on ReScript, benchmark accepted (name-only renames, no metric change)
• unblocks a future deliberate TypeScript 6.x bump (the churn was the blocker)

🤖 Generated with Claude Code

[github-actions]

Benchmark: ✅ PASS

Package	Compile	Diff vs baseline	usable	review	broken	Verdict
@juspay/blend-design-system@0.0.36	✅	identical	102	5	0	✅ PASS
@juspay/blend-design-system@0.0.37-beta.8	✅	identical	215	7	0	✅ PASS
react-day-picker@10.0.1	✅	identical	19	7	0	✅ PASS
react-tooltip@6.0.7	✅	identical	1	0	0	✅ PASS
react-markdown@10.1.0	✅	identical	0	2	0	✅ PASS
@smastrom/react-rating@1.5.0	✅	identical	1	0	0	✅ PASS
clsx@2.1.1	✅	identical	0	0	0	✅ PASS
hono@4.12.25	✅	identical	0	0	0	✅ PASS
@base-ui-components/react@1.0.0-rc.0	✅	identical	174	21	0	✅ PASS

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@juspay/rescript-bindgen@140

commit: 8ec607b