From 30348af942a0c395db8b631dd7345ac611e8a54b Mon Sep 17 00:00:00 2001 From: Shay Date: Sun, 12 Jul 2026 15:20:28 -0700 Subject: [PATCH] docs(third-door): clarify sur_norm is the definite Euclidean threshold magnitude (#20 review) --- core/physics/surprise.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/core/physics/surprise.py b/core/physics/surprise.py index ac809fb1..063703d1 100644 --- a/core/physics/surprise.py +++ b/core/physics/surprise.py @@ -135,8 +135,11 @@ def surprise_residual( Both branches solve the metric normal equations ``G c = r`` (``G_ij = ``, ``r_i = ``) via ``lstsq``, fail-closed on a metric-degenerate span. Returns ``(residual_vector, residual_norm)`` where the - norm is the DEFINITE (Euclidean) magnitude of the residual — 0 iff nothing is - unexplained (see the module docstring on why this is not the metric norm). + norm is the DEFINITE Euclidean magnitude of the projection residual — NOT the + CGA metric — used as the stable threshold for productivity and discovery + routing; the projection itself is metric-orthogonal under ``cga_inner``. It is + 0 iff nothing is unexplained, whereas the indefinite reversion norm can vanish + on a nonzero null residual (see the module docstring). """ x_arr = np.asarray(x, dtype=np.float64) B = np.asarray(basis, dtype=np.float64)