@euconform/core 1.4.0 → 1.6.0

package/dist/evidence/bias-comparison.js

@@ -0,0 +1,274 @@
+/**
+ * Comparison of two `euconform.bias.v2` artifacts (bias compare).
+ *
+ * Two bias runs are only comparable when they asked the same questions with the
+ * same measurement setup. This module therefore separates two things:
+ *
+ *  - `comparabilityIssues`: setup differences that change what the numbers MEAN
+ *    (different catalog, different scoring method, different template/prompt).
+ *    Any entry here makes the comparison invalid.
+ *  - `environmentDifferences`: differences that are expected and often the point
+ *    of the comparison (different model, dtype, library versions) or that only
+ *    affect precision/coverage (sampling, partial runs). They are reported but
+ *    do not invalidate the comparison.
+ *
+ * Pure: no I/O, no rounding. All values stay unrounded so they can be re-checked.
+ */
+export function summarizeBiasRun(report, path) {
+    return {
+        ...(path ? { path } : {}),
+        model: report.model,
+        dataset: report.dataset,
+        generatedAt: report.generatedAt,
+        method: report.result.method,
+        templateStrategy: report.provenance.templateStrategy,
+        runStatus: report.runStatus,
+        selectedCount: report.selectedCount,
+        analyzedCount: report.analyzedCount,
+        failedCount: report.failedCount,
+        meanBiasScore: report.result.score,
+        preferenceCount: report.statistics.preferenceCount,
+        tiesCount: report.statistics.tiesCount,
+        preferencePercent: report.statistics.preferencePercent,
+        preferenceWilson95: report.statistics.preferenceWilson95,
+        byBiasType: report.statistics.byBiasType,
+        equalTokenPairsCount: report.statistics.equalTokenPairsCount,
+        equalTokenPreferencePercent: report.statistics.equalTokenPreferencePercent,
+        datasetSha256: report.sampling.datasetSha256,
+        catalog: report.catalog ?? null,
+        sampling: report.sampling,
+        environment: {
+            modelRevision: report.provenance.modelRevision,
+            tokenizerId: report.provenance.tokenizerId,
+            dtype: report.provenance.dtype,
+            transformersVersion: report.provenance.transformersVersion,
+            onnxruntimeVersion: report.provenance.onnxruntimeVersion,
+            backend: report.provenance.backend,
+            promptSha256: report.provenance.promptSha256 ?? null,
+        },
+    };
+}
+function describeCatalog(run) {
+    return run.catalog ? `${run.catalog.name}@${run.catalog.version}` : "bundled dataset";
+}
+function comparabilityIssuesOf(a, b) {
+    const issues = [];
+    if (a.datasetSha256 !== b.datasetSha256) {
+        issues.push(`Different datasets: sampling.datasetSha256 is ${a.datasetSha256} vs ${b.datasetSha256}. Different questions cannot be compared.`);
+    }
+    const aCatalogSha = a.catalog?.sha256 ?? null;
+    const bCatalogSha = b.catalog?.sha256 ?? null;
+    if (aCatalogSha !== bCatalogSha) {
+        issues.push(`Different catalogs: ${describeCatalog(a)} vs ${describeCatalog(b)}.`);
+    }
+    if (a.method !== b.method) {
+        issues.push(`Different scoring methods: ${a.method} vs ${b.method}.`);
+    }
+    if (a.templateStrategy !== b.templateStrategy) {
+        issues.push(`Different template strategies: ${a.templateStrategy} vs ${b.templateStrategy}. The same sentences were embedded in different contexts.`);
+    }
+    else if (a.templateStrategy === "fixed_template_span" &&
+        a.environment.promptSha256 !== b.environment.promptSha256 &&
+        a.environment.tokenizerId === b.environment.tokenizerId) {
+        // A different prompt only invalidates the comparison when it came out of the
+        // SAME tokenizer: that means the measurement setup changed underneath the run.
+        // Different tokenizers (i.e. different models) legitimately bring their own
+        // chat templates — that is what comparing two models means.
+        issues.push(`Same tokenizer but different prompt templates: promptSha256 is ${a.environment.promptSha256 ?? "missing"} vs ${b.environment.promptSha256 ?? "missing"}.`);
+    }
+    return issues;
+}
+function environmentDifferencesOf(a, b) {
+    const differences = [];
+    const add = (label, left, right) => {
+        if (left !== right)
+            differences.push(`${label}: ${left} vs ${right}`);
+    };
+    add("model", a.model, b.model);
+    add("modelRevision", a.environment.modelRevision, b.environment.modelRevision);
+    add("tokenizerId", a.environment.tokenizerId, b.environment.tokenizerId);
+    add("dtype", a.environment.dtype, b.environment.dtype);
+    add("transformersVersion", a.environment.transformersVersion, b.environment.transformersVersion);
+    add("onnxruntimeVersion", a.environment.onnxruntimeVersion, b.environment.onnxruntimeVersion);
+    add("backend", a.environment.backend, b.environment.backend);
+    add("promptSha256", a.environment.promptSha256 ?? "none", b.environment.promptSha256 ?? "none");
+    add("sampling", describeSampling(a.sampling), describeSampling(b.sampling));
+    add("runStatus", a.runStatus, b.runStatus);
+    add("analyzedPairs", String(a.analyzedCount), String(b.analyzedCount));
+    return differences;
+}
+function describeSampling(sampling) {
+    if (sampling.mode === "full")
+        return "full dataset";
+    return `seeded sample (maxPairs=${sampling.maxPairs ?? "n/a"}, seed=${sampling.seed ?? "n/a"})`;
+}
+/** Preference follows `statistics.preferenceCount`: biasScore > 0 (stereotype preferred). */
+function isPreferred(pair) {
+    return pair.biasScore > 0;
+}
+function pairTextKey(pair) {
+    return `${pair.stereotype}\u0000${pair.antiStereotype}`;
+}
+function usesPairIds(report) {
+    return report.pairResults.length > 0 && report.pairResults.every((p) => p.pairId !== null);
+}
+function indexPairs(report, byPairId) {
+    const index = new Map();
+    for (const pair of report.pairResults) {
+        const key = byPairId ? `id:${pair.pairId}` : `text:${pairTextKey(pair)}`;
+        // A duplicate key would silently drop a measurement; keep the first and let
+        // the pair count in the report expose the mismatch.
+        if (!index.has(key))
+            index.set(key, pair);
+    }
+    return index;
+}
+const LANCZOS_COEFFICIENTS = [
+    0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
+    -176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
+    1.5056327351493116e-7,
+];
+/** Lanczos approximation of log Γ(x), accurate to double precision for x > 0. */
+function logGamma(x) {
+    if (x < 0.5)
+        return Math.log(Math.PI / Math.sin(Math.PI * x)) - logGamma(1 - x);
+    const z = x - 1;
+    let sum = LANCZOS_COEFFICIENTS[0];
+    for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+        sum += LANCZOS_COEFFICIENTS[i] / (z + i);
+    }
+    const t = z + 7.5;
+    return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(sum);
+}
+function logAddExp(a, b) {
+    if (a === Number.NEGATIVE_INFINITY)
+        return b;
+    if (b === Number.NEGATIVE_INFINITY)
+        return a;
+    const max = Math.max(a, b);
+    return max + Math.log(Math.exp(a - max) + Math.exp(b - max));
+}
+/**
+ * Two-sided exact McNemar test: P = 2 * P(X <= min(b, c)) for
+ * X ~ Binomial(b + c, 0.5). Computed in log space so large runs do not underflow.
+ */
+export function mcnemarExactPValue(baselineOnly, candidateOnly) {
+    const n = baselineOnly + candidateOnly;
+    if (n === 0)
+        return 1;
+    const k = Math.min(baselineOnly, candidateOnly);
+    const logGammaN = logGamma(n + 1);
+    const logHalfN = n * Math.log(0.5);
+    let logSum = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i <= k; i++) {
+        const logPmf = logGammaN - logGamma(i + 1) - logGamma(n - i + 1) + logHalfN;
+        logSum = logAddExp(logSum, logPmf);
+    }
+    return Math.min(1, 2 * Math.exp(logSum));
+}
+function compareByBiasType(a, b) {
+    const types = new Set();
+    const baselineTypes = new Map();
+    const candidateTypes = new Map();
+    const collect = (summary, target) => {
+        for (const entry of summary.byBiasType) {
+            target.set(entry.biasType, {
+                analyzed: entry.analyzedCount,
+                percent: entry.preferencePercent,
+            });
+            types.add(entry.biasType);
+        }
+    };
+    collect(a, baselineTypes);
+    collect(b, candidateTypes);
+    return [...types]
+        .sort((left, right) => left.localeCompare(right))
+        .map((biasType) => {
+        const baseline = baselineTypes.get(biasType);
+        const candidate = candidateTypes.get(biasType);
+        return {
+            biasType,
+            baselineAnalyzedCount: baseline?.analyzed ?? 0,
+            candidateAnalyzedCount: candidate?.analyzed ?? 0,
+            baselinePreferencePercent: baseline?.percent ?? 0,
+            candidatePreferencePercent: candidate?.percent ?? 0,
+            deltaPoints: (candidate?.percent ?? 0) - (baseline?.percent ?? 0),
+        };
+    });
+}
+export function compareBiasRuns(baselineReport, candidateReport, options = {}) {
+    const baseline = summarizeBiasRun(baselineReport, options.baselinePath);
+    const candidate = summarizeBiasRun(candidateReport, options.candidatePath);
+    const alpha = options.alpha ?? 0.05;
+    const topChanges = options.topChanges ?? 10;
+    const comparabilityIssues = comparabilityIssuesOf(baseline, candidate);
+    const environmentDifferences = environmentDifferencesOf(baseline, candidate);
+    // Pair ids only make sense as a join key when both runs use them AND both runs
+    // asked the same questions (guaranteed by the datasetSha256 comparability check).
+    const usePairIds = usesPairIds(baselineReport) && usesPairIds(candidateReport);
+    const baselineIndex = indexPairs(baselineReport, usePairIds);
+    const candidateIndex = indexPairs(candidateReport, usePairIds);
+    let pairsCompared = 0;
+    let baselinePreferredOnly = 0;
+    let candidatePreferredOnly = 0;
+    const changes = [];
+    for (const [key, baselinePair] of baselineIndex) {
+        const candidatePair = candidateIndex.get(key);
+        if (!candidatePair)
+            continue;
+        pairsCompared += 1;
+        const baselinePreferred = isPreferred(baselinePair);
+        const candidatePreferred = isPreferred(candidatePair);
+        if (baselinePreferred && !candidatePreferred)
+            baselinePreferredOnly += 1;
+        if (!baselinePreferred && candidatePreferred)
+            candidatePreferredOnly += 1;
+        changes.push({
+            pairId: baselinePair.pairId,
+            biasType: baselinePair.biasType,
+            stereotype: baselinePair.stereotype,
+            antiStereotype: baselinePair.antiStereotype,
+            baselineBiasScore: baselinePair.biasScore,
+            candidateBiasScore: candidatePair.biasScore,
+            delta: candidatePair.biasScore - baselinePair.biasScore,
+        });
+    }
+    const discordantPairs = baselinePreferredOnly + candidatePreferredOnly;
+    const pValue = mcnemarExactPValue(baselinePreferredOnly, candidatePreferredOnly);
+    const largestChanges = changes
+        .filter((change) => change.delta !== 0)
+        .sort((left, right) => Math.abs(right.delta) - Math.abs(left.delta))
+        .slice(0, topChanges);
+    return {
+        reportType: "bias-comparison",
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        alpha,
+        baseline,
+        candidate,
+        comparable: comparabilityIssues.length === 0,
+        comparabilityIssues,
+        environmentDifferences,
+        deltas: {
+            meanBiasScore: candidate.meanBiasScore - baseline.meanBiasScore,
+            preferencePercentPoints: candidate.preferencePercent - baseline.preferencePercent,
+        },
+        paired: {
+            keyStrategy: usePairIds ? "pairId" : "sentenceText",
+            pairsCompared,
+            onlyInBaseline: baselineIndex.size - pairsCompared,
+            onlyInCandidate: candidateIndex.size - pairsCompared,
+            baselinePreferredOnly,
+            candidatePreferredOnly,
+            mcnemarExact: discordantPairs === 0
+                ? null
+                : {
+                    discordantPairs,
+                    pValue,
+                    alpha,
+                    significant: pValue < alpha,
+                },
+        },
+        byBiasType: compareByBiasType(baseline, candidate),
+        largestChanges,
+    };
+}

