Public 3.2 leaf schemas accept protocol-invalid bidding and allocation values

[bokelley]

Version

@adcp/sdk@14.0.0-beta.1 (ADCP_VERSION is 3.2.0-beta.0)

Problem

The runtime schemas exported from @adcp/sdk/schemas are substantially weaker than the 3.2 contract they represent. In particular, BiddingPolicySchema accepts empty policies, negative monetary values, and combinations that the protocol says MUST be rejected. CanonicalBudgetAllocationSchema accepts an empty optimization_goals array for seller_optimized allocation.

This prevents adopters from retiring local 3.2 validators in favor of the SDK schemas without losing correctness.

Reproduction

import {
  BiddingPolicySchema,
  CanonicalBudgetAllocationSchema,
} from '@adcp/sdk/schemas'

for (const value of [
  {},
  { automatic: true, max_bid: 1 },
  { bid_amount: 1, max_bid: 2 },
  { bid_amount: -1 },
  {
    cost_per: { amount: 1, strength: 'cap' },
    roas: { value: 2, strength: 'target' },
  },
]) {
  console.log(BiddingPolicySchema.safeParse(value).success)
}

console.log(
  CanonicalBudgetAllocationSchema.safeParse({
    mode: 'seller_optimized',
    optimization_goals: [],
  }).success,
)

On beta.1 every result is true.

The generated declarations also expose these as loose objects (z.core.$loose), so arbitrary keys are accepted as well.

Expected

The SDK's public runtime schemas should enforce the normative constraints encoded by the 3.2 schemas/protocol, including at least:

• positive monetary values;
• a non-empty bidding policy;
• automatic as the only field when present;
• bid_amount exclusivity relative to max_bid, cost_per, and roas;
• cost_per / roas exclusivity;
• non-empty seller_optimized.optimization_goals; and
• the relevant nested cross-field rules (for example campaign duration and required custom event names).

If the generated structural schemas intentionally cannot provide semantic validation, the package should export a clearly named strict/semantic validation surface and document that the generated schemas are not safe protocol admission validators. Ideally server request validation and public leaf-schema validation should share the same refinements so they cannot drift.

Adoption impact

We currently maintain a quarantined repo-owned copy of these validators while preparing 3.2 support. The SDK now exports the desired types and shapes, but replacing the local runtime boundary with these schemas would admit invalid requests before provider mutation. This is therefore a blocker to retiring that compatibility work.

[bokelley]

Triage

