feat(creative): define preview rendering authority

[bokelley]

Summary

• make preview_creative support and fidelity discoverable per canonical creative capability
• add pinned, integrity-protected community reference_renderer metadata plus publisher-scoped preview_provider and presentation_ref declarations
• define and implement the presentation authority order: serving-platform preview, publisher-delegated preview, placement presentation metadata, community reference renderer, then manifest-only fallback
• return reproducible renderer audit metadata and provide representative image, native-in-feed, and safe inline-VAST previews

Reference renderer package

The community image example is pinned to the published @adcp/reference-renderers@1.0.0-beta.0 package and its exact npm integrity value. Reference renderers remain explicitly representative and cannot claim authoritative fidelity.

Safety and compatibility

• canonical preview routing uses capability IDs rather than restoring legacy named format IDs
• reference rendering accepts HTTPS assets only and emits restrictive preview markup
• inline VAST rendering does not fetch wrappers, execute interactive resources, expand macros, or fire trackers
• existing creative-library and legacy format behavior remains supported

Validation

• npm run test:schemas
• affected server unit tests: 852 passed
• pre-commit root unit tests: 1,045 passed
• npm run typecheck
• npm run test:adagents-catalog-only
• npm run test:json-schema
• npm run test:openapi
• npm run build:compliance -- --check
• node --test tests/creative-rendering-authority.test.cjs
• node scripts/check-changeset-protocol-scope.cjs origin/main
• npx --yes @changesets/cli@^3.0.0 status --since=origin/main

The repository-wide snippet sweep currently reports 25 failures outside the changed files. Every changed documentation file passes its file-specific snippet check (or contains no testable snippets). The full server pre-commit suite exceeded its 240-second local hook timeout while still progressing; the affected server tests and focused post-rebase checks pass.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS review.

