[numarasSigmaSoftware]

feat(creative): add signed creative addons for AdCP 3.3

Related: #6700. Implements the proposed decision addendum.

Draft for WG review. WG approval is pending. This PR requests reconsideration of the 3.4 deferral for the complete feature in 3.3. It records no release-scope approval or signing-profile approval and must remain draft while those decisions are pending.

Proposed behavior

The Sales Agent assembles operator-registered addons adjacent to an unchanged buyer creative. Vendors receive creative context without the buyer payload. Image, HTML5, and display-tag routes support live vendor calls and static references, including seller first-party loaders. Required failures block the affected delivery under finite original deadlines; best-effort omissions are recorded.

Each immutable served variant carries a mandatory signed addon chain. This specification PR includes the schemas, normative documentation, deterministic vectors, and reference tests. The existing training-server replay-protection registry and preview-specialism catalog are synchronized with the new protocol entries. Seller runtime implementation and deployed seller/buyer interoperability remain separate release-readiness work.

Purchase-path restrictions

The seller must atomically verify that the complete addon configuration seen by the buyer still applies when spend is committed.

Purchase path	Requirement
Proposal negotiation → accept_proposal	Complete resolved creative_addons is part of commercial_terms.purchases[] and covered by terms_digest. Changed configuration requires a successor proposal; stale acceptance returns TERMS_REJECTED before commitment.
list_products → buy_products	The feed must be resolved for the authenticated account. feed_version identifies the complete immutable disclosure and changes when effective addon rules change. Stale purchase returns TERMS_REJECTED. Global or partial feeds cannot bind account-specific addon rules.
Legacy create_media_buy / update_media_buy, or any other unbound path	Addon-enabled spend commitments return UNSUPPORTED_FEATURE before mutation. Supporting these paths later requires an explicitly reviewed binding.

The restriction also covers amendments that add or change addon-enabled delivery obligations. Ordinary transactions outside negotiated addon support, cancellation, and other non-spend operations keep their existing contracts. A prior get_products or sync_accounts read alone establishes no commitment-time freshness. Complete disclosure overrides field projection for directly purchasable addon-enabled offers. This proposal adds no buyer-echoed configuration token.

Post-purchase change policy

Publisher authority continues after purchase. The seller may change its execution configuration after commitment. The accepted snapshot records what was disclosed at purchase; the binding does not freeze the addon set for the duration of the buy.

The seller must retain that accepted snapshot and the actual configuration of each execution. A changed configuration produces a distinct immutable variant with its own signed chain. Later changes cannot overwrite historical evidence. Buyers may decline before commitment; the feature supplies no runtime instruction to disable, substitute, or reorder seller-required addons. Code outside this addon mechanism remains outside the disclosure completeness claim.

Signing proposal requiring human approval

adcp/addon-chain/v1 uses flattened JWS, Ed25519 (alg: EdDSA), and JCS canonical payloads. A dedicated adcp_use: addon-chain-signing key is resolved through supported 3.x agent identity/JWKS discovery and applicable publisher pins. Transport-signing key material remains separate.

The signature binds the unchanged creative fingerprint, ordered chain, actual configuration, and delivery identifiers. Verification enforces both agent and publisher revocation. Historical verification after revocation requires trusted pre-revocation observation of the exact signed record and its then-valid authority evidence; a self-asserted old iat is insufficient.

The signature attributes the seller's assembly claim. Independent browser execution and measurement accuracy are outside that claim. Loader hashes cover the loader, with no promise that subsequently fetched remote code is immutable.

DR-0023 schedules broader JWS document-signing work for 3.4. This bounded 3.3 use and its dedicated key purpose need an explicit human decision. This PR leaves Web Bot Auth behavior unchanged.

Validation

Merged upstream main 867fdce46a171bad69be18ce38b557276b6594bd and resolved five file conflicts in 36625d343. The PR remains within its original 46-file scope. The merge preserves upstream account-request tools and the withdrawal of definition pins, purchase rights, and installment selection from 3.3, alongside the addon proposal's existing purchase and signing rules.

