feat(schemas): x-adcp-hoist opt-in marker for canonically shared object schemas

[bokelley]

Closes #4557.

Summary

Opt-in companion to the pure-enum auto-hoist (hoistDuplicateInlineEnums, #3170). Spec authors set x-adcp-hoist: true on a source schema's root; the bundler moves it to root \$defs, replaces every inline occurrence with a \$ref, and strips the directive from bundled output.

Why opt-in for complex objects: structural identity ≠ semantic identity (BriefAsset and VASTAsset share fields today but represent different lifecycle concepts). Auto-hoisting would lock in coupling that's hard to walk back. x-adcp-hoist is the deliberate exception, not the default — and per-type decisions stay separate from landing the mechanism.

Naming follows the x-adcp-* precedent set by x-adcp-validation; the schema-extensions reference documents the directive's contract for source-tree consumers.

Behavior

• Hoists at any occurrence count (≥1). The marker declares intent; honoring it for single uses means adding a second reference later doesn't change the codegen surface.
• title is required — missing/empty → build error (the directive is meant to be deliberate).
• Same title + different shape is a build error — silently suffixing one to Foo2 would defeat the "canonical name" guarantee.
• Collision suffixing (PriceBlock2) only for a pre-existing \$defs key (non-marker name collision), matching the enum-hoist convention.
• Different titles never collapse, even with structurally identical bodies — preserves the BriefAsset/VASTAsset distinction by default.
• Recurses into hoisted defs so nested markers also collapse to refs.
• Final sweep strips stray markers that survived a pre-existing \$defs block — the directive never appears in bundled output.

Dry-run validation

Marked core/duration.json with x-adcp-hoist: true and rebuilt locally:

Check	Result
Bundles changed semantically	12 — exactly the bundles that referenced Duration
Bundles with timestamp-only diffs	69 — all other bundles unchanged
\$defs.Duration present in changed bundles	✅ canonical entry with title, no x-adcp-hoist
x-adcp-hoist anywhere in bundled output	✅ zero (directive stripped)
Inline \"title\": \"Duration\" outside \$defs	✅ zero (all 6 inline copies in create-media-buy-request collapsed)
Ajv compiles the hoisted bundle	✅ clean

Source change reverted before commit. No source schemas opt in here — per-type decisions ship in follow-ups.

Confirmed against this branch's full build: zero bundles change semantically vs. main (timestamp-only diffs only).

Review-driven changes

Two expert reviews flagged:

• BUG: tests not wired into npm test → fixed (test:build-schemas-hoist-marked added to the chain).
• BUG: missing changeset → added (.changeset/4557-x-adcp-hoist-opt-in-marker.md).
• RISK: stray markers inside pre-existing \$defs weren't stripped → fixed (final sweep + dedicated tests).
• RISK: same-title-different-shape silently produced Foo/Foo2 → fixed (build-time error + test).
• PROTOCOL: bare x-hoist namespace → renamed to x-adcp-hoist (matches x-adcp-validation precedent).
• PROTOCOL: source-tree publication surface → docs/reference/schema-extensions.mdx entry documents the directive contract, conformance, and SDK codegen impact.

Out of scope

• Per-type decisions for BriefAsset / VASTAsset / DAASTAsset / CatalogAsset (RFC default lean: keep-split).

Test plan

• 14 unit tests in tests/build-schemas-hoist-marked.test.cjs (basic hoist, single-occurrence, missing/empty title errors, same-title-different-shape error, PascalCase sanitization, pre-existing $defs collision, distinct-titles preservation, no-op, array items, nested markers, pre-existing $defs same-shape, stray-marker stripping in two configurations)
• Existing hoist-enums and preserve-subschema-ids tests still pass
• npm test chain now includes test:build-schemas-hoist-marked
• Full node scripts/build-schemas.cjs runs clean (81 bundled schemas, zero semantic diffs vs main)
• Ajv-compile spot-check on hoisted bundle (validated via dry-run)

🤖 Generated with Claude Code