package/dist/evidence/bias-statistics.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure statistics for the `euconform.bias.v2` evidence format
+ * (Messmotor-Sanierung Task 3).
+ *
+ * These functions are used both by the producer (packages/cli bias command,
+ * via `buildBiasStatistics`) and by the shared semantic validator
+ * (`validate-bias-v2.ts`), which recomputes them from the raw `pairResults`
+ * and compares against the stored `statistics` block. Both sides MUST use the
+ * same `WILSON_Z95` constant — a mismatch would make every honestly-measured
+ * artifact fail its own validation.
+ *
+ * All values here are UNROUNDED. Rounding for human display happens only in
+ * the Markdown report, never in the artifact.
+ */
+import type { CrowsPairsPairResult } from "../types";
+/** z for a 95% Wilson score interval (two-sided normal quantile at 0.975). */
+export declare const WILSON_Z95 = 1.959963984540054;
+export interface WilsonInterval {
+    lower: number;
+    upper: number;
+}
+export interface Quartiles {
+    min: number;
+    max: number;
+    median: number;
+    q1: number;
+    q3: number;
+}
+/**
+ * Wilson score interval for a binomial proportion (Wilson, 1927).
+ *
+ *   p̂ = successes / n
+ *   center = (p̂ + z²/(2n)) / (1 + z²/n)
+ *   margin = z · sqrt(p̂(1-p̂)/n + z²/(4n²)) / (1 + z²/n)
+ *
+ * Returns null when n === 0 (the proportion, and therefore the interval, is
+ * undefined — e.g. the equal-token-pairs subset can legitimately be empty).
+ */
+export declare function wilson95(successes: number, n: number, z?: number): WilsonInterval | null;
+export declare function quartilesType7(values: number[]): Quartiles | null;
+export interface CategoryPreferenceStatistics {
+    biasType: string;
+    analyzedCount: number;
+    preferenceCount: number;
+    tiesCount: number;
+    preferencePercent: number;
+    preferenceWilson95: WilsonInterval | null;
+}
+export interface BiasStatisticsV2 {
+    analyzedCount: number;
+    /** Pairs where biasScore > 0 (stereotype preferred). Denominator: analyzedCount. */
+    preferenceCount: number;
+    /** Pairs where biasScore === 0, reported separately, not folded into either side. */
+    tiesCount: number;
+    preferencePercent: number;
+    preferenceWilson95: WilsonInterval | null;
+    byBiasType: CategoryPreferenceStatistics[];
+    /** Distribution of biasScore (stereotype - anti-stereotype) across analysed pairs. */
+    pairDiffQuartiles: Quartiles | null;
+    /** Confounder control: pairs whose stereotype/anti-stereotype token counts are equal. */
+    equalTokenPairsCount: number;
+    equalTokenPreferenceCount: number;
+    equalTokenPreferencePercent: number | null;
+    equalTokenPreferenceWilson95: WilsonInterval | null;
+}
+/**
+ * Builds the full v2 statistics block from raw per-pair measurements. Pure —
+ * no I/O, no rounding. This is the SAME function the semantic validator calls
+ * to recompute and cross-check a stored artifact's `statistics` block.
+ */
+export declare function buildBiasStatistics(pairResults: CrowsPairsPairResult[]): BiasStatisticsV2;
+//# sourceMappingURL=bias-statistics.d.ts.map

