Skip to content

fix: keep stable pins off prerelease previews on SDK 16 - #3739

Open
bokelley wants to merge 3 commits into
16.xfrom
fix/16-prerelease-preview-pins
Open

bokelley wants to merge 3 commits into
16.xfrom
fix/16-prerelease-preview-pins

Conversation

@bokelley

@bokelley bokelley commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Backport of #3707 for #3597.

On SDK 16, selectServedAdcpRelease lets a release pin downshift onto an advertised prerelease, and lets an unlisted prerelease pin resolve to a different one. SDK 16 packages no prerelease, so this is reached only when a seller sets adcpVersion to a preview it registers with registerExternalSchemaRoot. Before this change, with an external 3.3.0-rc.0 root, adcpVersion: '3.3.0-rc.0' and supported_versions: ['3.0', '3.1', '3.2', '3.3-rc.0']:

  • a 3.3 or 3.4 pin was served 3.3-rc.0;
  • an unlisted 3.3-rc.1 pin was served 3.3-rc.0.

docs/reference/versioning.mdx ("Pre-release pins") forbids both.

This is a squash cherry-pick (-x) of #3707, and the production change is identical to main:

  • A release pin selects only releases. A prerelease pin matches an advertised prerelease exactly or gets VERSION_UNSUPPORTED, on direct invoke, MCP and A2A.
  • MCP tools/list keeps its lenient discovery fallback for an unsupported prerelease pin, and stamps each framework tool's _meta.adcp_version with the selected release instead of the ceiling.
  • Idempotency hashes the request as received, so a retry across a change from a stable to a preview ceiling replays.

One deviation from main, from review: the cherry-pick made tools/list throw VERSION_UNSUPPORTED for every unsupported stable pin (for example 3.0 against a server advertising 3.1 and 3.2), where 16.x listed the default release. That would change discovery for servers with no preview in a patch release, so 16.x keeps listing the default release for any unsupported pin. When the default is itself a preview, it lists the newest stable release instead, as #3707 does for prerelease pins. A new test covers the stable case.

The tests differ from main. The main tests used ADCP_VERSION as the preview, which is 3.2.10 on 16.x, so they register a minimal external 3.3.0-rc.0 root instead (test/helpers/external-preview-root.js). The changeset is reworded for 16.x.

The follow-up fix on main (#3740, the derived window of a preview ceiling) is not needed here: it removes a packaged SDK prerelease from that window, and 16.x packages none.

Validation

  • Before the fix, three of the backported tests fail on 16.x ('3.3-rc.0' == '3.2'). After it, the four touched files pass.
  • 231 test files that touch version negotiation, tools/list or adcp_version: 9,455 passed, 0 failed (after the discovery change).
  • build:lib, typecheck, lint, prettier, and generate-registry-types -- --sync (no drift).

🤖 Generated with Claude Code

Backport of #3707. selectServedAdcpRelease let a release pin downshift onto
an advertised prerelease, and let an unlisted prerelease pin resolve to a
different one. SDK 16 packages no prerelease, but a seller can set
adcpVersion to a preview it registers with registerExternalSchemaRoot. With
supported_versions ['3.2', '3.3-rc.0'], a 3.3 or 3.4 pin was served
3.3-rc.0, and 3.3-rc.1 was served 3.3-rc.0. Release pins now select only
releases, prerelease pins match exactly, and MCP tools/list stamps each
framework tool with the selected release.

The production change is identical to main. The main tests used
ADCP_VERSION as the preview, which is 3.2.10 on 16.x, so the tests register
a minimal external 3.3.0-rc.0 root instead (test/helpers/
external-preview-root.js). The changeset is reworded for 16.x.

(cherry picked from commit 5f61fde)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread src/lib/server/create-adcp-server.ts Resolved

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — prerelease-aware release selection with per-tool _meta.adcp_version projection; core logic sound and well-tested.

Medium findings

  • src/lib/server/create-adcp-server.ts:9839 — discoveryFallback makes tools/list fail-closed for all unsupported stable pins (not just preview servers), a behavior change broader than the patch changeset documents and untested for the non-preview path.

Reviewed the full diff: prerelease exact-match selection (stable pins never downshift onto a preview), the discoveryFallback helper, per-tool version projection in legacy and modern tools/list, and the test helper plus four suites. Changeset present (patch), official clients untouched, no witness/translator violations, uses parseFullAdcpRelease for patch comparison.

Decision: 1 medium finding, no critical/high, no gated paths (gated_paths=false), no high-risk flag, no author team gate, not a data-loss/schema/infra category. Falls through rows 1-8 to row 9 — approve. A single medium finding with no escalation trigger is not blocking.

Medium findings

  • src/lib/server/create-adcp-server.ts:9839 — Discovery fail-closed change is broader than changeset; untested for non-preview

The #3707 cherry-pick made tools/list throw VERSION_UNSUPPORTED for every
unsupported stable pin, where 16.x listed the default release. That is a
behavior change for servers with no preview, so 16.x keeps the old fallback.
When the default release is itself a preview, discovery lists the newest
stable release instead, as #3707 does for prerelease pins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — clean subsequent review; prior Medium resolved, no current findings.

This PR is a follow-up to the prior approve run. The prior Medium (create-adcp-server.ts:9839 — discovery fail-closed change broader than changeset and untested for non-preview) has been addressed: the guard removal makes discoveryFallback() lenient for every unsupported pin by listing the default release, a preview default still resolves to newest stable or throws VERSION_UNSUPPORTED rather than advertising an unnamed preview, the changeset prose now documents the behavior, and a new test covers the unsupported-stable-pin path.

Decision path: no critical/high findings (row 1 n/a); gated_paths false and review_decision APPROVED (row 2 n/a); high_risk false (rows 3/5 n/a); no medium findings (rows 4/8 n/a); prior decision was approve, not escalate (row 6 n/a); no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve.

Changeset present and consistent with the wire-behavior change; witness-not-translator posture preserved (fail-closed rather than fabricating a preview the caller did not request).

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — clean pass, no blocking or medium findings.

Reviewed: prerelease-aware release selection plus per-tool _meta.adcp_version on tools/list across 8 files (+257/-11). The stable branch now requires candidate.prerelease === undefined so stable pins never downshift onto a preview; the prerelease branch compares patch via the imported parseFullAdcpRelease (local parse drops patch) — load-bearing and correct. discoveryFallback stays lenient for stable defaults and fails closed (VERSION_UNSUPPORTED) only on a preview-only ceiling. _meta rewrite is gated to framework tools, preserving witness-not-translator. Changeset present; tests cover exact-match, non-downshift, patch/prerelease refusal, discovery leniency, and idempotency hash stability.

Gate check: gated_paths false, review_decision APPROVED, high_risk false, no no-auto-approve team match. No critical/high/medium findings. Prior decision was also approve. No decision-table rows 1–8 fire → row 9 approve.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant