spec(envelope): require status on every task response envelope (closes #4832)

[bokelley]

Closes #4832.

Summary

core/protocol-envelope.json now declares status in its required array. Every task response — including synchronous read-only metadata calls like get_adcp_capabilities — MUST carry a top-level status field. Synchronous calls emit "completed"; async calls emit submitted, working, input-required, etc. per the task-status enum.

Why this is a clarification, not a new requirement

The docs and storyboards already treat envelope status as canonical:

• sdk-stack.mdx:114 lists status as a Layer 1 response envelope responsibility
• mcp-response-extraction.mdx:77-87 shows status as a top-level structuredContent field in normative examples
• webhooks.mdx and error-handling.mdx discuss status values matter-of-factly across the sync/async/webhook lifecycle
• The v3_envelope_integrity/no_legacy_status_fields storyboard step asserts envelope_field_present: status — currently the only enforcement layer

The schema design just left status declared in properties but absent from required, which let SDKs ship without emitting it on some sync responses. This PR closes the ambiguity at the schema layer.

How the gap surfaced

Adopter @kapoost (production seller agent on @adcp/sdk@7.7.0, 117/121 storyboards passing) hit v3_envelope_integrity/no_legacy_status_fields failure (#4832). The SDK's auto-registered get_adcp_capabilities handler in adcp-client/src/lib/server/create-adcp-server.ts:4294-4376 builds capabilitiesData from adcp, supported_protocols, media_buy, account, creative, library_version — and never sets status. capabilitiesResponse in responses.ts:133 runs the payload through toStructuredContent, which is a type-only passthrough. The handler bypasses the v6 envelope-threading helpers, so no status is added.

The storyboard's expectation was correct in spirit but the schema didn't enforce it, leaving the SDK gap latent.

What this PR changes

• core/protocol-envelope.json: adds required: ["status"] and tightens the schema description and the status property description to spell out the contract for sync metadata responses.
• Changeset: minor (stricter wire contract).

What this PR does NOT change

• Per-task schema fold. The 64 task response schemas (create-media-buy-response.json, sync-creatives-response.json, etc.) still only $ref version-envelope.json. Folding them to also $ref protocol-envelope.json is mechanical cleanup that lets per-task response_schema validators catch envelope omissions directly. Filed as a separate follow-up before 3.1 GA.
• SDK fix. The adcp-client auto-registered get_adcp_capabilities handler still needs to emit status: "completed". Filed as a sibling-repo follow-up.

The two follow-ups together close the loop on the SDK side; this PR locks the spec contract.

Adopter impact

• Agents shipping responses without top-level envelope status are now non-conformant.
• The single broadly-distributed gap is @adcp/client's auto-registered get_adcp_capabilities (sibling follow-up).
• Other tools that go through the v6 handler pipeline already carry status because the SDK threads the envelope around typed platform returns.
• Adopters using raw-handler patterns (deprecated v5) should audit responses and add status: "completed" to any sync response missing it.

Validation

• npm run test:schemas — 8/8 passing including the new schema state
• npm run lint:schema-links — passing
• No other schemas $ref protocol-envelope.json, so the new required doesn't cascade through allOf chains

Cross-references

• Issue: v3_envelope_integrity/no_legacy_status_fields expects presence of status field on get_adcp_capabilities envelope, but SDK 7.7.0 does not inject one — schema/storyboard drift #4832 (kapoost, production adopter)
• Memory: SDK-is-canon-for-wire-contracts rule discussed; this PR resolves the schema/SDK divergence by locking the schema contract and tracking the SDK fix as the sibling follow-up.

[aao-release-bot]

Direction is right. One line-level contradiction blocks merge.

The schema now says two things at once. Line 60-62 requires status. Line 181 still reads:

"status and payload are intentionally NOT required on this schema. status may be carried via transport-native state on A2A (task.status.state); payload is a documentary grouping construct, never a required wire field."

That note isn't stale prose — it is the carve-out that explained how the envelope contract reconciles with A2A's transport-native state carrier. Per docs/building/by-layer/L0/a2a-response-extraction.mdx:30-43, A2A receivers read status.state from the task object, not a body-level status key. After this PR, an A2A sender reading the schema cannot tell whether they must now emit body-level status in the DataPart or whether task.status.state satisfies required: ["status"]. The carve-out got deleted by silence.

What to fix in this PR

Rewrite line 181 to (a) drop the "status … intentionally NOT required" claim and (b) state the A2A reconciliation explicitly — on A2A, required: ["status"] is satisfied by task.status.state carrying the value, even when the body DataPart omits the key. On MCP/REST it is satisfied by a root-level status field. Mirror the existing Transport serialization framing at lines 176-180.

The rest of the PR is clean — this is a one-line fix.

Things I checked

• Schema structure (lines 60-62): required lands as a top-level sibling of properties / additionalProperties / not / examples. Draft-07 compliant.
• not.anyOf (lines 64-69): orthogonal to the new required — different keys, different predicates. No interaction under draft-07.
• All five examples[] (lines 75, 99, 121, 145, 158) already carry status; they validate against the tightened schema.
• Cascade: confirmed the PR's claim that no other schema $refs protocol-envelope.json. Only static/schemas/source/index.json:257-258 (registry entry) and version-envelope.json:5 (prose pointer). The new required is normative-only until the per-task fold lands.
• Changeset front-matter (adcontextprotocol: minor) is valid; body matches the diff. minor is defensible — consistent with .changeset/2911-mcp-envelope-flat-serialization.md precedent for the same envelope.
• No drift against sdk-stack.mdx:114, mcp-response-extraction.mdx:77-87, webhooks.mdx, or error-handling.mdx. The drift is internal to this one file.

Follow-ups (non-blocking — file as issues)

• No negative test added. PR description claims npm run test:schemas 8/8 passing, but the diff adds zero test files. A constraint-coverage case (envelope without status → expected schema rejection) would close the loop and prevent future regressions when the per-task fold lands.
• Per-task schema fold (PR's own follow-up #1) — until the 64 task response schemas $ref protocol-envelope.json, this required is documentary. Worth landing before 3.1 GA so per-task validators actually catch envelope omissions instead of relying on the storyboard.
• SDK companion in adcp-client for the auto-registered get_adcp_capabilities handler — sibling-repo PR per the description.

Minor nits (non-blocking)

1. Changeset adopter specificity. .changeset/4832-envelope-status-required.md:13 names @adcp/sdk@7.7.0 and "production seller." Public changeset bodies usually anonymize the adopter SDK version. Fine to leave; flagging for the next one.

Request changes pending the line 181 reconciliation. Everything else is the right shape.

[aao-release-bot]

Sound clarification. Closes the schema-vs-storyboard gap where v3_envelope_integrity/no_legacy_status_fields asserted envelope_field_present: status but the schema let permissive producers slip through.

Things I checked

• Cascade scope. Only static/schemas/source/index.json:258 $refs protocol-envelope.json, and it's a catalog entry, not an allOf composition. Per-task response schemas (create-media-buy-response.json et al.) $ref version-envelope.json only. New required: ["status"] does not silently propagate into per-task validators. The per-task fold is correctly deferred in the changeset.
• Examples still validate. All 5 examples at protocol-envelope.json:75 / :99 / :121 / :145 / :158 carry status (completed / submitted / input-required / replayed-completed / failed). Examples-against-schema stays green.
• Internal coherence. Four prose touchpoints describe one contract without contradiction: top-level description (:5), status property description (:23), the new required array (:60-62), and the notes paragraph at :181 that explicitly bridges A2A — schema-level required: [status] enforces the post-extraction in-memory shape, transport-native task.status.state satisfies it on the A2A wire.
• task-status enum coverage. static/schemas/source/enums/task-status.json carries completed, so sync metadata calls have a valid value to emit.
• Legacy-fields constraint untouched. not.anyOf rejecting task_status / response_status at :64-69 still does its job.
• Storyboard alignment. static/compliance/source/universal/v3-envelope-integrity.yaml already required status via envelope_field_present — this PR is the schema catching up to the storyboard, not the other way around.
• Changeset. minor is the right call within the unreleased 3.1 window. Would be major if 3.1 were GA. Within-minor amendment of #2911 is fine; calling it major would imply the post-#2911 permissive state was the intended contract, which the docs and storyboard contradict.

Follow-ups (non-blocking — file as issues)

• Release-notes drift. docs/reference/release-notes.mdx:81 and :108 still describe the post-#2911 state ("schema drops required: [status, payload]") and the adopter matrix tells strict-validator consumers status will flip required→optional. After this lands, those lines actively misinform. Must update before 3.1 GA. docs/reference/whats-new-in-3-1.mdx:197 was already half-fixed (says payload.required only) but the line still treats #2911 in isolation — worth a hand-edit pass at the same time.
• A2A raw-payload validators. Worth adding one clause to the notes array making explicit that raw A2A task payloads validated directly against protocol-envelope.json are out of scope — the schema enforces the post-extraction in-memory envelope, not the A2A wire shape. The reasoning is already present at :181; just hoist the conclusion. Closes the only ambiguity an adopter running raw-task validation against the envelope schema might hit.
• SDK companion (already in changeset): @adcp/client's auto-registered get_adcp_capabilities handler needs to emit status: "completed" to close kapoost's storyboard failure end-to-end.
• Per-task schema fold (already in changeset): folding the 64 task response schemas to $ref protocol-envelope.json in addition to version-envelope.json is the right long-term shape — lets per-task response_schema validators catch envelope omissions directly.

Minor nits (non-blocking)

1. Top-level description hedge. protocol-envelope.json:5 reads "Agents shipping responses without a top-level status are non-conformant regardless of whether the task body schema would otherwise validate." For A2A the wire-native carrier is task.status.state, not a literal top-level key. notes[5] at :181 resolves it, but a one-clause hedge in the top-level description ("...top-level status — or its transport-native equivalent per Transport serialization below...") would remove the apparent tension on first read.

LGTM. Follow-ups noted below.