fix(protocols): normalize adcp_version to release-precision on the wire

[bokelley]

Summary

• Adds toReleasePrecisionWire(bundleKeyOrVersion) next to resolveBundleKey in schema-loader.ts.
• Wires it into buildVersionEnvelope at the single emit site so prerelease pins emit spec-valid wire values.
• Exports it publicly for storyboard fixtures + conformance harnesses that build their own wire envelopes.

Why this matters

AdCP 3.1's core/version-envelope.json constrains the adcp_version field to release-precision strings via pattern ^\d+\.\d+(-[a-zA-Z0-9.-]+)?$. The schema's own description carries the normalization rule:

SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

Before this fix, buildVersionEnvelope emitted the bundle key verbatim, so a 3.1.0-beta-pinned client would send adcp_version: "3.1.0-beta.0" and sellers would AJV-reject the request body with a pattern mismatch.

The bug is latent today — COMPATIBLE_ADCP_VERSIONS doesn't include any 3.1.x release, so no public-pin path can hit it. But a caller manually overriding adcpVersion past the compat gate, or the SDK's eventual 3.1 enablement, would silently break. Found while staging a local 3.1.0-beta cache from spec PR adcontextprotocol/adcp#3307 and exercising buildVersionEnvelope against the real envelope schema.

How it works

toReleasePrecisionWire:

• Stable bundle keys ('3.0', '3.1') pass through unchanged.
• Prerelease semver collapses the PATCH segment, preserving the prerelease tag: '3.1.0-beta.0' → '3.1-beta.0'.
• Full stable semver collapses to minor: '3.0.11' → '3.0'.
• Legacy aliases ('v3') pass through (gated out of the wire field by bundleSupportsAdcpVersionField anyway).
• Rejects unrecognized shapes loudly rather than silently emitting non-spec values.

Verification

End-to-end check: emitted envelopes for bundle = '3.0' | '3.1' | '3.1.0-beta.0' | '3.0.11' all validate against core/version-envelope.json from a locally-built 3.1.0-beta.0 cache.

Test plan

• 7 unit cases covering stable / prerelease / release-precision / legacy / garbage inputs.
• Cross-check that every non-legacy output matches the spec's wire pattern.
• All 28 existing version-envelope tests still pass.
• npm run format:check clean.
• npm run typecheck clean.
• CI green.

🤖 Generated with Claude Code

[bokelley]

Round 1 expert review — consensus: ship

Fired four reviewers in parallel per skills/run-by-experts/SKILL.md (protocol, code, security, dx). All four returned no blockers.

Convergent findings (2+ reviewers) — addressed in d3e6ad7:

• JSDoc note that the prerelease regex is intentionally stricter than the wire pattern. Protocol + code reviewers both flagged that [0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)* (SemVer §9) is tighter than the wire's [a-zA-Z0-9.-]+. Strictness is intentional (mirrors resolveBundleKey's path-traversal hardening); added a JSDoc note so a future reader doesn't try to "fix" it back to match the wire char-for-char.

Single-reviewer must-fix (worth doing) — also in d3e6ad7:

• JSDoc idempotency note (DX): added "Idempotent. Re-applying to an already-wire-shaped value is a no-op." Useful for conformance-test authors.
• Trailing-dot rejection tests (code): '3.1.0-beta.', '3.0.' — confirms the stricter-than-wire-pattern note is enforced by code, not just doc.
• Leading-zero round-trip test (code): '03.01' → '03.01' — documents that we don't normalize numeric components, only patch-collapse.

Single-reviewer suggestions — deferring to follow-up issues:

• Naming asymmetry (DX): toReleasePrecisionWire vs sibling bundleSupportsAdcpVersionField. DX suggested toAdcpVersionWire; code reviewer raised the opposite question ("should this be @internal?"). No convergence; keeping current name. The name is precise (spec literally calls this "release-precision normalization") and the JSDoc anchors discoverability.
• resolveBundleKey doesn't accept release-precision pins (protocol): a buyer reading seller supported_versions: ["3.1-beta"] and pinning to '3.1-beta' throws. Real gap, but scope-adjacent — the PR's job was wire-emit, not bundle resolution. Filed as a follow-up.
• Outgoing-envelope validation should name the helper in errors (DX): the seller's AJV rejection won't help a buyer find this function. Worth a follow-up where the SDK's own request-validation pre-flight catches the bad shape and throws a helpful error pointing here.

Security: explicit ship-it. No path coupling, no ReDoS (linear up to 512KB inputs), no log-injection vector, safe to export.

Reviewer summaries:

• protocol: "spec rule quoted verbatim in JSDoc. Single emit site. Public export for storyboard parity. Strict-mode test pattern cross-check is the right defense."
• code: "no blockers. Pattern matches other tests — testing harness expects dist to be built. Convention is consistent. No generated files touched."
• security: "Stateless, pure, throws on garbage, output bounded to the spec regex. Safe to export. Ship it."
• dx: "Test as documentation: excellent. Seven scenarios + a cross-check against the actual wire regex. Verdict: Ship it."