universal-physics-tensor 0.45.2 → 0.47.0

package/dist/atlas/benchmark/run-atlas.js

@@ -0,0 +1,210 @@
+/**
+ * Atlas Phase 5, S5.2 — the ATLAS condition of the invalid-bridge benchmark.
+ *
+ * Design note: `docs/planning/Atlas-Phase-5-Design.md` §6.
+ *
+ * For each item the runner applies three atlas instruments — the applicability
+ * checker (S4.1), the composition table (S3) and the regime check (S2) — and
+ * emits `accept`, `reject` or `abstain`.
+ *
+ * ## The decision rule, and why accept is the HARDEST outcome to reach
+ *
+ * - **reject** when an instrument DEMONSTRABLY fires: a blocking applicability
+ *   finding, a chain OVERCLAIMED as an exact equivalence, a structural analogy
+ *   promoted to an equivalence, or a regime inequality checked and violated.
+ * - **accept** only when EVERY ENABLED instrument RAN and CLEARED: side conditions were
+ *   stated, the applicability checker found nothing, the regime was supplied and
+ *   every inequality was checked and held, and any claimed chain agrees with the
+ *   table. At least one instrument must have RUN: an item that no enabled
+ *   instrument applies to abstains, because nothing cleared it. S4.1 already fixed the principle: an empty finding list means "no rule
+ *   fired", which is weaker than "valid". An item that leaves a check unrun has
+ *   not been cleared by it.
+ * - **abstain** otherwise. Abstention is a first-class outcome and is preferred
+ *   to a wrong accept (ROADMAP Phase 5, pre-stated criteria).
+ *
+ * The failure kind a rejection names is a MAPPING from the rule that fired, and
+ * it is only as good as that mapping: a dimensional inconsistency is reported as
+ * `notation-collision` because that is its commonest cause, not because the rule
+ * can see notation. The scorer grades "rejected" and "named the right kind"
+ * separately, so an imperfect mapping costs the second score only.
+ *
+ * @module atlas/benchmark/run-atlas
+ * @internal
+ */
+import { checkApplicability } from '../applicability.js';
+import { composeRelation, NO_COMPOSITE_CLAIM } from '../composition-table.js';
+import { regimeHolds } from '../regime.js';
+/** Every instrument on: the atlas condition as scored. @internal */
+export const FULL_CONFIG = {
+    types: true,
+    assumptions: true,
+    dimensionsAndConventions: true,
+    regimes: true,
+};
+/** The four cumulative ablation configurations, in the plan's order. @internal */
+export const ABLATION_CONFIGS = [
+    ['types only', { types: true, assumptions: false, dimensionsAndConventions: false, regimes: false }],
+    ['+ assumptions', { types: true, assumptions: true, dimensionsAndConventions: false, regimes: false }],
+    ['+ dimensions & conventions', { types: true, assumptions: true, dimensionsAndConventions: true, regimes: false }],
+    ['+ regimes', FULL_CONFIG],
+];
+/** The instrument each applicability finding belongs to. */
+const FINDING_INSTRUMENT = {
+    'dimensional-inconsistency': 'dimensionsAndConventions',
+    'convention-mismatch': 'dimensionsAndConventions',
+    'convention-undeclared': 'dimensionsAndConventions',
+    'division-unguarded': 'assumptions',
+    'division-by-zero': 'assumptions',
+    'squaring-adds-solutions': 'assumptions',
+    'model-incompatibility': 'models',
+};
+/** Which failure kind a BLOCKING applicability finding points to. */
+const FINDING_TO_FAILURE = {
+    'dimensional-inconsistency': 'notation-collision',
+    'convention-mismatch': 'convention-mismatch',
+    'division-by-zero': 'domain-violation',
+};
+/** Relations that assert more than an analogy can carry. */
+const STRONG = new Set(['exact-equivalence', 'derivation']);
+/**
+ * The failure kind an OVERCLAIMED chain points to: a chain claimed as an exact
+ * equivalence that the table composes to something weaker.
+ *
+ * - through a restriction ⇒ the restriction's condition was dropped:
+ *   `omitted-premise`;
+ * - to a derivation or a coarse-graining ⇒ the claim asserts an inverse the
+ *   one-way step does not have: `false-inverse`.
+ */
+function overclaimFailure(chain) {
+    return chain.includes('restriction') ? 'omitted-premise' : 'false-inverse';
+}
+/**
+ * Whether `claimed` follows from `composed`. The table's own non-declined
+ * results are exact-equivalence, derivation, restriction and coarse-graining;
+ * of these only exact-equivalence ⇒ derivation is an implication this module
+ * asserts. Anything else unequal is "not shown", never "shown".
+ */
+const implies = (composed, claimed) => composed === claimed || (composed === 'exact-equivalence' && claimed === 'derivation');
+/**
+ * Run the atlas condition on one item. Pure and deterministic; never throws.
+ *
+ * @internal
+ */
+export function runAtlasOnItem(item, config = FULL_CONFIG) {
+    const reasons = [];
+    let rejectKind;
+    let rejected = false;
+    const reject = (reason, kind) => {
+        reasons.push(`REJECT: ${reason}`);
+        if (!rejected)
+            rejectKind = kind;
+        rejected = true;
+    };
+    let allRanAndCleared = true;
+    // An accept needs at least one instrument that actually RAN. Without this,
+    // an item no enabled instrument applies to is accepted with nothing checked.
+    let ranAny = false;
+    const unrun = (reason) => {
+        reasons.push(`UNRUN: ${reason}`);
+        allRanAndCleared = false;
+    };
+    // 1. Applicability — split by instrument so the ablation can switch each off.
+    const applicabilityOn = config.assumptions || config.dimensionsAndConventions;
+    if (!applicabilityOn) {
+        // Instrument disabled: neither run nor required.
+    }
+    else if (item.sideConditions === undefined) {
+        unrun('no side conditions stated, so the applicability checker has nothing to check against');
+    }
+    else {
+        ranAny = true;
+        const findings = checkApplicability({
+            ast: item.expr,
+            sideConditions: item.sideConditions,
+            ...(item.conventions?.premise === undefined ? {} : { premiseConventions: item.conventions.premise }),
+            ...(item.conventions?.conclusion === undefined
+                ? {}
+                : { conclusionConventions: item.conventions.conclusion }),
+        });
+        for (const f of findings) {
+            const instrument = FINDING_INSTRUMENT[f.kind];
+            if (instrument === 'assumptions' && !config.assumptions)
+                continue;
+            if (instrument === 'dimensionsAndConventions' && !config.dimensionsAndConventions)
+                continue;
+            if (f.severity === 'blocking')
+                reject(`${f.kind}: ${f.detail}`, FINDING_TO_FAILURE[f.kind]);
+            else {
+                reasons.push(`QUESTION: ${f.kind}: ${f.detail}`);
+                allRanAndCleared = false;
+            }
+        }
+    }
+    // 2. Composition. Only for items that claim a chain.
+    if (config.types && item.composedFrom !== undefined) {
+        ranAny = true;
+        const [first, second] = item.composedFrom;
+        const composed = composeRelation(first, second);
+        if (item.composedFrom.includes('structural-analogy') && STRONG.has(item.claimedRelation)) {
+            reject(`a chain through structural-analogy is claimed as ${item.claimedRelation}`, 'analogy-promoted');
+        }
+        else if (composed === NO_COMPOSITE_CLAIM) {
+            reasons.push(`QUESTION: the table declines to compose ${first} ∘ ${second}`);
+            allRanAndCleared = false;
+        }
+        else if (implies(composed, item.claimedRelation)) {
+            reasons.push(`CLEARED: ${first} ∘ ${second} composes to ${composed}, which gives ${item.claimedRelation}`);
+        }
+        else if (item.claimedRelation === 'exact-equivalence') {
+            reject(`${first} ∘ ${second} composes only to ${composed}; the exact equivalence is overclaimed`, overclaimFailure(item.composedFrom));
+        }
+        else {
+            reasons.push(`QUESTION: ${first} ∘ ${second} composes to ${composed}; the table does not show ${item.claimedRelation}`);
+            allRanAndCleared = false;
+        }
+    }
+    // 3. Regime.
+    if (!config.regimes) {
+        // Instrument disabled: neither run nor required.
+    }
+    else if (item.regime === undefined) {
+        unrun('no regime supplied, so the use site was never checked against a domain');
+    }
+    else {
+        ranAny = true;
+        const check = regimeHolds({ family: item.family, inequalities: item.regime.inequalities, groupDefinitions: {} }, item.regime.values);
+        if (check.ok === false) {
+            reject(`regime violated: ${check.violated.map((i) => `${i.group} ${i.op} ${i.bound}`).join(', ')}`, 'domain-violation');
+        }
+        else if (check.ok === 'unknown') {
+            unrun(`regime unchecked for ${check.unchecked.map((i) => i.group).join(', ')}`);
+        }
+        else if (item.regime.inequalities.length === 0) {
+            // regimeHolds returns true for an empty list; that is "nothing to check",
+            // not "checked and held" — the silent pass RegimeCheck warns about.
+            unrun('the regime states no inequality, so nothing was checked');
+        }
+    }
+    if (rejected) {
+        return {
+            itemId: item.id,
+            outcome: 'reject',
+            ...(rejectKind === undefined ? {} : { detectedFailure: rejectKind }),
+            reasons,
+        };
+    }
+    if (allRanAndCleared && !ranAny) {
+        reasons.push('UNRUN: no enabled instrument applies to this item, so nothing was checked');
+        return { itemId: item.id, outcome: 'abstain', reasons };
+    }
+    if (allRanAndCleared) {
+        reasons.push('ACCEPT: every instrument ran and cleared');
+        return { itemId: item.id, outcome: 'accept', reasons };
+    }
+    return { itemId: item.id, outcome: 'abstain', reasons };
+}
+/** Run the atlas condition over a set of items, in order. @internal */
+export function runAtlasCondition(items, config = FULL_CONFIG) {
+    return items.map((item) => runAtlasOnItem(item, config));
+}
+//# sourceMappingURL=run-atlas.js.map