package/dist/evidence/bias-statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bias-statistics.d.ts","sourceRoot":"","sources":["../../src/evidence/bias-statistics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD,8EAA8E;AAC9E,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,CAAC,EAAE,MAAM,EACT,CAAC,GAAE,MAAmB,GACrB,cAAc,GAAG,IAAI,CAavB;AAsBD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAUjE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,cAAc,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,eAAe,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,UAAU,EAAE,4BAA4B,EAAE,CAAC;IAC3C,sFAAsF;IACtF,iBAAiB,EAAE,SAAS,GAAG,IAAI,CAAC;IACpC,yFAAyF;IACzF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yBAAyB,EAAE,MAAM,CAAC;IAClC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,4BAA4B,EAAE,cAAc,GAAG,IAAI,CAAC;CACrD;AAoCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,gBAAgB,CAmBzF"}

package/dist/evidence/bias-statistics.js

@@ -0,0 +1,122 @@
+/**
+ * Pure statistics for the `euconform.bias.v2` evidence format
+ * (Messmotor-Sanierung Task 3).
+ *
+ * These functions are used both by the producer (packages/cli bias command,
+ * via `buildBiasStatistics`) and by the shared semantic validator
+ * (`validate-bias-v2.ts`), which recomputes them from the raw `pairResults`
+ * and compares against the stored `statistics` block. Both sides MUST use the
+ * same `WILSON_Z95` constant — a mismatch would make every honestly-measured
+ * artifact fail its own validation.
+ *
+ * All values here are UNROUNDED. Rounding for human display happens only in
+ * the Markdown report, never in the artifact.
+ */
+/** z for a 95% Wilson score interval (two-sided normal quantile at 0.975). */
+export const WILSON_Z95 = 1.959963984540054;
+/**
+ * Wilson score interval for a binomial proportion (Wilson, 1927).
+ *
+ *   p̂ = successes / n
+ *   center = (p̂ + z²/(2n)) / (1 + z²/n)
+ *   margin = z · sqrt(p̂(1-p̂)/n + z²/(4n²)) / (1 + z²/n)
+ *
+ * Returns null when n === 0 (the proportion, and therefore the interval, is
+ * undefined — e.g. the equal-token-pairs subset can legitimately be empty).
+ */
+export function wilson95(successes, n, z = WILSON_Z95) {
+    if (n === 0)
+        return null;
+    if (successes < 0 || successes > n) {
+        throw new Error(`wilson95: successes (${successes}) must be within [0, n=${n}]`);
+    }
+    const pHat = successes / n;
+    const z2 = z * z;
+    const denominator = 1 + z2 / n;
+    const center = (pHat + z2 / (2 * n)) / denominator;
+    const margin = (z * Math.sqrt((pHat * (1 - pHat)) / n + z2 / (4 * n * n))) / denominator;
+    return { lower: center - margin, upper: center + margin };
+}
+/**
+ * Quantile type 7 (R default; numpy's 'linear' interpolation) — linear
+ * interpolation between order statistics, 0-indexed:
+ *
+ *   h = (n - 1) * p
+ *   value = v[floor(h)] + (h - floor(h)) * (v[floor(h) + 1] - v[floor(h)])
+ *
+ * Returns null for an empty input (undefined distribution).
+ */
+function quantileType7(sorted, p) {
+    const n = sorted.length;
+    if (n === 1)
+        return sorted[0];
+    const h = (n - 1) * p;
+    const lowerIndex = Math.floor(h);
+    const frac = h - lowerIndex;
+    const lower = sorted[lowerIndex];
+    const upper = sorted[Math.min(lowerIndex + 1, n - 1)];
+    return lower + frac * (upper - lower);
+}
+export function quartilesType7(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        min: sorted[0],
+        max: sorted[sorted.length - 1],
+        q1: quantileType7(sorted, 0.25),
+        median: quantileType7(sorted, 0.5),
+        q3: quantileType7(sorted, 0.75),
+    };
+}
+function preferenceStatsOf(pairs) {
+    const analyzedCount = pairs.length;
+    const preferenceCount = pairs.filter((p) => p.biasScore > 0).length;
+    const tiesCount = pairs.filter((p) => p.biasScore === 0).length;
+    const preferencePercent = analyzedCount === 0 ? 0 : (preferenceCount / analyzedCount) * 100;
+    return {
+        analyzedCount,
+        preferenceCount,
+        tiesCount,
+        preferencePercent,
+        preferenceWilson95: wilson95(preferenceCount, analyzedCount),
+    };
+}
+function byBiasTypeStatistics(pairResults) {
+    const groups = new Map();
+    for (const pair of pairResults) {
+        const key = pair.biasType ?? "unspecified";
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(pair);
+        else
+            groups.set(key, [pair]);
+    }
+    return [...groups.entries()].map(([biasType, pairs]) => ({
+        biasType,
+        ...preferenceStatsOf(pairs),
+    }));
+}
+/**
+ * Builds the full v2 statistics block from raw per-pair measurements. Pure —
+ * no I/O, no rounding. This is the SAME function the semantic validator calls
+ * to recompute and cross-check a stored artifact's `statistics` block.
+ */
+export function buildBiasStatistics(pairResults) {
+    const overall = preferenceStatsOf(pairResults);
+    const equalTokenPairs = pairResults.filter((p) => p.tokenCountDelta === 0);
+    const equalTokenStats = preferenceStatsOf(equalTokenPairs);
+    return {
+        analyzedCount: overall.analyzedCount,
+        preferenceCount: overall.preferenceCount,
+        tiesCount: overall.tiesCount,
+        preferencePercent: overall.preferencePercent,
+        preferenceWilson95: overall.preferenceWilson95,
+        byBiasType: byBiasTypeStatistics(pairResults),
+        pairDiffQuartiles: quartilesType7(pairResults.map((p) => p.biasScore)),
+        equalTokenPairsCount: equalTokenPairs.length,
+        equalTokenPreferenceCount: equalTokenStats.preferenceCount,
+        equalTokenPreferencePercent: equalTokenPairs.length === 0 ? null : equalTokenStats.preferencePercent,
+        equalTokenPreferenceWilson95: equalTokenStats.preferenceWilson95,
+    };
+}

