universal-physics-tensor 9.0.0 → 11.0.0

package/dist/composition/probe/study.js

@@ -26,6 +26,11 @@
  *
  * @internal
  */
+import { pairwiseDot, pairwiseSum } from '@danielsimonjr/mathts-core';
+import { betainc, gammainc, gammaincp, inv, propagateUncertainty } from '@danielsimonjr/mathts-functions';
+import { numberFrom } from '../../core/mathts-read.js';
+import { readJsonFile } from '../../core/data-file.js';
+import { isPlainObject } from '../../core/json-schema.js';
 import { readFileSync } from 'node:fs';
 import { DIMENSIONLESS } from '../../dimensional/types.js';
 import { equals, format } from '../../dimensional/algebra.js';
@@ -47,7 +52,8 @@ export class StudyRefusal extends Error {
         this.name = 'StudyRefusal';
     }
 }
-const DEFAULT_ALPHA = 0.001;
+/** The χ² test level a study file states none of. @internal */
+export const DEFAULT_ALPHA = 0.001;
 const TOP_KEYS = new Set([
     'description', 'gap', 'provenance', 'target', 'governing', 'observations', 'baselines', 'criterion', 'design',
     'correction',
@@ -55,18 +61,16 @@ const TOP_KEYS = new Set([
 const ROW_KEYS = new Set(['id', 'role', 'source', 'values', 'observed', 'sigma', 'inputSigma', 'note']);
 /** The keys a separate replication file may carry; the rest belong in the study file. */
 const REPLICATION_KEYS = new Set(['description', 'provenance', 'target', 'governing', 'observations']);
-const MAX_CORRECTION_TERMS = 6;
+/** How many powers a study file's correction may list in all. @internal */
+export const MAX_CORRECTION_TERMS = 6;
 function refuse(where, why) {
     throw new StudyRefusal(`study refused (${where}): ${why}`);
 }
-function isObject(v) {
-    return !!v && typeof v === 'object' && !Array.isArray(v);
-}
 function nonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0;
 }
 function quantity(raw, where) {
-    if (!isObject(raw) || !nonEmptyString(raw.name) || typeof raw.unit !== 'string') {
+    if (!isPlainObject(raw) || !nonEmptyString(raw.name) || typeof raw.unit !== 'string') {
         refuse(where, 'needs {"name", "unit"} ("unit": "" for a dimensionless quantity)');
     }
     let parsed;
@@ -109,11 +113,11 @@ function governingQuantity(raw, where) {
     return sigma === undefined ? q : { ...q, sigma: positiveSigma(sigma, q, `${where}.sigma`) };
 }
 function parseFamily(raw, governing, where) {
-    if (!isObject(raw) || !nonEmptyString(raw.input) || !Array.isArray(raw.powers)) {
+    if (!isPlainObject(raw) || !nonEmptyString(raw.input) || !Array.isArray(raw.powers)) {
         refuse(where, 'needs {"input": <dimensionless governing input>, "powers": [p, ...]}');
     }
     for (const k of Object.keys(raw)) {
-        if (k !== 'input' && k !== 'powers')
+        if (k !== 'input' && k !== 'powers' && k !== 'reference')
             refuse(where, `undeclared key '${k}'`);
     }
     const q = governing.find((g) => g.name === raw.input);
@@ -131,7 +135,19 @@ function parseFamily(raw, governing, where) {
     }
     if (new Set(powers).size !== powers.length)
         refuse(`${where}.powers`, 'must be distinct');
-    return { input: q.name, powers };
+    if (raw.reference === undefined)
+        return { input: q.name, powers };
+    if (!isPlainObject(raw.reference))
+        refuse(`${where}.reference`, 'must be {"<power>": number}, keyed by a declared power');
+    const reference = {};
+    for (const [k, v] of Object.entries(raw.reference)) {
+        if (!powers.some((p) => String(p) === k))
+            refuse(`${where}.reference`, `'${k}' is not a declared power of this family`);
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            refuse(`${where}.reference`, `'${k}' must be a finite number`);
+        reference[k] = v;
+    }
+    return { input: q.name, powers, reference };
 }
 /** One family `{input, powers}`, or a list of them, each in a different dimensionless input. */
 function parseCorrection(raw, governing) {
@@ -157,7 +173,7 @@ function parseCorrection(raw, governing) {
 /** Provenance text compared without case, spacing or punctuation: "Lab A" and "lab-a" are one source. */
 const provenanceKey = (s) => s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
 function parseProvenance(raw) {
-    if (!isObject(raw))
+    if (!isPlainObject(raw))
         refuse('provenance', 'is required: {"synthetic": true|false, "source": "..."}');
     if (typeof raw.synthetic !== 'boolean') {
         refuse('provenance.synthetic', 'must be declared true or false; it is never inferred');
@@ -180,7 +196,7 @@ function parseBaselines(raw, target, governing) {
     const checker = builtinFormulaDimensionChecker();
     return raw.map((b, i) => {
         const where = `baselines[${i}]`;
-        if (!isObject(b) || !nonEmptyString(b.name) || !nonEmptyString(b.formula)) {
+        if (!isPlainObject(b) || !nonEmptyString(b.name) || !nonEmptyString(b.formula)) {
             refuse(where, 'needs {"name", "formula"}');
         }
         let vars;
@@ -208,7 +224,7 @@ function parseBaselines(raw, target, governing) {
 function parseDesign(raw, governing) {
     if (raw === undefined)
         return undefined;
-    if (!isObject(raw) || !isObject(raw.variables))
+    if (!isPlainObject(raw) || !isPlainObject(raw.variables))
         refuse('design', 'needs {"variables": {name: {"min", "max"}}}');
     const byName = new Map(governing.map((g) => [g.name, g]));
     const out = {};
@@ -217,7 +233,7 @@ function parseDesign(raw, governing) {
         const where = `design.variables.${name}`;
         if (!q)
             refuse(where, 'is not a declared governing input');
-        if (!isObject(spec))
+        if (!isPlainObject(spec))
             refuse(where, 'needs {"min", "max"}');
         const min = toSi(spec.min, q, `${where}.min`, 'absolute');
         const max = toSi(spec.max, q, `${where}.max`, 'absolute');
@@ -235,9 +251,9 @@ function parseObservations(raw, provenance, target, governing, defaultSigma) {
         refuse('observations', 'must be a non-empty array');
     const ids = new Set();
     const rows = raw.map((row, i) => {
-        const id = isObject(row) && nonEmptyString(row.id) ? row.id : `row-${i + 1}`;
+        const id = isPlainObject(row) && nonEmptyString(row.id) ? row.id : `row-${i + 1}`;
         const where = `observation ${id}`;
-        if (!isObject(row))
+        if (!isPlainObject(row))
             refuse(where, 'is not an object');
         for (const k of Object.keys(row)) {
             if (!ROW_KEYS.has(k))
@@ -249,7 +265,7 @@ function parseObservations(raw, provenance, target, governing, defaultSigma) {
         if (row.role !== 'exploratory' && row.role !== 'holdout' && row.role !== 'replication') {
             refuse(where, `role must be exploratory, holdout or replication (got '${String(row.role)}')`);
         }
-        if (!isObject(row.values))
+        if (!isPlainObject(row.values))
             refuse(where, 'needs "values": {input: value}');
         for (const k of Object.keys(row.values)) {
             if (!governing.some((g) => g.name === k))
@@ -269,7 +285,7 @@ function parseObservations(raw, provenance, target, governing, defaultSigma) {
             refuse(where, 'has no uncertainty: give "sigma" on the row or on the target');
         }
         const sigma = positiveSigma(sigmaRaw, target, `${where} sigma`);
-        if (row.inputSigma !== undefined && !isObject(row.inputSigma))
+        if (row.inputSigma !== undefined && !isPlainObject(row.inputSigma))
             refuse(where, '"inputSigma" must be {input: σ}');
         const rowInputSigma = (row.inputSigma ?? {});
         for (const k of Object.keys(rowInputSigma)) {
@@ -327,7 +343,7 @@ function guardLeakage(rows) {
 }
 /** Parse and validate a study file. Throws {@link StudyRefusal}. @internal */
 export function parseStudy(raw, source = 'inline') {
-    if (!isObject(raw))
+    if (!isPlainObject(raw))
         refuse(source, 'is not a JSON object');
     for (const k of Object.keys(raw)) {
         if (!TOP_KEYS.has(k))
@@ -342,7 +358,7 @@ export function parseStudy(raw, source = 'inline') {
     const names = [target.name, ...governing.map((g) => g.name)];
     if (new Set(names).size !== names.length)
         refuse('governing', 'names must be distinct from each other and from the target');
-    const gapRaw = isObject(raw.gap) ? raw.gap : {};
+    const gapRaw = isPlainObject(raw.gap) ? raw.gap : {};
     const gap = {
         id: nonEmptyString(gapRaw.id) ? gapRaw.id : 'fg-study',
         kind: nonEmptyString(gapRaw.kind) ? gapRaw.kind : 'unexplained-observation',
@@ -352,7 +368,7 @@ export function parseStudy(raw, source = 'inline') {
         refuse('gap.kind', `unknown gap kind '${gap.kind}'`);
     let alpha = DEFAULT_ALPHA;
     if (raw.criterion !== undefined) {
-        if (!isObject(raw.criterion) || typeof raw.criterion.alpha !== 'number') {
+        if (!isPlainObject(raw.criterion) || typeof raw.criterion.alpha !== 'number') {
             refuse('criterion', 'needs {"alpha": number}');
         }
         alpha = raw.criterion.alpha;
@@ -379,18 +395,12 @@ export function parseStudy(raw, source = 'inline') {
 }
 /** Load a study JSON file. @internal */
 export function loadStudyFromJson(path) {
-    return parseStudy(JSON.parse(readFileSync(path, 'utf8')), path);
+    return parseStudy(readJsonFile(path), path);
 }
 function readStudyRaw(path) {
-    const text = readFileSync(path, 'utf8');
     if (/\.csv$/i.test(path))
-        return studyCsvToRaw(text, path);
-    try {
-        return JSON.parse(text);
-    }
-    catch (e) {
-        throw e instanceof SyntaxError ? new SyntaxError(`${path}: ${e.message}`) : e;
-    }
+        return studyCsvToRaw(readFileSync(path, 'utf8'), path);
+    return readJsonFile(path);
 }
 /**
  * Load a study file (`.csv`, else JSON) and, optionally, a separate
@@ -412,7 +422,7 @@ const sameDim = (a, b) => a.name === b.name && equals(a.dim, b.dim);
  * @internal
  */
 export function attachReplication(study, raw, source) {
-    if (!isObject(raw))
+    if (!isPlainObject(raw))
         refuse(source, 'is not a JSON object');
     for (const k of Object.keys(raw)) {
         if (!REPLICATION_KEYS.has(k)) {
@@ -469,23 +479,31 @@ function closeness(chi2, dof, alpha) {
     const pLower = chiSquareCdf(chi2, dof);
     return { chi2, dof, pLower, flagged: pLower < alpha / 2 };
 }
-/** Weighted straight line y = a + b·x with the effective variance σ_y² + b²σ_x², iterated from b = 1. */
+/**
+ * Weighted straight line y = a + b·x with the effective variance σ_y² + b²σ_x², iterated from b = 1.
+ * The weighted sums are core `pairwiseDot` and `pairwiseSum` (the stable sums), not a `reduce`.
+ */
 function affineFit(pts) {
     let b = 1;
     let a = 0;
+    const xs = pts.map((p) => p.x);
+    const ys = pts.map((p) => p.y);
+    const variance = (slope) => pts.map((p) => p.sy ** 2 + slope * slope * p.sx ** 2);
     for (let it = 0; it < 6; it++) {
-        const w = pts.map((p) => 1 / (p.sy ** 2 + b * b * p.sx ** 2));
-        const W = w.reduce((s, v) => s + v, 0);
-        const xm = pts.reduce((s, p, i) => s + w[i] * p.x, 0) / W;
-        const ym = pts.reduce((s, p, i) => s + w[i] * p.y, 0) / W;
-        const sxx = pts.reduce((s, p, i) => s + w[i] * (p.x - xm) ** 2, 0);
-        const sxy = pts.reduce((s, p, i) => s + w[i] * (p.x - xm) * (p.y - ym), 0);
+        const w = variance(b).map((v) => 1 / v);
+        const W = pairwiseSum(w);
+        const xm = pairwiseDot(w, xs) / W;
+        const ym = pairwiseDot(w, ys) / W;
+        const dx = xs.map((x) => x - xm);
+        const sxx = pairwiseDot(w, dx.map((d) => d * d));
+        const sxy = pairwiseDot(w, dx.map((d, i) => d * (ys[i] - ym)));
         if (!(sxx > 0) || !Number.isFinite(sxy))
             return null;
         b = sxy / sxx;
         a = ym - b * xm;
     }
-    const chi2 = pts.reduce((s, p) => s + (p.y - a - b * p.x) ** 2 / (p.sy ** 2 + b * b * p.sx ** 2), 0);
+    const v = variance(b);
+    const chi2 = pairwiseSum(pts.map((p, i) => (p.y - a - b * p.x) ** 2 / v[i]));
     return Number.isFinite(chi2) ? { a, b, chi2 } : null;
 }
 /**
@@ -594,7 +612,7 @@ function setPath(obj, path, value, where) {
     for (const k of path.slice(0, -1)) {
         if (at[k] === undefined)
             at[k] = {};
-        if (!isObject(at[k]))
+        if (!isPlainObject(at[k]))
             refuse(where, `'${k}' is already set to a value`);
         at = at[k];
     }
@@ -630,7 +648,9 @@ export function studyCsvToRaw(text, source = 'inline.csv') {
         const m = /^\s*#\s*([A-Za-z_][\w.()-]*)\s*:\s?(.*)$/.exec(l);
         if (!m)
             refuse(where, "a declaration is '# key: value'");
-        const [, key, valueText] = m;
+        // Both groups are unconditional in the pattern, so a match carries them.
+        const key = m[1];
+        const valueText = m[2];
         const value = declValue(valueText.trim());
         const path = key.split('.');
         if (key === 'target') {
@@ -700,13 +720,13 @@ export function studyCsvToRaw(text, source = 'inline.csv') {
         if (!governing.some((g) => g.name === k))
             refuse(`${source} governing.${k}.sigma`, `'${k}' is not a governing input column`);
     }
-    if (isObject(raw.target)) {
+    if (isPlainObject(raw.target)) {
         for (const k of Object.keys(raw.target)) {
             if (k !== 'sigma')
                 refuse(`${source} target.${k}`, "the target's name and unit come from its column; only 'target.sigma' is declared");
         }
     }
-    raw.target = { name: targetCol.name, unit: targetCol.unit, ...(isObject(raw.target) ? raw.target : {}) };
+    raw.target = { name: targetCol.name, unit: targetCol.unit, ...(isPlainObject(raw.target) ? raw.target : {}) };
     raw.governing = governing.map((g) => ({
         name: g.name,
         unit: g.unit,
@@ -742,64 +762,23 @@ export function studyCsvToRaw(text, source = 'inline.csv') {
     });
     return raw;
 }
-// --- χ² survival function -------------------------------------------------
-const LANCZOS = [
-    0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313, -176.61502916214059,
-    12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6, 1.5056327351493116e-7,
-];
-function lnGamma(z) {
-    if (z < 0.5)
-        return Math.log(Math.PI / Math.sin(Math.PI * z)) - lnGamma(1 - z);
-    const zz = z - 1;
-    let x = LANCZOS[0];
-    for (let i = 1; i < LANCZOS.length; i++)
-        x += LANCZOS[i] / (zz + i);
-    const t = zz + 7.5;
-    return 0.5 * Math.log(2 * Math.PI) + (zz + 0.5) * Math.log(t) - t + Math.log(x);
-}
-/** The series for the regularized lower incomplete gamma P(a, x); converges fast for x < a + 1. */
-function gammaSeries(a, x) {
-    const front = Math.exp(-x + a * Math.log(x) - lnGamma(a));
-    let ap = a;
-    let del = 1 / a;
-    let sum = del;
-    for (let n = 0; n < 1000; n++) {
-        ap += 1;
-        del *= x / ap;
-        sum += del;
-        if (Math.abs(del) < Math.abs(sum) * 1e-16)
-            break;
-    }
-    return sum * front;
+// --- χ² and F survival functions ------------------------------------------
+//
+// MathTS carries the regularized lower incomplete gamma `gammainc` (the
+// series for x < a + 1, else 1 − Q by continued fraction), the upper one
+// `gammaincp` (from `@danielsimonjr/mathts-functions` 0.68.3 the modified
+// Lentz continued fraction for x ≥ a + 1, computed directly; before that it
+// was `1 − gammainc`, which rounded a far upper tail to 0, and the χ² p-value
+// of a bad fit IS that tail) and the regularized incomplete beta `betainc`.
+/** Regularized lower incomplete gamma P(a, x), MathTS `gammainc`. */
+function gammaP(a, x) {
+    return numberFrom('gammainc', gammainc(a, x));
 }
-/** Regularized upper incomplete gamma Q(a, x). */
+/** Regularized upper incomplete gamma Q(a, x), MathTS `gammaincp` (direct in the upper tail). */
 function gammaQ(a, x) {
     if (x <= 0)
         return 1;
-    if (x < a + 1)
-        return Math.max(0, 1 - gammaSeries(a, x));
-    const front = Math.exp(-x + a * Math.log(x) - lnGamma(a));
-    const tiny = 1e-300;
-    let b = x + 1 - a;
-    let c = 1 / tiny;
-    let d = 1 / b;
-    let h = d;
-    for (let i = 1; i < 1000; i++) {
-        const an = -i * (i - a);
-        b += 2;
-        d = an * d + b;
-        if (Math.abs(d) < tiny)
-            d = tiny;
-        c = b + an / c;
-        if (Math.abs(c) < tiny)
-            c = tiny;
-        d = 1 / d;
-        const del = d * c;
-        h *= del;
-        if (Math.abs(del - 1) < 1e-16)
-            break;
-    }
-    return front * h;
+    return numberFrom('gammaincp', gammaincp(a, x));
 }
 /** P(χ²_ν ≥ chi2): the probability of a χ² at least this large if the model and σ are right. @internal */
 export function chiSquareSurvival(chi2, dof) {
@@ -810,8 +789,8 @@ export function chiSquareSurvival(chi2, dof) {
     return gammaQ(dof / 2, chi2 / 2);
 }
 /**
- * P(χ²_ν ≤ chi2), computed directly in the lower tail, where 1 − Q would
- * round a small probability away. @internal
+ * P(χ²_ν ≤ chi2), computed directly in the lower tail (MathTS `gammainc` is
+ * the series there), where 1 − Q would round a small probability away. @internal
  */
 export function chiSquareCdf(chi2, dof) {
     if (!(dof > 0))
@@ -820,51 +799,15 @@ export function chiSquareCdf(chi2, dof) {
         return 0;
     const a = dof / 2;
     const x = chi2 / 2;
-    return x < a + 1 ? Math.min(1, gammaSeries(a, x)) : 1 - gammaQ(a, x);
-}
-/** Continued fraction for the incomplete beta function (modified Lentz). */
-function betaCf(a, b, x) {
-    const tiny = 1e-300;
-    let c = 1;
-    let d = 1 - ((a + b) * x) / (a + 1);
-    if (Math.abs(d) < tiny)
-        d = tiny;
-    d = 1 / d;
-    let h = d;
-    for (let m = 1; m < 1000; m++) {
-        const m2 = 2 * m;
-        let aa = (m * (b - m) * x) / ((a + m2 - 1) * (a + m2));
-        d = 1 + aa * d;
-        if (Math.abs(d) < tiny)
-            d = tiny;
-        c = 1 + aa / c;
-        if (Math.abs(c) < tiny)
-            c = tiny;
-        d = 1 / d;
-        h *= d * c;
-        aa = (-(a + m) * (a + b + m) * x) / ((a + m2) * (a + m2 + 1));
-        d = 1 + aa * d;
-        if (Math.abs(d) < tiny)
-            d = tiny;
-        c = 1 + aa / c;
-        if (Math.abs(c) < tiny)
-            c = tiny;
-        d = 1 / d;
-        const del = d * c;
-        h *= del;
-        if (Math.abs(del - 1) < 1e-16)
-            break;
-    }
-    return h;
+    return x < a + 1 ? Math.min(1, gammaP(a, x)) : 1 - gammaQ(a, x);
 }
-/** Regularized incomplete beta I_x(a, b). */
+/** Regularized incomplete beta I_x(a, b), MathTS `betainc`. */
 function betaI(a, b, x) {
     if (x <= 0)
         return 0;
     if (x >= 1)
         return 1;
-    const front = Math.exp(lnGamma(a + b) - lnGamma(a) - lnGamma(b) + a * Math.log(x) + b * Math.log(1 - x));
-    return x < (a + 1) / (a + b + 2) ? (front * betaCf(a, b, x)) / a : 1 - (front * betaCf(b, a, 1 - x)) / b;
+    return numberFrom('betainc', betainc(a, b, x));
 }
 /** P(F_{d1,d2} ≥ f): the probability of an F ratio at least this large if the extra terms explain nothing. @internal */
 export function fSurvival(f, d1, d2) {
@@ -878,22 +821,58 @@ export function fSurvival(f, d1, d2) {
 }
 /**
  * The effective σ of one row under a model f: σ_eff² = σ_y² + Σ_i (∂f/∂x_i · σ_xi)²
- * over the inputs with a σ, each derivative by a central difference at the
- * recorded inputs. First order in σ_x: exact for f linear in x_i.
+ * over the inputs with a σ, the GUM first-order propagation of MathTS
+ * `propagateUncertainty` (the one uncertainty path of the library, as in
+ * `composition/uncertainty.ts`), each partial a central difference with the
+ * relative step 1e-6·|x_i| at the recorded inputs. An input that is exactly
+ * zero has no relative step, so it is passed to MathTS shifted by
+ * c = 1e3·σ_xi and read back as z − c inside the model: the derivative is
+ * unchanged and the step is 1e-6·c = 1e-3·σ_xi, the floor the hand-coded
+ * difference used before. First order in σ_x: exact for f linear in x_i.
  *
  * @internal
  */
 export function effectiveSigma(r, predict) {
-    let v = r.sigma * r.sigma;
-    for (const [name, sx] of Object.entries(r.inputSigma)) {
-        const x = r.inputs[name];
-        const h = Math.max(Math.abs(x) * 1e-6, sx * 1e-3);
-        const d = (predict({ ...r.inputs, [name]: x + h }) - predict({ ...r.inputs, [name]: x - h })) / (2 * h);
-        if (!Number.isFinite(d))
-            throw new RangeError(`the model's slope in ${name} is not finite on row ${r.id}`);
-        v += (d * sx) ** 2;
-    }
-    return Math.sqrt(v);
+    const names = Object.keys(r.inputSigma);
+    if (names.length === 0)
+        return r.sigma;
+    const values = {};
+    const shift = {};
+    for (const name of names) {
+        const x = r.inputs[name] ?? NaN;
+        shift[name] = x === 0 ? 1e3 * r.inputSigma[name] : 0;
+        values[name] = x + shift[name];
+    }
+    const unshifted = (v) => {
+        const inputs = { ...r.inputs };
+        for (const name of names)
+            inputs[name] = v[name] - shift[name];
+        return inputs;
+    };
+    const notFinite = (name) => new RangeError(`the model's slope in ${name} is not finite on row ${r.id}`);
+    // MathTS varies one input at a time; the input being varied when the model is not finite is
+    // the one to name, read from the stencil point itself rather than from MathTS's message.
+    let culprit = null;
+    const model = (v) => {
+        const y = predict(unshifted(v));
+        if (!Number.isFinite(y) && culprit === null)
+            culprit = names.find((name) => v[name] !== values[name]) ?? names[0];
+        return y;
+    };
+    let u;
+    try {
+        u = propagateUncertainty(model, values, r.inputSigma, { relativeStep: 1e-6 });
+    }
+    catch (e) {
+        if (culprit !== null)
+            throw notFinite(culprit);
+        throw e;
+    }
+    for (const name of names) {
+        if (!Number.isFinite(u.partials[name]))
+            throw notFinite(name);
+    }
+    return Math.hypot(r.sigma, u.sigma);
 }
 const hasInputSigma = (rows) => rows.some((r) => Object.keys(r.inputSigma).length > 0);
 function testRows(rows, predict, fitted, alpha) {
@@ -915,7 +894,42 @@ function testRows(rows, predict, fitted, alpha) {
     return { n: rows.length, chi2, dof, p, maxAbsZ, worstRow, pass: p === null ? null : p >= alpha };
 }
 const combine = (basis, coef) => (x) => basis.reduce((s, b, j) => s + coef[j] * b(x), 0);
-/** Solve the weighted normal equations for y ≈ Σ a_j·φ_j; null when they are singular. */
+/**
+ * The inverse of the equilibrated normal matrix B (k×k, unit diagonal), MathTS `inv`,
+ * unscaled back to the covariance of the coefficients: Σ = S⁻¹ B⁻¹ S⁻¹. Null when
+ * MathTS refuses the inverse or returns something other than a k×k number matrix.
+ */
+function covarianceOf(B, s) {
+    let raw;
+    try {
+        raw = inv(B.map((row) => [...row]));
+    }
+    catch {
+        return null;
+    }
+    const k = s.length;
+    if (!Array.isArray(raw) || raw.length !== k)
+        return null;
+    const out = [];
+    for (let a = 0; a < k; a++) {
+        const row = raw[a];
+        if (!Array.isArray(row) || row.length !== k)
+            return null;
+        const unscaled = [];
+        for (let b = 0; b < k; b++) {
+            const v = row[b];
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                return null;
+            unscaled.push(v / (s[a] * s[b]));
+        }
+        out.push(unscaled);
+    }
+    return out;
+}
+/**
+ * Solve the weighted normal equations for y ≈ Σ a_j·φ_j; null when they are singular.
+ * The covariance of the solution is the inverse of the same (equilibrated) matrix.
+ */
 function solveWeighted(phi, y, sigma) {
     const k = phi[0]?.length ?? 0;
     const A = Array.from({ length: k }, () => new Array(k + 1).fill(0));
@@ -927,8 +941,10 @@ function solveWeighted(phi, y, sigma) {
             A[a][k] += w * f[a] * y[i];
         }
     });
-    if (k === 1)
-        return A[0][0] > 0 ? [A[0][1] / A[0][0]] : null;
+    if (k === 1) {
+        const a00 = A[0][0];
+        return a00 > 0 ? { coef: [A[0][1] / a00], covariance: [[1 / a00]] } : null;
+    }
     // Equilibrate so the pivot test is scale-free, then eliminate with partial pivoting.
     const s = A.map((row, a) => Math.sqrt(row[a]));
     if (!s.every((v) => v > 0))
@@ -938,6 +954,7 @@ function solveWeighted(phi, y, sigma) {
             A[a][b] /= s[a] * s[b];
         A[a][k] /= s[a];
     }
+    const covariance = covarianceOf(A.map((row) => row.slice(0, k)), s);
     for (let c = 0; c < k; c++) {
         let p = c;
         for (let r = c + 1; r < k; r++)
@@ -954,13 +971,14 @@ function solveWeighted(phi, y, sigma) {
                 A[r][q] -= m * A[c][q];
         }
     }
-    return A.map((row, a) => row[k] / row[a] / s[a]);
+    return { coef: A.map((row, a) => row[k] / row[a] / s[a]), covariance };
 }
 const EV_ROUNDS = 50;
 /**
  * Weighted least squares y ≈ Σ a_j·φ_j(x), from the exploratory rows only.
  * With input σ the weights are 1/σ_eff² of the current fit, iterated to a
- * fixed point (the effective-variance method).
+ * fixed point (the effective-variance method); the covariance is that of the
+ * last solve, with the fixed-point weights.
  */
 function fitLinear(rows, basis) {
     const phi = rows.map((r) => basis.map((b) => {
@@ -970,20 +988,21 @@ function fitLinear(rows, basis) {
         return f;
     }));
     const y = rows.map((r) => r.observed);
-    let coef = solveWeighted(phi, y, rows.map((r) => r.sigma));
+    let sol = solveWeighted(phi, y, rows.map((r) => r.sigma));
     if (!hasInputSigma(rows))
-        return coef;
-    for (let round = 0; coef !== null && round < EV_ROUNDS; round++) {
+        return sol;
+    for (let round = 0; sol !== null && round < EV_ROUNDS; round++) {
+        const coef = sol.coef;
         const predict = combine(basis, coef);
         const next = solveWeighted(phi, y, rows.map((r) => effectiveSigma(r, predict)));
         if (next === null)
             return null;
-        const settled = next.every((a, j) => Math.abs(a - coef[j]) <= 1e-13 * Math.max(Math.abs(a), 1e-300));
-        coef = next;
+        const settled = next.coef.every((a, j) => Math.abs(a - coef[j]) <= 1e-13 * Math.max(Math.abs(a), 1e-300));
+        sol = next;
         if (settled)
             break;
     }
-    return coef;
+    return sol;
 }
 function split(study) {
     return {
@@ -1000,19 +1019,22 @@ function scoreModel(spec, sets, alpha, withheld) {
     const { id, kind, label } = spec;
     const k = spec.fit ? spec.basis.length : 0;
     const failed = (error) => ({
-        test: { id, kind, label, fittedParameters: k, prefactor: null, exploratory: null, holdout: null, replication: null, error },
+        test: { id, kind, label, fittedParameters: k, prefactor: null, prefactorStderr: null, exploratory: null, holdout: null, replication: null, error },
         predict: null,
         coef: null,
+        covariance: null,
     });
     try {
-        const coef = spec.fit ? fitLinear(sets.exploratory, spec.basis) : [1];
-        if (coef === null) {
+        const sol = spec.fit ? fitLinear(sets.exploratory, spec.basis) : { coef: [1], covariance: null };
+        if (sol === null) {
             return failed(k === 1
                 ? 'model is zero on every exploratory row; no scale can be fit'
                 : 'the model\'s terms are degenerate on the exploratory rows; they cannot be fit');
         }
+        const { coef, covariance } = sol;
         const predict = combine(spec.basis, coef);
         const on = (rows) => (withheld && rows.length > 0 ? testRows(rows, predict, 0, alpha) : null);
+        const v00 = covariance?.[0]?.[0];
         return {
             test: {
                 id,
@@ -1020,12 +1042,14 @@ function scoreModel(spec, sets, alpha, withheld) {
                 label,
                 fittedParameters: k,
                 prefactor: coef[0],
+                prefactorStderr: v00 !== undefined && v00 >= 0 ? Math.sqrt(v00) : null,
                 exploratory: sets.exploratory.length > 0 ? testRows(sets.exploratory, predict, k, alpha) : null,
                 holdout: on(sets.holdout),
                 replication: on(sets.replication),
             },
             predict,
             coef,
+            covariance,
         };
     }
     catch (e) {
@@ -1048,8 +1072,8 @@ function correctionBasis(shape, terms) {
 function admitCorrection(shape, families, rows, alpha) {
     const chi2With = (terms) => {
         const basis = correctionBasis(shape, terms);
-        const coef = fitLinear(rows, basis);
-        return coef === null ? null : testRows(rows, combine(basis, coef), terms.length + 1, alpha).chi2;
+        const sol = fitLinear(rows, basis);
+        return sol === null ? null : testRows(rows, combine(basis, sol.coef), terms.length + 1, alpha).chi2;
     };
     const steps = [];
     const admitted = [];
@@ -1058,23 +1082,25 @@ function admitCorrection(shape, families, rows, alpha) {
         for (const power of family.powers) {
             if (prev === null)
                 break families;
-            const term = { input: family.input, power };
+            const reference = family.reference?.[String(power)];
+            const term = { input: family.input, power, ...(reference !== undefined ? { reference } : {}) };
             const trial = [...admitted, term];
             const dof = rows.length - (trial.length + 1);
             if (dof < 1) {
-                steps.push({ ...term, F: null, dof, p: null, admitted: false, reason: 'ν < 1: too few exploratory rows to test another term' });
+                steps.push({ input: term.input, power: term.power, F: null, dof, p: null, admitted: false, reason: 'ν < 1: too few exploratory rows to test another term' });
                 break families;
             }
             const cur = chi2With(trial);
             if (cur === null) {
-                steps.push({ ...term, F: null, dof, p: null, admitted: false, reason: 'degenerate with the terms before it on the exploratory rows' });
+                steps.push({ input: term.input, power: term.power, F: null, dof, p: null, admitted: false, reason: 'degenerate with the terms before it on the exploratory rows' });
                 break;
             }
             const F = cur > 0 ? Math.max(0, prev - cur) / (cur / dof) : Infinity;
             const p = fSurvival(F, 1, dof);
             const ok = p < alpha;
             steps.push({
-                ...term,
+                input: term.input,
+                power: term.power,
                 F,
                 dof,
                 p,
@@ -1090,7 +1116,7 @@ function admitCorrection(shape, families, rows, alpha) {
     return { terms: admitted, steps };
 }
 /** Infix rendering of a scalar ExprNode for reports. */
-export function exprToInfix(e) {
+function exprToInfix(e) {
     if (e.kind === 'symbol')
         return e.name;
     if (e.kind === 'op') {
@@ -1125,9 +1151,10 @@ function credibility(t, nullTest, alpha) {
 function designAgainst(study, sets, candidate, baselines) {
     if (!candidate.predict)
         return { abstained: true, reason: 'no credible candidate to discriminate' };
-    const live = baselines
-        .filter((b) => b.predict && b.test.exploratory?.pass === true)
-        .sort((a, b) => (b.test.exploratory.p ?? 0) - (a.test.exploratory.p ?? 0));
+    const predict = candidate.predict;
+    // A live competitor has a predictor and passed on the exploratory rows; the guard types both.
+    const isLive = (b) => b.predict !== null && b.test.exploratory?.pass === true;
+    const live = baselines.filter(isLive).sort((a, b) => (b.test.exploratory.p ?? 0) - (a.test.exploratory.p ?? 0));
     const best = live[0];
     if (!best) {
         return {
@@ -1156,7 +1183,7 @@ function designAgainst(study, sets, candidate, baselines) {
             study.governing.forEach((g, i) => (point[g.name] = grids[i][idx[i]]));
             let disc;
             try {
-                disc = Math.abs(candidate.predict(point) - best.predict(point)) / sigma;
+                disc = Math.abs(predict(point) - best.predict(point)) / sigma;
             }
             catch {
                 return;
@@ -1176,7 +1203,8 @@ function designAgainst(study, sets, candidate, baselines) {
     if (bestPoint === null)
         return { abstained: true, reason: 'neither model is finite anywhere in the design bounds' };
     const chosen = bestPoint;
-    const maxEx = Math.max(...sets.exploratory.map((r) => Math.abs(candidate.predict(r.inputs) - best.predict(r.inputs)) / r.sigma));
+    // A reduce, not a spread: a spread of a large row set overflows the call stack.
+    const maxEx = sets.exploratory.reduce((m, r) => Math.max(m, Math.abs(predict(r.inputs) - best.predict(r.inputs)) / r.sigma), 0);
     return {
         abstained: false,
         against: best.test.label,
@@ -1250,17 +1278,39 @@ export async function runProbeStudy(study, opts = {}) {
             },
         ];
     });
-    const correctionOf = (s, coef) => 'correction' in s && s.correction && coef
-        ? {
+    const correctionOf = (s, coef, covariance) => {
+        if (!('correction' in s) || !s.correction || !coef)
+            return {};
+        const a0 = coef[0];
+        return {
             correction: {
                 base: s.correction.base,
-                terms: s.correction.terms.map((t, j) => ({ input: t.input, power: t.power, coefficient: coef[j + 1] / coef[0] })),
+                terms: s.correction.terms.map((t, j) => {
+                    const a = coef[j + 1];
+                    const coefficient = a / a0;
+                    // Delta method on c = a/a₀: Var(c) = Var(a)/a₀² + a²Var(a₀)/a₀⁴ − 2a·Cov(a, a₀)/a₀³.
+                    const cov = covariance;
+                    const variance = cov
+                        ? cov[j + 1][j + 1] / a0 ** 2 + (a * a * cov[0][0]) / a0 ** 4 - (2 * a * cov[j + 1][0]) / a0 ** 3
+                        : null;
+                    const stderr = variance !== null && Number.isFinite(variance) ? Math.sqrt(Math.max(0, variance)) : null;
+                    const reference = t.reference;
+                    const z = reference !== undefined && stderr !== null && stderr > 0 ? (coefficient - reference) / stderr : undefined;
+                    return {
+                        input: t.input,
+                        power: t.power,
+                        coefficient,
+                        stderr,
+                        ...(reference !== undefined ? { reference } : {}),
+                        ...(z !== undefined ? { z } : {}),
+                    };
+                }),
             },
-        }
-        : {};
+        };
+    };
     const scored = specs.map((s) => {
         const m = scoreModel(s.spec, sets, alpha, false);
-        return { model: m, spec: s.spec, complexity: s.complexity, extra: correctionOf(s, m.coef), ...credibility(m.test, nullModel, alpha) };
+        return { model: m, spec: s.spec, complexity: s.complexity, extra: correctionOf(s, m.coef, m.covariance), ...credibility(m.test, nullModel, alpha) };
     });
     const credibleOnes = scored
         .filter((s) => s.credible)
@@ -1460,11 +1510,18 @@ export function formatProbeStudy(r) {
     }
     L.push(`  null model (constant ${r.target.name}) — ${setLine('exploratory', r.nullModel.exploratory)}`);
     L.push('');
+    const pm = (stderr) => (stderr === null ? '' : ` ± ${stderr.toPrecision(2)}`);
     for (const c of r.candidates) {
-        const pre = c.prefactor === null ? '' : `, ĉ = ${c.prefactor.toPrecision(5)} (SI)`;
+        const pre = c.prefactor === null ? '' : `, ĉ = ${c.prefactor.toPrecision(5)}${pm(c.prefactorStderr)} (SI)`;
         L.push(`  candidate ${c.id}: ${c.label}${pre}`);
         if (c.correction) {
-            L.push(`    ${c.correction.terms.map((t, j) => `c${sub(j + 1)} = ${t.coefficient.toPrecision(4)}`).join(', ')} (fit on exploratory rows)`);
+            const term = (t, j) => {
+                const against = t.z !== undefined && t.reference !== undefined
+                    ? ` (z = ${t.z >= 0 ? '+' : ''}${t.z.toFixed(1)} against the declared ${Number(t.reference.toPrecision(4))})`
+                    : '';
+                return `c${sub(j + 1)} = ${t.coefficient.toPrecision(4)}${pm(t.stderr)}${against}`;
+            };
+            L.push(`    ${c.correction.terms.map(term).join(', ')} (fit on exploratory rows)`);
         }
         L.push(`    ${setLine('exploratory', c.exploratory)}`);
         L.push(`    ${c.credible ? 'credible' : 'not credible'}: ${c.credibility}`);
@@ -1479,7 +1536,7 @@ export function formatProbeStudy(r) {
         L.push('');
         L.push('  baselines (declared by the file; same rows, same criterion):');
         for (const b of r.baselines) {
-            const how = b.fittedParameters === 0 ? 'fixed, no fitted parameter' : `prefactor fit on exploratory rows = ${b.prefactor?.toPrecision(5)}`;
+            const how = b.fittedParameters === 0 ? 'fixed, no fitted parameter' : `prefactor fit on exploratory rows = ${b.prefactor?.toPrecision(5)}${pm(b.prefactorStderr)}`;
             L.push(`    ${b.label}  [${how}]`);
             if (b.error) {
                 L.push(`      not evaluable: ${b.error}`);