~. sigdot Positive Assertion Rune

README.md

@@ -47,6 +47,7 @@ UIPs can be divided into the following categories:
 | [0126](./UIPS/UIP-0126.md) | Pierport Protocol         | ~littul-pocdev                 | Draft     | Process   |
 | [0127](./UIPS/UIP-0127.md) | Lagoon IEEE 754 Reals     | ~lagrev-nocfep                 | Draft     | Standards |
 | [0128](./UIPS/UIP-0128.md) | Monadic Scry Interface    | ~fodwyt-ragful, ~mastyr-bottec | Draft     | Standards |
+| [0129](./UIPS/UIP-0129.md) | Positive Assertion Rune   | ~lagrev-nocfep                 | Draft     | Standards |
 
 
 ## Background

UIPS/UIP-0129.md

@@ -0,0 +1,78 @@
+---
+uip: "0129"
+title: Assertion Rune
+description: "Add a ~. sigdot rune to handle positive assertions cleanly"
+author: ~lagrev-nocfep (@sigilante)
+status: Draft
+type: Standards Track
+category: Hoon
+created: 2024-03-25
+---
+
+## Abstract
+
+Hoon supports several related runes for error handling and debugging:
+
+- `~&` is the classic `printf` side-effect rune.
+- `~|` adds a stack annotation in case of crash.
+- `~?` adds a debugging printf
+- `?>` is a positive assertion (crash if fail).
+- `?<` is a negative assertion (crash if pass).
+
+A common design pattern in Hoon is to have an assertion to succeed, then to wrap
+an intended error mesage with `~|` around `!!`.  By coupling the `?:`, `~|`, and
+`!!` together, we can achieve a more lapidary yet still clear code expression.
+We propose to call this the `~.` sigdot rune (patterned after `?.` wutdot
+"lest").
+
+```
+~:  test-to-pass
+  'message-on-fail'
+continuation if pass
+```
+
+The advantage of this rune is that it will avoid the footgun of an assertion
+passing but the message still printing.  (I.e. you can do other things in a
+`~|`-gated branch.)
+
+## Specification
+
+The `~.` rune should desugar from:
+
+```
+~.  test-to-pass
+  'message-on-fail'
+continuation if pass
+```
+
+to:
+
+```
+?.  test-to-pass
+  ~|  'message-on-fail'  !!
+continuation if pass
+```
+
+`~:` differs from `~?` in that it crashes with the error message (rather than
+the conditional printf).
+
+This involves two modest changes, one to the parser and another to the AST in
+`/sys/hoon`.  `~.` collides with the empty `@ta`, `*knot`, but should be
+generally distinguishable through precedence rules in syntax.
+
+## Rationale
+
+- Producing code that cleanly wraps an error message around an implicit crash is
+  clear to read and write for many programmers.
+- Offering a rune which allows `?.`-like assertion checks without incorrectly
+  invoking other `~|` stack trace messages in case of error will make failures
+  more clear to process.
+
+## Backwards Compatibility
+
+- This should be bundled into a Hoon kelvin decrement.  It will not break any
+  known existing code.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).