[release engineering] Validate schema PR bundles against both SDK generators

[bokelley]

Summary

Protocol schema PRs cannot currently be validated reproducibly against the Python and TypeScript SDK generators before the protocol bundle is published. The reporting RFC exposed this: both SDKs normally download /protocol/{version}.tgz, so testing an unmerged protocol worktree required manual schema copying/overlays and produced SDK branches whose source provenance was easy to lose as the RFC continued changing.

Concrete failure mode

While validating #6953:

1. The SDK branches were generated from a local snapshot of the protocol PR.
2. The protocol PR then added required reporting coverage fields.
3. The dependent SDK branches were immediately stale, but neither their generated artifacts nor CI had a machine-readable assertion identifying the exact protocol commit/bundle digest they represented.
4. Full regeneration also mixed the intended RFC delta with unrelated latest drift, producing thousands of noisy generated changes.

This is exactly the point at which we want generator incompatibilities and semantic drift to fail before the protocol PR merges.

Proposed release-engineering contract

• Build a deterministic protocol bundle artifact for every schema-changing PR, using the same layout and integrity metadata as a release bundle.
• Record the protocol commit SHA and bundle SHA-256 in generated SDK artifacts/metadata.
• Provide a supported local input in each SDK (--bundle, --schema-dir, or equivalent) rather than requiring an HTTP publication or manual overlay.
• Run both SDK generators and focused contract tests against the PR artifact as a required/visible protocol PR check.
• Fail when generated output is based on a different protocol commit than the declared artifact.
• Offer a scoped generation/diff mode so an RFC can be reviewed without unrelated latest drift.
• Document how a protocol author creates dependent SDK PRs and refreshes them after a protocol force-push/rebase.

Acceptance signal

A contributor should be able to point both SDK repos at the artifact for #6953, regenerate, and prove which protocol commit they consumed without publishing a fake version or copying individual files.

Related implementation PRs: adcontextprotocol/adcp-client#2726 and adcontextprotocol/adcp-client-python#1095.

[bokelley]

Triage

Classification: Feature request (CI/release engineering capability gap)
Bucket(s): infra / agents (GitHub Actions, build tooling)
Status: ready-to-implement

What the experts said:

• dx-expert: SUPPORT — provenance tracking + local --bundle input close the two biggest contributor DX gaps simultaneously; scoped diff mode is the most underrated item; "document the workflow" alone won't stick — a thin make sdk-pr BUNDLE=<artifact> target that automates the create/refresh cycle should be a named deliverable.
• code-reviewer: SUPPORT with caveats — scripts/build-protocol-tarball.cjs is ~80% there; the generated_at: new Date().toISOString() field breaks byte-reproducibility (commit-anchored is fine, byte-identical is not achievable); PR workflows run on refs/pull/*/merge so Sigstore signing is out, SHA-256 checksums are sufficient; R2 at protocol/pr/{sha}/ reuses the existing CDN upload path cleanly; "scoped generation/diff mode" requires schema-to-file mapping in both SDKs and should be explicitly a follow-on, not a first-pass blocker.

My take: The failure mode is real and will recur on every schema-changing RFC — this is worth doing. The adcp-side work is a new GitHub Actions workflow plus a small patch to build-protocol-tarball.cjs; the SDK-side work is tracked by the referenced PRs (#2726, #1095). The critical scoping call: split "scoped generation/diff mode" into a follow-on issue so the core CI check doesn't stall on that harder problem.

Implementation scope:

• adcp (this repo): New GHA workflow triggered on schema-changing PRs; runs build-protocol-tarball.cjs (remove or pin generated_at for stable digests); uploads bundle to R2 at protocol/pr/{commit-sha}/ using the upload logic in .github/workflows/recover-protocol-cdn.yml; invokes both SDK generators against the artifact; fails on protocol SHA mismatch. Files: .github/workflows/validate-schema-bundle.yml (new), scripts/build-protocol-tarball.cjs (minor patch).
• adcp-client / adcp-client-python: --bundle <url> input flag + protocol SHA recorded in generated artifacts — already in flight at adcp-client#2726 and adcp-client-python#1095. These define the contract adcp CI needs to verify.
• Docs: contributor guide for creating dependent SDK PRs and refreshing after protocol rebase/force-push. Should include a script or make target, not just prose.
• Out of scope for v1: Sigstore-signed PR bundles (PR identity constraint blocks it); scoped generation/diff mode (requires schema-to-output mapping in both SDKs — file a follow-on).
• .github/** requires a human-authored PR per repo policy — no agent draft.

---

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

---

Generated by Claude Code

[bokelley]

Fresh end-to-end evidence from the reporting implementation:

• TypeScript SDK feat(editorial): reviewer notifications on pending_review (#2701) #2726 has a valid local build and adopter typechecks, but its generated-drift job regenerates from published beta.9 and removes the pending get_reporting_status / sync_agent_configuration surfaces. The actual SDK unit regression was separately identified and fixed; today both conditions are collapsed into one red SDK PR. SDK-side bundle-input tracking: [release engineering] Support protocol PR bundles in codegen CI adcp-client#2751.
• Python VCS installation exposed a separate release-path defect: PEP 517 wheels built directly from Git omitted all schema resources even though editable installs worked. Fixed on feat: Consolidate individual profiles and show contributions #1095 and tracked as fix(packaging): make VCS-built wheels include runtime schemas adcp-client-python#1104.

This confirms the PR artifact needs to exercise the same install/codegen paths consumers use—not only copy schema directories into SDK worktrees.