Document normal distribution commands

Author: timschmidt

README.md

@@ -198,14 +198,14 @@ object-level facts rather than asking the scalar layer to infer geometry or topo
 
 ```toml
 [dependencies]
-hyperreal = "0.12.0"
+hyperreal = "0.13.0"
 ```
 
 With the `Simple` parser and calculator binary:
 
 ```toml
 [dependencies]
-hyperreal = { version = "0.12.0", features = ["simple"] }
+hyperreal = { version = "0.13.0", features = ["simple"] }
 ```
 
 Feature flags:
@@ -323,6 +323,18 @@ assert_eq!(value.exact_rational(), Some(Rational::fraction(7, 8).unwrap()));
 inverse hyperbolic functions, normal distribution helpers (`erf`, `dnorm`, `pnorm`,
 `qnorm`), integers, decimals, fractions, `pi`, and `e`.
 
+Normal-distribution forms use the same `Real` methods as Rust callers:
+
+| Form | Meaning | Domain |
+| --- | --- | --- |
+| `(erf x)` | error function | all real inputs |
+| `(dnorm x)` | standard normal density | finite values with `abs(x) <= 10` |
+| `(pnorm x)` | standard normal cumulative distribution | finite values with `abs(x) <= 10` |
+| `(qnorm p)` | inverse standard normal CDF | `pnorm(-10) < p < pnorm(10)` |
+
+Inputs outside those supported numeric ranges return `Problem` rather than silently
+falling back to primitive floating point.
+
 ## Conversions
 
 Supported conversions include:

src/README.md

@@ -65,6 +65,8 @@ numeric domain failures:
 - square root of known-negative values
 - logarithm of non-positive values
 - inverse trig / inverse hyperbolic domain failures
+- normal density/CDF inputs outside the supported finite approximation window
+- normal quantile inputs outside the supported probability window
 - invalid primitive float import such as `NaN` or infinity
 
 Internal `expect` calls are reserved for representation invariants that should

src/computable/README.md

@@ -48,6 +48,9 @@ Approximation kernels should:
 - avoid cancellation-prone forms when a stable transform is available
 - reuse shared constants such as `pi`, `tau`, `e`, `sqrt(2)`, `sqrt(3)`, and
   common logarithms
+- provide dedicated kernels for supported statistical functions such as `erf`,
+  standard normal density/CDF, and standard normal quantile rather than routing
+  through primitive floating point
 - keep approximation precision explicit rather than silently falling back to
   primitive floating point
 

src/real/README.md

@@ -62,6 +62,9 @@ shape unless benchmarks show no cost.
 - arithmetic preserves recognizable symbolic structure where benchmarks justify
   it.
 - fallible methods return `Problem` for known domain errors.
+- `erf`, `dnorm`, `pnorm`, and `qnorm` expose computable standard-normal helpers;
+  `dnorm`/`pnorm` are bounded to finite inputs with `abs(x) <= 10`, and `qnorm`
+  is bounded to probabilities strictly between `pnorm(-10)` and `pnorm(10)`.
 - structural queries return conservative facts and should not force expensive
   approximation when representation facts are enough.
 - borrowed arithmetic should avoid unnecessary expression cloning.