Skip to content

fix(server): keep a preview ceiling's derived window to that preview - #3740

Open
bokelley wants to merge 2 commits into
mainfrom
fix/3597-preview-ceiling-leak
Open

bokelley wants to merge 2 commits into
mainfrom
fix/3597-preview-ceiling-leak

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Closes #3597.

Where the issue stands

#3707 (merged on main) already fixed the issue's negotiation problems: a release pin never selects a prerelease, a prerelease pin matches exactly, and MCP tools/list stamps the listing release rather than the ceiling. I checked them again on main with adcpVersion: '3.3-rc.0' and defaultAdcpVersion: '3.2'. 3.2, 3.3 and 3.4 pins are served 3.2, 3.3-rc.0 is served the preview, 3.3-rc.1 gets VERSION_UNSUPPORTED, and major-only and unpinned callers are unchanged. This PR closes the two items #3707 left open.

1. Derived window of a preview ceiling (point 3, first bullet)

With a prerelease adcpVersion and no capabilities.supported_versions (or only major_versions, or a major-only supported_versions entry), the server built its advertised and negotiable window from every bundled release up to the ceiling. That included the SDK's own packaged prerelease. A seller that registered a different preview with registerExternalSchemaRoot therefore also advertised and served the SDK's preview. On main, a seller with an external 3.99.0-beta.0 ceiling advertised ["3.0","3.1","3.2","3.3-rc.0","3.99-beta.0"] and served a 3.3-rc.0 pin.

bundledReleasesForMajors now leaves out bundled prereleases when the configured ceiling is itself a prerelease. The configured preview is still added, so a server whose ceiling is the SDK's own preview (the default on 17.x) advertises exactly what it did before. A stable ceiling keeps its current window. That matters because identity33 defaults to '3.3' and is reached by SDK 17 clients pinned to 3.3-rc.0.

2. Response projection through the ceiling (point 2)

The issue's minimum ask was to document this. #3707 deliberately kept the contract: requests are converted up to the ceiling, and responses are read in the ceiling's shape and converted down. Changing that would break existing integrations. The adcpVersion JSDoc now says so, and says that raising the ceiling to a preview changes the shape handlers return for older pins. The issue's concrete case no longer differs between ceilings on main: a check_governance handler that returns the 3.0 status: "approved" shape to a 3.0 pin gets the same response under a 3.2 and a 3.3-rc.0 ceiling.

No per-request selection hook is added (the second ask in the comments). With pins resolved correctly, servers no longer need to rewrite them.

16.x

16.x has the original point 1 bug: it lacks #3707. It packages no prerelease, but a seller can enable a preview through registerExternalSchemaRoot, and then a 3.3 or 3.4 pin is served the preview. The backport of #3707 is #3739. The change in this PR is not needed on 16.x, because it only removes a packaged SDK prerelease from the window and 16.x packages none.

Tests

  • New createAdcpServer test that registers an external preview root and covers a derived window, major_versions: [3], and supported_versions: ['3', preview]. It checks the advertised window, that every SDK-packaged preview pin gets VERSION_UNSUPPORTED, and that stable pins stay on stable releases. It fails on main without the fix.
  • Full test:node suite passes. typecheck, lint, prettier and generate-agent-docs show no drift. generate-registry-types -- --sync shows no drift, so no registry change is included.

🤖 Generated with Claude Code

Closes the remaining negotiation item of #3597. #3707 already keeps release
pins off previews and matches prerelease pins exactly. This removes the last
leak in negotiation: with a prerelease adcpVersion and no
capabilities.supported_versions, createAdcpServer derived its advertised and
negotiable window from every bundled release up to the ceiling, including the
SDK's own packaged prerelease. A seller that registered a different preview
with registerExternalSchemaRoot therefore also advertised and served the
SDK's preview. The derived window now holds the stable releases plus the
configured preview. A stable ceiling (identity33 defaults to 3.3) keeps its
current window.

The adcpVersion docs now state the handler contract the issue asked to have
documented: handlers run in the ceiling release for every caller, so raising
the ceiling to a preview changes the shape handlers return for older 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 diff, no blocking or medium findings.

Reviewed all 3 files (94 additions / 3 deletions). The negotiation fix in src/lib/server/create-adcp-server.ts drops SDK-bundled prereleases from the derived window only when the configured ceiling is itself a prerelease, re-adding the seller's configured preview via the existing opt-in block — consistent with existing prerelease comparison semantics, and the happy path (stable ceiling) is unchanged. The test covers all three capability shapes with cleanup, and a right-sized patch changeset is present for this #3597 bug fix (no removed/renamed export or response-shape change, so patch is correct).

Decision table: no critical/high findings (row 1 n/a). gated_paths: false (row 2 n/a). high_risk: false (rows 3/5 n/a). No medium findings (rows 4/8 n/a). No prior escalation (row 6 n/a). No no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve. Note: review_decision is REVIEW_REQUIRED, but with gated_paths: false this does not block approval.

@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.

Delta is 3 files / ~142 lines: one logic line in bundledReleasesForMajors (src/lib/server/create-adcp-server.ts) that drops SDK-bundled prereleases from the derived window when the configured ceiling is itself a preview, a matching doc block, and a test covering all three capability shapes with an external schema root. Logic is correct (stable ceilings untouched, configured preview re-added below), and the patch changeset type fits a preview-path fix.

Checked gates: no critical/high/medium findings (table row 1/4 N/A); gated_paths false; high_risk false; no no-auto-approve team match; review_decision APPROVED. This is a subsequent push after a prior approve with no new findings. Falls through to row 9.

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.

createAdcpServer: a prerelease preview ceiling leaks into stable negotiation and stable response shapes

1 participant