feat(types, validation): opt-in support for AdCP 3.1.0-beta.1 (catalog-sync cluster)

[bokelley]

Summary

Side-bundle support for AdCP 3.1.0-beta.1 — adopters can now pin adcpVersion: '3.1.0-beta.1' (or '3.1-beta') on AdCPClient and get strict validation + typed access to the catalog-sync cluster from adcontextprotocol/adcp#4767: if_catalog_version / if_pricing_version conditional fetch on get_products / get_signals, wholesale discovery_mode for signals, the catalog_change_feed capability stanza, and the new core/catalog-event.json + core/catalog-events-response.json.

The SDK's primary pin stays at the GA ADCP_VERSION — this is a side-bundle, not a default move. The latest symlink in schemas/cache/ continues to point at the GA pin.

Closes adcontextprotocol/adcp#4794 for the schema/types prerequisite. CatalogSync client (the consumer-facing change-feed mirror) lands in a follow-on PR — this opt-in unblocks adopters building their own mirror loop directly against the typed surface today.

Consumer flow this unblocks

import { AdCPClient } from '@adcp/sdk';
import type {
  GetProductsRequest,
  GetProductsResponse,
  CatalogEvent,
  CatalogEventsResponse,
} from '@adcp/sdk/types/v3-1-beta';

const client = new AdCPClient({
  agentUrl: 'https://salesagent.example.com',
  adcpVersion: '3.1-beta', // or '3.1.0-beta.1' for full-semver pinning
});

const req: GetProductsRequest = {
  buying_mode: 'wholesale',
  if_catalog_version: 'v2026-05-18T08:00:00Z-acme-rev412',
};

Plumbing

• scripts/sync-3-1-beta-schemas.ts wraps syncSchemas() with two safety properties:
  • Restores the latest symlink to the primary GA pin after the beta tarball extraction.
  • Restores tracked side-effect paths (schemas/registry/registry.yaml, protocol-managed skills) from HEAD so an opt-in beta sync never bumps GA-pinned check-in surfaces.
• scripts/generate-3-1-beta-types.ts emits the parallel src/lib/types/v3-1-beta/tools.generated.ts surface, mirroring the v2.5 codegen pipeline with two additions specific to 3.1 schemas:
  • Intra-schema $ref reseating (#/oneOf/... → #/definitions/<Name>/oneOf/...) for tools whose schemas reference their own internal sub-trees (get_brand_identity, verify_brand_claims, etc.). Without this, the mega-schema bundling causes MissingPointerError.
  • Index-signature widening on inline anonymous objects so optional named properties (e.g. ForecastPoint.metrics.audience_size?: ForecastRange) don't collide with the [k: string]: ForecastRange index signature (TS2411). json-schema-to-typescript's strictIndexSignatures handles top-level types but not inline objects.
• COMPATIBLE_ADCP_VERSIONS extended via COMPATIBLE_PREFIX. The major/minor gate in buildCompatibleVersions stays closed for primary-pin moves — opt-in betas land in the prefix list, GA bumps still require an explicit range extension. Pattern matches the existing 3.0.0-beta.1 / 3.0.0-beta.3 entries.
• package.json ./types/v3-1-beta export + typesVersions entry mirror the v2.5 pattern.

Verified

• tsc --noEmit clean (0 errors)
• format:check clean
• npm run build:lib clean; dist/lib/schemas-data/3.1.0-beta.1/ ships alongside 3.0 and v2.5
• 21/21 schema-loader-per-version + v2-5-types-import tests pass
• 21/21 validation tests pass
• End-to-end: resolveBundleKey('3.1-beta') resolves; getValidator('get_products', 'sync', '3.1.0-beta.1') compiles; a beta-shaped response (unchanged: true, catalog_version, cache_scope: 'public') validates against the beta schema

Test plan

• Reviewer pulls the branch, runs npm run sync-schemas:3.1-beta, confirms cosign verification passes
• Reviewer runs npm run generate-types:3.1-beta && npx tsc --noEmit and confirms 0 errors
• Reviewer imports a beta type (import type { CatalogEvent } from '@adcp/sdk/types/v3-1-beta') in a downstream consumer and confirms IntelliSense exposes the catalog-sync fields
• CatalogSync follow-on PR (issue #4794 client implementation) opens against main once this lands

🤖 Generated with Claude Code