• Schema generation, compliance checks, and changeset checks pass. All 386 schema-tagged documentation examples pass.
• The complete npm run test:schemas command passes: 36 schema-validation checks, 1,167 contract/vector tests, 10 premium-display tests, and 6 geographic-targeting tests.
• The focused schema/projection suite passes 66 of 67 tests. The remaining test stops at the overall projection-size limit; independent measurement also confirms that the controller exceeds its parity-compilation allowance. Both limits remain unchanged.
• The normal precommit hook passes: 1,282 root tests, the full 829-file server suite, and type checking. One unrelated exact-inference test failed under parallel load and passed the hook's automatic isolated rerun, with no assertion or timeout changes.
• Normal pre-push checks pass, including all 58 navigation checks after refreshing the local stable-release reference.

Size guard	Unchanged main	With addon proposal	Current allowance
Complete MCP schema projection	24,022,812 bytes	24,129,636 bytes	24,117,248 bytes (23 MiB)
Controller schema parity compilation	1,383,804 bytes	1,386,653 bytes	1,384,000 bytes

The proposal adds 106,824 bytes to the complete projection and 2,849 bytes to the controller projection. The media-buy model-context size check now passes against current main. Resolving the remaining size guards needs a separate decision; this conflict-resolution update neither raises the allowances nor removes fixture validation. These measurements supersede the October 26 validation figures.

A complete npm test run has not been performed on this merge. The local storyboard matrix remains advisory and is deferred to authoritative CI. Required CI results and human reviews remain merge gates; WG release-scope/signing approval and named seller/buyer interoperability evidence remain pending.

Pending decisions and release gates

• WG approves reconsideration of the full feature for 3.3.
• Human trust review approves the signing profile and records its relationship to DR-0023.
• WG accepts the supported purchase bindings and the post-purchase change policy above.
• Named seller and buyer partners demonstrate assembly and verification against exact versions.
• Required repository checks and human reviews pass before merge.

Proposed decision: normative; status: pending; record number: unassigned. This PR supplies evidence for WG review of #6700.

Prepared with Codex.

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 36625d3.

Approve preview

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths touched without an approving review.

This PR modifies static/schemas/source/** (a deterministic hard approval gate) and review_decision is REVIEW_REQUIRED, not APPROVED. Per decision row 2, the outcome must be escalate (there are no blocking findings that would make it request-changes).

Escalation reasons

• Gated paths touched under static/schemas/source/** (e.g. creative-addon-chain.json, product-purchase.json, error-code.json, specialism.json, plus 15 others) require human/CODEOWNERS approval. review_decision is REVIEW_REQUIRED — gate not satisfied.

Review notes (non-blocking)
Reviewer found no Critical/High/Medium findings across all 46 files. Changeset is minor and additive (new get_creative_addons task, 7 core schemas, disclosure/chain fields, 7 ADDON_* error codes, creative-addon specialism) — no required-flip, no removed/renamed field, so not breaking-class. The sole new oneOf (creative-addon-chain discriminator status with const-pinned arms) is properly discriminated and won't fail audit-oneof. Schema↔docs coherence holds; dist/<semver>/ untouched. This is a clean additive proposal; the escalation is purely the deterministic approval gate, not a code concern.

Follow-up disclosed by author (non-blocking): two size-guard reds (controller 1,321,066>1,320,000; media-buy 476,621>475,136) left unraised pending a separate decision; full npm test not run.

Why human review

• Modifies gated paths under static/schemas/source/** (19 files incl. product-purchase.json, error-code.json, specialism.json, creative-addon-chain.json) — hard approval gate requires human/CODEOWNERS review; review_decision is REVIEW_REQUIRED, not APPROVED.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/account/sync-accounts-response.json (modified) matches static/schemas/source/**; static/schemas/source/core/canonical-product.json (modified) matches static/schemas/source/**; static/schemas/source/core/creative-addon-capability.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-chain.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-disclosure.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-failure.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-fragment.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-registration.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-addon-signing-key.json (added) matches static/schemas/source/**; static/schemas/source/core/creative-variant.json (modified) matches static/schemas/source/**; static/schemas/source/core/product.json (modified) matches static/schemas/source/**; static/schemas/source/creative/get-creative-addons-request.json (added) matches static/schemas/source/**; static/schemas/source/creative/get-creative-addons-response.json (added) matches static/schemas/source/**; static/schemas/source/enums/error-code.json (modified) matches static/schemas/source/**; static/schemas/source/enums/specialism.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/product-fields.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/product-purchase.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.

[bryanSigma]

Hi @bokelley, if you can please review the bot feedback and approve the changes. I would like for this to be released in 3.3.