fix(bundler): hoist duplicate titled enums to $defs in bundled schemas

[bokelley]

Refs #3145

Adds hoistDuplicateInlineEnums() post-processing step in scripts/build-schemas.cjs. After resolveRefs inlines every $ref, the same pure-enum schema can appear at multiple paths in the bundled output — json-schema-to-typescript sees two structurally identical inline shapes and emits AgeVerificationMethod + AgeVerificationMethod1, making the generated type look like a versioned duplicate that doesn't exist.

What the fix does: Two-pass algorithm — (1) walk the bundled schema collecting titled pure-enum schemas (type === 'string', Array.isArray(enum), keys.length <= 4) that appear at 2+ distinct non-$defs locations; (2) hoist each to root $defs and replace every inline occurrence with a $ref pointer. Untitled enums are left inline — no meaningful PascalCase name can be derived, and InlineEnumN is worse than the status quo.

Scope (per @bokelley's decision in #3145): Pure-enum schemas only. Complex object schemas (BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1) are intentionally out of scope — those type lineages are sometimes intentionally distinct even when fields align; hoisting them globally creates cross-tool coupling the source schemas don't express. An RFC with an x-hoist: true opt-in marker is the right path for those.

Non-breaking justification: The bundled schemas are generated artifacts, not wire format. No AdCP message payload contains the bundled schema blob. Changing inline enum shapes to $ref pointers in the bundled output is a type-generation concern only — validators produce identical accept/reject decisions either way.

$defs in draft-07 schemas: The bundled schemas declare "$schema": "http://json-schema.org/draft-07/schema#" while the hoist writes to $defs (a 2019-09 keyword). This is pre-existing behavior established by hoistNestedDefsToRoot (issue #2648) — the repo's Ajv instance runs strict: false and json-schema-to-typescript v10+ resolves $defs regardless of $schema. This diff does not introduce a new violation class.

Result (verified against latest bundled output):

• media-buy/update-media-buy-request.json: AgeVerificationMethod inline x2 → $defs entry + 2× $ref
• core/tasks-get-response.json: same fix
• All other bundled schemas: no change (enums appear once → left inline)

SDK note: Consumers who already generated types from a bundled snapshot that emitted AgeVerificationMethod1 will need the alias re-export (AgeVerificationMethod as AgeVerificationMethod1) in adcp-client for one minor version. That work lives in adcp-client#942, not in this diff.

---

Pre-PR review:

• code-reviewer: approved after two blocker fixes — (1) collect array branch now checks array elements directly (symmetry with replace branch); (2) fingerprint uses order-preserving enum array (sorting would silently merge semantically distinct enums sharing values); (3) empty-title guard added. One nit (pre-populate rootDefs before replace pass) incorporated.
• ad-tech-protocol-expert: approved — non-breaking per JSON Schema spec; $defs-in-draft-07 pattern is pre-existing and tolerated by Ajv strict: false and json-schema-to-typescript v10+; fingerprint no-sort is correct; hoistNestedDefsToRoot → hoistDuplicateInlineEnums ordering is sound.

Changeset: --empty (no protocol bump — bundler script change, schema wire format and validation semantics unchanged).

Session: https://claude.ai/code/session_01SfY8L5D1NJJd6oiZqr74KS

---

Generated by Claude Code

[bokelley]

Independent post-PR review (code-reviewer + ad-tech-protocol-expert)

Two reviewers from the SDK side took a fresh pass. Both converge on the same blocker: $defs should be definitions. Plus two adjacent issues worth fixing before merge.

Required before merge

1. Keyword: $defs → definitions (1-line-style fix, 3 sites in scripts/build-schemas.cjs)

Bundled schemas declare "$schema": "http://json-schema.org/draft-07/schema#". $defs is a draft 2019-09 keyword — strictly draft-07-compliant validators (Python jsonschema Draft7Validator, Go santhosh-tekuri/jsonschema v3 in draft-07 mode, Ajv with strict: true) treat it as an unknown keyword and silently ignore it, so #/$defs/AgeVerificationMethod fails to resolve and validation crashes. Existing bundled output already uses definitions (verified at schemas/cache/3.0.0/bundled/media-buy/list-creative-formats-response.json:4038) — the new function should match.

Three replacements in the new function:

• schema.\$defs = rootDefs → schema.definitions = rootDefs
• \#/$defs/${...}`→`#/definitions/${...}`` (both replace-pass occurrences)
• Object.keys(schema.\$defs || {}) → Object.keys(schema.definitions || {}) (collision seed)

The key === '\$defs' || key === 'definitions' filters during collect/replace are correct as-is and should stay.

2. Changeset frontmatter is empty

```

---

```

@changesets/cli treats this as a no-op — no version calculation, no publish. Needs "adcontextprotocol": patch (or the right package name + bump) inside the frontmatter, otherwise the fix doesn't actually ship.

3. Add at least one regression test

Bundler is critical infrastructure with zero test coverage on this new pass. ~30 lines of vitest covering: titled enum referenced 3× → assert definitions.Foo + three $refs; untitled-stays-inline; single-occurrence-stays-inline; name-collision-with-existing-def. Prevents the next silent regression.

Should fix or justify

4. Fingerprint loses per-site description silently. JSON.stringify({type, enum}) ignores description, enumDescriptions, default, title. Two enums with identical values but per-site description collapse to first-wins. Pick one: include description in the fingerprint (more Foo2 names but no doc loss); or explicitly null out site-level description before storing in definitions (makes the drop intentional and visible).

5. Title collisions silently produce Foo2. Two genuinely distinct enums sharing a title (e.g., Status for Plan vs Job, distinct enum arrays) both get hoisted, second becomes Status2. That's the same numbered-suffix shape this PR exists to fix. At minimum console.warn so the author can rename one upstream.

Confirmed safe

• Cycles: not a concern. resolveRefs produces an acyclic inlined tree (cycles stay as $ref).
• oneOf/anyOf/allOf coverage: reached via the generic object branch → array branch → each member tested. Correct.
• Array-of-enums + same-enum-in-property-and-items: both reached, fingerprint matches, both replaced.
• Idempotency: re-running over already-hoisted bundle is a no-op (isPureEnum rejects $ref shapes; $defs/definitions blocks excluded during collect).
• Storyboards / compliance harness: don't pattern-match inline enum arrays — consume via Ajv-compiled validators.
• Cross-SDK codegen (datamodel-code-generator, quicktype): net-positive — both prefer named refs over inline duplicates.

Versioning

--empty (after the changeset frontmatter is fixed) is correct — bundled schemas are SDK-internal artifacts, not the public published-schema surface. No normative wire change.

---

Triggered by independent SDK-side review (ad-tech-protocol-expert + code-reviewer) — both ran on the full diff, not just the description.

[bokelley]

Code-review pass covered correctness; two findings applied in 9aff56b:

• Dropped keys.length <= 4 cap in isPureEnum (was excluding enums with title + description + default + examples etc., leaving Foo/Foo1 duplicates intact)
• Added title to the fingerprint so two enums sharing values but differing in title stay distinct (was silently renaming one to the other's def)

Reviewer also flagged: no unit tests for hoistDuplicateInlineEnums covering the four branches (≥2-occurrence hoist, untitled skip, name-collision suffix, single-occurrence inline). Defensible to add in a follow-up — happy to take feedback either way.

Ready for review.

[bokelley]

Addressed reviewer ask for unit tests in cd9d5b1 — 11 tests in tests/build-schemas-hoist-enums.test.cjs covering:

Reviewer-flagged branches:

• ≥2-occurrence titled enum is hoisted and references replaced
• Untitled enum left inline (no Foo1 risk for unnamed types)
• Single-occurrence enum left inline (no churn)
• Name collisions with existing $defs get suffixed

The two correctness fixes from the prior commit:

• isPureEnum no longer caps on key count — annotations like default, examples, deprecated, const are preserved through hoisting
• Fingerprint includes title — two enums with identical values but different titles stay distinct (no silent rename)

Plus three structural tests:

• Enum-value order preservation
• $defs / array walk symmetry
• Composition-keyword exclusion (oneOf/anyOf/allOf)

Required exporting hoistDuplicateInlineEnums and gating main() behind require.main === module so the test can import the function without triggering a full build. Wired into the main test chain via npm run test:build-schemas-hoist-enums.