Skip to content

fix(build): keep GA-superseded prerelease snapshots out of the runtime image - #9093

Draft
bokelley wants to merge 1 commit into
mainfrom
fix/runtime-image-prune-superseded-prereleases
Draft

bokelley wants to merge 1 commit into
mainfrom
fix/runtime-image-prune-superseded-prereleases

Conversation

@bokelley

@bokelley bokelley commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Correction, after CI: this PR does not change the image. The "Production Docker build" log on this PR reads retained 6 docs snapshots; pruned 0 GA-superseded prerelease snapshots (none) and Runtime application size: 7366 MiB, the same as main. .dockerignore (#8814) already sends only the six docs.json snapshots into the build context, so no superseded prerelease docs reach the image. The local figures below came from a full git checkout, which .dockerignore does not filter, so they overstate the savings. The image's weight is in dist/schemas. The superseded prereleases that are still in the image are there because published-versions.json lists them for hosted grading. They are 3.1.0-beta.7, 3.1.0-rc.4, rc.6, rc.7 and rc.10, plus 3.2.0-rc.0 through rc.6, and together they hold about 1.1 GiB of schemas. Removing them is a hosted-grading policy decision, not a build change. This PR stays a draft and is not for merge as the fix for #9091.

Summary

The runtime image bundles every dist/docs/<v> snapshot. Nothing in the app reads most of them. This PR stops bundling docs snapshots of prereleases whose line has gone GA: a prerelease X.Y.0-(beta|rc).N counts as superseded once X.Y has a stable release. It keeps a superseded snapshot when docs.json, published-versions.json, a schema discovery alias or RETAINED_SCHEMA_BUNDLES names that version. Every 3.3 prerelease stays, because 3.3 has no GA yet. Nothing is deleted from git, and the CDN and Mintlify keep serving everything.

Draft: this change alone does not give rc.2 (#9091) the headroom we targeted. The numbers are below. Because the build hard-links identical files across snapshots, removing 21 snapshots frees only 134 MiB. The decision on how far to widen the prune is open.

Size

I measured with the image's own steps on a full clone of each tree: npm run build:schemas, build:compliance, build:protocol-tarball, then scripts/deduplicate-runtime-artifacts.cjs, then the prune. I compared du -sm dist under main's prune script against du -sm dist under this PR's. The measurement skips only the protocol offload, which downloads from the CDN, and the offload is the same on both sides. The difference between main and rc.2 under main's script is 172 MiB, which matches the gate exactly (7538 − 7366). So the dist difference carries straight into the gate's du -sm /app.

Tree Gate today dist, main's prune dist, this PR Freed Projected gate Headroom under 7424
main 859ea919 7366 MiB (CI) 8368 MiB 8234 MiB 134 MiB 7232 MiB 192 MiB
rc.2 e8923135 7538 MiB (CI, fails) 8540 MiB 8406 MiB 134 MiB 7404 MiB 20 MiB

This passes the rc.2 gate, but only by 20 MiB. The next RC adds about 172 MiB, which would overflow it again.

Wider options, measured on the same rc.2 clone:

Option Freed rc.2 projected gate Headroom
This PR: superseded prereleases, anchored versions kept 134 MiB 7404 MiB 20 MiB
Also drop the docs snapshots of the 13 superseded prereleases that hosted grading or training names (schemas and compliance stay) 230 MiB 7308 MiB 116 MiB
Keep only the docs.json snapshots (the only ones any runtime code reads) 619 MiB 6919 MiB 505 MiB

Consumer trace

Artifact Runtime consumer When a version isn't on local disk
dist/docs/<v> Addie's docs index (server/src/addie/mcp/docs-indexer.ts) reads only the snapshots docs.json navigation.versions names. It cites Mintlify URLs. The "Production docs index smoke" job checks exactly those versions. No effect. docs.json versions are always kept. None of them is a superseded prerelease today (they are 2.5.3, 3.0.28, 3.1.32, 3.2.8, 3.3.0-beta.5 and 3.3.0-rc.0).
/docs/<v>, /dist/docs/<v> on adcontextprotocol.org None. The Express app mounts no docs route, and both paths return a 404 from the app today. The docs site is Mintlify on docs.adcontextprotocol.org, built from git. Same 404 as today. Mintlify serves docs.adcontextprotocol.org/dist/docs/3.2.0-rc.7/… from git.
dist/schemas/<v> schemas-middleware.ts serves /schemas. The training agent (schema-compat.ts) uses retained and preview bundles. Hosted compliance uses published bundles. The Addie indexer uses docs.json versions. The schema keep set is unchanged by this PR: superseded prereleases were already pruned unless anchored. In production, the workers/artifact-cdn Worker answers adcontextprotocol.org/schemas/*, /compliance/* and /protocol/* from R2 before the app sees them. Checked live: /schemas/3.2.0-beta.0/index.json returns 200 with an R2 strong ETag and no fly-request-id, though that directory is not in the image.
dist/compliance/<v> hosted-compliance-version.ts (hostedComplianceOptions, bundledComplianceVersions) and forward-introduced-specialisms.ts. Not touched. Compliance is never pruned.
Schema discovery rewrite rewriteSchemaDiscovery filters dist/schemas/index.json to the schema keep set. Unchanged.

Superseded prereleases that a runtime list names are kept, docs snapshot included:

  • published-versions.json: 3.1.0-beta.7, 3.1.0-rc.4, rc.6, rc.7, rc.10, 3.2.0-beta.6 and 3.2.0-rc.0 through rc.7
  • RETAINED_SCHEMA_BUNDLES: 3.2.0-beta.6 and 3.2.0-rc.7

I didn't edit either list.

What's excluded

There are 21 docs snapshots: 3.0.0-beta.3; 3.0.0-rc.1 and rc.2; 3.1.0-beta.0, 1, 3 and 4; 3.1.0-rc.11, 13 and 15; 3.2.0-beta.0 through 5; and 3.2.0-beta.7 through 11.

Changes

  • scripts/prune-runtime-artifacts.cjs: adds manifest.docsSnapshots, prunes dist/docs to it, and makes verifyPrunedTree enforce the docs closure. A line counts as GA when any stable X.Y.z artifact exists. 3.2.0 shipped package-only, so the 3.2 line's first bundled stable is 3.2.1.
  • tests/runtime-artifact-pruning.test.cjs: covers a superseded prerelease pruned, a prerelease on a pre-GA line kept, superseded prereleases named by hosted grading, training or docs.json kept, a patch-only stable line, repeat runs, and a fail-closed check when a superseded snapshot survives.
  • Dockerfile: comment only.

There's no changeset, because this is build-only and must not change the pending rc.2 release.

Tests

  • npm run test:runtime-artifacts: 17 of 17 passed.
  • docs-indexer, hosted-compliance-version and training-agent-schema-compat unit tests: 75 of 75 passed.
  • schema-routing integration tests: 31 of 31 passed.
  • artifact-cdn-worker tests: 41 of 41 passed.
  • npm run typecheck and npm run precommit passed.

🤖 Generated with Claude Code

…e image

The runtime image bundled every dist/docs snapshot, but at runtime only
Addie's docs index reads dist/docs, and only the docs.json versions.
Mintlify serves the docs site from git, and the artifact CDN answers
/schemas, /compliance and /protocol from R2.

Prune dist/docs/<X.Y.0-(beta|rc).N> once the X.Y line has a stable
release, unless docs.json, hosted grading, a schema alias or a training
checkpoint names that version. 3.3 prereleases stay until 3.3 goes GA.
The pruned-tree check now also enforces the docs closure.

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

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