@mcpdesc/validator 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -8,6 +8,15 @@ Dates for published releases are the UTC publication dates recorded by npm.
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-09-08
+
+### Fixed
+
+- Added terminal-target provenance to RC.4 component reference resolution and
+	enabled RC.4 through the public resolver. This is an approved additive
+	tooling-metadata correction; schemas, conformance results, diagnostics, and
+	frozen fixtures are unchanged.
+
 ## [0.11.0] - 2026-09-08
 
 ### Added
@@ -155,7 +164,8 @@ Dates for published releases are the UTC publication dates recorded by npm.
 - Added synchronous structural and semantic validation for parsed JavaScript values with deterministic diagnostics and exact selector dispatch.
 - Added ESM browser support, TypeScript declarations, embedded schema provenance, frozen fixtures, and package-content checks.
 
-[Unreleased]: https://github.com/mcpdesc/core/compare/validator-v0.11.0...HEAD
+[Unreleased]: https://github.com/mcpdesc/core/compare/validator-v0.11.1...HEAD
+[0.11.1]: https://github.com/mcpdesc/core/compare/validator-v0.11.0...validator-v0.11.1
 [0.11.0]: https://github.com/mcpdesc/core/compare/validator-v0.10.1...validator-v0.11.0
 [0.10.1]: https://github.com/mcpdesc/core/compare/validator-v0.10.0...validator-v0.10.1
 [0.10.0]: https://github.com/mcpdesc/core/compare/validator-v0.9.0...validator-v0.10.0

package/README.md

@@ -57,9 +57,8 @@ should select RC.4. Earlier selectors remain available by pinning an older
 immutable validator release. npm integrity and trusted-publishing provenance identify released
 package bytes; specification repository tags and commits are informational.
 
-Component reference resolution remains available for RC.3. RC.4 validation is
-supported, but its snapshot resolver does not expose the terminal-target
-provenance required by the package's public resolution result contract.
+Component reference resolution is available for RC.3 and RC.4 with
+terminal-target provenance for each authored reference.
 
 ## Usage
 
@@ -141,9 +140,9 @@ maturity only; it does not validate extension-specific settings.
 
 npm package SemVer tracks implementation releases independently from specification snapshot identity. Adding a later snapshot is additive: it must use a sibling implementation and selector rather than changing an existing snapshot's schema, semantics, metadata, fixtures, or results.
 
-The RC.3 component resolver reports authored and terminal target paths for
-successful substitutions. RC.4 component resolution is unavailable because its
-snapshot resolver does not expose that provenance result.
+The RC.3 and RC.4 component resolvers report authored and terminal target paths
+for successful substitutions. Additive tooling corrections that provide this
+metadata are recorded explicitly in the integrity manifest.
 
 The runtime bundles its schema, performs no network fetches for external schema references, and imports no Node.js built-ins. Unresolved external Tool-schema references produce incomplete-validation warnings and are preserved. All three ESM entry points support Node.js 20 or later and browser bundlers.
 

package/index.d.ts

@@ -38,7 +38,7 @@ export interface McpDescriptionComponentResolutionResult {
 }
 
 export interface ResolveMcpDescriptionComponentReferencesOptions {
-  readonly specification: '0.8.0-rc.3';
+  readonly specification: '0.8.0-rc.3' | '0.8.0-rc.4';
 }
 
 export type McpExtensionMaturity = 'official' | 'experimental' | 'uncatalogued';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpdesc/validator",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Structural and semantic validation for MCP Description snapshots",
   "type": "module",
   "types": "./index.d.ts",

package/src/index.js

@@ -1,6 +1,7 @@
 import * as rc3 from './snapshots/0.8.0-rc.3/index.js';
 import * as rc4 from './snapshots/0.8.0-rc.4/index.js';
 import { resolveComponentReferences as resolveRc3ComponentReferences } from './snapshots/0.8.0-rc.3/semantic.js';