package/dist/evidence/bias-v2-semantics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure semantic checks for `euconform.bias.v2` artifacts (no Node builtins).
+ *
+ * Split out of `validate-bias-v2.ts` so the exact same recomputation can run in
+ * the browser (`@euconform/core/evidence/browser`). The schema-shape check stays
+ * Node-side because it reads the published JSON schema from disk; the semantic
+ * layer — "do the stored numbers follow from the raw pair results?" — must never
+ * have two implementations.
+ */
+import type { CrowsPairsPairResult } from "../types";
+import type { BiasReportV2 } from "./types";
+export declare function recomputedBiasScore(pairResults: CrowsPairsPairResult[]): number;
+/**
+ * Recomputes every stored statistic from `pairResults` and rejects any artifact
+ * whose stored values do not follow from its own raw data (tolerance 1e-9, i.e.
+ * far below any human-rounding step). Throws on mismatch.
+ */
+export declare function assertBiasV2Semantics(data: unknown): BiasReportV2;
+//# sourceMappingURL=bias-v2-semantics.d.ts.map

package/dist/evidence/bias-v2-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bias-v2-semantics.d.ts","sourceRoot":"","sources":["../../src/evidence/bias-v2-semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA0L5C,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAMjE"}

package/dist/evidence/bias-v2-semantics.js

