[bokelley]

Fixes the downstream targeting migration contract on the current 3.2.0-rc.3 pin. Request-side targeting accepts every schema-defined null clear command, while effective targeting and proposal snapshots remain strict.

Candidate identity

Item	Value
Base (origin/main, #2939)	cccb3ea83cb07dc24584e07aa2626b55761564bf
Head	264625c4cfa5e0d64e19a452e819a850ea7f1343
Tree	6d6bf0ffa292cad8f5fb6cfd5a53e1ae5eaa16ec
Binary diff SHA-256	eb40f40f608b18b9ab10660086f4ea531f739f01d1d50a993a157fd6beabb522
Scope	15 files, 2,247 additions / 246 deletions
SDK / protocol	14.0.0-rc.38 / 3.2.0-rc.3
Protocol bundle SHA-256	1cd940f76516b43327cbfa6c17c0befd4c093ca85b53a81a4062d38bb522d831

The rebase onto #2939 was conflict-free and has no path overlap with that change. This candidate inherits #2939's removal of obsolete preview artifacts and its exact publish-inventory guard. Package verification reports 6,107 files and permits only 3.2.0-rc.3 plus stable legacy protocol bundles.

Contract and migration

• Generated TargetingOverlayInput accepts null for all 37 targeting dimensions; effective TargetingOverlay and canonical proposal snapshots reject clear commands.
• The corrected public narrowing is ProposalPurchase['targeting_overlay']. The root TargetingOverlay type was already strict and remains so.
• Clear commands belong in TargetingOverlayInput / BuyProductsRequest; persisted and echoed values must be resolved targeting state.
• Both public targeting Zod schemas now derive their exact runtime constraints from the verified local protocol cache. Cardinality, patterns, enums, boolean constraints, open root extensions, and closed nested objects agree with AJV.
• Exact-schema dereferencing is cache-only with HTTP and filesystem fallback disabled. Public Zod object methods (pick, omit, extend, and shape) remain typed and available.
• The minor changeset documents the proposal compile migration and the newly stricter rejection of formerly accepted but wire-invalid Zod inputs.

Qualification

Local qualification on the exact generated candidate passed:

• Full npm run generate-types, repeated idempotently with unchanged core/tools/Zod hashes
• Typecheck and declaration/library build
• 65 focused passes, one environment-gated PostgreSQL skip, covering all 37 clears, proposal kinds/statuses, AJV/Zod parity, open/closed objects, offline cache resolution, helpers, persistence, and the official-MCP starter
• Complete npm run check:package, including examples, publint, Are The Types Wrong, packed links, and published-protocol inventory
• Generated docs, release worksheet, formatting, diff checks, and Conventional Commit validation

Three independent expert reviews (protocol/schema, compatibility/code, and DX/docs/tests) converged with no blockers on this head. Fresh protected CI and Ladon review are running. bmilekic remains requested for the required normal human maintainer review; auto-merge should merge only after branch protection is satisfied.

No protocol pin, package version, release, or tag is changed here.

[bokelley]

Seam constraints for the overlap with #2907 (ecf1c745), from the author of that side. Flagging the ones where a reasonable change would silently regress rather than fail loudly.

alignTargetingInputArrayCardinality (scripts/generate-types.ts)

It is deliberately narrow, and a naming resolver should make it no-op rather than fight it. It fires only when the Input side is provably the item type of the Overlay side's array — soleArrayItemTypeName matches [T, ...T[]] or T[] for a single identifier T, and the null-stripped Input type must equal T exactly. So if your six-alias resolver gives those four remaining collisions real array aliases, my pass stops firing for them by design (the continue is hit before any replace, so no throw). That is the preferred end state — a correct alias should never be rewritten into an inline tuple.

Two ordering constraints that are load-bearing:

1. Tools pipeline: it must stay before addCoreGeneratedTypeImports. After that rewrite, TargetingOverlay is an import rather than a local declaration, generatedObjectTypeProperties finds nothing, and the pass returns the input unchanged — the device arrays regress to scalars with no error. Current call site is right after simplifyPriceBreakdown.
2. Core pipeline: it is the outermost wrapper of processedCoreTypes. It expects the block in its final form.

The weak spot, stated plainly: the guard against a silent miss is a throw when a replacement doesn't land, but that throw can only fire if block extraction succeeded. generatedObjectTypeProperties matches export type <Name> = ...{ ... }; — if #2919 changes TargetingOverlayInput to an interface, or changes the intersection/brace shape, extraction returns undefined and the whole pass silently no-ops. If you touch that declaration form, either update the regex or tell me and I'll convert the no-op into a hard failure. I'd rather harden it than have it quietly stop working.

The invariant it relies on is that core/targeting.json and core/targeting-input.json declare identical property sets (37 at rc.3). It only iterates shared properties, so an Input-only field won't break it, but the comment would become stale.

Tests: test/lib/targeting-input-cardinality-codegen.test.js. The four case (four repairs with the last property affected) is the one that fails against a naive implementation — please keep it.

resolveTargetingInput / applyTargetingInput / hasTargetingClears

These are the public helpers you said you're preserving. Three non-obvious constraints:

1. compactOverlay must keep the null-prototype accumulator and the UNSAFE_OVERLAY_KEYS drop. Do not simplify to {...prior, ...input}. targeting_overlay comes off JSON.parse, which yields a real own __proto__ key; assigning it with = invokes the inherited setter and swaps the result's prototype, so an attacker-chosen dimension reads back off the overlay while staying invisible to Object.keys and JSON.stringify. Regression test: a wire-supplied __proto__ key cannot inject inherited targeting.
2. hasTargetingClears must filter the same key set, or the two functions disagree about whether {"__proto__": null} is a clear.
3. They return undefined, never {}, when no dimension survives. createMediaBuyStore depends on that to delete a tracked overlay; returning {} would persist and then echo an empty overlay into get_media_buys, whose schema forbids it.

Known and unfixed, if you're in these signatures anyway: applyTargetingInput infers TOverlay from prior, so applyTargetingInput(undefined, input) degrades to object — the first thing anyone writes on the update path. Inferring from input instead (ResolvedTargetingInput<TInput>) is the fix; I left it because it wasn't worth widening that PR.

Store semantics (createMediaBuyStore)

persistFromCreate's fallback to the request overlay, and the new_packages arm of mergeFromUpdate, both must keep resolving clears away — those were the two paths that wrote a null command into durable state, which backfill then echoed into a response. Inputs are TargetingOverlayInput; anything persisted or echoed stays strict TargetingOverlay. The three-way 'targeting_overlay' in pkg / === undefined / === null distinction in mergeFromUpdate is what separates "not mentioned" from "clear it" — please don't collapse it.

Supported-field starter snapshot — concrete gotcha

src/lib/schemas/index.ts:82 derives canonicalGetProductsFields from GetProductsRequest_FieldsValues (inline-enums) filtered against CanonicalGetProductsRequest['fields'] (core). Those come from different codegen stages, so a partial regeneration desyncs them and you get a confusing TS2677 ... 'media_buy_support' is not assignable at that exact line.

I hit this while qualifying #2907 and briefly mis-read it as a defect in someone else's PR. Always run the full npm run generate-types, never just npx tsx scripts/generate-types.ts — the inline-enum and enum-array stages are separate scripts in that npm script. If you see that TS2677, regenerate fully before believing it.

No action taken on this PR — not touching its content, draft state, or automation. Happy to review the naming resolver against these seams once you rebase onto an exact head.

🤖 Generated with Claude Code

Independently reproduced against merged ecf1c745, and I can give you the precise root cause — it's a title collision, which I think makes your resolver the right shape of fix rather than a workaround.

Those four fields are inlined in both schemas with the same title and different types:

	core/targeting.json	core/targeting-input.json
geo_metros (title: "Targeting Geo Metros")	type: "array"	type: ["array", "null"]
language ("Targeting Languages")	type: "array"	type: ["array", "null"]
keyword_targets ("Targeting Keywords")	type: "array"	type: ["array", "null"]
negative_keywords ("Targeting Negative Keywords")	type: "array"	type: ["array", "null"]

jsts names the type from the title, so one name has two meanings and whichever definition the compiler meets first in a compilation unit wins for both. That's why the breakage direction flips per unit:

core.generated.ts     TargetingGeoMetros = [GeoMetro, ...GeoMetro[]] | null   ← input def won
tools.generated.ts    TargetingGeoMetros = [GeoMetro, ...GeoMetro[]]          ← strict def won

so in core the strict TargetingOverlay wrongly admits null, and in tools the Input wrongly rejects it. 4 titles × 2 units = the 8 you counted. The per-unit flip is the tell that it's first-encounter ordering, not a per-field modelling difference — and it means anything that patches one unit's symptom will get the other unit backwards.

Worth noting these four are also the only Input dimensions that don't use the anyOf: [$ref, {type: "null"}] wrapper the other 27 use. Whether that asymmetry is intentional upstream is a separate question; a resolver that gives each unit distinct names is correct either way, which is why I'd rather you fix it at the naming layer than have the SDK special-case four fields.

Seam: my cardinality pass provably cannot interfere

alignTargetingInputArrayCardinality only fires when the Input-side type, null-stripped, equals the item type of the Overlay-side array. For these four the Input side is TargetingGeoMetros and the item type is GeoMetro — not equal, so the loop continues before reaching the replace, and before the throw. No interaction, no spurious failure, in either the current or the corrected generation.

And yes: once your resolver gives the four device/browser aliases distinct correct names, my pass becomes a permanent no-op. That is the intended end state, not a fallback I want to preserve. If your resolver also covers the array-vs-item-type collapse (device_platform → DevicePlatform instead of [DevicePlatform, ...]), say so and I'll delete alignTargetingInputArrayCardinality and its test in a follow-up rather than leave dead machinery with a throw in it. Two overlapping guards on the same invariant is worse than one.

If it doesn't cover that case, keep it — and please keep test/lib/targeting-input-cardinality-codegen.test.js's four case, which is the one that catches a naive implementation.

Starter — agreed, with one thing I'll pick up

Rejecting a supplied overlay in the starter is more defensible than what I did, and it's what DR-0020 actually asks for ("sellers reject a clear the product cannot execute rather than silently retaining the default"). A starter that supports no overlay dimensions shouldn't be projecting one. Removing the now-unused import is right.

The cost is that it deletes the repo's only worked example of resolveTargetingInput — and the DX review on my side had already flagged that the null-clear semantics appear in no doc and no skill. Don't keep dead code to solve that. I'll take the docs debt: a three-state table plus the helper names in MEDIA-BUY-3.2-COMPATIBILITY.md, docs/TYPE-SUMMARY.md, and skills/build-seller-agent/, in my rc.3 audit PR. Nothing for you to carry.

No action taken on this PR — content, draft state, and automation untouched.

🤖 Generated with Claude Code

Ladon verdict: Request changes

Request changes — 1 blocking finding.

The generator fix in scripts/generate-types.ts correctly splits the strict TargetingOverlay from the request-only TargetingOverlayInput, resolving real AdCP spec drift, and is well covered by new type-generator, proposal-contract, and persistence tests. Good work on the test coverage.

Blocking findings

• .changeset/fix-targeting-input-aliases.md — Changeset is typed patch but the change narrows the public TargetingOverlay export and alters TargetingOverlayInput Zod validation (a public shape/behavior change). Under the repo's mandatory changeset-vs-wire-impact rule, a changeset whose type understates a response/export-shape change is a high finding. Bump the changeset to minor.

Despite the change being a legitimate drift fix, the repo policy treats an understated changeset type as blocking. Re-run should pass once the changeset is corrected to minor.

Blocking findings

• .changeset/fix-targeting-input-aliases.md — changeset typed patch understates a public export/shape + Zod-validation change; must be minor (changeset-vs-wire-impact rule = high)

Superseded by a later Ladon review that rechecked and resolved its blocking findings.

Ladon verdict: Approve

Approve — clean resolution pass; prior blocker resolved.

The prior request-changes was driven by a changeset typed patch that understated the public targeting-type narrowing and Zod-validation change. This has been fixed: .changeset/fix-targeting-input-aliases.md is now minor, correctly reflecting the wire/contract impact. The reviewer verified the generator naming transform is non-mutating/idempotent and fail-closed, the generated core/tools/schemas deltas match intent, the example's removed resolveTargetingInput is safe behind the existing UNSUPPORTED_FEATURE rejection, and the new type/persistence/proposal tests are load-bearing.

No Critical/High/Medium findings in this run. high_risk is false, gated_paths is false, and no no-auto-approve team match. None of decision rows 1–8 fire, so the outcome falls through to row 9 (approve).

Ladon verdict: Approve

Approve — clean pass, no blocking or medium findings.

This PR splits nullable request-side targeting input aliases from strict snapshot state via an idempotent, fail-closed codegen naming transform (nameTargetingInputForCodegen/codegenRefResolvers), regenerates the committed deterministic-gated output with no wire-shape drift, removes an unreachable resolveTargetingInput call from the starter example (targeting_overlay already rejected upstream), and adds comprehensive type + runtime coverage.

Checks:

• Witness-not-translator: no fabrication or re-shaping at a seam; codegen-only naming transform with no wire-shape change.
• Changeset: present and correctly minor for a type-only correction to an unreleased rc contract.
• Transport clients: no changes under protocols/client.
• gated_paths: false; review_decision: APPROVED; no high-risk flag; no no-auto-approve team match.

No decision-table trigger fired (rows 1–8), so this falls through to row 9 = approve. Consistent with the prior approve.

Ladon verdict: Approve

Approve.

Subsequent pass on PR #2919 (targeting input/proposal snapshot contract). Reviewed the non-generated deltas: generate-types.ts (annotation-only input aliasing, fail-closed cache-only ref resolver), generate-zod-from-ts.ts (verified-cache dereferencing with HTTP/filesystem disabled, exact Zod projection mirroring the existing CanonicalProposal precedent), the seller starter, and the type/unit tests.

No mock/fallback injection, official-client usage intact, changeset present (.changeset/fix-targeting-input-aliases.md) with impact fully disclosed, coverage thorough. No new Critical/High/Medium findings; prior clean approve stands.

Decision: no findings at any tier (rows 1, 4–6, 8 do not fire). high_risk false (rows 3, 5 skip). gated_paths false (row 2 skips despite review_decision: REVIEW_REQUIRED). No no-auto-approve team match (row 7 skips). Falls through to row 9 → approve.