Simplify specification compatibility and snapshot provenance from RC.3

[ObjectIsAdvantag]

Problem

The current validator snapshot intake policy couples an exact MCP Description selector to an immutable specification repository tag and source commit, a complete exported runtime/fixture manifest, and a second integrity baseline in this repository. That makes unrelated maintenance of specification changelogs, FAQs, and guides difficult after a release candidate is published.

The coupling is stronger than the consumer requirement. Consumers need a validator package version and exact selector to provide stable schema and validation behavior. They do not need every non-normative file in the specification repository to remain attached to the same Git commit.

RC.2 demonstrates the pain: documentation corrections leave the normative specification, schema, semantic validator, examples, and fixtures unchanged, but downstream provenance records make correcting the release tag impractical.

Proposed trust model

Starting with MCP Description 0.8.0-rc.3:

• treat the published @mcpdesc/validator package as the executable conformance authority;
• keep npm package versions and exact validator selectors immutable;
• embed the schema and semantic implementation used by each selector in the validator package;
• keep the schema SHA-256 and focused frozen-fixture tests as inexpensive integrity evidence;
• document an explicit compatibility mapping among specification selector, validator version, and core version;
• allow non-normative specification repository documentation to evolve independently;
• require a new specification selector only when normative text, schema identity or behavior, semantic validation, or conformance fixtures change; and
• rely on npm package integrity and trusted-publishing/SLSA provenance for released package bytes.

The required invariant is: given a validator package version and exact selector, users receive identical schema and validation behavior. Whole specification-repository commit immutability is not a required consumer invariant.

Existing selectors, package versions, tags, and published behavior remain untouched.

Implementation plan

1. Define policy boundaries

• Update root and validator guidance to distinguish immutable package/selector behavior from mutable non-normative repository documentation.
• State which specification changes require a new selector: normative text, canonical schema bytes or $id, semantic validator behavior, and conformance fixtures.
• State that changelogs, FAQs, guides, governance, and release-page prose may be corrected without a validator release when they do not alter those inputs.
• Keep core package and validator package release tags immutable.

2. Simplify RC.3 intake

• Add 0.8.0-rc.3 as a new sibling selector; do not alter existing selectors.
• Replace the source-tag/source-commit intake requirement with reviewed embedded schema/runtime files and frozen fixture tests.
• Retain the schema SHA-256 exported through specificationProvenance.
• Stop requiring a copied specification export manifest and source commit as validator integrity inputs for RC.3 and later.
• Keep the local snapshot integrity check for package-owned immutable selector bytes, or simplify it to cover only package-owned runtime and fixture files.

3. Publish compatibility metadata

• Add a maintained table mapping specification selectors to the first supporting validator and core versions.
• Document whether each core operation supports RC.3 in the existing operation-by-selector matrix.
• Keep exact selector resolution; never infer RC.3 from mcpdesc: "0.8.0" alone.

4. Tests and package checks

• Test that RC.3 schema bytes match the exported SHA-256.
• Run all RC.3 frozen fixtures against default, browser, and standalone entries.
• Test selector immutability and exact resolution.
• Update declarations, browser checks, package contents, isolated consumers, and the exhaustive core support contract.
• Verify existing selectors and fixture outcomes remain unchanged.

5. Release sequencing

• Publish the specification RC.3 first.
• Release @mcpdesc/validator with RC.3 support and verify npm integrity/provenance.
• Release @mcpdesc/core only if it adds RC.3 support or updates its validator dependency.
• Consumer repositories then update package versions and opt into the exact RC.3 selector.

Acceptance criteria

• Existing selectors and published package behavior are unchanged.
• RC.3 validation remains deterministic, offline, browser-safe, and strict-CSP compatible.
• The same validator package version and selector always produce the same schema and validation behavior.
• Specification documentation corrections do not require a validator or core release.
• Package provenance remains tied to immutable core repository release tags and commits.
• Documentation clearly distinguishes specification, validator package, and core package version axes.

Non-goals

• Moving or recreating any existing tag.
• Retargeting an existing selector.
• Inferring prerelease selectors from the unqualified format version.
• Weakening npm trusted publishing, package integrity, or SLSA provenance.
• Treating validator package versions and core package versions as the specification version.

Compatibility

This is a process and provenance simplification for RC.3 and later. It does not change the public behavior of Draft 1 through RC.2. RC.3 is additive and consumers opt into it explicitly.

AI assistance

GitHub Copilot analyzed the current snapshot, release, and provenance policies and drafted this proposal. The maintainer remains accountable for the decision and implementation.

[ObjectIsAdvantag]

Proposed RC.3 rollout

Specification repository

RC.3 can be published now as a clean transition point. It should contain:

• the corrected RC.2 changelog and FAQ text currently pending;
• the new v0.8.0-rc.3 release identity and date;
• the mechanically updated RC.3 schema $id, status metadata, front matter, assembled specification metadata, and $schema references; and
• otherwise the same normative requirements, schema validation behavior, semantic validation behavior, examples, and conformance fixtures as RC.2.

The RC.3 release notes should say explicitly that it is behavior-equivalent to RC.2 and introduces the simplified compatibility/provenance policy. Do not move or recreate RC.2. Future non-normative documentation corrections should merge to the default branch and may update the editable GitHub release description without requiring a new selector or validator release.

Before tagging RC.3, merge the policy change that defines normative inputs versus maintainable companion documentation. Run the existing RC, publication, repository, and diff checks. The existing exporter may still be used as a convenient transfer mechanism for RC.3, but its source commit and tag should be informational rather than part of the validator consumer contract.

Core repository

Suggested release sequence:

1. Land the policy and intake simplification without changing existing selectors.
2. Add RC.3 to @mcpdesc/validator as a sibling and preserve every existing selector byte.
3. Publish validator, likely as 0.10.0 because adding a selector is an additive pre-1.0 feature.
4. Decide RC.3 support independently for every core operation and update the exhaustive support matrix.
5. If core supports RC.3, publish core, likely as 0.9.0, pinned to the released validator version.
6. Publish a compatibility table such as 0.8.0-rc.3 -> validator 0.10.0 -> core 0.9.0. Final versions remain a maintainer decision.

Consumer repositories

Public GitHub code search currently finds no mcpdesc organization repository outside mcpdesc/core importing or depending on @mcpdesc/core or @mcpdesc/validator. No coordinated consumer release is therefore currently required.

When consumers adopt RC.3:

• direct validator users update @mcpdesc/validator, select 0.8.0-rc.3, and use the RC.3 schema URI;
• core users update @mcpdesc/core, use RC.3 only for operations marked supported, and normally do not add a direct validator dependency;
• applications update generated examples or defaults only when intentionally changing their advertised specification baseline;
• lockfiles and fixture expectations are refreshed;
• RC.2 compatibility tests remain in place; and
• historical RC.2 documents and links are not rewritten.

Private or unindexed consumers should be inventoried separately before changing any organization-wide default.