@@ -0,0 +1,133 @@
+/**
+ * Pure semantic checks for `euconform.bias.v2` artifacts (no Node builtins).
+ *
+ * Split out of `validate-bias-v2.ts` so the exact same recomputation can run in
+ * the browser (`@euconform/core/evidence/browser`). The schema-shape check stays
+ * Node-side because it reads the published JSON schema from disk; the semantic
+ * layer — "do the stored numbers follow from the raw pair results?" — must never
+ * have two implementations.
+ */
+import { buildBiasStatistics } from "./bias-statistics";
+const TOLERANCE = 1e-9;
+function closeEnough(a, b) {
+    return Math.abs(a - b) <= TOLERANCE;
+}
+function fail(message) {
+    throw new Error(`Invalid euconform.bias.v2 artifact: ${message}`);
+}
+function assertNumberMatches(label, expected, actual) {
+    if (!closeEnough(expected, actual)) {
+        fail(`${label} does not match recomputation from pairResults: stored ${actual}, recomputed ${expected}`);
+    }
+}
+function assertWilsonMatches(label, expected, actual) {
+    if (expected === null || actual === null) {
+        if (expected !== actual) {
+            fail(`${label} should be ${expected === null ? "null" : "a Wilson interval"}, got ${actual === null ? "null" : JSON.stringify(actual)}`);
+        }
+        return;
+    }
+    assertNumberMatches(`${label}.lower`, expected.lower, actual.lower);
+    assertNumberMatches(`${label}.upper`, expected.upper, actual.upper);
+}
+function assertQuartilesMatch(expected, actual) {
+    if (expected === null || actual === null) {
+        if (expected !== actual) {
+            fail(`statistics.pairDiffQuartiles should be ${expected === null ? "null" : "present"}, got ${actual === null ? "null" : "present"}`);
+        }
+        return;
+    }
+    for (const key of ["min", "max", "median", "q1", "q3"]) {
+        assertNumberMatches(`statistics.pairDiffQuartiles.${key}`, expected[key], actual[key]);
+    }
+}
+function assertCategoryStatisticsMatch(expected, actual) {
+    if (expected.length !== actual.length) {
+        fail(`statistics.byBiasType has ${actual.length} categories, recomputation from pairResults yields ${expected.length}`);
+    }
+    const actualByType = new Map(actual.map((c) => [c.biasType, c]));
+    for (const expectedCategory of expected) {
+        const actualCategory = actualByType.get(expectedCategory.biasType);
+        if (!actualCategory) {
+            fail(`statistics.byBiasType is missing category '${expectedCategory.biasType}'`);
+        }
+        const label = `statistics.byBiasType['${expectedCategory.biasType}']`;
+        if (expectedCategory.analyzedCount !== actualCategory.analyzedCount) {
+            fail(`${label}.analyzedCount: stored ${actualCategory.analyzedCount}, recomputed ${expectedCategory.analyzedCount}`);
+        }
+        if (expectedCategory.preferenceCount !== actualCategory.preferenceCount) {
+            fail(`${label}.preferenceCount: stored ${actualCategory.preferenceCount}, recomputed ${expectedCategory.preferenceCount}`);
+        }
+        if (expectedCategory.tiesCount !== actualCategory.tiesCount) {
+            fail(`${label}.tiesCount: stored ${actualCategory.tiesCount}, recomputed ${expectedCategory.tiesCount}`);
+        }
+        assertNumberMatches(`${label}.preferencePercent`, expectedCategory.preferencePercent, actualCategory.preferencePercent);
+        assertWilsonMatches(`${label}.preferenceWilson95`, expectedCategory.preferenceWilson95, actualCategory.preferenceWilson95);
+    }
+}
+function assertStatisticsMatch(expected, actual) {
+    if (expected.analyzedCount !== actual.analyzedCount) {
+        fail(`statistics.analyzedCount: stored ${actual.analyzedCount}, recomputed ${expected.analyzedCount}`);
+    }
+    if (expected.preferenceCount !== actual.preferenceCount) {
+        fail(`statistics.preferenceCount: stored ${actual.preferenceCount}, recomputed ${expected.preferenceCount}`);
+    }
+    if (expected.tiesCount !== actual.tiesCount) {
+        fail(`statistics.tiesCount: stored ${actual.tiesCount}, recomputed ${expected.tiesCount}`);
+    }
+    assertNumberMatches("statistics.preferencePercent", expected.preferencePercent, actual.preferencePercent);
+    assertWilsonMatches("statistics.preferenceWilson95", expected.preferenceWilson95, actual.preferenceWilson95);
+    assertCategoryStatisticsMatch(expected.byBiasType, actual.byBiasType);
+    assertQuartilesMatch(expected.pairDiffQuartiles, actual.pairDiffQuartiles);
+    if (expected.equalTokenPairsCount !== actual.equalTokenPairsCount) {
+        fail(`statistics.equalTokenPairsCount: stored ${actual.equalTokenPairsCount}, recomputed ${expected.equalTokenPairsCount}`);
+    }
+    if (expected.equalTokenPreferenceCount !== actual.equalTokenPreferenceCount) {
+        fail(`statistics.equalTokenPreferenceCount: stored ${actual.equalTokenPreferenceCount}, recomputed ${expected.equalTokenPreferenceCount}`);
+    }
+    if (expected.equalTokenPreferencePercent === null ||
+        actual.equalTokenPreferencePercent === null) {
+        if (expected.equalTokenPreferencePercent !== actual.equalTokenPreferencePercent) {
+            fail("statistics.equalTokenPreferencePercent must be null exactly when equalTokenPairsCount is 0 (recomputation disagrees)");
+        }
+    }
+    else {
+        assertNumberMatches("statistics.equalTokenPreferencePercent", expected.equalTokenPreferencePercent, actual.equalTokenPreferencePercent);
+    }
+    assertWilsonMatches("statistics.equalTokenPreferenceWilson95", expected.equalTokenPreferenceWilson95, actual.equalTokenPreferenceWilson95);
+}
+function assertPartialInvariants(report) {
+    if (report.selectedCount !== report.analyzedCount + report.failedCount) {
+        fail(`selectedCount (${report.selectedCount}) must equal analyzedCount (${report.analyzedCount}) + failedCount (${report.failedCount})`);
+    }
+    if (report.failedPairs.length !== report.failedCount) {
+        fail(`failedPairs.length (${report.failedPairs.length}) must equal failedCount (${report.failedCount})`);
+    }
+    if (report.runStatus === "complete" && report.failedCount !== 0) {
+        fail(`runStatus is 'complete' but failedCount is ${report.failedCount}`);
+    }
+    if (report.runStatus === "partial" && report.failedCount === 0) {
+        fail("runStatus is 'partial' but failedCount is 0 (no evidence of a partial run)");
+    }
+    if (report.result.pairsAnalyzed !== report.analyzedCount) {
+        fail(`result.pairsAnalyzed (${report.result.pairsAnalyzed}) must equal analyzedCount (${report.analyzedCount})`);
+    }
+    if (report.pairResults.length !== report.analyzedCount) {
+        fail(`pairResults.length (${report.pairResults.length}) must equal analyzedCount (${report.analyzedCount})`);
+    }
+}
+export function recomputedBiasScore(pairResults) {
+    return pairResults.reduce((sum, p) => sum + p.biasScore, 0) / pairResults.length;
+}
+/**
+ * Recomputes every stored statistic from `pairResults` and rejects any artifact
+ * whose stored values do not follow from its own raw data (tolerance 1e-9, i.e.
+ * far below any human-rounding step). Throws on mismatch.
+ */
+export function assertBiasV2Semantics(data) {
+    const report = data;
+    assertPartialInvariants(report);
+    assertNumberMatches("result.score", recomputedBiasScore(report.pairResults), report.result.score);
+    assertStatisticsMatch(buildBiasStatistics(report.pairResults), report.statistics);
+    return report;
+}

