Catalog envelope-level fields and migrate to allOf shared-envelope pattern

[bokelley]

Context

PR #3493 introduced the allOf \$ref to core/version-envelope.json pattern for fields that appear on every AdCP request and response. The pattern eliminates per-schema duplication (was 127 inline copies, now one source of truth).

Multiple other envelope-level fields exist as inline-per-schema definitions today and would benefit from the same factoring. This issue catalogs them and serves as a tracker for follow-up PRs.

Don't bundle. Each candidate has its own deprecation/migration story. Land them as separate additive PRs across 3.x.

Candidates

idempotency_key

• Currently inlined on mutating requests (create_media_buy, update_media_buy, sync_creatives, etc.).
• ~50+ source files affected.
• Companion field replayed (currently in core/protocol-envelope.json's payload contract) is the response-side correlation.
• Factor into core/idempotency-envelope.json referenced via allOf from mutating-request schemas; keep replayed in the protocol envelope.

governance_context

• Already exists on core/protocol-envelope.json for the transport-layer wrapper.
• The request-side shape (when a buyer presents an upstream-issued JWS token to a seller on a governed task) isn't envelope-factored — it appears inline on relevant request schemas.
• 3.1 makes governance verification MUST for sellers; this is the moment to factor cleanly.

context and ext

• Already \$ref'd to core/context.json and core/ext.json, but referenced as inline properties (context: { \$ref: ... }) rather than allOf-composed.
• Inconsistent with the new envelope pattern.
• Migration is mechanical and additive — pull context and ext into the shared envelope allOf, keep the per-schema properties empty for these fields. Wire-compatible.

replayed and other protocol-envelope payload fields

• core/protocol-envelope.json describes the protocol-layer wrapper (context_id, task_id, status, message, payload, replayed, push_notification_config, governance_context, timestamp).
• The wrapper is added by the transport (MCP, A2A, REST), not the AdCP payload.
• Worth a re-read to confirm what belongs in the wrapper vs. in a payload-level envelope.

Plan

For each candidate above, file a separate PR that:

1. Adds (or refactors) a core/<name>-envelope.json schema.
2. Removes the inline definitions from each affected request/response.
3. Composes via allOf: [{ \$ref: ... }] at the schema root.
4. Confirms npm run build:schemas, npm run test:schemas, npm run test:composed, npm run test:examples are green.

Use PR #3493 as the template — it shows the pattern end-to-end.

What this issue is NOT

• Not about migrating the JSON Schema draft level. That's the 4.0 story (filed separately as Migrate JSON Schema source from draft-07 to 2019-09 (4.0) #3534).
• Not a single mega-refactor PR. Each candidate ships independently.

Related

• PR spec(versioning): release-precision protocol version negotiation #3493 (the precedent)
• Migrate JSON Schema source from draft-07 to 2019-09 (4.0) #3534 (the 4.0 schema-draft bump, which will gain unevaluatedProperties: false for additional strictness on these envelopes)

[bokelley]

Triage

Classification: Tracking / meta
Bucket(s): spec / protocol (schema)
Status: deferred

My take: This is an explicit tracker for sequential allOf-envelope factoring work across 3.x. The pattern it catalogs (shared-envelope via allOf $ref) doesn't exist on main until #3493 merges; landing any of these candidates before then would be building on an unstable surface. PR #3493 is large (132 files) and the issue author explicitly calls for separate PRs — fold candidate ruled out.

Blocked-on: #3493 — resurfaces on merge

---

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

---

Generated by Claude Code