Skip to content

chore: update spec.types.ts from upstream #2027

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
+1 −1
Open

chore: update spec.types.ts from upstream #2027

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/core-internal/src/types/spec.types.2026-07-28.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
*
* Source: https://github.com/modelcontextprotocol/modelcontextprotocol
* Pulled from: https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/draft/schema.ts
* Last updated from commit: f68d864a813754e188c6df52dcc5772a12f96c63
* Last updated from commit: 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184

Check failure on line 6 in packages/core-internal/src/types/spec.types.2026-07-28.ts

View check run for this annotation

Claude / Claude Code Review

Anchor provenance bumped without atomically refreshing schema-twin/example-corpus manifests (lifecycle rule 4) 

This sync bumps the anchor's provenance header to upstream commit `2ffc3fa2`, but the derived twins that the repo's OPERATIVE lifecycle rule 4 requires to be refreshed in the same commit still pin the old commit `f68d864a`: `packages/core-internal/test/corpus/schema-twins/manifest.json` and `test/corpus/fixtures/2026-07-28/manifest.json`. Please run `pnpm fetch:schema-twins 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184` (and `pnpm fetch:spec-examples` if upstream examples changed) in this PR so both

@claude claude Bot Jun 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔴 This sync bumps the anchor's provenance header to upstream commit 2ffc3fa2, but the derived twins that the repo's OPERATIVE lifecycle rule 4 requires to be refreshed in the same commit still pin the old commit f68d864a: packages/core-internal/test/corpus/schema-twins/manifest.json and test/corpus/fixtures/2026-07-28/manifest.json. Please run pnpm fetch:schema-twins 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184 (and pnpm fetch:spec-examples if upstream examples changed) in this PR so both manifests record the same commit as the anchor — and longer-term, the nightly cron workflow should regenerate the twins alongside the anchor, since it currently only runs fetch:spec-types and only git adds the anchor file.

Extended reasoning...

What the bug is

This automated sync updates the 2026-07-28 anchor's provenance header to upstream commit 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184 (packages/core-internal/src/types/spec.types.2026-07-28.ts:6), but it does not refresh the derived artifacts that the repo's own lifecycle policy ties to that anchor. packages/core-internal/src/types/README.md lifecycle rule 4 — explicitly marked OPERATIVE — states: "any refresh that changes the anchor must regenerate those artifacts in the same commit. The anchor and its derived twins must never be out of sync at any commit on main." It then names the governed artifacts: the vendored schema.json twins under packages/core-internal/test/corpus/schema-twins/ (whose manifest.json records the source commit and content hashes), and the spec example corpus manifest (test/corpus/fixtures/<revision>/manifest.json), which "follows the same atomicity rule when the examples are re-vendored."

The code path / state that triggers it

After this PR merges, the repository on main is in exactly the state rule 4 forbids:

  1. The anchor header (spec.types.2026-07-28.ts:6) says Last updated from commit: 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184.
  2. packages/core-internal/test/corpus/schema-twins/manifest.json:5 still records \"commit\": \"f68d864a813754e188c6df52dcc5772a12f96c63\" — and its own header comment says refreshes must happen "ATOMICALLY with the matching spec.types anchor (see … lifecycle rule 4)".
  3. packages/core-internal/test/corpus/fixtures/2026-07-28/manifest.json:6 likewise still records f68d864a.
  4. So the anchor and its derived twins disagree about which upstream commit they were generated from, on every commit of main from the merge onward.

Why existing checks don't prevent it

This divergence lands silently. schemaTwinConformance.test.ts only hashes the vendored twin bytes against the manifest's own sha256/bytes entries and validates fixtures against the twin — it never cross-checks the manifest's source.commit against the anchor header's commit. Because the anchor's TypeScript body is byte-identical in this diff (only the provenance line changed), the content lock stays green and CI gives no signal. The README anticipates a content mismatch being "the desired loud signal of a missed twin update", but a header-only bump produces a provenance-only mismatch that nothing detects.

The root cause is structural: .github/workflows/update-spec-types.yml only runs pnpm run fetch:spec-types 2026-07-28 (line 48) and only git adds the anchor file (line 73). fetch:schema-twins and fetch:spec-examples are separate scripts that the cron job never invokes, so every nightly sync that bumps the anchor will recreate this violation.

Step-by-step proof

  1. Merge this PR as-is.
  2. On main, run grep 'Last updated from commit' packages/core-internal/src/types/spec.types.2026-07-28.ts → 2ffc3fa2….
  3. Run grep '\"commit\"' packages/core-internal/test/corpus/schema-twins/manifest.json packages/core-internal/test/corpus/fixtures/2026-07-28/manifest.json → both say f68d864a….
  4. This is the out-of-sync state rule 4 says "must never" exist at any commit on main, and the schema-twins manifest's "ATOMICALLY with the matching spec.types anchor" instruction has been violated.
  5. pnpm vitest run test/wire/schemaTwinConformance.test.ts stays green, so nothing flags it.

Impact

Beyond the policy violation itself, the practical risk is that the vendored test oracles silently go stale: if upstream's generated schema.json or examples changed between f68d864a and 2ffc3fa2 (descriptions, required lists, examples), the conformance suites would be validating against an older oracle while the anchor claims a newer commit, and the manifests would be lying about their provenance. (Mitigating fact: the anchor's TS body is byte-identical here, so the twin content is likely unchanged — but the only way to know, and the thing the policy demands, is to regenerate and re-pin in the same commit.)

How to fix

In this PR: run pnpm fetch:schema-twins 2ffc3fa2d00e637ae7c3d1438aaa0561ddfda184 (and pnpm fetch:spec-examples if upstream examples changed) so the twin and both manifests record the same commit as the anchor — or, if the twins are intentionally being left at f68d864a, document why in the PR. Longer-term, update .github/workflows/update-spec-types.yml to run the twin/example fetch scripts and git add their outputs alongside the anchor, so the nightly sync can satisfy rule 4 on its own; optionally add a check in schemaTwinConformance.test.ts that compares the manifest's source.commit to the anchor header so a future provenance-only divergence fails loudly.

*
* DO NOT EDIT THIS FILE MANUALLY. Changes will be overwritten by automated updates.
* To update this file, run: pnpm run fetch:spec-types 2026-07-28
Expand Down