docs: correct Hoon stdlib signatures that mislead readers into broken code

[sigilante]

Second of three PRs from an audit against urbit/urbit@08026c84b2. This batch is arms whose documented signature or behaviour no longer matches source. Every claim was reproduced on a fake ship booted from urbit-408k-rc1.pill ([%zuse 408]) unless noted as source-only.

Companion PRs: mechanical corrections, and user-manual commands.

!@ zappat — branches are reversed

87adc94d16 (2025-07-21, "!@ reverse polarity") changed the compile of %zppt from ?: to ?.. .q is now the does-not-exist branch and .r the exists branch. Verified both directions:

> =foo 42
> !@(foo 'exists' 'does not exist')
'does not exist'
> !@(baz 'exists' 'does not exist')
'exists'

The Discussion and both example outputs asserted the opposite, so a reader following them writes inverted logic that still compiles. Examples rewritten so the branch labels match the new order. No rationale is given upstream (empty commit body), so none is invented here.

+trim — dry tape gate → wet list gate

Now |* [a=@ b=(list)] / ^+ [p=b q=b] (hoon.hoon:4317). The example outputs also changed, since the product is no longer cast to $tape:

> (trim 5 "lasok termun")
[p=[i='l' t="asok"] q=[i=' ' t="termun"]]

Added a generic-list example and a note that only the inferred type and its printed form changed, not the value.

+bif:by — takes the key alone, and old callers fail silently

Signature went from |* [b=* c=*] to |* b=* (hoon.hoon:1445), and it no longer inserts. Critically, the old two-argument call does not error — with sample b=* the arguments arrive as the single cell [b c], so the map is split at that cell instead of at the key:

> `[(map @tas @) (map @tas @)]`(~(bif by a) %b)
[{[p=%e q=5]} {[p=%d q=4] [p=%a q=1] [p=%c q=3]}]

> `[(map @tas @) (map @tas @)]`(~(bif by a) b+2)
[{[p=%e q=5] [p=%b q=2] [p=%d q=4] [p=%a q=1]} {[p=%c q=3]}]

Note [p=%b q=2] survives in the second — the key was never removed. The doc's own examples used that broken form, so the page was demonstrating the failure while claiming the correct output.

+inde / +iny — new delimiter arguments

+inde is now |* [[ope=rule end=rule] sef=rule] (hoon.hoon:4910, d5af20fec1). The documented one-argument call fails to compile with mull-grow / -find.sef. +iny is now simply ++ iny inde, where the doc carried a stale 19-line copy of the old body.

The replacement example is not invented — +inde's only call site in the tree is +quote-innards parsing """ block strings (hoon.hoon:11842), so it mirrors that shape, verified verbatim:

> `tape`(scan "\"\"\"\0afoo\0abar\0a\"\"\"" (inde [(jest '"""') (jest '"""')] (star ;~(pose prn (just `@`10)))))
"foo\0abar"

+mink / +mock / +mack — ~ scry sentinel

The scry argument is now $@(~ $-(^ (unit (unit)))) (hoon.hoon:6021, :6182). Passing ~ means "no scry handler": ordinary formulas evaluate, a Nock 12 blocks immediately.

> (mink [[1 2] [0 2]] ~)
[%0 product=1]
> (mink [0 [12 [1 0] [1 0]]] ~)
[%2 trace=~]

+mong was checked and is unchanged — still a bare gate — so it is deliberately left alone.

+shas — salt-length behaviour

Now =/ len (max 32 (met 3 sal)) / (shay len ...) (hoon.hoon:3314). Worth stating precisely: a 1-byte salt and a 40-byte salt both still agree with the old formula. The forms diverge only when the XOR result has fewer significant bytes than max(32, (met 3 sal)) — when leading bytes cancel to zero. Confirmed by constructing such a salt.

Smaller

• +peg (1b.md) — undocumented crash on a zero second argument; source has ?< =(0 b) alongside ?< =(0 a). Verified both (peg 4 0) and (peg 0 4) crash.
• +apt:in (2h.md) — gained strict-inequality checks at every node. (+apt:by was checked and is already correct.)
• +dif:by (2i.md) — dropped its =+ b=a |@ ++ $ wrapper for |* b=_a and now calls (bif p.n.b) with one argument. Knock-on from the +bif change. +dif:by itself is correct upstream — verified it still returns the right difference and ~(apt by ...) on the result is %.y; only the listing was stale.
• +del:in / +del:by (2h.md, 2i.md) — source blocks gained => .(b ...). Source-verified only: the coercion does not produce a mint error for a wrong-typed key ((~(del in s) "abc") returns the set unchanged), so no behavioural claim is documented.

🤖 Generated with Claude Code