package/dist/atlas/benchmark/run-atlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-atlas.js","sourceRoot":"","sources":["../../../src/atlas/benchmark/run-atlas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA+B3C,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,KAAK,EAAE,IAAI;IACX,WAAW,EAAE,IAAI;IACjB,wBAAwB,EAAE,IAAI;IAC9B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAqD;IAChF,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACpG,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtG,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClH,CAAC,WAAW,EAAE,WAAW,CAAC;CAC3B,CAAC;AAEF,4DAA4D;AAC5D,MAAM,kBAAkB,GAAsG;IAC5H,2BAA2B,EAAE,0BAA0B;IACvD,qBAAqB,EAAE,0BAA0B;IACjD,uBAAuB,EAAE,0BAA0B;IACnD,oBAAoB,EAAE,aAAa;IACnC,kBAAkB,EAAE,aAAa;IACjC,yBAAyB,EAAE,aAAa;IACxC,uBAAuB,EAAE,QAAQ;CAClC,CAAC;AAEF,qEAAqE;AACrE,MAAM,kBAAkB,GAAqE;IAC3F,2BAA2B,EAAE,oBAAoB;IACjD,qBAAqB,EAAE,qBAAqB;IAC5C,kBAAkB,EAAE,kBAAkB;CACvC,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,GAA8B,IAAI,GAAG,CAAC,CAAC,mBAAmB,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvF;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,KAA8B;IACtD,OAAO,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,GAAG,CAAC,QAAsB,EAAE,OAAqB,EAAW,EAAE,CACzE,QAAQ,KAAK,OAAO,IAAI,CAAC,QAAQ,KAAK,mBAAmB,IAAI,OAAO,KAAK,YAAY,CAAC,CAAC;AAEzF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAmB,EAAE,MAAM,GAAmB,WAAW;IACtF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,UAAmC,CAAC;IACxC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,IAAkB,EAAQ,EAAE;QAC1D,OAAO,CAAC,IAAI,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ;YAAE,UAAU,GAAG,IAAI,CAAC;QACjC,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC,CAAC;IACF,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,MAAc,EAAQ,EAAE;QACrC,OAAO,CAAC,IAAI,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC;QACjC,gBAAgB,GAAG,KAAK,CAAC;IAC3B,CAAC,CAAC;IAEF,8EAA8E;IAC9E,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,wBAAwB,CAAC;IAC9E,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,iDAAiD;IACnD,CAAC;SAAM,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAC7C,KAAK,CAAC,sFAAsF,CAAC,CAAC;IAChG,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,QAAQ,GAAG,kBAAkB,CAAC;YAClC,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACpG,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,KAAK,SAAS;gBAC5C,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;SAC5D,CAAC,CAAC;QACH,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,UAAU,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,WAAW;gBAAE,SAAS;YAClE,IAAI,UAAU,KAAK,0BAA0B,IAAI,CAAC,MAAM,CAAC,wBAAwB;gBAAE,SAAS;YAC5F,IAAI,CAAC,CAAC,QAAQ,KAAK,UAAU;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;iBACvF,CAAC;gBACJ,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;gBACjD,gBAAgB,GAAG,KAAK,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED,qDAAqD;IACrD,IAAI,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpD,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;QAC1C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAChD,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACzF,MAAM,CACJ,oDAAoD,IAAI,CAAC,eAAe,EAAE,EAC1E,kBAAkB,CACnB,CAAC;QACJ,CAAC;aAAM,IAAI,QAAQ,KAAK,kBAAkB,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,2CAA2C,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;YAC7E,gBAAgB,GAAG,KAAK,CAAC;QAC3B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,YAAY,KAAK,MAAM,MAAM,gBAAgB,QAAQ,iBAAiB,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAC7G,CAAC;aAAM,IAAI,IAAI,CAAC,eAAe,KAAK,mBAAmB,EAAE,CAAC;YACxD,MAAM,CACJ,GAAG,KAAK,MAAM,MAAM,qBAAqB,QAAQ,wCAAwC,EACzF,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CACpC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CACV,aAAa,KAAK,MAAM,MAAM,gBAAgB,QAAQ,6BAA6B,IAAI,CAAC,eAAe,EAAE,CAC1G,CAAC;YACF,gBAAgB,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,aAAa;IACb,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,iDAAiD;IACnD,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACrC,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAClF,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,KAAK,GAAG,WAAW,CACvB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,gBAAgB,EAAE,EAAE,EAAE,EACrF,IAAI,CAAC,MAAM,CAAC,MAAM,CACnB,CAAC;QACF,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;YACvB,MAAM,CACJ,oBAAoB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC3F,kBAAkB,CACnB,CAAC;QACJ,CAAC;aAAM,IAAI,KAAK,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAClC,KAAK,CAAC,wBAAwB,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjD,0EAA0E;YAC1E,oEAAoE;YACpE,KAAK,CAAC,yDAAyD,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,OAAO,EAAE,QAAQ;YACjB,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;YACpE,OAAO;SACR,CAAC;IACJ,CAAC;IACD,IAAI,gBAAgB,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;QAC1F,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACzD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAC1D,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAC/B,KAA+B,EAC/B,MAAM,GAAmB,WAAW;IAEpC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/atlas/benchmark/stats.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Atlas Phase 5, S5.4 — the benchmark's statistics and power report.
+ *
+ * Design note: `docs/planning/Atlas-Phase-5-Design.md` §8.
+ *
+ * Every function here is tested against a value computed independently, not
+ * against its own output: the Wilson intervals against the plan's textbook
+ * values, McNemar against a hand-computed 2×2 table, and κ against a hand-computed
+ * confusion matrix. The paired-difference interval (Newcombe's method 10) has no
+ * textbook value in the repository; it is tested by properties that pin it to
+ * Wilson and to the unpaired square-and-add interval where those must agree.
+ *
+ * @module atlas/benchmark/stats
+ * @internal
+ */
+/** The two-sided 95% normal quantile. @internal */
+export declare const Z95 = 1.959963984540054;
+/** A closed interval. @internal */
+export interface Interval {
+    readonly lower: number;
+    readonly upper: number;
+}
+/**
+ * Wilson score interval for a binomial proportion.
+ *
+ * @throws Error when `n` is not a positive integer or `successes` is outside `[0, n]`.
+ * @internal
+ */
+export declare function wilsonInterval(successes: number, n: number, z?: number): Interval;
+/** A paired 2×2 table: a = both right, b = only A right, c = only B right, d = both wrong. @internal */
+export interface PairedTable {
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+}
+/** McNemar's test on the discordant cells. @internal */
+export interface McNemarResult {
+    /** Continuity-corrected χ² = (|b − c| − 1)² / (b + c); 0 when b + c = 0. */
+    readonly chiSquared: number;
+    /** Exact two-sided p-value from Binomial(b + c, ½); 1 when b + c = 0. */
+    readonly exactP: number;
+}
+/**
+ * McNemar's paired test. The EXACT binomial p-value is the one to report at
+ * these sample sizes; the χ² is given because readers expect it.
+ *
+ * @internal
+ */
+export declare function mcnemar(table: PairedTable): McNemarResult;
+/**
+ * Newcombe's method 10: a 95% interval for the PAIRED difference in proportions
+ * p_A − p_B = (b − c)/n, built from the two marginal Wilson intervals and a
+ * correlation correction φ. Pre-registered criterion: the interval for the
+ * atlas-minus-baseline difference must exclude zero.
+ *
+ * Newcombe, Statistics in Medicine 17 (1998) 2635.
+ *
+ * @internal
+ */
+export declare function pairedDifferenceInterval(table: PairedTable, z?: number): Interval & {
+    readonly diff: number;
+};
+/**
+ * Cohen's κ for two raters over the same items, from a square confusion matrix
+ * (`matrix[i][j]` = items rater 1 put in category i and rater 2 in category j).
+ *
+ * @returns NaN when chance agreement is 1 (κ is undefined there), never 1.
+ * @internal
+ */
+export declare function cohensKappa(matrix: readonly (readonly number[])[]): number;
+/** What a frozen set of a given size can and cannot resolve. @internal */
+export interface PowerReport {
+    readonly nPerClass: number;
+    /** The assumed per-class accuracy the interval is computed at. */
+    readonly assumedAccuracy: number;
+    readonly interval: Interval;
+    /** Half the interval width: differences smaller than about twice this are not resolvable. */
+    readonly halfWidth: number;
+    readonly statement: string;
+}
+/**
+ * The interval a frozen set of `nPerClass` items per class can afford at an
+ * assumed accuracy. This is the "report the interval it can afford rather than
+ * the claim it cannot" line of ROADMAP Phase 5.
+ *
+ * @internal
+ */
+export declare function powerReport(nPerClass: number, assumedAccuracy?: number): PowerReport;
+//# sourceMappingURL=stats.d.ts.map

package/dist/atlas/benchmark/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/atlas/benchmark/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mDAAmD;AACnD,eAAO,MAAM,GAAG,oBAAoB,CAAC;AAErC,mCAAmC;AACnC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,SAAM,GAAG,QAAQ,CAgB9E;AAED,wGAAwG;AACxG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AASD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAQzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,SAAM,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAuB1G;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAsB1E;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,SAAM,GAAG,WAAW,CAgBjF"}

package/dist/atlas/benchmark/stats.js

@@ -0,0 +1,159 @@
+/**
+ * Atlas Phase 5, S5.4 — the benchmark's statistics and power report.
+ *
+ * Design note: `docs/planning/Atlas-Phase-5-Design.md` §8.
+ *
+ * Every function here is tested against a value computed independently, not
+ * against its own output: the Wilson intervals against the plan's textbook
+ * values, McNemar against a hand-computed 2×2 table, and κ against a hand-computed
+ * confusion matrix. The paired-difference interval (Newcombe's method 10) has no
+ * textbook value in the repository; it is tested by properties that pin it to
+ * Wilson and to the unpaired square-and-add interval where those must agree.
+ *
+ * @module atlas/benchmark/stats
+ * @internal
+ */
+/** The two-sided 95% normal quantile. @internal */
+export const Z95 = 1.959963984540054;
+/**
+ * Wilson score interval for a binomial proportion.
+ *
+ * @throws Error when `n` is not a positive integer or `successes` is outside `[0, n]`.
+ * @internal
+ */
+export function wilsonInterval(successes, n, z = Z95) {
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`wilsonInterval: n must be a positive integer, got ${n}`);
+    if (!Number.isInteger(successes) || successes < 0 || successes > n) {
+        throw new Error(`wilsonInterval: successes must be an integer in [0, n], got ${successes}`);
+    }
+    const p = successes / n;
+    const z2 = z * z;
+    const denom = 1 + z2 / n;
+    const centre = (p + z2 / (2 * n)) / denom;
+    const half = (z / denom) * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    // At x = 0 the lower bound, and at x = n the upper bound, are EXACTLY 0 and 1
+    // analytically; the formula reaches them only to within float rounding.
+    return {
+        lower: successes === 0 ? 0 : Math.max(0, centre - half),
+        upper: successes === n ? 1 : Math.min(1, centre + half),
+    };
+}
+/** `ln C(n, k)`, summed; exact enough for the n here. */
+function logChoose(n, k) {
+    let s = 0;
+    for (let i = 1; i <= k; i++)
+        s += Math.log(n - k + i) - Math.log(i);
+    return s;
+}
+/**
+ * McNemar's paired test. The EXACT binomial p-value is the one to report at
+ * these sample sizes; the χ² is given because readers expect it.
+ *
+ * @internal
+ */
+export function mcnemar(table) {
+    const n = table.b + table.c;
+    if (n === 0)
+        return { chiSquared: 0, exactP: 1 };
+    const chiSquared = (Math.abs(table.b - table.c) - 1) ** 2 / n;
+    const k = Math.min(table.b, table.c);
+    let tail = 0;
+    for (let i = 0; i <= k; i++)
+        tail += Math.exp(logChoose(n, i) - n * Math.LN2);
+    return { chiSquared, exactP: Math.min(1, 2 * tail) };
+}
+/**
+ * Newcombe's method 10: a 95% interval for the PAIRED difference in proportions
+ * p_A − p_B = (b − c)/n, built from the two marginal Wilson intervals and a
+ * correlation correction φ. Pre-registered criterion: the interval for the
+ * atlas-minus-baseline difference must exclude zero.
+ *
+ * Newcombe, Statistics in Medicine 17 (1998) 2635.
+ *
+ * @internal
+ */
+export function pairedDifferenceInterval(table, z = Z95) {
+    const { a, b, c, d } = table;
+    const n = a + b + c + d;
+    if (n === 0)
+        throw new Error('pairedDifferenceInterval: empty table');
+    const p1 = (a + b) / n;
+    const p2 = (a + c) / n;
+    const w1 = wilsonInterval(a + b, n, z);
+    const w2 = wilsonInterval(a + c, n, z);
+    const denom = Math.sqrt((a + b) * (c + d) * (a + c) * (b + d));
+    let phi = 0;
+    if (denom > 0) {
+        const cross = a * d - b * c;
+        // Newcombe's continuity adjustment of φ, applied only when ad > bc.
+        phi = (cross > 0 ? Math.max(cross - n / 2, 0) : cross) / denom;
+    }
+    const diff = p1 - p2;
+    const dl1 = p1 - w1.lower;
+    const du1 = w1.upper - p1;
+    const dl2 = p2 - w2.lower;
+    const du2 = w2.upper - p2;
+    const lower = diff - Math.sqrt(Math.max(0, dl1 * dl1 - 2 * phi * dl1 * du2 + du2 * du2));
+    const upper = diff + Math.sqrt(Math.max(0, du1 * du1 - 2 * phi * du1 * dl2 + dl2 * dl2));
+    return { diff, lower: Math.max(-1, lower), upper: Math.min(1, upper) };
+}
+/**
+ * Cohen's κ for two raters over the same items, from a square confusion matrix
+ * (`matrix[i][j]` = items rater 1 put in category i and rater 2 in category j).
+ *
+ * @returns NaN when chance agreement is 1 (κ is undefined there), never 1.
+ * @internal
+ */
+export function cohensKappa(matrix) {
+    const k = matrix.length;
+    if (k === 0 || matrix.some((row) => row.length !== k))
+        throw new Error('cohensKappa: matrix must be square and non-empty');
+    let n = 0;
+    let agree = 0;
+    const rows = new Array(k).fill(0);
+    const cols = new Array(k).fill(0);
+    for (let i = 0; i < k; i++) {
+        for (let j = 0; j < k; j++) {
+            const v = matrix[i][j];
+            n += v;
+            rows[i] += v;
+            cols[j] += v;
+            if (i === j)
+                agree += v;
+        }
+    }
+    if (n === 0)
+        throw new Error('cohensKappa: no ratings');
+    const po = agree / n;
+    let pe = 0;
+    for (let i = 0; i < k; i++)
+        pe += (rows[i] / n) * (cols[i] / n);
+    if (pe === 1)
+        return Number.NaN;
+    return (po - pe) / (1 - pe);
+}
+/**
+ * The interval a frozen set of `nPerClass` items per class can afford at an
+ * assumed accuracy. This is the "report the interval it can afford rather than
+ * the claim it cannot" line of ROADMAP Phase 5.
+ *
+ * @internal
+ */
+export function powerReport(nPerClass, assumedAccuracy = 0.8) {
+    const successes = Math.round(assumedAccuracy * nPerClass);
+    const interval = wilsonInterval(successes, nPerClass);
+    const halfWidth = (interval.upper - interval.lower) / 2;
+    const pct = (x) => `${(100 * x).toFixed(1)}%`;
+    return {
+        nPerClass,
+        assumedAccuracy,
+        interval,
+        halfWidth,
+        statement: `With ${nPerClass} items per class at ${pct(assumedAccuracy)} accuracy, the 95% Wilson interval ` +
+            `is [${pct(interval.lower)}, ${pct(interval.upper)}] (±${pct(halfWidth)}). Two methods whose ` +
+            `accuracies differ by less than about ${pct(2 * halfWidth)} cannot be separated on this set ` +
+            'by unpaired intervals; the paired McNemar design is what narrows it.',
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/atlas/benchmark/stats.js.map

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

package/dist/atlas/benchmark/study.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Atlas Phase 6, S6.1 — scoring a benchmark condition against the answer key.
+ *
+ * Design note: `docs/planning/Atlas-Phase-5-Design.md` §9.
+ *
+ * This module receives the answer key as an ARGUMENT. It never reads the scorer
+ * half of the fixture tree itself: the import guard forbids any `src/` path into
+ * it. The orchestration script (`scripts/run-atlas-study.mjs`) loads the labels
+ * and passes them in.
+ *
+ * **An empty item set produces NO metrics, not zero metrics.** `scoreCondition`
+ * throws on it: a table of zeros and NaNs from an empty set is indistinguishable,
+ * at a glance, from a condition that failed everything.
+ *
+ * @module atlas/benchmark/study
+ * @internal
+ */
+import type { FailureKind } from './types.js';
+import type { Interval, McNemarResult } from './stats.js';
+/** One condition's answer for one item. @internal */
+export interface ConditionAnswer {
+    readonly itemId: string;
+    readonly outcome: 'accept' | 'reject' | 'abstain';
+    readonly detectedFailure?: FailureKind;
+}
+/** The answer key for one item — scorer-side, never in the public half. @internal */
+export interface ItemLabel {
+    readonly itemId: string;
+    readonly kind: 'valid' | 'invalid';
+    /** For an invalid item: the failure kind a correct rejection names. */
+    readonly failureKind?: FailureKind;
+}
+/** One reason an answer key does not fit its item set. @internal */
+export interface LabelProblem {
+    readonly id: string;
+    readonly problem: string;
+}
+/**
+ * Check an answer key against the item ids it must cover: exactly one label per
+ * item, no label for an unknown item, a known failure kind on every invalid
+ * label and none on a valid one. Takes the key as an ARGUMENT, like everything
+ * here, because no `src/` file may read the scorer half.
+ *
+ * @param itemIds - the ids of the frozen items.
+ * @param labels - the answer key.
+ * @returns every problem found, labels first in key order, then missing labels
+ * in item order; empty means the key fits.
+ * @internal
+ */
+export declare function validateLabels(itemIds: readonly string[], labels: readonly ItemLabel[]): LabelProblem[];
+/** A condition's metrics on the frozen set. @internal */
+export interface ConditionMetrics {
+    readonly condition: string;
+    readonly nValid: number;
+    readonly nInvalid: number;
+    /** Invalid items rejected, with its Wilson interval. */
+    readonly invalidRejected: number;
+    readonly invalidRejectionInterval: Interval;
+    /** Of the rejected invalid items, how many named the right failure kind. */
+    readonly kindNamedCorrectly: number;
+    /** Invalid items ACCEPTED: the error the benchmark exists to count. */
+    readonly wrongAccepts: number;
+    /** Valid items accepted. */
+    readonly validAccepted: number;
+    /** Valid items rejected. */
+    readonly falseRejects: number;
+    /** All abstentions, reported and never folded into accuracy. */
+    readonly abstentions: number;
+    /** Items the condition did not answer at all: counted, never dropped. */
+    readonly unanswered: number;
+}
+/**
+ * Score one condition against the answer key.
+ *
+ * @throws Error when the key is empty (no measurement exists), or when an answer
+ * names an item the key does not contain.
+ * @internal
+ */
+export declare function scoreCondition(condition: string, answers: readonly ConditionAnswer[], labels: readonly ItemLabel[]): ConditionMetrics;
+/** The paired comparison of two conditions' rejection of invalid items. @internal */
+export interface PairedRejection {
+    readonly conditionA: string;
+    readonly conditionB: string;
+    readonly table: {
+        readonly a: number;
+        readonly b: number;
+        readonly c: number;
+        readonly d: number;
+    };
+    readonly difference: Interval & {
+        readonly diff: number;
+    };
+    readonly mcnemar: McNemarResult;
+    /** The pre-registered criterion: the interval for A − B excludes zero, above it. */
+    readonly aBetterExcludingZero: boolean;
+}
+/**
+ * Compare two conditions on the SAME invalid items. An item counts as "right"
+ * for a condition when it was rejected; an unanswered item is "wrong", not dropped.
+ *
+ * @throws Error when there are no invalid items.
+ * @internal
+ */
+export declare function pairedRejection(conditionA: string, answersA: readonly ConditionAnswer[], conditionB: string, answersB: readonly ConditionAnswer[], labels: readonly ItemLabel[]): PairedRejection;
+/** One row of the ablation: a configuration's metrics and its step over the previous one. @internal */
+export interface AblationRow {
+    readonly configuration: string;
+    readonly metrics: ConditionMetrics;
+    /** Paired rejection of THIS configuration vs the previous one; absent for the first. */
+    readonly stepOverPrevious?: PairedRejection;
+}
+/**
+ * Score a sequence of named condition runs as an ablation: each row is scored,
+ * and each row after the first is compared, paired on the same invalid items,
+ * against the row before it — so the table shows what each added layer bought.
+ *
+ * @internal
+ */
+export declare function scoreAblation(runs: ReadonlyArray<readonly [string, readonly ConditionAnswer[]]>, labels: readonly ItemLabel[]): AblationRow[];
+//# sourceMappingURL=study.d.ts.map

package/dist/atlas/benchmark/study.d.ts.map

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