Classification: Bug — codegen fidelity gap; generated Zod schemas drop normative MUST constraints from the 3.2 JSON Schema source
Bucket(s): library (schema generation + public export pipeline)
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: All five constraint classes (positive monetary values, automatic exclusivity, bid_amount/max_bid/cost_per/roas mutual exclusivity, non-empty optimization_goals) are normative — they appear in conformance storyboards that the grader designates as normative. z.core.$loose is a codegen artifact, not an intentional design choice (ext is the protocol's actual extensibility valve). The function injectJsdocConstraints exists in schema-utils.ts to recover constraints lost in the TS→Zod path; the JSON Schema→Zod path never calls it and json-schema-to-zod silently drops oneOf discriminators. Tightening is non-breaking even outside beta — any caller that passes a rejected combination was already sending a protocol-invalid wire request.
• code-reviewer: The SyncCreativesItemSchema in src/lib/validation/sync-creatives.ts is an established pattern for exactly this: a hand-authored .passthrough().superRefine() wrapper that shadows a generated schema via a named re-export in src/lib/schemas/index.ts. The generator cannot close this gap (json-schema-to-zod does not convert oneOf to z.discriminatedUnion()). Scope is 6–10 schemas; BiddingPolicy and CanonicalBudgetAllocation are the most load-bearing. Note: use .passthrough().superRefine() — not .strict() — to preserve ext field passthrough.

My take: Both experts agree on the mechanism, the fix pattern, and the non-breaking status. The right approach is hand-authored .passthrough().superRefine() refinement files (mirroring sync-creatives.ts) wired into src/lib/schemas/index.ts as shadowing named exports — the generator phase cannot emit these constraints automatically so they must be maintained separately. A deeper generator fix (adding oneOf → z.discriminatedUnion() translation or calling injectJsdocConstraints in the Zod path) would close the systematic gap long-term but is out of scope for the unblocking fix the reporter needs.

Implementation scope:

• Create src/lib/validation/bidding-policy.ts — export BiddingPolicySchema as a .passthrough().superRefine() refinement of the generated schema enforcing: (1) at least one field present, (2) automatic is sole field when present, (3) bid_amount exclusive vs max_bid/cost_per/roas, (4) cost_per exclusive vs roas, (5) positive monetary values (bid_amount, max_bid, and cost_per.amount if present)
• Create src/lib/validation/budget-allocation.ts — export CanonicalBudgetAllocationSchema enforcing non-empty optimization_goals when mode === 'seller_optimized'
• Update src/lib/schemas/index.ts — add named re-exports of the refined schemas after the export * line (same pattern as SyncCreativesItemSchema / SyncCreativesResponseStrictSchema)
• Add unit tests for the rejection cases in the reproduction script
• Run npm run ci:quick and npm run ci:schema-check; create a patch changeset

Non-breaking rationale: Valid data passes through .superRefine() unchanged. Protocol-invalid combinations (the reported cases) were already rejected at wire time by conformant sellers — tightening the SDK schema makes that rejection happen earlier and more explicitly.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01Rc4uGDUx3WtMaerhV3xktA

---

Generated by Claude Code

[bokelley]

Here is the concrete semantic refinement we have been carrying locally, adapted for the SDK's passthrough policy. The important distinction from copying our local validator verbatim is that this keeps generated unknown-field behavior while requiring at least one recognized bidding control.

import { z } from 'zod'
import {
  BiddingPolicySchema as GeneratedBiddingPolicySchema,
  CanonicalBudgetAllocationSchema as GeneratedCanonicalBudgetAllocationSchema,
} from '../types/schemas.generated'

const biddingControlKeys = [
  'automatic',
  'bid_amount',
  'max_bid',
  'cost_per',
  'roas',
] as const

export const BiddingPolicySchema =
  GeneratedBiddingPolicySchema.superRefine((policy, ctx) => {
    const presentControls = biddingControlKeys.filter(
      (key) => policy[key] !== undefined,
    )

    if (presentControls.length === 0) {
      ctx.addIssue({
        code: 'custom',
        message: 'bidding policy must contain at least one bidding control',
      })
    }

    if (policy.automatic === true && presentControls.length !== 1) {
      ctx.addIssue({
        code: 'custom',
        path: ['automatic'],
        message: 'automatic must be the only bidding control',
      })
    }

    for (const [path, value] of [
      [['bid_amount'], policy.bid_amount],
      [['max_bid'], policy.max_bid],
      [['cost_per', 'amount'], policy.cost_per?.amount],
      [['roas', 'value'], policy.roas?.value],
    ] as const) {
      if (value !== undefined && value <= 0) {
        ctx.addIssue({
          code: 'custom',
          path: [...path],
          message: 'must be greater than zero',
        })
      }
    }

    if (
      policy.bid_amount !== undefined &&
      (policy.max_bid !== undefined ||
        policy.cost_per !== undefined ||
        policy.roas !== undefined)
    ) {
      ctx.addIssue({
        code: 'custom',
        path: ['bid_amount'],
        message:
          'bid_amount cannot be combined with max_bid, cost_per, or roas',
      })
    }

    if (policy.cost_per !== undefined && policy.roas !== undefined) {
      ctx.addIssue({
        code: 'custom',
        path: ['roas'],
        message: 'cost_per and roas cannot be combined',
      })
    }
  })

export const CanonicalBudgetAllocationSchema =
  GeneratedCanonicalBudgetAllocationSchema.superRefine((allocation, ctx) => {
    if (
      allocation.mode === 'seller_optimized' &&
      allocation.optimization_goals.length === 0
    ) {
      ctx.addIssue({
        code: 'custom',
        path: ['optimization_goals'],
        message:
          'seller_optimized allocation requires at least one optimization goal',
      })
    }
  })

Suggested tests should cover the reproduction cases in the issue plus two passthrough-specific cases:

• an object containing only an unknown property still fails because it has no recognized bidding control;
• a valid recognized control plus an unknown property preserves the unknown property, matching the generated schema's compatibility behavior.

One nuance: max_bid combined with cost_per or roas is capability-dependent according to the protocol text, so the context-free leaf schema should not reject that combination. That validation belongs at the media-buy/package admission layer where the relevant advertised capability is available.

This is the portion we can upstream and then delete locally. Our surrounding media-buy intent schema remains application-owned because it adds persistence identity and authored-form provenance rather than wire-contract validation.

[bokelley]

Beta.8 closes the semantic-validation gap, and the stricter public schema is working as intended. One consumer migration implication is worth documenting: exported object schemas that now carry .superRefine() checks can no longer be composed with Zod's .extend().

For example, a consumer that extracts the object and adds application-owned fields now fails during module import:

Error: Object schemas containing refinements cannot be extended. Use `.safeExtend()` instead.

The mechanical migration is to use .safeExtend() for SDK-derived object schemas (including after .partial() where appropriate). We found this on CreativeAssetSchema; the same precaution applies to other refined public leaf schemas.

This is not a request to remove the refinements. A short note in the SDK 13→14 migration guide would prevent an otherwise surprising boot-time failure for adopters that compose the exported schemas.