[bugfix] Speak decoded UTF-8 resource names on the wire

[joewiz]

[This PR was co-authored with Claude Code. -Joe]

Summary

The /api/db endpoints spoke eXist's stored, percent-encoded form on the wire. This PR makes the API speak decoded UTF-8 in both directions: a client sends and receives café-ünïcode.xml, never caf%C3%A9-%C3%BCn%C3%AFcode.xml.

eXide and TEI Publisher already work this way (decode for display, encode before storage). This brings existdb-openapi in line, so a name from a listing can be echoed straight back as an operation path and always resolve to the same resource.

What changed

modules/db.xqm — two boundary helpers, applied uniformly across every handler:

• db:to-stored — an incoming wire path → the stored form, applied once at the top of each handler before any doc()/collection()/xmldb:*-available/xmldb:* call. It uses fn:iri-to-uri.
• db:to-display — a stored path/name → the decoded wire form, applied to every name and path leaving the API.

Why fn:iri-to-uri and not xmldb:encode

iri-to-uri is the inbound encoder because it reproduces exactly what eXist's storage layer writes. Verified against a live instance:

name	xmldb:store stores	fn:iri-to-uri	xmldb:encode
café.xml	caf%C3%A9.xml	caf%C3%A9.xml ✅	caf%C3%A9.xml
quote'name.xml	quote'name.xml	quote'name.xml ✅	quote%27name.xml ❌
a&b.xml	a&b.xml	a&b.xml ✅	a%26b.xml ❌
a b.xml	throws FORG0001	a%20b.xml ✅	a%20b.xml

iri-to-uri percent-encodes spaces and non-ASCII but leaves sub-delims (' & + @) and existing %XX untouched. So it (a) matches the stored form xmldb:store produces — including the literal-sub-delim names xmldb:store leaves un-encoded, which xmldb:encode would instead store as %27/%26 and then fail to resolve; (b) additionally encodes the space that xmldb:store rejects outright; and (c) is idempotent on already-encoded input, so older clients still sending caf%C3%A9.xml keep working with no double-encoding.

On the decode side, db:to-display protects a literal + (as %2B) before calling xmldb:decode-uri. xmldb:decode-uri otherwise form-decodes + to a space (the x-www-form-urlencoded convention; eXist-db/exist#1824), but a + in a stored name is always a literal + (spaces are stored as %20), so without this protection naïve+test.xml would read back as naïve test.xml. This mirrors URIUtils.decodeForURI (the core fix in eXist-db/exist#6451) at the API layer, so it is correct independent of the core build and forward-compatible once #6451 lands.

URLs in responses (e.g. runPath) stay encoded, since they are clickable links, not operation keys.

Test plan

• New Cypress coverage (db.cy.js) — store / read / list / remove a café déjà.xml, an o'brien.xml, and a naïve+test.xml by their decoded names, asserting listing names are never percent-encoded. (The existing db tests use ASCII names and don't exercise this boundary.)
• Real-client end-to-end (existdb-oxygen-plugin, against a beta3 instance carrying this fix): display, read, create, rename, and move/copy all round-trip on space, non-ASCII, CJK, Cyrillic, &, parentheses, and apostrophe — with zero plugin-side encode/decode logic.
• On-disk verification (bypassing the API): every stored name is the exact iri-to-uri form of the user-typed name, all resolve, and the full decoded-path round-trip returns content (including Cyrillic).

Known boundary (out of scope, documented)

• Literal % can't be disambiguated from a percent-escape in Phase 1 (needs a bijective encoding) — iri-to-uri leaves a literal % untouched. This is the one remaining edge of the broader resource-naming contract work; this PR is the existdb-openapi piece of it.

(The literal-+ case is handled here directly; see the decode note above.)