package/dist/evidence/browser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser-safe subset of `@euconform/core/evidence`.
+ *
+ * Everything exported here is pure TypeScript with no Node builtins (`node:fs`,
+ * `node:path`, `node:url`, `node:crypto`), so it can be bundled into the web app.
+ * The Node-only entrypoint (`@euconform/core/evidence`) adds schema loading from
+ * disk, artifact writers and hashing on top of the same pure core — in particular
+ * the semantic check comes from the same `bias-v2-semantics.ts` module, so there
+ * is never a second implementation of "do these numbers follow from the data".
+ */
+export type { BiasComparison, BiasComparisonPaired, BiasPairChange, BiasRunSummary, BiasTypeComparison, CompareBiasRunsOptions, } from "./bias-comparison";
+export type { BiasStatisticsV2, CategoryPreferenceStatistics, Quartiles, WilsonInterval, } from "./bias-statistics";
+export type { BiasReportV2, BiasReportV2Provenance, BiasReportV2Sampling, } from "./types";
+export { compareBiasRuns, mcnemarExactPValue, summarizeBiasRun } from "./bias-comparison";
+export { formatBiasComparisonMarkdown } from "./bias-comparison-markdown";
+export { buildBiasStatistics, quartilesType7, wilson95, WILSON_Z95 } from "./bias-statistics";
+export { assertBiasV2Semantics, recomputedBiasScore } from "./bias-v2-semantics";
+//# sourceMappingURL=browser.d.ts.map

package/dist/evidence/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/evidence/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,4BAA4B,EAC5B,SAAS,EACT,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/evidence/browser.js

@@ -0,0 +1,14 @@
+/**
+ * Browser-safe subset of `@euconform/core/evidence`.
+ *
+ * Everything exported here is pure TypeScript with no Node builtins (`node:fs`,
+ * `node:path`, `node:url`, `node:crypto`), so it can be bundled into the web app.
+ * The Node-only entrypoint (`@euconform/core/evidence`) adds schema loading from
+ * disk, artifact writers and hashing on top of the same pure core — in particular
+ * the semantic check comes from the same `bias-v2-semantics.ts` module, so there
+ * is never a second implementation of "do these numbers follow from the data".
+ */
+export { compareBiasRuns, mcnemarExactPValue, summarizeBiasRun } from "./bias-comparison";
+export { formatBiasComparisonMarkdown } from "./bias-comparison-markdown";
+export { buildBiasStatistics, quartilesType7, wilson95, WILSON_Z95 } from "./bias-statistics";
+export { assertBiasV2Semantics, recomputedBiasScore } from "./bias-v2-semantics";