Let the response envelope carry a ServerHello

[afogel]

What changed

response-envelope.json declared result as an unconditional $ref to AcsResult, which requires decision. handshake.json says a ServerHello is wrapped in that same envelope, and a ServerHello has no decision. So a conformant handshake/hello response could not satisfy the response envelope schema. An implementation that checks its own responses against the schema had to either report a correct handshake as invalid or skip the check for that method.

result is now a oneOf over AcsResult and handshake.json#/$defs/ServerHello. The two shapes share no required field, so a conformant response matches exactly one branch. A decision response that lost its decision still fails, because it matches neither branch.

tests/test_response_envelope.py validates instances against the real package with cross-file refs resolved by $id. It checks that a decision result and a ServerHello are both accepted, that an AcsResult without decision is rejected, and that a ServerHello missing one of its own required fields is rejected.

Type of change

• Specification change (schema, hooks, events, AgBOM)
• Documentation
• Tooling or CI
• Governance (licensing, security policy, contributor docs)

Specification changes

• I opened a Discussion before this PR
• Schema changes validate against the JSON Schema spec
• I described the impact on downstream implementers below

Breaking for implementers? No. Every response that validated before still validates. The change admits a shape the prose already required on the wire. Implementers who special-cased handshake/hello to skip response validation can remove that special case.

Checklist

• Commits are signed off with git commit -s (required by the DCO)
• Prose follows STYLE.md
• uv run mkdocs build --strict passes
• No secrets, tokens, or internal URLs in the diff

Security

• This change has no security impact

[rocklambros]

The defect is real and the fix is the right shape.

result pointed at AcsResult, which requires decision, while handshake.json puts a ServerHello in that same envelope. A conformant handshake/hello response could not validate against the envelope the prose said carried it. That is a specification bug, not an implementation inconvenience, and it is the kind that only surfaces when someone actually validates their own traffic.

The oneOf discriminates cleanly. AcsResult requires decision, ServerHello requires negotiated_version, and neither shape carries the other's required field, so a conformant response matches exactly one branch. A decision response that lost its decision still fails, because it does not fall through to the ServerHello branch.

The test earns its keep. Building the validator over every $id-bearing file in specification/v0.1.0/ exercises the same cross-file resolution the published package uses, and asserting the envelope $id against BASE in tools/publish_schemas.py ties the test to the real namespace instead of a local copy of it. test_a_server_hello_missing_a_required_field_is_rejected is the one that carries the most weight, because it proves the ServerHello branch is checked against handshake.json rather than waved through.

The non-breaking claim holds. oneOf only widens what validates, so every response that passed before still passes.

I checked the release commit's claim about the Sync Version workflow and it is correct. sync_version.yml guards on git diff --quiet, and pyproject.toml and uv.lock are already synced on this branch, so the workflow will run on merge and find nothing to do.

Landing this as a squash, so it arrives as one commit with your authorship and your sign-off intact. I am dropping the two AI trailers from the commit message. This project keeps human authorship in its git history, and that was written down nowhere when you opened this, which is our gap rather than yours. I am adding it to CONTRIBUTING.md in a follow-up so the next contributor learns it before merge time instead of at it.

Good catch. This is the sort of thing that would have cost an implementer an afternoon.