URI: one canonical identifier

yggdryl::uri parses every spelling of a resource identifier - URI, URL,
URN, ARN, or a bare platform path - into one canonical value: lowercase
scheme, uppercase percent escapes, / for \ under file:, an authority
marker on every absolute file: path. Two spellings of one resource compare
and hash equal, and the canonical text re-parses to the same value. Uri is
the general value; Url (a location), Urn (a name) and Arn (an AWS
resource name) are its three narrowings, and the scheme decides which. Parse
once at the boundary and carry the value: past it nothing splits a string on
/, ? or =.

Opening what a URL names (a handle, its bytes, listing a folder) is
yggdryl-storage; reading a partitioned folder's rows is yggdryl-records.
Install and conventions are in yggdryl.

Choose the door

Rules for fast, correct use

1. Parse once, carry the value. Equality, hashing and ordering run on the
   canonical form, so HTTPS://x/caf%c3%a9 equals https://x/caf%C3%A9.
   Never compare or cache raw strings, and never re-parse a value you hold.
2. Pick the door by where the text came from. Stored data takes the strict
   parse (Url::from_str, Url.from_str, Url.fromString): relative text is
   refused. A user argument takes the location door (Url::from_location,
   Python Url(...), JS Url.from), which roots a bare path at the working
   directory and resolves a URN or an S3 or S3 Tables ARN to where it points.
3. No scheme token means a file path. /var/x is file:///var/x,
   data/x.csv the relative file:data/x.csv; a colon after the first
   separator is data (/d/2026-08-16T00:00:00/p), and an invalid token before
   a colon is a parse error with its byte offset, never a silent fallback.
4. Cross the OS boundary with from_path/into_path. Drive and UNC
   detection is textual, identical on every host; from_path encodes names,
   into_path decodes them and refuses an escape that would become a
   separator, a dot segment, a drive or a UNC name. Never concatenate.
5. Escapes are stored as written. path, query, fragment answer the
   stored bytes; ask decode=true for text. Decoded text is never structure:
   %2F stays inside its segment, %26 inside its pair, + is a literal plus.
6. joinpath takes URI text; join_path takes an OS path. joinpath
   resolves .. like a shell cd and refuses 100%.csv; Rust join_path /
   Python joinpath(os.PathLike) encode each component as a name. An absolute
   argument replaces the path; .. past an absolute root is clamped.
7. Suffixes are the media type. The last suffix is the MIME type, the
   chain is base + codings (x.csv.gz.zst = CSV, gzip, zstd). An unknown
   suffix is application/octet-stream, not an error. Setters are atomic: a
   refused name (bad/name, a MIME type with no preferred extension) changes
   nothing.
8. Store authorities follow one rule. On s3:/gs:/az: families, a
   first component ending .com/.io/.net, carrying a port, an IP literal,
   or localhost is the host and the bucket is the next part; otherwise it is
   the bucket. key() is the path below the bucket as spelled, trailing slash
   and escapes kept. All of it reads the authority - no network request.
9. User info splits at the first colon. user:pass:word@host has password
   pass:word. Never log a URL that carries one.
10. Globs live in the path, spelled with *. ? opens a query and [ is
    an IPv6 host in a URL, so neither is a glob there; the full syntax
    (?, [a-z], [!a-z]) is for matches_glob pattern text. A pattern with
    no / matches the name at any depth; with a / it is anchored at the root.
11. List from the glob's fixed root. glob_parts() answers the deepest
    location with no pattern character and the rest; a handle's glob descends
    that prefix instead of listing everything and filtering.
12. Hive partitions are path segments. column=value directories, in path
    order. Use hive_partitions_under(root) / partitions_under(root) for the
    table's own columns - year is a partition of /lake, not of
    /lake/year=2024. children_where on a handle keeps the leaves whose path
    spells every pair - it walks the whole tree (no call per file beyond the
    listing, but no pruning); to skip other partitions, glob from the fixed
    prefix.
13. A name resolves by reading it as a path. A URN's namespace then its
    :-separated parts are the path (urn:lake:t:2026:p.parquet ->
    lake/t/2026/p.parquet); resolve(base) joins it under a store,
    locator() under the working directory. An Amazon S3 bucket ARN locates
    its s3: URL and an Amazon S3 Tables bucket/... ARN its s3tables: one;
    every other ARN service is refused by name.
14. Local predicates never touch the network. exists, is_dir, is_file
    answer for file: URLs and are false for every other scheme - they are
    not a remote existence check (and storage code should act, not probe).
15. Python wrappers lock on first hash. After hash(uri) (a dict key,
    a set member) a setter raises TypeError; copy.copy gives an unlocked
    copy. stable_hash() never locks.

Pitfalls

Language references

• references/rust.md - read when writing Rust (Uri, Url, Urn, Arn, UriPath, Scheme, Parameters).
• references/python.md - read when writing Python (yggdryl.Uri subclasses, pathlib-style Url, live Parameters).
• references/javascript.md - read when writing Node.js (camelCase getters, Url.from vs Url.fromString, no Parameters).

Deeper

• URI contract, canonical form, credentials, store locations, columns: https://platob.github.io/yggdryl/uri/
• Path: segments, filenames, media type, platform paths, navigation: https://platob.github.io/yggdryl/uri/path/
• URL and URN, name resolution, scheme facts: https://platob.github.io/yggdryl/uri/url-urn/
• ARN and Amazon S3 Tables: https://platob.github.io/yggdryl/uri/arn/
• Query parameters: https://platob.github.io/yggdryl/uri/parameters/
• Globs and Hive partitions: https://platob.github.io/yggdryl/uri/patterns/
• Listings, globs and partition pruning on a handle: https://platob.github.io/yggdryl/holder/#partitions
• Sibling skills: yggdryl-storage (open what a URL names), yggdryl-records
  (partitioned reads and writes), yggdryl-types (url/urn columns in a schema).