docs: document typed paths ($pith, $iota, +pave, +pout, +stip)

[sigilante]

Fifteenth PR from the audit against urbit/urbit@08026c84b2. Typed paths were entirely undocumented. Every example was run on a fake ship (urbit-408k-rc1.pill).

Companion PRs: #266, #267, #269–#279.

Molds (stdlib/4o.md)

• $iota — typed path segment (hoon.hoon:2105). Either a bare @tas, or a tagged pair naming the aura of the value it holds.
• $pith — typed Urbit path (hoon.hoon:2097). A (list iota); a path whose segments carry their aura rather than being flattened to @ta.

Formatting functions (stdlib/4m.md)

• +pave — path → pith (:5999). Segments matching no known aura fall back to [%ta segment].
• +pout — pith → path (:5992). The inverse, rendering each $iota with +scot.
• +stip — typed path parser (:5972), with +spot:stip (one segment) and +swot:stip (a whole path). The core reduces to +swot, so +stip used directly parses a path.

The trap, found by trying it rather than reading it

Casting a $path to a $pith does not parse the segments.

> (pave /foo/123/0xdead)
~[%foo [%ud 123] [%ux 0xdead]]

> `pith`/foo/123
~[%foo %123]

The cast merely retypes the existing @ta segments, so %123 stays a term rather than becoming [%ud 123]. Anyone reaching for a $pith by casting gets something that type-checks and is silently wrong. Noted in both the $pith and +pave entries.

All examples verified

(pave /foo/123/0xdead)          ~[%foo [%ud 123] [%ux 0xdead]]
(pout (pave /foo/123/0xdead))   /foo/123/0xdead
(rash '123' spot:stip)          [%ud 123]
(rash '0xdead' spot:stip)       [%ux 0xdead]
(rash '/foo/123' swot:stip)     [%foo [i=[%ud 123] t=~]]

+hew went to #272 instead

+hew belongs in stdlib/2c.md immediately before +lsh — the same insertion point #272 already uses for +ham, so putting it here would have conflicted. It has been added to that branch instead, alongside the other bit-arithmetic arms, and #272 has been updated.

Worth noting how that went: I wrote +hew's source block from inference on a first pass and it was wrong — I had the tail as two =/ bindings threading d by hand, where the source uses =^ f d $(b -.b) twice and produces [[f g] d]. Caught by diffing against hoon.hoon before commit, the same check that caught +rig earlier on that branch. All five blocks in 2c.md now verify as exact matches.

All anchors verified to resolve. Test-merged against the fourteen open companion PRs — all clean.

🤖 Generated with Claude Code