Address review nits on synthetic _score collision guard

- Use OpenSearchIndex.METADATA_FIELD_SCORE constant in place of the bare
  "_score" literal for the mapping-field check.
- Drop "stored field" wording in the error message and code comment;
  the mapping does not use "store": true, so "user field" is what we
  actually mean.
- Scope the block comment to the _id / _score cases this PR actually
  locks in; drop the broader "(and most other metadata names)" claim.
- Shorten comments on the guard and both ITs to minimal WHY-only form.
- Assert HTTP 400 in testVectorSearchAgainstIndexWithScoreFieldRejects
  so the IT surfaces an accidental status-code regression explicitly.

Signed-off-by: Eric Wei <mengwei.eric@gmail.com>

Author: mengweieric

integ-test/src/test/java/org/opensearch/sql/sql/VectorSearchIT.java

@@ -437,28 +437,17 @@ public void testMissingRequiredArgRejected() throws IOException {
   }
 
   // Synthetic column collision (metadata vs. user field).
-  //
-  // v._score and v._id on a vectorSearch() relation are synthetic columns that expose the k-NN
-  // similarity score and the document metadata _id. A user-defined stored field of the same name
-  // would collide with these synthetic columns in the response tuple. Probe results on
-  // OpenSearch 3.6:
-  //   - _id: OpenSearch's mapper rejects a property named _id at mapping time, so no collision
-  //     is possible. The testUserMappingWithIdFieldIsRejectedByOpenSearch test locks this in.
-  //   - _score: OpenSearch accepts a property named _score. Left unchecked the SQL response
-  //     layer would fail with an opaque duplicate-key error when the hit's _source contains the
-  //     user field and the metadata _score both write to the same tuple key. VectorSearchIndex
-  //     therefore rejects the mapping at scan-build time with a clear SQL error; the
-  //     testVectorSearchAgainstIndexWithScoreFieldRejects test exercises that guard (works via
-  //     _explain so no k-NN plugin is needed).
+  // vectorSearch() exposes synthetic v._id and v._score columns. A user mapping property of the
+  // same name would collide on the response tuple key. OpenSearch blocks _id at mapping time;
+  // _score is not blocked, so VectorSearchIndex rejects it at scan-build time.
 
   @Test
   public void testUserMappingWithIdFieldIsRejectedByOpenSearch() throws IOException {
+    // Locks in OpenSearch's rejection of a user property named _id: without it, v._id could
+    // collide with a user field at response time. The exact error message belongs to OpenSearch.
     String indexName = "vs_collision_id";
     deleteIndexIfExists(indexName);
 
-    // OpenSearch rejects _id as a user mapping property; this guarantees v._id on a
-    // vectorSearch() relation always resolves to the document metadata _id. The exact error
-    // message belongs to OpenSearch; this test only locks in that the mapping creation fails.
     Request createIndex = new Request("PUT", "/" + indexName);
     createIndex.setJsonEntity("{\"mappings\":{\"properties\":{\"_id\":{\"type\":\"keyword\"}}}}");
 
@@ -467,15 +456,10 @@ public void testUserMappingWithIdFieldIsRejectedByOpenSearch() throws IOExceptio
 
   @Test
   public void testVectorSearchAgainstIndexWithScoreFieldRejects() throws IOException {
+    // _explain exercises planning (where the guard runs) without needing the k-NN plugin.
     String indexName = "vs_collision_score";
     deleteIndexIfExists(indexName);
 
-    // Unlike _id, OpenSearch accepts _score as a user-defined mapping property. Without the
-    // VectorSearchIndex guard, a vectorSearch() query against such an index would fail at
-    // response time with an opaque duplicate-key error because the stored _score field and the
-    // metadata _score both map to the same tuple key. The guard raises a clear SQL error
-    // up-front. Using _explain here exercises planning (which runs the guard) without needing
-    // the k-NN plugin.
     Request createIndex = new Request("PUT", "/" + indexName);
     createIndex.setJsonEntity("{\"mappings\":{\"properties\":{\"_score\":{\"type\":\"float\"}}}}");
     client().performRequest(createIndex);
@@ -490,6 +474,7 @@ public void testVectorSearchAgainstIndexWithScoreFieldRejects() throws IOExcepti
                         + "', field='embedding', vector='[1.0, 2.0]', option='k=5') AS v "
                         + "LIMIT 5"));
 
+    assertEquals(400, ex.getResponse().getStatusLine().getStatusCode());
     assertThat(ex.getMessage(), containsString("_score"));
     assertThat(ex.getMessage(), containsString("collides"));
   }

opensearch/src/main/java/org/opensearch/sql/opensearch/storage/VectorSearchIndex.java

@@ -75,20 +75,16 @@ public VectorSearchIndex(
 
   @Override
   public TableScanBuilder createScanBuilder() {
-    // Reject mappings that declare a user field named _score. OpenSearch rejects _id (and most
-    // other metadata names) at mapping time, but _score is not blocked there, so a user index
-    // can legitimately contain a stored _score field. If it did, the response path would collide
-    // with the synthetic v._score column (both get written to the same tuple key) and the query
-    // would fail with an opaque duplicate-key error. We check here so the user sees a clear,
-    // actionable SQL error instead, and so _explain surfaces the problem without sending a
-    // request to k-NN. Running in createScanBuilder keeps this out of the AstBuilder /
-    // TableFunction resolver paths which are off-limits for this change.
-    if (getFieldTypes().containsKey("_score")) {
+    // _score is not blocked at mapping time, so a user field named _score would collide with the
+    // synthetic v._score column on the response tuple and fail with an opaque duplicate-key error.
+    // Reject here so the user sees a clear SQL error (and _explain surfaces the problem without a
+    // k-NN request).
+    if (getFieldTypes().containsKey(METADATA_FIELD_SCORE)) {
       throw new IllegalArgumentException(
           String.format(
               "Index '%s' defines a user field named '_score' that collides with the synthetic"
-                  + " _score column exposed by vectorSearch(). Rename the stored field or query"
-                  + " the index without vectorSearch().",
+                  + " _score column exposed by vectorSearch(). Rename the field or query the index"
+                  + " without vectorSearch().",
               getIndexName()));
     }
     final TimeValue cursorKeepAlive =