chore: sync AdCP 3.1 rc4

[bokelley]

Summary

• update the SDK AdCP pin from 3.1.0-rc.3 to 3.1.0-rc.4
• regenerate generated TypeScript/Zod schemas, manifest constants, wire-field metadata, entity hydration metadata, and llms docs
• add GitHub dist fallback for schema syncs when adcontextprotocol.org has not mirrored a signed protocol bundle yet
• keep media-buy mode mismatch recovery tolerant of older 3.1 prerelease sellers that can still emit requires_proposal

Validation

• npm run build:lib
• npm run test:lib
• npm run ci:codegen-strict
• npm run ci:docs-check
• npm run ci:schema-check
• git diff --check
• npx commitlint --from origin/main --to HEAD --verbose
• pre-push hook: typecheck + build:lib

Schema diff

Compared schemas/cache/3.1.0-rc.3 to schemas/cache/3.1.0-rc.4. Notable wire changes: signed_response is required on successful brand claim verification responses, pricing_currencies is available on product filters, requires_proposal is removed from media-buy action modes, signal definition enrichment is added.

[aao-ipr-bot]

LGTM. Follow-ups noted below. Right shape for an rc-tracking bump: the only hand-written code change is two lines of compat-cast in preflight.ts:653-655 with the spec-lineage comment baked in, and the rest is mechanical regeneration plus a CI-resilience fallback in scripts/sync-schemas.ts.

Things I checked

• .changeset/adcp-3-1-rc4.md present, type minor. Defensible — rc4 narrows MediaBuyActionMode (removes requires_proposal), but the runtime cast at preflight.ts:655 preserves behavior for legacy emitters and this is rc→rc prerelease churn, not a GA contract change. requires_proposal lives on the buyer-side switch arm, not the wire response shape.
• ADCP_VERSION (3.1.0-rc.3 → 3.1.0-rc.4) and package.json#adcp_version move together. package.json#version untouched — changesets keep ownership.
• sync-version.ts:99 appends '3.1.0-rc.4' to COMPATIBLE_PREFIX; version.ts regenerated and COMPATIBLE_ADCP_VERSIONS extends through 3.1-rc.4. 3.0.x compat surface preserved.
• scripts/sync-schemas.ts fallback threads baseUrl through syncFromTarball / syncSchemasPerFile / downloadSchema cleanly. verifyCosignSignature already receives baseUrl for sidecar lookup — sidecars get resolved against the same origin as the bundle.
• All generated surfaces stamp schemas/cache/3.1.0-rc.4/ consistently — entity-hydration, wire-spec-fields, manifest, schemas, tools, enums all agree on the pin. No mixed-version drift.

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

• scripts/sync-schemas.ts:543-551 — fallback catches every throw, including cosign and sha256 failures. If adcontextprotocol.org ever serves a bundle that fails cosign or sha256 verification, the script silently retries against raw.githubusercontent.com/.../dist, where missing sidecars trip the verifyCosignSignature "predates signing — checksum-only" branch at scripts/sync-schemas.ts:191-194. Net effect: a genuine signature failure on the canonical mirror is masked by an unsigned re-fetch. Scope the catch to network/404-class errors only — let cosign verify-blob failed and Tarball sha256 mismatch propagate. Minimum viable: re-throw if err.message matches /cosign|sha256 mismatch/i.
• ADCP_GITHUB_FALLBACK=0 opt-out is undocumented. Only escape hatch when the fallback misbehaves; mention it in the comment block above the try/catch at minimum.
• rc4 requires_proposal removal — is there a new wire signal the SDK should dispatch on? The compat cast at preflight.ts:655 keeps the old code path alive for legacy emitters, which is correct. But if rc4 sellers now signal proposal-required via a different surface (a new error code on create_media_buy, a different mode value, an ext hint), recoveryForModeMismatch won't pick it up. Worth confirming against schemas/cache/3.1.0-rc.4/media-buy/ and the upstream spec PR that did the removal — link the spec PR in a follow-up if there's no new dispatch site needed.

Minor nits (non-blocking)

1. Warn message overstates the failure mode. scripts/sync-schemas.ts:550 reads "was not reachable from adcontextprotocol.org" but the catch fires on any throw — including signature/checksum failures. Either narrow the catch (preferred, see follow-up #1) or say "sync against adcontextprotocol.org failed".

LGTM.

[aao-ipr-bot]

LGTM. Faithful schema-pin bump tracking rc4 with a load-bearing compat shim for sellers still emitting requires_proposal.

Things I checked

• MediaBuyActionMode correctly drops 'requires_proposal' at src/lib/types/core.generated.ts:4664; signed_response on VerifyBrandClaimSuccess lands as a required additive field with a well-typed ResponsePayloadJWSEnvelope shape.
• The runtime compat shim at src/lib/media-buy/preflight.ts:655 (entry.mode as MediaBuyActionMode | 'requires_proposal') keeps the recovery path working for rc.3-era sellers — wire-compat preserved while the type narrows.
• scripts/sync-version.ts:99 extends COMPATIBLE_PREFIX correctly. No other dispatch table needed updating.
• Cosign verification at scripts/sync-schemas.ts:177-243 is threaded through the new baseUrl parameter — checksum and signature checks still run against whichever mirror is serving the bundle. The GitHub-raw fallback is opt-out-able via ADCP_GITHUB_FALLBACK=0, and the try/catch retry only triggers when the primary mirror is the canonical adcontextprotocol.org (no double-fallback against custom ADCP_BASE_URL overrides — right call).
• Changeset is minor, which matches the established beta-track convention for AdCP RC pin bumps (adcp-3-1-beta-5, adcp-3-1-beta-7 both shipped minor on the 8.x.x-beta.NN line).

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

• src/lib/errors/index.ts:514 declares an inline mode union that still includes 'requires_proposal' as a current value, and buildModeMismatchRecovery at line 541 switches on it as a present-tense case. Pre-existing — this PR didn't touch it — but the analogous surface to preflight.ts:655, and now diverges from MediaBuyActionMode. Worth a follow-up to mirror the cast trick (or narrow the union and accept the legacy literal explicitly) so the SDK's two error-reasoning paths agree about what the rc.4 wire claims.
• scripts/sync-schemas.ts:539-549 — the fallback retry isn't transactional across the two replaceTree calls. If attempt-1 succeeds on schemas/ (line 379) but fails on compliance/ (line 380), the catch retries and the new .previous snapshot of schemas captures the attempt-1 partial, clobbering the genuine prior. Narrow window (committed cache is also in git, so recovery is git checkout), but the schema-diff tool could be misled. Either snapshot both trees atomically before either rename, or treat any post-replaceTree failure as fatal.
• Changeset prose mentions the recovery-path tolerance but not that MediaBuyActionMode lost a union member. Worth a sentence so adopters with switch statements on the type know to expect a now-unreachable case.

Minor nits (non-blocking)

1. Cosign log message at scripts/sync-schemas.ts:192. When the GitHub mirror serves the tarball but not .sig/.crt, the existing "upstream predates signing" message reads wrong — the cause is "this mirror doesn't carry sidecars," not version age. Surface baseUrl in the log.
2. Comment accuracy at src/lib/media-buy/preflight.ts:653. "Removed from the rc4+ mode enum" — removed in rc.4, not "rc4+". Audit-trail nit.

Safe to merge.