feat!: cut 8.0-beta line — flip ADCP_VERSION to 3.1.0-beta.2 (foundation)

[bokelley]

Draft. Foundation for the 8.0-beta line per the v8.0-beta plan doc. CI will be red on 17 structural compile errors that map to separate follow-up PRs — listed below.

What's in the foundation

• Enters changesets pre-mode with tag `beta`. Subsequent releases publish as `8.0.0-beta.N` under the `@beta` npm dist-tag.
• `ADCP_VERSION` file: `3.0.12` → `3.1.0-beta.2`. `src/lib/version.ts` regenerated via `sync-version --force`.
• `scripts/sync-version.ts` extended: `buildCompatibleVersions()` now accepts `3.1.0-beta.x` pins and retains 3.0.x GA compat through `LAST_3_0_GA_PATCH = 12` so an 8.0-beta SDK still talks to 3.0-pinned sellers (spec's open-enum wire compat).
• Synced `schemas/cache/3.1.0-beta.2` as primary (cosign verified).
• Regenerated types: `tools`, `schemas`, `core`, `manifest` (80 codes, 61 tools, 20 specialisms), `enums`, `entity-hydration` map.
• `FORWARD_COMPAT_ERROR_CODES` emptied — `AUTH_MISSING`, `AUTH_INVALID`, `AGENT_SUSPENDED`, `AGENT_BLOCKED` are now in the primary manifest-driven `ErrorCodeValues`. The compile-time disjointness assertion would fail if a code returned to the overlay after manifest absorption.
• `BuyerRetryPolicy.DEFAULT_CODE_POLICY` gained 31 entries for new 3.1 codes (provenance, billing, format-projection, pixel-tracker, scope/permission, etc.).
• Mechanical `undefined`-guards in `responses.ts`, `signals.ts`, `test-controller-bridge.ts`, `test-controller.ts`.

What's red (17 structural compile errors, separate PRs)

Each maps to a per-feature spec migration:

1. `OutcomeMeasurement` export removed — 2 sites in `index.ts` and `compat.ts`. Needs investigation of what replaced it in 3.1.0-beta.2.
2. Brand object lost `categories` field — 7 sites (`account.ts` × 5, `responses.ts` × 2). Spec migration; need to locate where categories moved.
3. `AssetVariant` is now a union with array — 3 sites in `manifest-helpers.ts`. Need to handle the new union shape.
4. `creative-asset` shape changed — 4 sites in `preview-utils.ts` (`format_id`, `manifest` accesses). Spec migration.
5. `ControllerScenario` exhaustiveness guard fails — `test-controller.ts:210`. 3.1.0-beta.2 added new scenarios; need to add them to `CONTROLLER_SCENARIOS`.

Plus from the beta.2 release notes, not yet implemented:

6. Envelope `status` REQUIRED — spec explicitly calls our auto-registered `get_adcp_capabilities` handler out as the gap. Small focused fix in a follow-up.
7. Drop legacy `mirror.adcontextprotocol.org` from `DEFAULT_MIRROR_HOSTS` — text-only spec change.

Why merge this draft now

This is the foundation. Every `needs:adcp-3.1` queue item now becomes a per-feature PR against this branch line, exactly as the v8.0-beta plan predicted. Without this foundation merged, every follow-up PR carries the pin-flip + type regen as duplicated work.

Recommended sequencing:

1. Merge this foundation (mark ready when reviewers OK the strategy + breaks list)
2. Each structural break gets its own PR (small, focused, reviewable)
3. `changeset version` periodically to cut `8.0.0-beta.N` releases
4. When upstream AdCP 3.1 goes GA: `changeset pre exit` + cut `8.0.0`

Verification

• `sync-version --force` succeeded; `COMPATIBLE_ADCP_VERSIONS` includes 3.0.0–3.0.12, all 3.1.0-beta.N, plus the new pin.
• `generate-types` succeeded against beta.2 schemas (80 codes, 61 tools, 20 specialisms).
• tsc on tsconfig.lib.json: 30 errors → 17 errors after mechanical sweep. Remaining 17 are the structural items above.
• prettier --check clean on all touched files.

References

• v8.0-beta plan
• 3.1.0-beta.2 release notes
• Closes foundation work in Umbrella: AdCP 3.1 schema bump — checklist of SDK-side adoptions #1580 (umbrella)

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[bokelley]

Expert review summary (all three: SHIP)

code-reviewer — strategy is sound, hand-written surface is small and defensible. Two non-blocking should-fixes both addressed in commit 44b4538:

• Added 'capability' to RetryDecision.escalate.reason union; 7 format-projection/pixel-tracker codes routed from 'commercial' → 'capability'.
• Divergence-comment in the escalate union now enumerates billing + provenance + scope/permission families explicitly.

ad-tech-protocol-expert — wire-compat retention correct, overlay-empty rationale correct, retry-policy defaults mostly correct with two specific notes:

• PROVENANCE_VERIFIER_NOT_ACCEPTED / PROVENANCE_CLAIM_CONTRADICTED: spec says correctable but we operator-grade override to commercial. Documented in the extended divergence comment (commit above).
• FORMAT_DECLARATION_* and PIXEL_TRACKER_* codes are spec-advisory (200-success errors[]), not failures. Tracked separately as #1904 — start with JSDoc clarification, defer advisory action variant until adopters surface real cases.

code-reviewer on #1903 — also SHIP, no issues. Dual-name re-export pattern is correct.

CI status

Still 17 errors in this PR on its own (15 with #1903 stacked) — the 5 structural breaks listed in the PR body. Each will be its own focused follow-up PR. Foundation is ready for review; will mark "ready" once the remaining structural break PRs close out CI.

Follow-ups filed

• #1904 — BuyerRetryPolicy advisory-vs-error policy dispatch (deferred design)

[bokelley]

Acknowledged. Expert sign-offs recorded, CI state noted (17 errors → structural breaks tracked as follow-up PRs), #1904 filed for the advisory-vs-error dispatch question. Waiting on the structural break PRs to clear before the "ready" flip.

---

Generated by Claude Code

[bokelley]

Fold suggestion from issue triage (#1904): before merging, consider adding JSDoc to the seven advisory-code entries in BuyerRetryPolicy.DEFAULT_CODE_POLICY (FORMAT_PROJECTION_FAILED, FORMAT_DECLARATION_DIVERGENT, FORMAT_DECLARATION_V1_AMBIGUOUS, FORMAT_CAPABILITY_UNRESOLVED, FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE, PIXEL_TRACKER_LOSSY_DOWNGRADE, PIXEL_TRACKER_UPGRADE_INFERRED).

The note to add: these entries fire only when an adopter explicitly routes an advisory code (emitted in errors[] on a 200-success response) through decideRetry(). The spec's intended path is that the buyer surfaces the advisory and continues without entering the retry surface. Zero behavior change; purely doc signal so adopters don't escalate-on-advisory by accident.

If scope expansion would slow review, a follow-up PR against bokelley/cut-8-0-beta is equally fine — tracked at #1904.

---

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

---

Generated by Claude Code

[nastassiafulconis]

JSDoc says "Returns undefined if the slot is missing or empty" but ![] is false in JS, so an empty array slot flows through to the filter and returns [], not undefined. either fix the doc to "returns undefined if the slot is missing; returns [] if the slot is empty or no elements match assetType", or add || arr.length === 0 to the !slot guard. behavior is probably fine since empty slots would be spec-invalid, just needs the docs to match the code.

[nastassiafulconis]

heads up: updatePackageJsonVersion lower in this file uses the same adcpVersion.split('.').map(Number) pattern without the prerelease guard, so '0-beta' becomes NaN at index 2. current destructuring only pulls [newMajor, newMinor] so it doesn't blow up today, but worth a comment on that block noting only major/minor are used and the NaN at patch position is intentional — otherwise the next person who adds a newPatch destructure will be surprised.

[aao-ipr-bot]

LGTM. Follow-ups noted below. The pre-mode foundation pattern is the right shape -- pin flip, type regen, overlay drain, and per-feature breaks folded into the cut as discrete changesets gives reviewers a real surface to read instead of one mega-diff.

Things I checked

• Largest-file rule. Read every non-generated TS file with >50 net lines: envelope-status-compat.ts (new, 90L), buyer-retry-policy.ts (+89), forward-compat-error-codes.ts (rewritten to empty overlay), preview-utils.ts (rewrite, -112 net), response-unwrapper.ts (+17), responses.ts (+20 net), test-controller.ts (+17 net), manifest-helpers.ts (+31), compat.ts (+11), scripts/sync-version.ts (+28). Generated files skipped.
• BuyerRetryPolicy grading vs spec recovery class. All 31 new entries trace correctly. CREDENTIAL_IN_ARGS: terminal (buyer-retry-policy.ts:322) -- retrying would re-leak. IDEMPOTENCY_EXPIRED: idempotency_check_required (:196) -- natural-key check before fresh mint. IDEMPOTENCY_IN_FLIGHT: retry with same key (:258) -- safe; seller replay window dedupes. PROVENANCE_VERIFIER_NOT_ACCEPTED and _CLAIM_CONTRADICTED route to commercial (:288-289); other provenance codes route to mutate-and-retry/validation. STALE_RESPONSE: terminal (:327) with the consume-payload, surface-advisory semantic. New capability reason on the escalate union (:76) cleanly separates implementation-choice tickets from commercial.
• stripGovernanceAgentSecrets defense-in-depth. Both v5 (responses.ts:768-784 -- explicit url-only projection) and v6 (decisioning/account.ts via projectGovernanceAgent) project at the wire-emit seam. Closes the as-any smuggling path even for adopters writing raw JS. authentication.credentials strip on notification_configs (responses.ts:111-133) covered by existing tests at four boundaries.
• SAFE_VERSION regex. The anchor pattern at scripts/sync-version.ts:67 has no m flag, so newlines cannot satisfy the end anchor. Newlines, NUL, quotes, backticks, backslashes, underscore, slash all rejected by the class. Template-injection-into-generated-version.ts sealed. MAX_PATCH_ENUMERATION = 500 defensive cap (:120) and LAST_3_0_GA_PATCH = 12 (:132) at the right shape.
• FORWARD_COMPAT_ERROR_CODES empty-overlay disjointness. as const satisfies on an empty object compiles. ForwardCompatErrorCode resolves to never; the compile-time check at error-codes.ts would fail closed if a code returned post-absorption.
• AssetVariant slot widening. getAsset and requireAsset unwrap single-element arrays (manifest-helpers.ts:48-51, 99-100); new getAssetSlot returns the filtered array. Pre-3.1 single-asset callers keep working without code changes.
• product_card self-rendering migration scope. batchPreviewProducts rewrite (preview-utils.ts:131-143) only touches product_card; format_card and batchPreviewFormats correctly left alone -- only the product surface changed in beta.2.
• OutcomeMeasurement rename. Type alias to OutcomeMeasurementDeprecated (compat.ts:15, 22) plus index.ts re-export -- wire shape unchanged, adopter imports preserved, deprecation visible at the new identifier.
• No transport reimplementation. New code is post-unwrap object manipulation. Generated agent surface at agents/index.generated.ts:155-178 delegates to ProtocolClient.callTool plus unwrapProtocolResponse. Official @a2a-js/sdk and @modelcontextprotocol/sdk paths intact.

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

1. L1 MCP error branch missing envelope status. src/lib/utils/response-unwrapper.ts:315-323 synthesizes an adcp_error-shaped envelope with no top-level status, while the sibling synthetic envelope at :371 correctly carries status: 'failed' as const. Both are 3.1-strict-validator surfaces. Add status: 'failed' as const to the L1 raw-text fallback to match.
2. wrapStoreSuccess 'status' in result bypass. src/lib/server/test-controller.ts:614-617 -- the in-operator returns true when an adopter explicitly sets status: undefined, short-circuiting injection and producing an envelope with undefined status that fails wire validation. Match the truthiness check at envelope-status-compat.ts:74 (response.status truthy, not just in).
3. Changeset coordination produces 9.0.0-beta.0, not 8.x-beta.N. Six changesets in this PR: cut-8-0-beta.md is minor (intentionally demoted in the merge commit), the other five (asset-variant-array-slots, governance-agents-categories-removed, outcome-measurement-rename, product-card-self-rendering, promote-query-upstream-traffic) are major. Under changesets pre-mode the highest bump wins per release, so the next changeset version will compute 9.0.0-beta.0 from the current 8.0.0 initialVersion -- undoing the merge-commit-documented "stays on the 8.x line" intent. Either demote the five follow-ups to minor (intra-beta surface churn, not first-publish-of-major bumps) or update the foundation plan plus the cut-8-0-beta.md body to acknowledge the line is actually 9.0-beta.
4. Envelope shim no-version-fields-to-legacy branch. src/lib/utils/envelope-status-compat.ts:50-51 grants status synthesis to ANY version-less payload. A buggy or compromised 3.1 peer that omits both adcp_version and adcp_major_version gets the leniency and passes strict 3.1 envelope validation. Tighten to strict-reject once 3.1 GA ships (or now -- the SDK's own server stamps adcp_version, and a peer that does not is already drifting from spec). Witness-not-translator points the same direction.
5. Shim is blind to legacy task_status and response_status. Per the spec note at tools.generated.ts:1151 ("Agents MUST NOT emit the legacy task_status or response_status fields alongside this field"), a 3.0.x payload carrying task_status: 'submitted' with no top-level status gets stamped completed by the synthesizer. Extend isLegacy30xPayload and injectLegacyEnvelopeStatus to read the legacy fields before defaulting to completed or failed.
6. Changeset body cites 3.1.0-beta.2; actual pin is 3.1.0-beta.3. .changeset/cut-8-0-beta.md:5,7,17 will land in CHANGELOG.md verbatim once the Release PR runs. Update before cut.
7. schema-validator.ts v2-vs-v3 leakage. validation/schema-validator.ts:695-711 runs injectLegacyEnvelopeStatus before the isV2Bundle gate, so a v2.x seller that omits both adcp_version and adcp_major_version lands in the no-version-fields-to-legacy branch and gets status: 'completed' injected. Mostly harmless because v2 schemas are additionalProperties: true, but cross-version leakage is a code smell. Gate on parseAdcpMajorVersion(version) === 3 || version == null.

Minor nits (non-blocking)

1. testing/client.ts:676-679 does not strip _message pre-inject. Other call sites do (response-unwrapper.ts:162-166, storyboard/validations.ts:471-482). Low-risk because raw wire data here typically does not carry _message, but the inconsistency is worth a one-line comment or a symmetric strip.
2. A2A extraction-layer divergence. core/ResponseValidator.ts:301-309 reads artifacts[0].parts[0].data (FIRST artifact, FIRST data part); the canonical unwrapper at response-unwrapper.ts:508-520 reads LAST of both (conversational-protocol semantics). Pre-existed this PR; the new shim amplifies the divergence -- missing status may be caught on one extractor but not the other. Worth a separate cleanup PR.
3. responses.ts:178 capabilitiesResponse spread order. Spreading data first and status: 'completed' last overwrites any adopter-set status silently. Today GetAdCPCapabilitiesResponse does not carry status on its typed surface so this is theoretical, but spreading status first is the safer default since the auto-registered handler at create-adcp-server.ts:5048 already stamps it upstream -- making the in-builder stamp a backstop, not the source of truth.
4. buyer-retry-policy.ts:77 doc-comment lists RETENTION_EXPIRED as a terminal example, but RETENTION_EXPIRED is not in DEFAULT_CODE_POLICY and the ErrorCode manifest dropped it in beta.3 (STALE_RESPONSE replaced it). Either re-add the code if the spec still emits it, or drop the reference so a copy-paste into an override does not land on a stale code.
5. enforceMapCap is exported but not enforced. The TestControllerStore interface JSDoc names it in the example but does not require it. An adopter who forgets the cap in their custom forceAccountStatus is vulnerable to a sandbox caller looping over fresh IDs. Consider a BoundedSessionMap wrapper class for adopters, or strengthen the per-method JSDoc on the interface.
6. envelope-status-compat.ts:67 generic constraint lies on the null edge. <T extends Record<string, unknown>> plus the return response on non-object input means injectLegacyEnvelopeStatus(null) returns null typed as T. Runtime fine; type is sloppy. Widen the signature to T | null | undefined or add a runtime-guard JSDoc note.

Approving on the strength of the V2/V3 ergonomic strategy plus the clean overlay-drain pattern. The forward-compat overlay plus manifest absorption plus compile-time disjointness check is the textbook ratchet -- that part is worth borrowing into adjacent SDKs.