[feature] Decode-then-encode collection() and xmldb: read paths too (decision 2, all surfaces)

Extends the doc() decode-then-encode canonicalization to the remaining read
surfaces so a literal '%' (and any decoded/descriptor-derived name) resolves
consistently everywhere, not just in fn:doc (#6463, decisions 1+2+5):

- fn:collection (ExtCollection.eval): canonicalize a bare db-path before asUri,
  so collection("/db/x/50%done") reaches the 50%25done key. asUri's new URI(path)
  rejected a literal '%' (malformed escape) before; a scheme-ful URI (xmldb:,
  file:, ...) is left untouched so its scheme/authority are not rewritten.
- xmldb: collection reads (XMLDBAbstractCollectionManipulator.getLocalCollection):
  upgrade the earlier escape=true normalization to decode-then-encode, so
  xmldb:collection-available / get-child-resources / get-child-collections resolve
  a literal-% collection by its decoded name, matching fn:doc / fn:collection.

decodeForURI is the exact inverse of encodeForURILenient, so each is idempotent on
an already-encoded path. XmldbCollectionAddressByDecodedNameTest gains
literalPercentCollectionResolvesByDecodedName (xmldb:collection-available and
fn:collection over a literal-% collection). XPathQueryTest (150) stays green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: joewiz

exist-core/src/main/java/org/exist/xquery/functions/fn/ExtCollection.java

@@ -34,6 +34,7 @@
 import org.exist.storage.lock.ManagedDocumentLock;
 import org.exist.util.LockException;
 import org.exist.xmldb.XmldbURI;
+import org.exist.xquery.util.URIUtils;
 import org.exist.xquery.*;
 import org.exist.xquery.functions.xmldb.XMLDBModule;
 import org.exist.xquery.value.*;
@@ -81,7 +82,15 @@ public Sequence eval(final Sequence[] args, final Sequence contextSequence) thro
         if (args.length == 0 || args[0].isEmpty()) {
             collectionUri = null;
         } else {
-            collectionUri = asUri(args[0].itemAt(0).getStringValue());
+            final String raw = args[0].itemAt(0).getStringValue();
+            // Resource-naming contract (eXist-db/exist#6463, decisions 1 + 2 + 5): canonicalize a bare
+            // db-path to its stored key by decode-then-encode, so collection("/db/x/café-col") and a
+            // literal '%' resolve, mirroring fn:doc. A scheme-ful URI (xmldb:, file:, ...) is left
+            // untouched so its scheme/authority are not rewritten.
+            final String effective = raw.startsWith(XmldbURI.ROOT_COLLECTION)
+                    ? URIUtils.encodePathForURILenient(URIUtils.decodePathForURI(raw))
+                    : raw;
+            collectionUri = asUri(effective);
         }
 
         return getCollectionItems(new URI[] { collectionUri });

exist-core/src/main/java/org/exist/xquery/functions/xmldb/XMLDBAbstractCollectionManipulator.java

@@ -75,15 +75,16 @@ public static LocalCollection getLocalCollection(final Expression callingExpress
         try {
             return new InTxnLocalCollection(context.getSubject(), context.getBroker().getBrokerPool(), null, execAndAddErrorIfMissing(callingExpression, () -> {
                 try {
-                    // Resource-naming contract (eXist-db/exist#6463, decision 5): resolve the collection
-                    // path with escape=true -- the same codec XmldbURI.create / xmldb:store apply when a
-                    // collection is written -- so a caller's decoded or descriptor-derived literal path
-                    // (e.g. "/db/system/repo/badver-${app.version}") resolves the percent-encoded key that
-                    // was actually stored ("badver-$%7Bapp.version%7D"). AnyURIValue.toXmldbURI() resolved
-                    // with escape=false, so an awkward name either missed or threw on a raw illegal char.
-                    // escape=true leaves a literal '%' alone, so it is idempotent on an already-encoded
-                    // path (such as the internal collection URI passed by the node branch of eval()).
-                    return XmldbURI.xmldbUriFor(name, true);
+                    // Resource-naming contract (eXist-db/exist#6463, decisions 1 + 2 + 5): canonicalize
+                    // the collection path to its stored key by decode-then-encode -- the same mapping
+                    // fn:doc / fn:collection apply -- so a caller's decoded or descriptor-derived literal
+                    // path (e.g. "/db/system/repo/badver-${app.version}") resolves the percent-encoded key
+                    // that was actually stored ("badver-$%7Bapp.version%7D"), and a literal '%' resolves by
+                    // its decoded form. AnyURIValue.toXmldbURI() resolved with escape=false, so an awkward
+                    // name either missed or threw on a raw illegal char. decodeForURI is the exact inverse
+                    // of encodeForURILenient, so this is idempotent on an already-encoded path (such as the
+                    // internal collection URI passed by the node branch of eval()).
+                    return XmldbURI.xmldbUriFor(URIUtils.encodePathForURILenient(URIUtils.decodePathForURI(name)), false);
                 } catch (final URISyntaxException e) {
                     throw new XPathException(callingExpression, org.exist.xquery.ErrorCodes.FORG0001,
                             "failed to convert '" + name + "' into an XmldbURI: " + e.getMessage(), e);

exist-core/src/test/java/org/exist/xquery/functions/xmldb/XmldbCollectionAddressByDecodedNameTest.java

@@ -91,6 +91,37 @@ public void getChildResourcesResolvesDecodedLiteralPath() throws XMLDBException
         assertEquals("1", rs.getResource(0).getContent());
     }
 
+    /**
+     * Decision 2, read side, across the xmldb: and fn:collection surfaces: a collection whose name
+     * literally contains '%' is stored bijectively (the '%' is escaped to %25) and is resolvable by
+     * its decoded literal name via xmldb:collection-available and fn:collection -- the same
+     * decode-then-encode canonicalization fn:doc applies. (The '%' here is not a valid escape, so
+     * decoding is a no-op and the decoded form round-trips to its own stored key.)
+     */
+    @Test
+    public void literalPercentCollectionResolvesByDecodedName() throws XMLDBException {
+        final String name = "pctcol-50%done";
+        existEmbeddedServer.executeQuery(
+                "declare variable $n external; xmldb:create-collection('/db', $n)",
+                Map.of("n", new StringValue(name)));
+
+        // bijective lenient store escapes the literal '%' to %25 (no collision)
+        assertTrue("precondition: the name must encode to a %25 stored key",
+                URIUtils.encodeForURILenient(name).contains("%25"));
+
+        // xmldb:collection-available by the decoded literal name
+        assertEquals("xmldb:collection-available by decoded literal-% name", "true", available("/db/" + name));
+
+        // fn:collection over the decoded literal path resolves the same collection
+        existEmbeddedServer.executeQuery(
+                "declare variable $c external; xmldb:store($c, 'd.xml', document { <d/> })",
+                Map.of("c", new StringValue("/db/" + name)));
+        final ResourceSet count = existEmbeddedServer.executeQuery(
+                "declare variable $c external; count(collection($c))",
+                Map.of("c", new StringValue("/db/" + name)));
+        assertEquals("collection() by decoded literal-% path", "1", count.getResource(0).getContent());
+    }
+
     private static String available(final String path) throws XMLDBException {
         final ResourceSet rs = existEmbeddedServer.executeQuery(
                 "declare variable $p external; xmldb:collection-available($p)", Map.of("p", new StringValue(path)));