feat(v2): prototype v2 → v1 Product projection layer

[bokelley]

Draft. Companion to PR #1809 (8.0 design proposal). This implements and stress-tests the v2 → v1 projection layer the design proposes — to see if the "v2-only public API, project to v1 at the boundary" stance is actually operable today.

What it does

Takes a V2 Product (with format_options[]) and produces a v1 Product (with format_ids[]) suitable for sending to a v1-only seller. The resolution order mirrors v1-canonical-mapping.json, inverted:

Step	Path	Outcome
1	format_kind: "custom" + canonical_formats_only: true	No v1 emit. FORMAT_DECLARATION_V1_UNREACHABLE diagnostic.
2	v1_format_ref present on the declaration	Use verbatim (seller-asserted equivalence — highest confidence).
3	Registry reverse-lookup finds an invertible literal entry	Synthesize a v1 format_id.
4	Registry has entries but none invert (wildcarded / structural)	No v1 emit. FORMAT_DECLARATION_V1_AMBIGUOUS diagnostic.
5	Registry has no entries for this canonical	No v1 emit. FORMAT_DECLARATION_V1_UNREACHABLE diagnostic.

All diagnostics on a structured channel — never logger-only, per the spec's resolution-order amendment.

Coverage against 13 spec reference fixtures

Vendored from adcontextprotocol/adcp#3307 static/examples/products/canonical/. The fixtures span 12 of the 13 canonical format_kinds.

=== v2 → v1 projection coverage (13 spec fixtures) ===

Clean v1 emit (1/13):
  ✓ nytimes_homepage_mrec

Explicit canonical_formats_only opt-out (1):
  ✗ nytimes_homepage_takeover_custom (custom)

Ambiguous registry match — family exists but not invertible (7):
  ? gam_3p_display_tag (display_tag)
  ? meta_reels_us (video_hosted)
  ? nytimes_homepage_html5 (html5)
  ? the_daily_30s_host_read (audio_hosted)
  ? triton_daast_audio_30s (audio_daast)
  ? veo_generative_video_15s (video_hosted)
  ? youtube_vast_preroll (video_vast)

No registry entry for the canonical (4):
  ✗ amazon_sponsored_products (sponsored_placement)
  ✗ chatgpt_brand_mention (agent_placement)
  ✗ google_performance_max (responsive_creative)
  ✗ meta_carousel (image_carousel)

Headline findings

1. Only 8% of v2 fixtures project cleanly without seller intervention

92% of the spec's own reference fixtures can't be downgraded today. Implications for the 8.0 design:

• The "V2-only public API, projection at the boundary" stance still works — products that can't downgrade surface via diagnostics; the v1 buyer doesn't see them. Honest.
• But the "make v1 sellers look V2-shaped" promise depends on sellers actively adding v1_format_ref to their declarations. The current spec reference fixtures don't model this — none of them carry v1_format_ref.
• 4 of the 13 canonicals (sponsored_placement, agent_placement, responsive_creative, image_carousel) are genuinely new concepts in v2 with no v1 form possible. Those products simply won't exist on the v1 wire — and that's correct.

2. The registry's IAB-named entries produce wire-invalid format_ids

The only fixture that projects cleanly (nytimes_homepage_mrec) synthesizes format_id.id: "iab/mrec_300x250" — but format-id.json requires ^[a-zA-Z0-9_-]+$, which rejects slashes. Same cross-schema mismatch we flagged upstream when surveying the registry earlier. The clean-emit path itself currently produces wire-invalid output. The projection layer surfaces this rather than papering over it.

3. Registry needs an explicit "v1-unreachable" signal per canonical

Four canonicals (sponsored_placement, agent_placement, responsive_creative, image_carousel) have NO registry entries. The projection emits reason: "no_v1_format_ref_or_registry_match" — but really, the spec could declare these canonicals as inherently v1-unreachable, the same way canonical_formats_only: true declares per-product unreachability. Would let adopters distinguish "spec says no v1 form exists for this canonical" from "spec hasn't filled in this entry yet."

