nx_url_canonical.nx

url.nx -- URL percent-encoding + decoding (RFC 3986). Used by: HTTP query strings, path segments, form-urlencoded POST bodies, JWT segments. Complements base64.nx / hex.nx for the URL-safe text-encoding niche. Encoding rules (RFC 3986 §2.3): Unreserved: A-Z a-z 0-9 - . _ ~ (encoded as-is) Reserved: : / ? # [ ] @ ! $ & ' ( ) * + , ; = -- reserved chars DEPEND on context. We offer two encoders: url_encode_component -- encodes everything reserved url_encode_path -- preserves / for path segments All other bytes: encoded as %HH (two uppercase hex digits). Invariants: UR1 Output is deterministic: same input -> same bytes. UR2 Decoder rejects malformed sequences (%X or %XY where Y isn't hex) with a negative return. No silent skip. UR3 Decoder accepts both upper and lower case hex digits. UR4 Round-trip exact for any byte sequence: decode(encode(x)) == x UR5 Encoder never outputs non-ASCII; caller always gets 7-bit safe text.