+import { resolveComponentReferences as resolveRc4ComponentReferences } from './snapshots/0.8.0-rc.4/semantic.js';
 import {
   mcpExtensionCatalogue,
   mcpExtensionMaturity
@@ -14,7 +15,8 @@ const snapshots = Object.freeze({
 });
 
 const componentResolvers = Object.freeze({
-  '0.8.0-rc.3': resolveRc3ComponentReferences
+  '0.8.0-rc.3': resolveRc3ComponentReferences,
+  '0.8.0-rc.4': resolveRc4ComponentReferences
 });
 
 const schemaUris = Object.freeze({

package/src/snapshots/0.8.0-rc.4/semantic.js

@@ -62,6 +62,7 @@ function componentDiagnostic(code, rel, message, path) {
 export function resolveComponentReferences(document, rel = 'document') {
   const resolved = structuredClone(document);
   const diagnostics = [];
+  const provenance = [];
   let substitutions = 0;
 
   function resolve(reference, expectedNamespace, path, stack = []) {
@@ -75,7 +76,7 @@ export function resolveComponentReferences(document, rel = 'document') {
         `must target #/components/${expectedNamespace}, not #/components/${namespace}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
 
     const key = `${namespace}/${name}`;
@@ -86,7 +87,7 @@ export function resolveComponentReferences(document, rel = 'document') {
         `forms a cycle through ${[...stack, key].join(' -> ')}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
 
     const target = document?.components?.[namespace]?.[name];
@@ -97,18 +98,29 @@ export function resolveComponentReferences(document, rel = 'document') {
         `targets missing component ${JSON.stringify(reference.$componentRef)}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
     substitutions += 1;
     return isReferenceObject(target)
       ? resolve(target, expectedNamespace, path, [...stack, key])
-      : structuredClone(target);
+      : {
+          value: structuredClone(target),
+          targetPath: ['components', namespace, name]
+        };
+  }
+
+  function substitute(reference, expectedNamespace, path, stack = []) {
+    const result = resolve(reference, expectedNamespace, path, stack);
+    if (result.targetPath) {
+      provenance.push({ referencePath: path, targetPath: result.targetPath });
+    }
+    return result.value;
   }
 
   for (const namespace of componentNamespaces) {
     for (const [name, value] of Object.entries(document?.components?.[namespace] ?? {})) {
       if (isReferenceObject(value)) {
-        resolved.components[namespace][name] = resolve(value, namespace, ['components', namespace, name], [`${namespace}/${name}`]);
+        resolved.components[namespace][name] = substitute(value, namespace, ['components', namespace, name], [`${namespace}/${name}`]);
       }
     }
   }
@@ -124,7 +136,7 @@ export function resolveComponentReferences(document, rel = 'document') {
       if (collection === 'tools') {
         for (const field of ['inputSchema', 'outputSchema']) {
           if (isReferenceObject(declaration[field])) {
-            resolvedDeclaration[field] = resolve(declaration[field], 'schemas', [collection, declarationIndex, field]);
+            resolvedDeclaration[field] = substitute(declaration[field], 'schemas', [collection, declarationIndex, field]);
           }
         }
       }
@@ -138,7 +150,7 @@ export function resolveComponentReferences(document, rel = 'document') {
             : 'promptExamples';
       for (const [name, example] of Object.entries(declaration.examples ?? {})) {
         if (isReferenceObject(example)) {
-          resolvedDeclaration.examples[name] = resolve(
+          resolvedDeclaration.examples[name] = substitute(
             example,
             exampleNamespace,
             [collection, declarationIndex, 'examples', name]
@@ -152,7 +164,7 @@ export function resolveComponentReferences(document, rel = 'document') {
     for (const [declarationIndex, declaration] of (document?.[collection] ?? []).entries()) {
       for (const [elicitationIndex, elicitation] of (declaration.elicitations ?? []).entries()) {
         if (isReferenceObject(elicitation.requestedSchema)) {
-          resolved[collection][declarationIndex].elicitations[elicitationIndex].requestedSchema = resolve(
+          resolved[collection][declarationIndex].elicitations[elicitationIndex].requestedSchema = substitute(
             elicitation.requestedSchema,
             'schemas',
             [collection, declarationIndex, 'elicitations', elicitationIndex, 'requestedSchema']
@@ -162,7 +174,7 @@ export function resolveComponentReferences(document, rel = 'document') {
     }
   }
 
-  return { document: resolved, diagnostics, substitutions };
+  return { document: resolved, diagnostics, substitutions, provenance };
 }
 
 function structuralPath(document, error) {