fix: prefer canonical Javadoc type pages

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}

src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java

@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat.application.search;
 
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -94,25 +95,20 @@ public String typePageFileName() {
  /**
  * Determines whether a Javadoc URL path identifies this selector's declaring type.
  *
- * <p>Unqualified selectors match the type filename in any package. Qualified selectors require
- * the exact package path immediately before that filename, preventing same-named JDK types in
- * different packages from receiving the same citation priority.</p>
+ * <p>Qualified selectors use their query package and ignore the candidate package. Unqualified
+ * selectors require a canonical Java package derived from the candidate source URL, which
+ * keeps package-relative API pages from being mistaken for canonical type pages.</p>
  *
  * @param javadocPath decoded Javadoc URL path
- * @return true when the path names this selector's declaring type
+ * @param candidatePackageName package derived from the candidate source URL, or {@code null}
+ * when absent
+ * @return true when the path names this selector's declaring type in its expected package
  */
- public boolean matchesJavadocPath(String javadocPath) {
+ public boolean matchesJavadocPath(String javadocPath, String candidatePackageName) {
  Objects.requireNonNull(javadocPath, "javadocPath");
- int filenameStartIndex = javadocPath.lastIndexOf('/') + 1;
- String candidateFilename = javadocPath.substring(filenameStartIndex);
- if (!typePageFileName().equals(candidateFilename)) {
- return false;
- }
- if (packageName.isBlank()) {
- return true;
- }
- String qualifiedPagePathSuffix = "/" + packageName.replace('.', '/') + "/" + typePageFileName();
- return javadocPath.endsWith(qualifiedPagePathSuffix);
+ return expectedPackageName(candidatePackageName)
+ .map(expectedPackageName -> matchesPackageTypePath(javadocPath, expectedPackageName))
+ .orElse(false);
  }
 
  /**
@@ -124,6 +120,18 @@ public String sparseQueryTerms() {
  return typePageName;
  }
 
+ private Optional<JavaPackageName> expectedPackageName(String candidatePackageName) {
+ if (!packageName.isBlank()) {
+ return JavaPackageName.from(packageName);
+ }
+ return JavaPackageName.from(candidatePackageName);
+ }
+
+ private boolean matchesPackageTypePath(String javadocPath, JavaPackageName expectedPackageName) {
+ String expectedPagePath = "/" + expectedPackageName.javadocPath() + "/" + typePageFileName();
+ return javadocPath.endsWith(expectedPagePath);
+ }
+
  private static ParsedQualifiedName parseQualifiedName(String query, int startIndex) {
  List<String> segments = new ArrayList<>();
  int currentIndex = startIndex;

src/main/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageName.java

@@ -0,0 +1,54 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import java.util.Optional;
+import javax.lang.model.SourceVersion;
+
+/**
+ * Represents an exact, syntactically valid Java 25 package name.
+ *
+ * <p>The value preserves its source spelling so URL projections and query selectors share one
+ * package-identity boundary without trimming or accepting documentation-only path segments.</p>
+ *
+ * @param qualifiedName dot-separated Java package name
+ */
+public record JavaPackageName(String qualifiedName) {
+
+ /**
+ * Enforces exact Java 25 package-name syntax for every constructed value.
+ *
+ * @throws IllegalArgumentException when the package name is null, blank, padded, or invalid
+ */
+ public JavaPackageName {
+ if (!isValid(qualifiedName)) {
+ throw new IllegalArgumentException("qualifiedName must be an exact Java 25 package name");
+ }
+ }
+
+ /**
+ * Creates a package name only when the candidate satisfies the Java 25 name grammar exactly.
+ *
+ * @param candidateQualifiedName candidate dot-separated package name
+ * @return validated package name, or empty when the candidate is absent or invalid
+ */
+ public static Optional<JavaPackageName> from(String candidateQualifiedName) {
+ return isValid(candidateQualifiedName)
+ ? Optional.of(new JavaPackageName(candidateQualifiedName))
+ : Optional.empty();
+ }
+
+ /**
+ * Projects the package into the path syntax used by canonical Javadoc URLs.
+ *
+ * @return slash-separated package path without leading or trailing delimiters
+ */
+ public String javadocPath() {
+ return qualifiedName.replace('.', '/');
+ }
+
+ private static boolean isValid(String candidateQualifiedName) {
+ return candidateQualifiedName != null
+ && !candidateQualifiedName.isBlank()
+ && candidateQualifiedName.equals(candidateQualifiedName.trim())
+ && SourceVersion.isName(candidateQualifiedName, SourceVersion.RELEASE_25);
+ }
+}

src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.application.search.JavaApiMethodSelector;
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Comparator;
@@ -86,7 +87,8 @@ private static boolean matchesTypePage(JavaApiMethodSelector selector, Document
  if (documentPath == null || documentPath.isBlank()) {
  return false;
  }
- return selector.matchesJavadocPath(documentPath);
+ String candidatePackageName = JavaPackageExtractor.extractJavaApiPackage(sourceUrl);
+ return selector.matchesJavadocPath(documentPath, candidatePackageName);
  }
 
  private static boolean hasMethodDeclarationEvidence(JavaApiMethodSelector selector, Document citationCandidate) {

src/main/java/com/williamcallahan/javachat/service/RetrievalService.java

@@ -4,6 +4,7 @@
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.ModelConfiguration;
 import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.service.ingestion.JavaPackageExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
@@ -415,10 +416,8 @@ public CitationOutcome toCitations(List<Document> documents) {
  Map<String, ?> sourceDocMetadata = sourceDocument.getMetadata();
  String rawUrl = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.URL_FIELD);
  String title = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.TITLE_FIELD);
- String packageName = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.PACKAGE_FIELD);
  String documentType = stringMetadataValue(sourceDocMetadata, QdrantPayloadFieldSchema.DOC_TYPE_FIELD);
- String refinedCitationUrl =
- refineCitationUrl(rawUrl, sourceDocument.getText(), packageName, documentType);
+ String refinedCitationUrl = refineCitationUrl(rawUrl, sourceDocument.getText(), documentType);
  String citationIdentity = citationIdentityFor(rawUrl, refinedCitationUrl);
  if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
  continue;
@@ -478,10 +477,11 @@ private static String citationIdentityFor(String rawUrl, String citationUrl) {
  * Refines a raw document URL and gates Javadoc member anchors to {@code api-docs} metadata.
  *
  */
- private String refineCitationUrl(String rawUrl, String documentText, String packageName, String documentType) {
+ private String refineCitationUrl(String rawUrl, String documentText, String documentType) {
  String normalizedUrl = DocsSourceRegistry.normalizeDocUrl(rawUrl);
  String citationUrl = normalizedUrl;
  if (DOCUMENT_TYPE_API_DOCS.equals(documentType)) {
+ String packageName = JavaPackageExtractor.extractJavaApiPackage(normalizedUrl);
  String nestedTypeRefinedUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineNestedTypeUrl(
  citationUrl, documentText);
  citationUrl = com.williamcallahan.javachat.util.JavadocLinkResolver.refineMemberAnchorUrl(

src/main/java/com/williamcallahan/javachat/service/ingestion/JavaPackageExtractor.java

@@ -2,6 +2,7 @@
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import com.williamcallahan.javachat.domain.javaapi.JavaPackageName;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -34,6 +35,25 @@ public static boolean isJavaApiUrl(String url) {
  return findJavaApiSourceUrl(url).isPresent();
  }
 
+ /**
+ * Derives the Java package encoded by a manifest-governed Java API source URL.
+ *
+ * <p>URL consumers use this projection instead of persisted package metadata so package
+ * identity follows the canonical source path across ingestion generations.</p>
+ *
+ * @param url source URL
+ * @return package encoded by the canonical Java API path, or an empty string when the URL is
+ * not a canonical Java API source or its path does not identify a package
+ */
+ public static String extractJavaApiPackage(String url) {
+ Objects.requireNonNull(url, "url");
+ return findJavaApiSourceUrl(url)
+ .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
+ .flatMap(JavaPackageName::from)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
+ }
+
  /**
  * Attempts to derive a package name from the URL and extracted page text.
  *
@@ -45,9 +65,7 @@ public static String extractPackage(String url, String bodyText) {
  Objects.requireNonNull(url, "url");
  Objects.requireNonNull(bodyText, "bodyText");
 
- String pathDerivedPackageName = findJavaApiSourceUrl(url)
- .map(JavaPackageExtractor::extractPackageFromJavaApiPath)
- .orElse("");
+ String pathDerivedPackageName = extractJavaApiPackage(url);
  if (!pathDerivedPackageName.isBlank()) {
  return pathDerivedPackageName;
  }
@@ -58,7 +76,10 @@ public static String extractPackage(String url, String bodyText) {
  String snippet = bodyText.substring(packageIndex, end);
  for (String token : snippet.split("\\s+")) {
  if (AsciiTextNormalizer.toLowerAscii(token).startsWith("java.")) {
- return token.replaceAll("[,.;]$", "");
+ String candidatePackageName = token.replaceAll("[,.;]$", "");
+ return JavaPackageName.from(candidatePackageName)
+ .map(JavaPackageName::qualifiedName)
+ .orElse("");
  }
  }
  }

src/main/java/com/williamcallahan/javachat/util/JavadocLinkResolver.java

@@ -24,7 +24,7 @@ public static String refineNestedTypeUrl(String url, String text) {
  *
  * @param url Javadoc page URL ending with .html
  * @param text Extracted chunk text from the same page
- * @param packageName Package name of the type (from metadata), can be empty
+ * @param packageName Java package derived from the canonical Javadoc source URL, can be empty
  * @return URL with a fragment to the member if a confident match is found; original URL otherwise
  */
  public static String refineMemberAnchorUrl(String url, String text, String packageName) {

src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java

@@ -57,7 +57,7 @@ void normalizesWhitespaceWhenConstructedDirectly() {
  assertEquals("of", selector.methodName());
  assertEquals("List.html", selector.typePageFileName());
  assertEquals("List", selector.sparseQueryTerms());
- assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html"));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
  }
 
  @Test
@@ -76,6 +76,25 @@ void rejectsFilenameShapedPseudoMethods() {
  void requiresCaseSensitiveJavadocTypePageNames() {
  JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "List", "of");
 
- assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/list.html", null));
+ }
+
+ @Test
+ void requiresCanonicalCandidatePackageForUnqualifiedSelectors() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("", "List", "of");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/List.html", "java.util"));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/class-use/List.html", "java.util.class-use"));
+ assertFalse(selector.matchesJavadocPath("/List.html", ""));
+ assertFalse(selector.matchesJavadocPath("/java.base/java/util/List.html", null));
+ }
+
+ @Test
+ void matchesQualifiedSelectorsByPathRegardlessOfCandidateMetadata() {
+ JavaApiMethodSelector selector = new JavaApiMethodSelector("java.util", "Date", "toString");
+
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", null));
+ assertTrue(selector.matchesJavadocPath("/java.base/java/util/Date.html", "java.sql"));
+ assertFalse(selector.matchesJavadocPath("/java.sql/java/sql/Date.html", "java.util"));
  }
 }

src/test/java/com/williamcallahan/javachat/domain/javaapi/JavaPackageNameTest.java

@@ -0,0 +1,45 @@
+package com.williamcallahan.javachat.domain.javaapi;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/** Verifies exact Java 25 package validation and Javadoc path projection. */
+class JavaPackageNameTest {
+
+ @Test
+ void acceptsJavaPackageNamesAndProjectsJavadocPaths() {
+ JavaPackageName packageName =
+ JavaPackageName.from("java.util.concurrent").orElseThrow();
+
+ assertEquals("java.util.concurrent", packageName.qualifiedName());
+ assertEquals("java/util/concurrent", packageName.javadocPath());
+ }
+
+ @Test
+ void rejectsAbsentPaddedAndInvalidPackageNames() {
+ List<String> invalidPackageNames = List.of(
+ "",
+ " ",
+ " java.util",
+ "java.util ",
+ "java..util",
+ "java.util.class-use",
+ "java.class",
+ "java.true",
+ "java.false",
+ "java.null");
+
+ assertTrue(JavaPackageName.from(null).isEmpty());
+ invalidPackageNames.forEach(candidatePackageName ->
+ assertTrue(JavaPackageName.from(candidatePackageName).isEmpty()));
+ }
+
+ @Test
+ void preventsDirectConstructionOfInvalidPackageNames() {
+ assertThrows(IllegalArgumentException.class, () -> new JavaPackageName("java.util.class-use"));
+ }
+}