peeksafe 0.0.0-stage → 0.1.0

package/dist/cluster.js

@@ -0,0 +1,598 @@
+/**
+ * cluster.ts: the suite-level effect, with the cases treated as what they are.
+ *
+ * ## The bug this module exists to fix
+ *
+ * The obvious summary of a suite effect is an ordinary normal interval over the
+ * per-case differences:
+ *
+ *     mean ± 1.96 · sd / √n         with n = 200 cases
+ *
+ * That formula is only correct if the 200 numbers are 200 independent draws.
+ * They usually are not. A suite of **40 case files, each expanded into 5
+ * variants**, is typical: `extract.pricing#saas` and `extract.pricing#api`
+ * share a prompt template, a grader, an expectation shape and a failure mode.
+ * When one moves, its four siblings move with it. The effective number of
+ * independent observations is closer to 40 than to 200, the true standard error
+ * is larger than √(s²/200), and the reported interval is **too narrow**.
+ *
+ * A too-narrow interval on the headline number is the exact failure this whole
+ * package exists to prevent, so it gets a proper estimator rather than a fudge
+ * factor.
+ *
+ * ## What is estimated here, and what is not
+ *
+ * Clustering touches **only the suite-level (and family-level) summary**.
+ * Specifically:
+ *
+ *   affected      the across-case mean difference and its interval
+ *                 (`clusteredEffect`), plus any family-level roll-up.
+ *
+ *   NOT affected  every per-case quantity. Each case's e-value is its own
+ *                 self-contained test on that case's own runs; nothing about
+ *                 case *A* enters case *B*'s likelihood ratio. And the
+ *                 multiplicity correction is **e-BH**, which controls FDR under
+ *                 *arbitrary* dependence between the tested hypotheses, that
+ *                 is the whole reason it was chosen over BH. So `gate`'s
+ *                 verdict, its regressed cases and its thresholds are all
+ *                 bit-for-bit identical whether or not the cases cluster.
+ *
+ * In other words: clustering makes the *description* honest. It does not, and
+ * must not, move the *decision*.
+ *
+ * ## Two estimators, because they fail in different directions
+ *
+ * **CR2 (the headline).** A cluster-robust sandwich with the Bell-McCaffrey
+ * bias reduction. For the intercept-only model that a mean is, the hat matrix
+ * is H = J/n, so each cluster's leverage block is (I − J_{n_g}/n) and the CR2
+ * adjustment `A_g = (I − H_gg)^{-1/2}` collapses to a scalar on the cluster's
+ * residual sum:
+ *
+ *     Var̂(ȳ) = (1/n²) · Σ_g  (Σ_{i∈g} ê_i)²  /  (1 − n_g/n)
+ *
+ * Assumption-light: it needs the *families* to be independent of each other and
+ * nothing at all about the correlation structure *inside* a family. It does not
+ * assume the family effects are normal, or exchangeable, or even
+ * identically distributed. Paired with Bell-McCaffrey/Satterthwaite degrees of
+ * freedom (which, for equal-sized families, reduce exactly to G − 1; see the
+ * derivation in the comment above `dfRaw` below) it is the estimator you want
+ * when there are 40 clusters rather than 4,000.
+ *
+ * **Random effects (the cross-check).** The one-way model
+ * y_gi = μ + u_g + e_gi with the ANOVA (Swamy-Arora) estimators for τ² and σ².
+ * More efficient *if* its assumptions hold, and it yields the number that
+ * actually explains the width change: the intra-class correlation
+ * ρ = τ²/(τ² + σ²). If the two estimators disagree materially, that is itself
+ * information, and `compareEstimators` says so rather than picking a winner.
+ *
+ * ## The design effect
+ *
+ * `designEffect` = (clustered SE / naive iid SE)². It is the factor by which
+ * the naive analysis overstated its own information, "these 200 cases carry
+ * the information of 200/DEFF independent ones". For roughly equal families of
+ * size k it tracks the textbook 1 + (k − 1)ρ, which is the sanity check the
+ * tests assert.
+ */
+import { PeeksafeError } from "./errors.js";
+import { normalQuantile, tQuantile } from "./stats.js";
+/* ────────────────────────── the clustering key ───────────────────────── */
+/**
+ * The cluster a case belongs to: its **case file**.
+ *
+ * Variant ids are expected as `<fileId>#<variant>`, so everything before
+ * the first `#` is the file, and the file is the unit an author actually wrote.
+ * A case with no `#` is its own family of one, which is correct, not a
+ * degenerate case: an unexpanded case file shares its template with nobody.
+ */
+export function caseFamily(caseId) {
+    const i = caseId.indexOf("#");
+    return i < 0 ? caseId : caseId.slice(0, i);
+}
+/**
+ * The cluster key for a case: the one it **declares**, or its case file.
+ *
+ * `caseFamily` sees exactly one reason two cases correlate, that they were
+ * minted from the same file, and is blind to every other: a shared grader, a
+ * shared fixture directory, one flaky tool that six unrelated cases happen to
+ * call. Those cases are correlated too, and the interval will be too narrow
+ * again for a reason the id cannot express. So a case may declare its own key.
+ *
+ * A wrong key is worse than no key, which is why `clusterKeyDiagnostic` ships
+ * alongside: declaring two genuinely independent cases into one family throws
+ * away real information and widens the interval for nothing, and the only way
+ * to know is to look at the ICC the declared grouping actually exhibits.
+ */
+export const clusterKey = (c) => {
+    // Trimmed, so `cluster: "  "` is not a distinct family that silently merges
+    // every case that has one. An all-whitespace key is no key.
+    const declared = c.cluster?.trim();
+    return declared ? declared : caseFamily(c.id);
+};
+// Called before the early returns, which never reach a quantile, so every suite refuses the same level.
+function requireLevel(level, where) {
+    if (!(level > 0 && level < 1)) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: level must be in (0,1), got ${level}`, {
+            detail: { level },
+            hint: "a two-sided confidence level such as 0.95, not a percentage and not an error budget",
+        });
+    }
+}
+/** Group observations by cluster, preserving first-seen order. */
+export function groupByCluster(obs) {
+    const m = new Map();
+    for (const o of obs) {
+        if (!Number.isFinite(o.value)) {
+            throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `clustered mean: value for cluster "${o.cluster}" is not finite`, {
+                detail: { cluster: o.cluster, value: o.value },
+            });
+        }
+        const xs = m.get(o.cluster);
+        if (xs)
+            xs.push(o.value);
+        else
+            m.set(o.cluster, [o.value]);
+    }
+    return m;
+}
+/** The naive iid interval, kept so the two can be printed side by side. */
+export function iidMean(values, level = 0.95) {
+    requireLevel(level, "iidMean");
+    const n = values.length;
+    if (n === 0)
+        return { low: -1, high: 1, point: 0, observations: 0 };
+    const mean = values.reduce((a, b) => a + b, 0) / n;
+    const sd = n > 1 ? Math.sqrt(values.reduce((a, x) => a + (x - mean) ** 2, 0) / (n - 1)) : 0;
+    const z = normalQuantile(1 - (1 - level) / 2);
+    const half = (z * sd) / Math.sqrt(n);
+    return { low: mean - half, high: mean + half, point: mean, observations: n };
+}
+/**
+ * CR2 cluster-robust interval for a mean, with Bell-McCaffrey degrees of
+ * freedom. See the module header for the derivation; the short version is that
+ * for an intercept-only design the whole apparatus collapses to
+ *
+ *     Var̂ = (1/n²) Σ_g (Σ_{i∈g} ê_i)² / (1 − n_g/n)
+ *
+ * and the Satterthwaite df to a closed form in the cluster sizes alone.
+ */
+export function clusterRobustMean(obs, level = 0.95) {
+    requireLevel(level, "clusterRobustMean");
+    const groups = groupByCluster(obs);
+    const n = obs.length;
+    const G = groups.size;
+    const sizes = [...groups.values()].map((xs) => xs.length);
+    const naive = iidMean(obs.map((o) => o.value), level);
+    const naiveSe = n > 1 ? Math.sqrt(obs.reduce((a, o) => a + (o.value - naive.point) ** 2, 0) / (n - 1) / n) : 0;
+    const base = {
+        point: naive.point,
+        observations: n,
+        clusters: G,
+        largestCluster: sizes.length ? Math.max(...sizes) : 0,
+        meanClusterSize: G > 0 ? n / G : 0,
+        naiveSe,
+        method: "CR2",
+    };
+    // One cluster is one observation. There is nothing to average over, so there
+    // is no standard error, and saying "±0.4 points" here would be exactly the
+    // fabricated-precision failure this module was written to remove.
+    if (n === 0 || G < 2) {
+        return {
+            ...base,
+            low: -1,
+            high: 1,
+            se: Infinity,
+            designEffect: Infinity,
+            widthRatio: Infinity,
+            df: 0,
+            tCritical: Infinity,
+            effectiveSampleSize: G,
+            degenerate: n === 0
+                ? "no cases contributed an estimate"
+                : `all ${n} cases belong to one family ("${[...groups.keys()][0]}"), a single cluster carries no ` +
+                    "information about between-family variation, so no interval is estimable",
+        };
+    }
+    const mean = base.point;
+    let meat = 0;
+    for (const xs of groups.values()) {
+        const sumRes = xs.reduce((a, x) => a + (x - mean), 0);
+        const leverage = 1 - xs.length / n; // > 0 because G ≥ 2
+        meat += (sumRes * sumRes) / leverage;
+    }
+    const variance = meat / (n * n);
+    const se = Math.sqrt(variance);
+    // Bell-McCaffrey / Satterthwaite df. With g_g = M b_g the closed forms are
+    //   tr(G)  = Σ n_g/n² = 1/n
+    //   tr(G²) = Σ_g (n_g/n²)² + Σ_{g≠h} (n_g n_h)² / (n⁶ (1−n_g/n)(1−n_h/n))
+    // and df = tr(G)² / tr(G²). For equal cluster sizes this is exactly G − 1.
+    const n2 = n * n;
+    let trG2 = 0;
+    for (let i = 0; i < G; i++) {
+        const ni = sizes[i];
+        trG2 += (ni / n2) ** 2;
+        for (let j = 0; j < G; j++) {
+            if (i === j)
+                continue;
+            const nj = sizes[j];
+            const denom = (1 - ni / n) * (1 - nj / n);
+            trG2 += (ni * nj) ** 2 / (n2 * n2 * n2 * denom);
+        }
+    }
+    const trG = 1 / n;
+    const dfRaw = trG2 > 0 ? (trG * trG) / trG2 : G - 1;
+    const df = Math.min(n - 1, Math.max(1, dfRaw));
+    const t = tQuantile(1 - (1 - level) / 2, df);
+    const half = t * se;
+    const z = normalQuantile(1 - (1 - level) / 2);
+    const naiveHalf = z * naiveSe;
+    return {
+        ...base,
+        low: mean - half,
+        high: mean + half,
+        se,
+        designEffect: naiveSe > 0 ? (se / naiveSe) ** 2 : se > 0 ? Infinity : 1,
+        widthRatio: naiveHalf > 0 ? half / naiveHalf : half > 0 ? Infinity : 1,
+        df,
+        tCritical: t,
+        // n / DEFF, **capped at n**. When the families happen to disagree less than
+        // the cases within them, the CR2 standard error lands below the iid one and
+        // DEFF comes out under 1, a finite-sample fact about this sample, not
+        // information the clustering created. Uncapped, this read "worth
+        // 222 independent cases / 200", which claims a suite of 200 carries more
+        // than 200 cases' worth of evidence. It does not. The design effect itself
+        // is reported unclamped, because *that* number is the estimate.
+        effectiveSampleSize: naiveSe > 0 ? Math.min(n, n / Math.max(1e-12, (se / naiveSe) ** 2)) : n,
+        degenerate: null,
+    };
+}
+/**
+ * One-way random-effects (hierarchical) estimate of the same mean.
+ *
+ *   y_gi = μ + u_g + e_gi,   u_g ~ (0, τ²),   e_gi ~ (0, σ²)
+ *
+ * τ² and σ² come from the ANOVA decomposition (the Swamy-Arora estimator,
+ * unbiased and closed-form, and it does not need the normality that REML would
+ * lean on). μ̂ is the GLS weighted mean of the family means with
+ * w_g = 1/(τ² + σ²/n_g), so its variance is 1/Σw_g.
+ *
+ * Two properties worth knowing before trusting it:
+ *  - at τ̂² = 0 it degenerates **exactly** to the naive iid interval, which is
+ *    the correct behaviour: no between-family variance means the cases really
+ *    were exchangeable;
+ *  - it weights families by information rather than by size, so unlike the
+ *    unweighted mean it is not the same point estimate as CR2 when families
+ *    differ in size. That difference is a feature and it is reported.
+ */
+export function randomEffectsMean(obs, level = 0.95) {
+    requireLevel(level, "randomEffectsMean");
+    const groups = groupByCluster(obs);
+    const n = obs.length;
+    const G = groups.size;
+    const grand = n > 0 ? obs.reduce((a, o) => a + o.value, 0) / n : 0;
+    const shell = {
+        observations: n,
+        clusters: G,
+        method: "random-effects",
+    };
+    if (n === 0 || G < 2) {
+        return {
+            ...shell,
+            point: grand,
+            low: -1,
+            high: 1,
+            tauSquared: 0,
+            sigmaSquared: 0,
+            icc: 0,
+            se: Infinity,
+            df: 0,
+            degenerate: n === 0 ? "no cases contributed an estimate" : "a single family cannot separate τ² from σ²",
+        };
+    }
+    const entries = [...groups.entries()].map(([k, xs]) => ({
+        key: k,
+        size: xs.length,
+        mean: xs.reduce((a, x) => a + x, 0) / xs.length,
+        values: xs,
+    }));
+    let ssw = 0;
+    let ssb = 0;
+    for (const g of entries) {
+        for (const x of g.values)
+            ssw += (x - g.mean) ** 2;
+        ssb += g.size * (g.mean - grand) ** 2;
+    }
+    const dfW = n - G;
+    const dfB = G - 1;
+    // Every family has exactly one member: there is no within-family replication,
+    // so σ² is not identified, and there is also no clustering left to correct
+    // for. The iid interval is then the right answer, not an approximation.
+    if (dfW === 0) {
+        const iid = iidMean(obs.map((o) => o.value), level);
+        return {
+            ...shell,
+            point: iid.point,
+            low: iid.low,
+            high: iid.high,
+            tauSquared: dfB > 0 ? ssb / dfB : 0,
+            sigmaSquared: 0,
+            icc: 1,
+            se: dfB > 0 ? Math.sqrt(ssb / dfB / n) : 0,
+            df: dfB,
+            degenerate: "every family has exactly one case, no within-family replication, so σ² is not identified " +
+                "and the observations are already independent",
+        };
+    }
+    const msw = ssw / dfW;
+    const msb = ssb / dfB;
+    // k₀: the "average" cluster size the ANOVA estimator divides by. Equals the
+    // common size when families are balanced.
+    const sumSq = entries.reduce((a, g) => a + g.size * g.size, 0);
+    const k0 = (n - sumSq / n) / dfB;
+    const sigmaSquared = msw;
+    const tauSquared = k0 > 0 ? Math.max(0, (msb - msw) / k0) : 0;
+    // Neither variance component is positive, so every case took the same value.
+    // The GLS weight 1/(τ² + σ²/n_g) is then 1/0 for every family, the total
+    // weight is Infinity, and the weighted mean came out Infinity/Infinity, i.e.
+    // NaN, with `degenerate` left null, which says the estimate was formed. A
+    // pull request that moved nothing produces exactly this: every per-case
+    // difference is zero. CR2 and the iid interval both answer the grand mean
+    // with a zero-width interval here, and so does this.
+    if (!(tauSquared + sigmaSquared > 0)) {
+        return {
+            ...shell,
+            point: grand,
+            low: grand,
+            high: grand,
+            tauSquared: 0,
+            sigmaSquared: 0,
+            icc: 0,
+            se: 0,
+            df: dfB,
+            degenerate: null,
+        };
+    }
+    let sumW = 0;
+    let sumWY = 0;
+    for (const g of entries) {
+        const w = 1 / (tauSquared + sigmaSquared / g.size);
+        sumW += w;
+        sumWY += w * g.mean;
+    }
+    const point = sumW > 0 ? sumWY / sumW : grand;
+    const se = sumW > 0 ? Math.sqrt(1 / sumW) : Infinity;
+    const df = dfB;
+    const t = tQuantile(1 - (1 - level) / 2, df);
+    return {
+        ...shell,
+        point,
+        low: point - t * se,
+        high: point + t * se,
+        se,
+        tauSquared,
+        sigmaSquared,
+        icc: tauSquared + sigmaSquared > 0 ? tauSquared / (tauSquared + sigmaSquared) : 0,
+        df,
+        degenerate: null,
+    };
+}
+const fmtPts = (x) => `${x >= 0 ? "+" : ""}${(x * 100).toFixed(1)}`;
+/**
+ * The whole suite-level story in one object: the honest interval, the naive one
+ * it replaces, the factor between them, and whether swapping them changes what
+ * a reader would conclude.
+ */
+export function clusteredEffect(obs, level = 0.95) {
+    const cr2 = clusterRobustMean(obs, level);
+    const re = randomEffectsMean(obs, level);
+    const naive = iidMean(obs.map((o) => o.value), level);
+    const groups = groupByCluster(obs);
+    const families = [...groups.entries()]
+        .map(([family, xs]) => {
+        const m = xs.reduce((a, x) => a + x, 0) / xs.length;
+        const sd = xs.length > 1 ? Math.sqrt(xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1)) : 0;
+        return { family, cases: xs.length, point: m, sd, min: Math.min(...xs), max: Math.max(...xs) };
+    })
+        .sort((a, b) => a.point - b.point || (a.family < b.family ? -1 : 1));
+    const excludesZero = (i) => i.low > 0 || i.high < 0;
+    const signFlippedByClustering = excludesZero(naive) && !excludesZero(cr2);
+    const headline = cr2.degenerate
+        ? `suite effect ${fmtPts(cr2.point)}pts, no interval: ${cr2.degenerate}`
+        : `suite effect ${fmtPts(cr2.point)}pts [${fmtPts(cr2.low)}, ${fmtPts(cr2.high)}] ` +
+            `over ${cr2.clusters} case families (${cr2.observations} cases); ` +
+            `clustering widens the interval ${cr2.widthRatio.toFixed(2)}× (design effect ${cr2.designEffect.toFixed(2)}, ` +
+            `ICC ${re.icc.toFixed(2)}), so the suite is worth ~${Math.round(cr2.effectiveSampleSize)} independent cases, not ${cr2.observations}` +
+            (signFlippedByClustering
+                ? ". The naive interval excluded zero and this one does not, the apparent suite-level move does not survive the correction."
+                : "");
+    return {
+        cr2,
+        randomEffects: re,
+        naive,
+        designEffect: cr2.designEffect,
+        widthRatio: cr2.widthRatio,
+        icc: re.icc,
+        clusters: cr2.clusters,
+        observations: cr2.observations,
+        families,
+        signFlippedByClustering,
+        headline,
+    };
+}
+/**
+ * Do the two estimators tell the same story? They rest on different
+ * assumptions, so agreement is evidence and disagreement is a warning worth
+ * printing rather than resolving by fiat.
+ */
+export function compareEstimators(e) {
+    if (e.cr2.degenerate || e.randomEffects.degenerate) {
+        return { agree: true, seRatio: 1, note: e.cr2.degenerate ?? e.randomEffects.degenerate ?? "" };
+    }
+    // Two estimators that both report a standard error of zero agree; it is only
+    // a zero model-based SE under a positive robust one that is an infinite
+    // ratio. Reading every zero as Infinity made the note say "the family effects
+    // are not behaving like independent draws from one distribution, so trust CR2
+    // and not the hierarchical fit" about a suite with no variance at all, where
+    // the two estimators had produced the same number. Same shape as
+    // `designEffect` in `clusterRobustMean`, for the same reason.
+    const seRatio = e.randomEffects.se > 0 ? e.cr2.se / e.randomEffects.se : e.cr2.se > 0 ? Infinity : 1;
+    const agree = seRatio > 0.7 && seRatio < 1.45;
+    return {
+        agree,
+        seRatio,
+        note: agree
+            ? `CR2 and the random-effects model agree to within ${(Math.abs(seRatio - 1) * 100).toFixed(0)}% on the standard error`
+            : seRatio > 1
+                ? `the robust SE is ${seRatio.toFixed(2)}× the model-based one, the family effects are not behaving like ` +
+                    "independent draws from one distribution, so trust CR2 and not the hierarchical fit"
+                : `the robust SE is only ${seRatio.toFixed(2)}× the model-based one, with this few families CR2 can be ` +
+                    "optimistic; report the wider of the two",
+    };
+}
+/**
+ * Below this many clusters, a cluster-robust standard error is optimistic even
+ * with small-cluster degrees of freedom. Standard practice; `compareEstimators`
+ * says the same thing from the other direction.
+ */
+export const MIN_TRUSTWORTHY_CLUSTERS = 20;
+const summarise = (key, obs) => {
+    const cr2 = clusterRobustMean(obs);
+    const re = randomEffectsMean(obs);
+    return {
+        key,
+        // Only CR2 decides whether this grouping has an interval, which is what
+        // `degenerate` documents. The random-effects fit degenerating is a
+        // different fact about a different estimator: with one case per family σ²
+        // is not identified, so there is no ICC to report, but the cluster-robust
+        // interval is estimable and is in fact the iid one. Folding the two
+        // together made `clusterKeyDiagnostic` answer "no suite-level interval is
+        // estimable ... it is no claim at all" about a grouping whose standard
+        // error it had just computed, in a sentence reading "collapses 8 case-file
+        // groups into 80".
+        degenerate: cr2.degenerate,
+        clusters: cr2.clusters,
+        meanClusterSize: cr2.meanClusterSize,
+        icc: re.icc,
+        designEffect: cr2.designEffect,
+        widthRatio: cr2.widthRatio,
+        se: cr2.se,
+        effectiveSampleSize: cr2.effectiveSampleSize,
+        iccEstimable: re.degenerate === null,
+    };
+};
+/**
+ * Does a user-declared cluster key carry anything?
+ *
+ * The honest answer is a comparison, not a number: the same observations are
+ * grouped both ways and the intra-class correlation of each grouping is
+ * reported. A declared key that merges cases which do not in fact move together
+ * shows an ICC near zero while having *fewer, larger* clusters than the
+ * fallback, it has thrown away real information and widened the interval to
+ * pay for it. A declared key that finds correlation the case ids could not see
+ * shows a higher ICC and a larger design effect, and is doing its job. A
+ * declared key that is *finer* than the fallback, splitting apart files whose
+ * variants do move together, narrows the interval instead, and that is the
+ * dangerous direction rather than the merely wasteful one.
+ *
+ * Neither outcome is corrected automatically. A cluster key is a claim about
+ * the world and only the person who made it can say whether it is true; this
+ * says what the data thinks of it.
+ */
+export function clusterKeyDiagnostic(declared, fallback) {
+    if (declared.length !== fallback.length) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `clusterKeyDiagnostic: the two groupings must cover the same observations (${declared.length} vs ${fallback.length})`, {
+            detail: { declared: declared.length, fallback: fallback.length },
+            hint: "group the same value array twice; do not filter one of them",
+        });
+    }
+    const d = summarise("declared", declared);
+    const f = summarise("case-id", fallback);
+    // A grouping with fewer than two clusters has no estimable between-family
+    // variance, so its design effect is Infinity and its ICC is meaningless.
+    // Comparing those against the fallback produces a verdict full of `Infinity×`
+    // that reads like a very large finding and is really an absence of one.
+    if (d.degenerate !== null) {
+        return {
+            declared: d,
+            fallback: f,
+            mergesUncorrelatedCases: true,
+            narrowsOnTooFewClusters: false,
+            narrowsBySplitting: false,
+            findsHiddenCorrelation: false,
+            verdict: `the declared key collapses ${f.clusters} case-file groups into ${d.clusters}, ${d.degenerate}. ` +
+                "No suite-level interval is estimable under this grouping, so it is not a tighter claim " +
+                "than the default; it is no claim at all",
+        };
+    }
+    // "Materially positive" rather than "> 0": the ANOVA ICC estimator is noisy
+    // and routinely lands slightly above zero on independent data, so a test at
+    // exactly zero would call every grouping useful.
+    const ICC_FLOOR = 0.05;
+    const coarser = d.clusters < f.clusters;
+    const mergesUncorrelatedCases = coarser && d.iccEstimable && d.icc < ICC_FLOOR;
+    const narrowsOnTooFewClusters = mergesUncorrelatedCases && d.widthRatio < f.widthRatio && d.clusters < MIN_TRUSTWORTHY_CLUSTERS;
+    // The other direction. Both flags above require `coarser`, so a key that
+    // *splits* the case files apart fell through every branch to "it is not
+    // changing the answer either way", on a grouping that had just taken the
+    // interval from 3.90× the iid one to 1.02×. Gated on the fallback showing
+    // real correlation: when the case files do not move together anyway,
+    // splitting them costs nothing and there is nothing to warn about.
+    //
+    // Sharing ICC_FLOOR with `mergesUncorrelatedCases` also shares its noise. On
+    // 8 families of 10 this fires on every seed where the families really move
+    // and on 0.195 of the seeds where they do not; `cluster.test.ts` costs both
+    // out. That asymmetry is the one to have: the flag errs toward asking an
+    // operator to look again at an interval that got narrower, which is the
+    // question this module exists to make people ask.
+    const narrowsBySplitting = d.clusters > f.clusters && f.iccEstimable && f.icc >= ICC_FLOOR && d.widthRatio < f.widthRatio;
+    // `iccEstimable` first: a grouping of singletons reports ICC exactly 1 as an
+    // artifact of σ̂² = 0, which sailed past this floor and could announce that a
+    // one-case-per-cluster key had "found correlation the case ids could not
+    // see". One case per cluster is the absence of within-cluster correlation.
+    const findsHiddenCorrelation = d.iccEstimable && d.icc >= ICC_FLOOR && d.designEffect > f.designEffect * 1.1;
+    // Quote the *interval width*, not the design effect. They do not move
+    // together: a coarse grouping with near-zero ICC can have a design effect
+    // below 1 and still produce a much wider interval, because 4 clusters buy 3
+    // degrees of freedom and a t-critical to match. The first draft of this line
+    // said "widening the interval (0.11× vs 0.91×)", which reads as narrowing.
+    const widths = `its interval is ${d.widthRatio.toFixed(2)}× the iid one against ${f.widthRatio.toFixed(2)}× for the case-file default`;
+    // "ICC 1.00" is what a singleton grouping prints, and it says the cases are
+    // perfectly correlated when the grouping is the statement that they are not
+    // correlated at all. Say the number is missing rather than inventing one.
+    const icc = (g) => (g.iccEstimable ? g.icc.toFixed(2) : "not identified");
+    const verdict = narrowsOnTooFewClusters
+        ? `the declared key merges ${f.clusters} case-file groups into ${d.clusters}, and those ${d.clusters} show ` +
+            `ICC ${icc(d)}, they do not move together, so ${widths}. That is the wrong direction: ` +
+            `a cluster-robust interval over fewer than ${MIN_TRUSTWORTHY_CLUSTERS} clusters is optimistic, and this key has ` +
+            `made the suite-level claim *tighter* than the default on cases that share nothing`
+        : mergesUncorrelatedCases
+            ? `the declared key merges ${f.clusters} case-file groups into ${d.clusters}, and those ${d.clusters} show ` +
+                `ICC ${icc(d)}, they do not move together, so ${widths}, and the extra width is ` +
+                `buying no information`
+            : narrowsBySplitting
+                ? `the declared key splits ${f.clusters} case-file groups into ${d.clusters}, but those ${f.clusters} files ` +
+                    `show ICC ${icc(f)}, they do move together, so ${widths}. The split is a claim that the suite is worth ` +
+                    `~${Math.round(d.effectiveSampleSize)} independent cases rather than ~${Math.round(f.effectiveSampleSize)}, ` +
+                    "and it buys a narrower suite-level interval than the default with nothing behind it"
+                : findsHiddenCorrelation
+                    ? `the declared key finds correlation the case ids could not see: design effect ` +
+                        `${d.designEffect.toFixed(2)} against ${f.designEffect.toFixed(2)} over ${d.clusters} groups rather than ` +
+                        `${f.clusters} (ICC ${icc(d)} within the declared groups, ${icc(f)} within case files). ` +
+                        `The suite is worth ~${Math.round(d.effectiveSampleSize)} independent cases, not ${Math.round(f.effectiveSampleSize)}` +
+                        (d.clusters < MIN_TRUSTWORTHY_CLUSTERS
+                            ? `. Treat the interval as a lower bound on the width: ${d.clusters} clusters is below the ${MIN_TRUSTWORTHY_CLUSTERS} ` +
+                                "a cluster-robust estimator needs to be trusted"
+                            : "")
+                    : `the declared key and the case-file default agree to within ` +
+                        `${((Math.abs(d.designEffect - f.designEffect) / Math.max(1e-9, f.designEffect)) * 100).toFixed(0)}% on the design effect ` +
+                        `(ICC ${icc(d)} vs ${icc(f)}), it is not changing the answer either way`;
+    return {
+        declared: d,
+        fallback: f,
+        mergesUncorrelatedCases,
+        narrowsOnTooFewClusters,
+        narrowsBySplitting,
+        findsHiddenCorrelation,
+        verdict,
+    };
+}
+//# sourceMappingURL=cluster.js.map

package/dist/cluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../src/cluster.ts"],"names":[],"mappings":"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"}