Audit: finish the 2026-07-28 spec lifecycle cutover #1

Context

Ginbing modelcontextprotocol#245-style review of modelcontextprotocol/typescript-sdk, run against upstream main at 7f7a94c22017e121a960e071bb50ec75e34450bd.

The goal is not to turn every observation into a PR. Each mechanism is classified by whether it still has a real consumer and whether changing it produces a smaller, clearer maintenance surface.

Findings

Product bugs outside these mechanisms should be handled separately and are not evidence that the architecture above should be removed.

Primary finding: unfinished 2026 release cutover

The independent requirement is valid: each supported MCP revision needs an accurate, reproducible upstream reference for parity and conformance checks.

The stale part is the producer/lifecycle around 2026-07-28:

2026-07-28 released
        ↓
SDK still maps it to schema/draft
        ↓
nightly workflow continues polling draft
        ↓
anchor-only refresh PRs continue after release

Upstream PR modelcontextprotocol#2252 explicitly said the draft mapping should be removed once schema/2026-07-28/ exists. That directory now exists.

Upstream PR modelcontextprotocol#2027 is still the automated draft-refresh PR. The repository's own lifecycle documentation requires generated reference artifacts to stay synchronized, while that workflow updates only the anchor.

Correct maintenance scope

The smallest justified action is one 2026 release-cutover PR:

• switch 2026-07-28 from schema/draft to schema/2026-07-28;
• pin it to the released source commit;
• regenerate the 2026 anchor, schema twin, example corpus, manifests, and parity/conformance evidence from that released source;
• include the final released SubscriptionsListenResultMetaObject / SubscriptionsListenResultResponse delta required by regeneration;
• remove the obsolete 2026 nightly draft updater;
• update lifecycle documentation and direct spec-name comments.

Do not include unrelated 2025 cleanup.

Repository-wide draft-reference sweep

A follow-up search found one additional operational stale reference: REVIEW.md still tells reviewers to compare types against main/schema/draft/schema.ts and calls that file the schema source of truth.

That instruction is now wrong for released revisions and belongs in the 2026 release cutover.

Other draft hits do not justify separate cleanup PRs:

• historical changelog entries describe what was true when those releases shipped;
• JSON Schema "draft-07"/"draft 2020-12" references are unrelated;
• conformance command/suite names may be imposed by the external conformance tooling;
• code comments describing what an earlier draft removed are historical rationale, not active authority.

Do not churn those files solely to remove the word "draft".

Follow-ups

• Decision: keep per-revision schema-twin provenance for the 2026 cutover #4 records why per-revision twin provenance is required for this cutover and why the CLI itself should remain unchanged.
• Cleanup: make the 2025 spec anchor reproducible from its release pin #5 tracks the 2025 anchor-header provenance mismatch. The schema content is unchanged, so this is a small cleanup.

PR strategy

A finding does not imply a PR. A KEEP result means no code change.

For upstream work:

• Direct PR for a straightforward, locally validated maintenance fix with clear behavior and narrow scope.
• Issue first when the change needs design agreement, changes a maintained internal contract/CLI, introduces a new mechanism, or has meaningful product/API trade-offs.
• Generated artifacts that must move atomically with their source change stay in the same PR even if that increases the file count.

The current 2026 cutover is maintenance work. The already-open upstream issue modelcontextprotocol#2857 is acceptable context, but a separate upstream issue was not strictly necessary for this scope.

Planned upstream PR count

Two upstream PRs are justified by this audit:

1. fix(spec): freeze 2026-07-28 release references modelcontextprotocol/typescript-sdk#2858 — finish the 2026-07-28 release cutover, including the stale REVIEW.md authority.
2. Cleanup: make the 2025 spec anchor reproducible from its release pin #5 — tiny 2025 anchor reproducibility/provenance cleanup. Implemented and validated as fork PR chore(spec): align 2025 anchor provenance with release pin #6; upstream PR creation is pending because the current GitHub integration returned 403 on create.

#4 is part of PR modelcontextprotocol#2858, not a separate PR. KEEP findings produce no PRs.

Implementation and current PR status are tracked in #2.