What's in scope vs not

In scope (this PR):

• src/lib/v2/projection/{types,registry,v2-to-v1}.ts — projection module.
• test/lib/v2-to-v1-projection.test.js — 16 cases across 4 suites.
• Vendored fixtures at test/lib/v2-projection-fixtures/.
• Diagnostic surface (typed).
• Hand-rolled TypeScript types matching schema shape at projection precision.

Explicit non-scope:

• v1 → v2 (upgrade) direction — symmetric counterpart, follow-up.
• Full versioned codegen — separate piece of the 8.0 enablement; types here are minimal hand-rolls.
• Public barrel export — projection is internal-only until auto-negotiation lands.
• Auto-negotiation per agent — design-doc territory; not implemented here.
• fetchFormatSchema for custom shapes — separate piece.

Test plan

• Typecheck clean.
• All 16 test cases pass (4 suites: per-fixture verdict, opt-out, IAB image, ecosystem coverage).
• npm run format:check clean (vendored fixtures added to .prettierignore per the same rule as webhook-signing-vectors/).
• Structural invariant verified for every fixture: format_ids.length + diagnostics.length === format_options.length.
• CI green.

Reviewer focus

Treat this as a design-prototype PR, not a feature PR. The key questions:

1. Does the projection algorithm produce honest output for the messy fixtures? (Read the coverage report.)
2. Are the diagnostic codes (FORMAT_DECLARATION_V1_UNREACHABLE, FORMAT_DECLARATION_V1_AMBIGUOUS) the right vocabulary, or should they unify?
3. Does this confirm the 8.0 design (PR docs(development): draft 8.0 design proposal for AdCP 3.1 support #1809) is workable, or does it surface a flaw?

🤖 Generated with Claude Code

[bokelley]

Re-run after upstream landed all five asks

Upstream adcontextprotocol/adcp committed all five spec changes the prototype surfaced. Re-synced the local 3.1.0-beta cache and updated the projection layer to honor the new normative rules. Pushed at `61e043f6`.

What landed upstream:

• `v1_translatable` boolean on `_base.json` (default true) with overrides on the 4 inherently-v2 canonicals (`image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`). MUST NOT emit `FORMAT_PROJECTION_FAILED` on these.
• New error code `FORMAT_DECLARATION_V1_AMBIGUOUS` with full normative prose + drift disposition + `errors[]` augmentation contract.
• Direction-of-truth statement: registry is v1→v2 authoritative only.
• Resolution-order step 5 (ambiguous family) before fail-closed.
• `v1_format_ref` added to 2 reference fixtures (`nytimes_homepage_mrec` → `iab_mrec_300x250`, `triton_daast_audio_30s` → `daast_audio_30s_v1_1`).
• "SDKs MUST NOT synthesize v1_format_ref" rule (best-effort literal-glob inversion is MAY-do but non-normative).
• Bonus: IAB-named registry globs respelled with underscores. Closes the wire-validity cross-schema mismatch.

Coverage post-upstream-fixes (13 spec fixtures):

Bucket	Pre-fix	Post-fix
Clean via `v1_format_ref` (normative)	0	2
Clean via registry synthesis (non-normative)	1	0
`canonical_formats_only` opt-out	1	1
Inherently v2 (`v1_translatable: false`)	n/a (conflated)	4
Ambiguous family	7	6
Registry-coverage gap	4	0

The spec fixes did real work: the four inherently-v2 canonicals are now correctly separated from registry gaps; the registry covers every v1_translatable canonical the fixture set exercises; the two seller-annotated fixtures project cleanly via the normative path.

SDK changes in this commit:

• New `src/lib/v2/projection/canonical-properties.ts` reads `v1_translatable` from the canonical schemas with `_base.json` inheritance.
• `v2-to-v1.ts` gains a canonical-level check before the seller-asserted `v1_format_ref` step.
• Diagnostic shape updated to spec's `errors[]` augmentation contract (`source: "sdk"`, `sdk_id`, `field`, `error.details`).
• Diagnostic codes split into 4 buckets: 2 spec codes (`FORMAT_PROJECTION_FAILED`, `FORMAT_DECLARATION_V1_AMBIGUOUS`) + 2 SDK-local (`FORMAT_DECLARATION_V1_NOT_APPLICABLE`, `CANONICAL_NOT_V1_TRANSLATABLE`).

Tests: 21 pass across 5 suites. New invariants assert every diagnostic carries spec-mandated `source` + `sdk_id`.

The remaining 6 ambiguous-family fixtures (display_tag, video_hosted ×2, html5, audio_hosted, video_vast) need sellers to add `v1_format_ref` to project cleanly. That's the expected migration pattern — the upstream-added fixtures (mrec + daast) now model it.

[bokelley]

Post-reconciliation: 7/13 project cleanly. Zero ambiguous, zero gaps.

Upstream landed the registry↔catalog↔fixtures reconciliation (`03e10e83`):

• Registry: 13 IAB-prefixed entries → 17 catalog-actual entries (8 image sizes + 2 html5 + display_js + video_vast family + audio_standard ×3 + video_standard ×2 + meta_reels).
• AAO catalog: 32 entries gained `canonical` annotations (image, html5, display_tag, video_hosted, video_vast, audio_hosted, sponsored_placement).
• 5 fixtures now carry `v1_format_ref` pointing at real catalog ids; triton_daast moved to `canonical_formats_only: true` since the catalog has no DAAST entry yet.

Coverage shifted dramatically:

Bucket	Round 1	Round 2 (v1_translatable)	Round 3 (reconciliation)
Clean via `v1_format_ref` (NORMATIVE)	0	2	5
Clean via registry synthesis (NON-NORMATIVE)	1	0	2
`canonical_formats_only` opt-out	1	1	2
Inherently v2 (`v1_translatable: false`)	n/a	4	4
Ambiguous family	7	6	0
Registry-coverage gap	4	0	0
Clean total	1 (8%)	2 (15%)	7 (54%)

The remaining 6 are inherently v1-unreachable by design — 4 v2-only canonicals and 2 explicit opt-outs. They SHOULDN'T project; the SDK correctly emits structured diagnostics. Every fixture in the prior "ambiguous" bucket either got `v1_format_ref` (4) or now synthesizes via the new literal registry entries (2).

The convergence pattern works

Of the 5 seller-asserted projections:

• 4 point at the AAO canonical agent_url `creative.adcontextprotocol.org/` with catalog ids: `display_300x250_image`, `display_300x250_html`, `display_js`, `video_vast_30s`. Same canonical shape across N publishers produces the SAME format_id — convergent, not divergent. Solves the per-publisher format-id sprawl concern.
• 1 points at the publisher-specific agent_url (`meta.adcp/meta_reels`) because Meta Reels is a proprietary format with no IAB-standard equivalent.

This is exactly the pattern the spec now models: converge on AAO ids for industry-standard formats; keep publisher namespacing for proprietary platforms.

SDK changes in `03e10e83`

• Step 1 (`canonical_formats_only`) broadened to apply to any format_kind, not just `custom`. The 3.1 spec uses it on `audio_daast` (triton_daast) as a "no v1 form yet" signal.
• Synthesized agent_url uses `creative.adcontextprotocol.org/` (trailing slash) to match upstream's canonicalized form.
• Tests updated: 25 pass, including round-trips against all 5 seller-asserted fixtures and structural-invariant assertions for all 13.

What this leaves us

The v2 → v1 projection prototype is essentially complete for the 3.1 reference fixture set. The remaining work is:

1. v1 → v2 projection (the upgrade direction) — symmetric counterpart, not yet implemented.
2. Wire into auto-negotiation — projection layer is internal-only until the per-agent negotiation surface from PR docs(development): draft 8.0 design proposal for AdCP 3.1 support #1809 lands.
3. Versioned codegen — separate piece of the 8.0 enablement; current types are hand-rolled.

The honest design takeaway: the 8.0 "v2-only public API, project at the boundary" stance works for ~54% of products today (the realistic ceiling once 4 inherently-v2 canonicals + opt-outs are accounted for, it's actually 7/7 = 100% of projectable products). The adoption curve depends on sellers annotating `v1_format_ref` on their declarations — which the upstream reference fixtures now demonstrate.

[bokelley]

v1 → v2 projection landed (`c3a7d84d`)

Symmetric counterpart to v2 → v1. The 8.0 design's "V2-only public API" needs both directions; v1 → v2 is the practically more valuable one today because most inventory in the wild speaks v1, and this is what makes V2-written buyers see v1 sellers as V2.

Coverage: 57/57 catalog entries land in a precise bucket

Bucket	Count	What it means
Step 1 — NORMATIVE clean projection	32/57 (56%)	Catalog entry has explicit `canonical:` annotation. Image, html5, display_tag, video_hosted, video_vast, audio_hosted, sponsored_placement.
`catalog_lacks_canonical_annotation`	25/57 (44%)	AAO catalog knows the format but hasn't blessed a v2 canonical yet. Symmetric to `v1_translatable: false` on the v2 side. Native, DOOH, broadcast, generative, card-scaffolding.
`no_match`	0/57	Every catalog entry either projects cleanly or surfaces a precise reason.

Resolution order

1. Catalog entry with `canonical:` annotation → use it (NORMATIVE).
2. Catalog entry without `canonical:` → fail-closed with `catalog_lacks_canonical_annotation`. Don't shoehorn. The AAO's deliberate absence of annotation is the spec saying "no v2 form yet for this category" — same intent as `v1_translatable: false` on the v2 side.
3. Not in catalog → registry glob match.
4. No registry hit but catalog provides assets → structural match (only fires for non-catalog ids).
5. Fail-closed with `no_match`.

Key design call: refused to shoehorn

First-pass let structural-match catch everything. Produced semantically-wrong projections — DOOH billboards → `display_tag`, native mentions → `display_tag`, AI-generative banners → `display_tag`. All because the registry's `url` structural entry matches any format with a tracking url.

The right call: when the AAO catalog explicitly knows about a format but hasn't annotated it, the SDK respects that silence. Fail-closed with a distinct diagnostic so buyers see "category not yet v2-mapped" rather than a wrong canonical that misroutes downstream creative submission flows.

This mirrors the spec's stance on `v1_translatable: false` (v2 → v1 direction): the spec is explicit about "no v1 form possible"; the SDK respects it. Now the v1 → v2 direction has the same honesty principle.

Scope (deliberate prototype gaps)

• AAO catalog only. Seller-specific catalogs (publisher's own `list_creative_formats`) deferred to the auto-negotiation surface that PR docs(development): draft 8.0 design proposal for AdCP 3.1 support #1809 proposes.
• Param extraction is dimensions + duration only. Full canonical-specific params (slots, codecs, char limits, platform_extensions) deferred.
• Asset-slot translation deferred. v1 `assets[]` → v2 `slots[]` via the `asset_group_vocabulary` aliases is the most adopter-relevant piece for actual creative submission and lands in a follow-up. The projection here only produces `format_kind` + `params` + `v1_format_ref`; `slots` come from the canonical's base shape.

Symmetric story across both directions

Direction	Clean projections	Honest fail-closed	What it enables
v2 → v1	7/13 (54%)	6/13	V2 buyers writing to v1-only sellers. Limited by what sellers annotate as `v1_format_ref`.
v1 → v2	32/57 (56%)	25/57	V2 buyers reading v1 sellers' existing inventory as V2. Limited by what the AAO catalog annotates.

Same pattern: high signal on the annotated subset, honest fail-closed for the un-annotated tail.

Upstream observation worth filing

The 25 un-annotated catalog entries cluster into 5 categories that all need v2-canonical decisions:

• Generative variants (8 entries) — display_*_generative are parameterized AI-generation formats. Could be a new canonical `display_generative` or extend `html5` with a `generative: true` mode.
• Native (3 entries: native_standard, native_content, native_mention) — native ads have their own structural shape. Worth a `native` canonical, or `native_mention` could project to `agent_placement`.
• DOOH (4 entries: dooh_billboard_*, dooh_transit_screen) — out-of-home is structurally different from display. Needs a `dooh` canonical.
• Broadcast (3 entries: broadcast_spot_15s/30s/60s) — broadcast TV could be `video_hosted` with a `channel: linear_tv` parameter, or its own canonical.
• Card scaffolding (7 entries: product_card_, format_card_, proposal_card_*, native_product_card) — these aren't ad formats, they're UI scaffolding for browsing. Probably shouldn't be in `reference-formats.json` at all; maybe move to a separate UI-scaffolding registry.

Worth filing as five separate roadmap items for the canonicals catalog beyond 3.1.

Tests

30 cases across both projection directions. Skip-in-CI pattern with the clear reason marker — same as the v2 → v1 tests.

[bokelley]

Reconciled with publisher-scoped catalog (`9b312cc2`)

Upstream restructured the format-discovery model — registry shrank to 7 pure-structural fallbacks, literal globs moved into per-publisher `adagents.json#/formats` declarations, AAO community mirror tier at `mirror.adcontextprotocol.org/translated/` handles publishers who haven't adopted (Meta uses it now with full Reels + Feed + Stories + WhatsApp coverage).

Catalog grew 9 new annotations — including 2 that match my prior roadmap suggestions:

• `display_*_generative` (×8) → `image` — parameterized AI generators that produce image output (vs my earlier `display_tag` shoehorning attempt, which was wrong)
• `native_mention` → `agent_placement` — exact match for my proposal

Updated coverage report

Bucket	Round 3	Round 4 (now)
Step 1 NORMATIVE clean	32/57 (56%)	41/57 (72%)
catalog_lacks_canonical_annotation	25/57	16/57
no_match	0/57	0/57

The remaining 16 un-annotated entries cluster into the 3 categories that still need v2 canonical decisions:

• 3 broadcast_spot (15s/30s/60s) — broadcast linear TV
• 2 native (`native_standard`, `native_content`)
• 4 dooh (`dooh_billboard_*`, `dooh_transit_screen`)
• 7 cards (`product_card_`, `format_card_`, `proposal_card_*`, `native_product_card`) — these are UI scaffolding, probably shouldn't be in the format catalog at all

SDK code unchanged

The architectural shift is transparent to the projection layer at the prototype's scope:

• v2 → v1 uses `v1_format_ref` verbatim; the agent_url change to the community mirror is opaque to the SDK.
• v1 → v2 reads catalog `canonical:` annotations; the source-of-truth shift from registry to publisher catalog doesn't change the SDK code path.

The literal-glob registry shrinkage means the SDK's `forwardLookupByGlob` never fires for catalog-known formats at 3.1 GA — but the function stays in place for forward-compat (the registry MAY grow literal entries again).

What the full 8.0 enablement still owes

The publisher-scoped catalog opens up real adopter value that the prototype doesn't yet deliver:

1. Loading `adagents.json#/formats` for publishers we encounter (with `property_id`/`property_tag` scoping). Today we only load the AAO catalog.
2. Resolving `capability_id` references between `placement.format_options[]` and `adagents.formats[]`.
3. Fetching at the auto-negotiation boundary, not at projection time — projection should be sync; the AgentClient should populate the per-agent catalog cache on first contact.

These are real 8.0 work items, not projection-prototype scope. The projection layer is now structurally correct for the new world; the data sources just need to grow.

Tests

30 pass across 9 suites in both directions. Skip-in-CI pattern preserved. Meta Reels test updated to the community-mirror agent_url; registry-literal-fallback test reframed as publisher-bespoke-fail-closed.