This PR modifies and adds files under static/schemas/source/**, which are under a hard, deterministic approval gate (gated_paths: true). The required review status is REVIEW_REQUIRED, not APPROVED, so decision-table row 2 fires and the outcome must be escalate.

The reviewer surfaced no blocking or Medium findings: the change is an additive minor defining creative preview rendering authority (get_adcp_capabilities.creative.preview fidelity discovery, publisher-scoped preview_provider and presentation_ref on placements, pinned community reference_renderer metadata, reproducible renderer audit metadata). Schema↔docs coherence holds, the changeset type/scope is correct, and the new wire surface is covered by schema, unit, and server tests. Security hardening (HTTPS-only assets, no-referrer, tightened CSP, no VAST wrapper fetching, credential isolation) is load-bearing and sound.

Because this defines new normative protocol surface on the published schema, human ratification of the wire shape is required before merge.

Escalation reasons

• Touches gated protocol schema files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/presentation-ref.json [added], core/preview-provider.json [added], core/preview-renderer-metadata.json [added], core/reference-renderer.json [added], creative/preview-render.json, index.json, protocol/get-adcp-capabilities-response.json) with review_decision: REVIEW_REQUIRED — human/CODEOWNERS approval required to satisfy the hard approval gate.

Why human review

• Modifies/adds gated protocol schema files under static/schemas/source/** while review_decision is REVIEW_REQUIRED (not APPROVED) — hard approval gate requires human/CODEOWNERS review before merge
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated protocol schema files touched and review not yet approved.

This PR modifies/adds files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, creative/preview-render.json, index.json, protocol/get-adcp-capabilities-response.json), which fall under the repo's hard, non-overridable approval gate (gated_paths: true). The current review_decision is REVIEW_REQUIRED, not APPROVED, so decision-table row 2 fires and the outcome must be escalate.

No blocking findings were surfaced. The reviewer's delta pass on the 'decouple renderer and package versions' commit is clean: description-only refinements to the reference_renderer field, schema↔docs coherent (canonical-formats.mdx / adagents.mdx read identically to the schema), no wire-shape change (no required/type/enum/pattern change), no dist artifact touched. But a clean diff cannot lift a hard path gate — only a human/CODEOWNERS approval can.

This continues the prior escalate outcome, which persists here on the deterministic gated-paths trigger (row 2), independent of the sticky-escalation rule.

Escalation reasons

• Modifies/adds gated protocol schema files under static/schemas/source/** while review_decision is REVIEW_REQUIRED (not APPROVED). Human/CODEOWNERS approval is required before merge.

Why human review

• Touches gated protocol schema files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, creative/preview-render.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is REVIEW_REQUIRED, not APPROVED — hard approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[bokelley]

SDK/package follow-up is now open: adcontextprotocol/adcp-client#2601

It adds validated dependency-free image + image_carousel reference rendering, declared-macro expansion, an explicit asset/navigation network plan, capability-minimal iframe mounting, renderer-metadata preservation, and a pure consumer helper for the authority order defined here. It does not fetch registry metadata or dynamically load/execute registry code.

One protocol shape issue surfaced while implementing the resolver: creative.preview.fidelity currently classifies the entire supported_capability_ids set with one value, while an agent can plausibly expose both serving-platform/first-party preview routes and representative generic renderer routes. Because the set must equal every capability whose operations include preview, that mixed agent cannot describe its routes truthfully. I recommend making fidelity route-scoped before this lands, for example either:

{
  "routes": [
    { "capability_id": "platform_preview", "fidelity": "authoritative" },
    { "capability_id": "generic_preview", "fidelity": "representative" }
  ]
}

or separate authoritative_capability_ids / representative_capability_ids arrays. An aggregate shorthand could remain for homogeneous agents.

The generated SDK discovery/preview types should then be synced normally after this protocol change merges and is published. The SDK PR deliberately preserves the new renderer metadata at its compatibility boundary but does not hand-edit generated protocol types.

[bokelley]

The gap is real. A mixed agent — one exposing both a serving-platform route and a community/generic fallback — cannot emit a truthful creative.preview block under the flat fidelity shape without either misclassifying a route or omitting it from supported_capability_ids, which violates the MUST that the set equals all preview-operation capability IDs.

Implemented as a follow-up commit on this branch: the block-level fidelity stays required (homogeneous default, backward-compatible with every existing declaration in this PR), and routes[] is added as an optional per-capability override. Route-level fidelity takes precedence over the block default for named IDs; unlisted IDs inherit the block default.

Homogeneous agent — unchanged, no routes[] needed:

{
  "supported_capability_ids": ["ref_renderer_a", "ref_renderer_b"],
  "fidelity": "representative"
}

Mixed agent — serving-platform route + community fallback:

{
  "supported_capability_ids": ["platform_preview", "community_fallback"],
  "fidelity": "representative",
  "routes": [
    { "capability_id": "platform_preview", "fidelity": "authoritative" }
  ]
}

Over the XOR variant (your Option A, separate arrays in your Option B), fidelity-as-default + routes-as-override requires the smallest schema delta, keeps all existing examples valid without modification, and leaves the route record as a natural extension point for future per-capability metadata. The routes[*].capability_id verifier constraint is appended to x-adcp-validation so conformance tooling can check that listed IDs are a subset of supported_capability_ids.

The canonical-formats.mdx spec text is updated to describe both patterns. New test assertions in creative-rendering-authority.test.cjs cover the mixed-agent valid case and the invalid-enum-in-routes case; all five tests pass. The SDK PR's generated types sync normally after this merges and is published, per your note.

---

Generated by Claude Code

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated protocol schema files touched without an approving review.

This PR adds an optional routes[] per-capability fidelity override to the preview capability block, with matching docs, schema, and tests. The change is additive/optional and carries a correct minor changeset; schema↔docs coherence holds. There is one non-blocking medium finding, but the deciding factor is the hard approval gate.

Gated paths (hard approval gate): This PR modifies/adds files under static/schemas/source/** — a hard, non-overridable approval gate — while review_decision is REVIEW_REQUIRED, not APPROVED. Per decision-table row 2, the outcome must be escalate until a human/CODEOWNERS approval is recorded. Gated files include:

• static/schemas/source/adagents.json (modified)
• static/schemas/source/core/placement-definition.json (modified)
• static/schemas/source/core/presentation-ref.json (added)
• static/schemas/source/core/preview-provider.json (added)
• static/schemas/source/core/preview-renderer-metadata.json (added)
• static/schemas/source/core/reference-renderer.json (added)
• static/schemas/source/creative/preview-render.json (modified)
• static/schemas/source/index.json (modified)
• static/schemas/source/protocol/get-adcp-capabilities-response.json (modified)

Medium findings

• static/schemas/source/protocol/get-adcp-capabilities-response.json:2112 — routes[] uniqueItems permits conflicting fidelity overrides for one capability_id.

Escalation reasons

• Gated protocol schema files under static/schemas/source/** are modified while review_decision is REVIEW_REQUIRED; human/CODEOWNERS approval is required before merge.

Medium findings

• static/schemas/source/protocol/get-adcp-capabilities-response.json:2112 — routes[] uniqueItems permits conflicting fidelity overrides for one capability_id

Why human review

• Modifies/adds gated protocol schema files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, creative/preview-render.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is REVIEW_REQUIRED, not APPROVED — hard approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated protocol schema files touched without an APPROVED review.

This PR modifies/adds files under static/schemas/source/**, which are under a hard, non-overridable approval gate (gated_paths: true). The current review_decision is unknown/none — not APPROVED — so decision rule row 2 fires: the gate cannot be lifted by a clean diff. Human/CODEOWNERS approval is required before merge.

The reviewer surfaced no blocking or Medium findings in this pass (row 1 does not apply), and notably the prior Medium (routes[] permitting conflicting fidelity/rendering_origin per capability_id) is now resolved via x-adcp-validation.unique_item_properties:[capability_id] plus runtime rejection in sanitizeCreativeCapabilities. Schema↔docs coherence holds and the additive minor changeset is present and correctly scoped. This is a net improvement over the prior escalate — the escalation persists purely because the deterministic gated-path gate is not yet satisfied, not because of unresolved code issues.

Escalation reasons

• Modifies/adds gated schema files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/placement-presentation.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, core/assets/image-asset.json, creative/preview-render.json, formats/canonical/audio_hosted.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is not APPROVED — hard approval gate requires human/CODEOWNERS review.

Why human review

• Modifies/adds gated protocol schema files under static/schemas/source/** (adagents.json, core/placement-definition.json, core/placement-presentation.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, core/assets/image-asset.json, creative/preview-render.json, formats/canonical/audio_hosted.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is not APPROVED — hard, non-overridable approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/assets/image-asset.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-presentation.json (added) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/formats/canonical/audio_hosted.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated protocol schema files under static/schemas/source/** are modified/added while review_decision is not APPROVED (hard, non-overridable approval gate).

No blocking findings. The reviewer's only delta since the prior clean pass is a security hardening in server/src/creative-agent/index.ts (drops the request-controlled token param and names the temp file adcp-preview-asset-${randomUUID()} instead of interpolating req.params.id); the random path is bound to the token independently and unlinked on eviction/expiry/error — fix is complete and correct. No new findings.

Why escalate (row 2): This PR touches 12 files under static/schemas/source/** (a deterministic gated path). gated_paths: true AND review_decision ≠ APPROVED requires human/CODEOWNERS approval before merge. Ladon cannot auto-approve regardless of how clean the diff is.

Escalation reasons:

• Gated protocol schema files under static/schemas/source/** are added/modified (adagents.json, core/placement-definition.json, core/placement-presentation.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, core/assets/image-asset.json, creative/preview-render.json, formats/canonical/audio_hosted.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is unknown/not APPROVED — human/CODEOWNERS review required.

Once a real GitHub/CODEOWNERS approval is recorded, this PR (with no blocking findings) would fall through to approve.

Why human review

• Gated protocol schema files under static/schemas/source/** are added/modified (adagents.json, core/placement-definition.json, core/placement-presentation.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, core/assets/image-asset.json, creative/preview-render.json, formats/canonical/audio_hosted.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is not APPROVED — hard, non-overridable approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/assets/image-asset.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-presentation.json (added) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/formats/canonical/audio_hosted.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated protocol schema files touched without an APPROVED review.

This PR modifies/adds files under static/schemas/source/**, which is a hard, non-overridable approval gate (gated_paths: true). The current review_decision is unknown/none, not APPROVED, so decision-table row 2 fires: the gate is not satisfied and Ladon cannot auto-approve regardless of how clean the diff is. Human/CODEOWNERS review is required.

The reviewer surfaced no critical, high, or medium findings — the change is described as additive and clean (per-scenario schema constraints correct, storyboard context paths resolve to real schema fields, error codes defined, minor changeset matches the additive wire change). Absent any blocking findings, this is not request-changes; it stays escalate purely on the unsatisfied gated-path gate (consistent with the prior escalate on this PR).

Gated files requiring human/CODEOWNERS approval:

• static/schemas/source/adagents.json (modified)
• static/schemas/source/core/assets/image-asset.json (modified)
• static/schemas/source/core/placement-definition.json (modified)
• static/schemas/source/core/placement-presentation.json (added)
• static/schemas/source/core/presentation-ref.json (added)
• static/schemas/source/core/preview-provider.json (added)
• static/schemas/source/core/preview-renderer-metadata.json (added)
• static/schemas/source/core/reference-renderer.json (added)
• static/schemas/source/creative/preview-render.json (modified)
• static/schemas/source/formats/canonical/audio_hosted.json (modified)
• static/schemas/source/index.json (modified)
• static/schemas/source/protocol/get-adcp-capabilities-response.json (modified)

Once a human/CODEOWNERS approval is recorded (review_decision: APPROVED), this PR can fall through to a normal approve on the next pass given no blocking findings.

Why human review

• Gated paths under static/schemas/source/** are added/modified (adagents.json, core/placement-definition.json, core/placement-presentation.json, core/presentation-ref.json, core/preview-provider.json, core/preview-renderer-metadata.json, core/reference-renderer.json, core/assets/image-asset.json, creative/preview-render.json, formats/canonical/audio_hosted.json, index.json, protocol/get-adcp-capabilities-response.json) while review_decision is not APPROVED — hard, non-overridable approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/adagents.json (modified) matches static/schemas/source/**; static/schemas/source/core/assets/image-asset.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-definition.json (modified) matches static/schemas/source/**; static/schemas/source/core/placement-presentation.json (added) matches static/schemas/source/**; static/schemas/source/core/presentation-ref.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-provider.json (added) matches static/schemas/source/**; static/schemas/source/core/preview-renderer-metadata.json (added) matches static/schemas/source/**; static/schemas/source/core/reference-renderer.json (added) matches static/schemas/source/**; static/schemas/source/creative/preview-render.json (modified) matches static/schemas/source/**; static/schemas/source/formats/canonical/audio_hosted.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.