@mmnto/totem 1.64.2 → 1.66.0

package/dist/spine/windtunnel-scorer.js

@@ -0,0 +1,191 @@
+// ─── Types ──────────────────────────────────────────
+// ─── Pure scorer ─────────────────────────────────────
+/**
+ * Score a wind-tunnel run. Pure function: no IO, no clock, no randomness.
+ * Implements ADR-110 §4/§5 done-criterion exactly per spec invariants.
+ *
+ * Verdict ordering (highest precedence first) — #2189 ruling:
+ *   1. Any firing labeled FP → FAIL (confirmed FP is a claim; precision = breaching value)
+ *   2. Positive control does not fire its target → FAIL (vacuous pass; precision = null)
+ *   3. Exposure floor below minimum → HONEST-NEGATIVE (masquerade guard; precision = null)
+ *   4. Cull rate exceeds threshold → HONEST-NEGATIVE (cull-laundering guard; precision = null)
+ *   5. Any unlabeled firing → HONEST-NEGATIVE (needs adjudication, not PASS; precision = null)
+ *   6. All labeled TP → PASS (precision = 1.0)
+ *
+ * The FAIL tier (1–2) outranks the masquerade guards (3–4): a guard may only
+ * DEMOTE a would-be PASS, never UPGRADE a FAIL. survivorPrecision (diagnostics)
+ * carries the informative survivor ratio distinct from the certifying precision.
+ */
+export function scoreWindtunnel(input) {
+    const { firings, groundTruth, positiveControlTargets, mintedRuleIds, cullRateThreshold, exposureFloors, actualExposure, } = input;
+    const mintedRuleCount = mintedRuleIds.length;
+    const cullLedger = [];
+    const needsAdjudication = [];
+    // Step 1: Cull rules that fire on negative controls (S2/C5).
+    // A rule firing on ANY negative-control item is culled + recorded in
+    // cullLedger. Never silently dropped.
+    const culledRuleIds = new Set();
+    for (const firing of firings) {
+        if (firing.controlKind === 'negative') {
+            culledRuleIds.add(firing.ruleId);
+            cullLedger.push({
+                ruleId: firing.ruleId,
+                pr: firing.pr,
+                filePath: firing.filePath.replace(/\\/g, '/'),
+                matchedLine: firing.matchedLine,
+                reason: 'negative-control-fired',
+            });
+        }
+    }
+    const culledCount = culledRuleIds.size;
+    const survivingRuleCount = mintedRuleCount - culledCount;
+    // Exposure tuple: always a 3-tuple, never collapsed (spec invariant).
+    const exposureTuple = [
+        actualExposure.activeRulesEvaluated,
+        actualExposure.filesTouchedInWindow,
+        actualExposure.positiveControlsExercised,
+    ];
+    // Step 2: Label surviving (non-negative-control, non-culled) firings. Computed
+    // BEFORE the masquerade guards because the FAIL tier outranks them (#2189) — we
+    // must know hasFp/nonVacuity before deciding whether a guard may short-circuit.
+    let hasFp = false;
+    let tpCount = 0;
+    let labeledCount = 0;
+    for (const firing of firings) {
+        if (firing.controlKind === 'negative')
+            continue;
+        if (culledRuleIds.has(firing.ruleId))
+            continue;
+        const label = groundTruth.get(firing.labelId);
+        if (label === undefined) {
+            needsAdjudication.push(firing.labelId);
+        }
+        else if (label === 'FP') {
+            hasFp = true;
+            labeledCount++;
+        }
+        else {
+            tpCount++;
+            labeledCount++;
+        }
+    }
+    // survivorPrecision (diagnostic, descriptive): TP/(TP+FP) over labeled surviving
+    // firings — informative even on no-claim verdicts, NEVER the gate decision.
+    const survivorPrecision = labeledCount > 0 ? tpCount / labeledCount : null;
+    const diagnostics = { survivorPrecision };
+    // Step 3: Positive control non-vacuity check. Every positive control target
+    // must have its targetRuleId fire on an un-culled rule. A vacuous pass → FAIL.
+    let nonVacuity = true;
+    for (const target of positiveControlTargets) {
+        const fired = firings.some((f) => f.controlKind === 'positive' &&
+            f.pr === target.pr &&
+            f.ruleId === target.targetRuleId &&
+            !culledRuleIds.has(f.ruleId));
+        if (!fired) {
+            nonVacuity = false;
+            break;
+        }
+    }
+    // ── FAIL tier (outranks the masquerade guards, #2189) ──
+    // Step 4a: Confirmed FP → FAIL. precision = the breaching value (the evidence,
+    // must be reported). A 0 here is a REAL all-FP measurement, never a sentinel.
+    // labeledCount ≥ 1 whenever hasFp, so the ratio is always defined.
+    if (hasFp) {
+        return {
+            verdict: 'FAIL',
+            precision: tpCount / labeledCount,
+            mintedRuleCount,
+            culledCount,
+            survivingRuleCount,
+            exposureTuple,
+            cullLedger,
+            nonVacuity,
+            needsAdjudication,
+            diagnostics,
+        };
+    }
+    // Step 4b: Vacuous positive control → FAIL. precision = null — a structural
+    // failure makes no precision claim (#2189 Q-A); 0 would falsely read as all-FP.
+    if (!nonVacuity) {
+        return {
+            verdict: 'FAIL',
+            precision: null,
+            mintedRuleCount,
+            culledCount,
+            survivingRuleCount,
+            exposureTuple,
+            cullLedger,
+            nonVacuity: false,
+            needsAdjudication,
+            diagnostics,
+        };
+    }
+    // ── Masquerade guards (may only DEMOTE a would-be PASS) ──
+    // Step 5: Exposure floor (P2). activeRules/positiveControls below floor →
+    // HONEST-NEGATIVE (no claim → precision null). Ranked above needs-adjudication
+    // (Step 7): labeling won't rescue a sub-floor run (strategy-claude tie-break).
+    if (actualExposure.activeRulesEvaluated < exposureFloors.activeRulesEvaluated ||
+        actualExposure.positiveControlsExercised < exposureFloors.positiveControlsExercised) {
+        return {
+            verdict: 'HONEST-NEGATIVE',
+            precision: null,
+            mintedRuleCount,
+            culledCount,
+            survivingRuleCount,
+            exposureTuple,
+            cullLedger,
+            nonVacuity,
+            needsAdjudication,
+            diagnostics,
+        };
+    }
+    // Step 6: Cull-rate guard (C5/S2). culledCount / mintedRuleCount > threshold →
+    // HONEST-NEGATIVE. Guard applies only when mintedRuleCount > 0 (avoids division
+    // by zero at the harness phase). No claim → precision null.
+    if (mintedRuleCount > 0 && culledCount / mintedRuleCount > cullRateThreshold) {
+        return {
+            verdict: 'HONEST-NEGATIVE',
+            precision: null,
+            mintedRuleCount,
+            culledCount,
+            survivingRuleCount,
+            exposureTuple,
+            cullLedger,
+            nonVacuity,
+            needsAdjudication,
+            diagnostics,
+        };
+    }
+    // Step 7: Unlabeled firings → not PASS (operator must adjudicate first). No
+    // claim → precision null.
+    if (needsAdjudication.length > 0) {
+        return {
+            verdict: 'HONEST-NEGATIVE',
+            precision: null,
+            mintedRuleCount,
+            culledCount,
+            survivingRuleCount,
+            exposureTuple,
+            cullLedger,
+            nonVacuity,
+            needsAdjudication,
+            diagnostics,
+        };
+    }
+    // Step 8: All firings labeled TP, exposure floors met, positive controls
+    // verified → PASS. precision = 1.0 (tpCount === labeledCount here; vacuously
+    // 1.0 when no firings — the harness phase).
+    return {
+        verdict: 'PASS',
+        precision: labeledCount > 0 ? tpCount / labeledCount : 1.0,
+        mintedRuleCount,
+        culledCount,
+        survivingRuleCount,
+        exposureTuple,
+        cullLedger,
+        nonVacuity,
+        needsAdjudication,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=windtunnel-scorer.js.map

package/dist/spine/windtunnel-scorer.js.map

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

package/dist/spine/windtunnel-scorer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=windtunnel-scorer.test.d.ts.map

package/dist/spine/windtunnel-scorer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windtunnel-scorer.test.d.ts","sourceRoot":"","sources":["../../src/spine/windtunnel-scorer.test.ts"],"names":[],"mappings":""}