@lapxo/obligations 0.3.5 → 0.4.1

package/dist/measures/capacity.d.ts

@@ -0,0 +1,302 @@
+import { type RationalInput } from './rational.ts';
+export type CapacityModel = Readonly<{
+    n: number;
+    c: RationalInput;
+    p: RationalInput;
+}>;
+export type LogarithmPolicy = Readonly<{
+    logarithm: 'binary64-log2';
+}>;
+export type CapacityPolicy = LogarithmPolicy & Readonly<{
+    budget: string;
+}>;
+export type DecisionRule = 'plurality-uniform-ties@1' | 'posterior-map-uniform-ties@1';
+export declare function capacityBound(n: number, c: RationalInput, policy: LogarithmPolicy): {
+    model: "single-dominant-factor@1";
+    parameters: {
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: Readonly<{
+        logarithm: "binary64-log2";
+    }>;
+    status: "measured";
+    unit: "bits";
+    value: number;
+    meaning: "upper bound for every k; achievability depends on the private channel";
+};
+export declare function capacityP0(n: number, c: RationalInput, policy: LogarithmPolicy): {
+    value: number;
+    meaning: "mutual information at p=0 for every positive k";
+    model: "single-dominant-factor@1";
+    parameters: {
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: Readonly<{
+        logarithm: "binary64-log2";
+    }>;
+    status: "measured";
+    unit: "bits";
+};
+export declare function unanimityNoFactor(k: number, n: number, p: RationalInput, policy: Readonly<{
+    budget: string;
+}>): {
+    status: "unmeasured";
+    cause: string;
+    required: string;
+    workUnit: "rational-bit-bound";
+    model?: undefined;
+    parameters?: undefined;
+    policy?: undefined;
+    value?: undefined;
+} | {
+    status: "measured";
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: Readonly<{
+        budget: string;
+    }>;
+    workUnit: "rational-bit-bound";
+    value: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    cause?: undefined;
+    required?: undefined;
+};
+export declare function mutualInformation(k: number, model: CapacityModel, policy: CapacityPolicy): {
+    status: "measured";
+    unit: "bits";
+    value: number;
+    probabilitySum: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    work: string;
+    loss: {
+        exclusion: number;
+        privateUncertainty: number;
+        factorAmbiguity: number;
+    };
+    exactConditionalEntropy: {
+        mass: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        posterior: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    }[];
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+} | {
+    status: "unmeasured";
+    cause: string;
+    requiredAtLeast: string;
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+} | {
+    decision: {
+        rule: DecisionRule | undefined;
+        accuracy: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        information: number;
+        joint: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>[][];
+        tiePolicy: "uniform-over-maximizers";
+    };
+    status: "measured";
+    unit: "bits";
+    value: number;
+    probabilitySum: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    work: string;
+    loss: {
+        exclusion: number;
+        privateUncertainty: number;
+        factorAmbiguity: number;
+    };
+    exactConditionalEntropy: {
+        mass: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        posterior: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    }[];
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+};
+export declare function decisionInformation(k: number, model: CapacityModel, rule: DecisionRule, policy: CapacityPolicy): {
+    status: "measured";
+    unit: "bits";
+    value: number;
+    probabilitySum: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    work: string;
+    loss: {
+        exclusion: number;
+        privateUncertainty: number;
+        factorAmbiguity: number;
+    };
+    exactConditionalEntropy: {
+        mass: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        posterior: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    }[];
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+} | {
+    status: "unmeasured";
+    cause: string;
+    requiredAtLeast: string;
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+} | {
+    decision: {
+        rule: DecisionRule | undefined;
+        accuracy: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        information: number;
+        joint: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>[][];
+        tiePolicy: "uniform-over-maximizers";
+    };
+    status: "measured";
+    unit: "bits";
+    value: number;
+    probabilitySum: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    work: string;
+    loss: {
+        exclusion: number;
+        privateUncertainty: number;
+        factorAmbiguity: number;
+    };
+    exactConditionalEntropy: {
+        mass: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        posterior: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    }[];
+    model: "single-dominant-factor@1";
+    parameters: {
+        k: number;
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: CapacityPolicy;
+    conditions: readonly ["uniform-truth", "factor-independent-of-truth", "uniform-shared-wrong-value", "independent-homogeneous-private-channel"];
+};

package/dist/measures/capacity.js

@@ -0,0 +1,168 @@
+import { add, sub, mul, div, q, pow, zero, one, pack, probability } from "./rational.js";
+const refuse = (cause) => { throw new Error('REFUSE·capacity ' + cause); };
+function cardinality(n) { if (!Number.isSafeInteger(n) || n < 2)
+    refuse('invalid cardinality'); }
+function logPolicy(policy) { if (!policy || policy.logarithm !== 'binary64-log2')
+    refuse('logarithm policy required'); }
+function logInteger(value) {
+    const bits = value.toString(2).length, shift = Math.max(0, bits - 53);
+    return Math.log2(Number(value >> BigInt(shift))) + shift;
+}
+function logQ(value) { return logInteger(value[0]) - logInteger(value[1]); }
+function numeric(value) { return value[0] === 0n ? 0 : 2 ** logQ(value); }
+function entropy(probabilities) {
+    let value = 0, correction = 0;
+    for (const p of probabilities) {
+        if (p[0] === 0n)
+            continue;
+        const term = -numeric(p) * logQ(p) - correction, next = value + term;
+        correction = (next - value) - term;
+        value = next;
+    }
+    return value;
+}
+export function capacityBound(n, c, policy) {
+    cardinality(n);
+    logPolicy(policy);
+    const factor = probability(c);
+    return { model: 'single-dominant-factor@1', parameters: { n, c: pack(factor) }, policy,
+        status: 'measured', unit: 'bits', value: Math.log2(n) - numeric(factor) * Math.log2(n - 1),
+        meaning: 'upper bound for every k; achievability depends on the private channel' };
+}
+export function capacityP0(n, c, policy) {
+    const bound = capacityBound(n, c, policy), factor = probability(c);
+    return { ...bound, value: bound.value - entropy([factor, sub(one, factor)]), meaning: 'mutual information at p=0 for every positive k' };
+}
+export function unanimityNoFactor(k, n, p, policy) {
+    cardinality(n);
+    if (!Number.isSafeInteger(k) || k < 1)
+        refuse('invalid witness count');
+    if (!policy || typeof policy.budget !== 'string' || !/^\d+$/.test(policy.budget))
+        refuse('power budget required');
+    const error = probability(p);
+    const required = BigInt(k) * (BigInt(error[1].toString(2).length) + BigInt(BigInt(n - 1).toString(2).length) + 2n);
+    if (required > BigInt(policy.budget))
+        return { status: 'unmeasured', cause: 'capacity/power-budget', required: String(required), workUnit: 'rational-bit-bound' };
+    return { status: 'measured', model: 'single-dominant-factor@1', parameters: { k, n, p: pack(error) },
+        policy, workUnit: 'rational-bit-bound', value: pack(add(pow(sub(one, error), k), div(pow(error, k), pow(q(BigInt(n - 1)), k - 1)))) };
+}
+function term(terms, mass, posterior) {
+    if (mass[0] === 0n)
+        return;
+    const key = posterior.join('/'), previous = terms.get(key);
+    terms.set(key, { mass: previous ? add(previous.mass, mass) : mass, posterior });
+}
+function evaluateEntropy(terms) {
+    let sum = 0, correction = 0;
+    for (const item of terms.values()) {
+        const contribution = -numeric(item.mass) * logQ(item.posterior) - correction, next = sum + contribution;
+        correction = (next - sum) - contribution;
+        sum = next;
+    }
+    return sum;
+}
+function prepared(k, model, policy) {
+    if (!model)
+        refuse('model required');
+    cardinality(model.n);
+    logPolicy(policy);
+    if (!Number.isSafeInteger(k) || k < 1)
+        refuse('invalid witness count');
+    if (typeof policy.budget !== 'string' || !/^\d+$/.test(policy.budget))
+        refuse('invalid enumeration budget');
+    const c = probability(model.c), p = probability(model.p), cap = BigInt(policy.budget);
+    let work = 1n;
+    for (let i = 0; i <= k; i++) {
+        work *= BigInt(model.n);
+        if (work > cap)
+            break;
+    }
+    return { c, p, cap, work };
+}
+export function mutualInformation(k, model, policy) {
+    return evaluateCapacity(k, model, policy);
+}
+export function decisionInformation(k, model, rule, policy) {
+    if (rule !== 'plurality-uniform-ties@1' && rule !== 'posterior-map-uniform-ties@1')
+        refuse('unknown decision rule');
+    return evaluateCapacity(k, model, policy, rule);
+}
+function evaluateCapacity(k, model, policy, rule) {
+    const { c, p, cap, work } = prepared(k, model, policy), n = model.n;
+    const metadata = { model: 'single-dominant-factor@1', parameters: { k, n, c: pack(c), p: pack(p) }, policy,
+        conditions: ['uniform-truth', 'factor-independent-of-truth', 'uniform-shared-wrong-value',
+            'independent-homogeneous-private-channel'] };
+    if (work > cap)
+        return { ...metadata, status: 'unmeasured', cause: 'capacity/budget', requiredAtLeast: String(work) };
+    const terms = new Map(), privateTerms = new Map();
+    const decisions = rule ? Array.from({ length: n }, () => Array.from({ length: n }, () => zero)) : undefined;
+    let total = zero, accuracy = zero;
+    const counts = Array(n).fill(0);
+    function visit(depth) {
+        if (depth < k) {
+            for (let value = 0; value < n; value++) {
+                counts[value]++;
+                visit(depth + 1);
+                counts[value]--;
+            }
+            return;
+        }
+        const unanimous = counts.findIndex(count => count === k), privateMass = [], joint = [];
+        for (let t = 0; t < n; t++) {
+            const channel = mul(pow(sub(one, p), counts[t]), pow(div(p, q(BigInt(n - 1))), k - counts[t]));
+            const independent = div(channel, q(BigInt(n)));
+            privateMass.push(independent);
+            const forced = unanimous >= 0 && unanimous !== t ? div(c, q(BigInt(n) * BigInt(n - 1))) : zero;
+            joint.push(add(mul(sub(one, c), independent), forced));
+        }
+        const mass = joint.reduce(add, zero), privateTotal = privateMass.reduce(add, zero);
+        total = add(total, mass);
+        joint.forEach(value => { if (value[0] !== 0n)
+            term(terms, value, div(value, mass)); });
+        privateMass.forEach(value => { if (value[0] !== 0n)
+            term(privateTerms, value, div(value, privateTotal)); });
+        if (!decisions || mass[0] === 0n)
+            return;
+        const winners = [];
+        if (rule === 'plurality-uniform-ties@1') {
+            const largest = Math.max(...counts);
+            counts.forEach((count, i) => { if (count === largest)
+                winners.push(i); });
+        }
+        else {
+            let largest = zero;
+            for (const value of joint)
+                if (value[0] * largest[1] > largest[0] * value[1])
+                    largest = value;
+            joint.forEach((value, i) => { if (value[0] * largest[1] === largest[0] * value[1])
+                winners.push(i); });
+        }
+        for (let t = 0; t < n; t++)
+            for (const answer of winners) {
+                const mass = div(joint[t], q(BigInt(winners.length)));
+                decisions[t][answer] = add(decisions[t][answer], mass);
+                if (answer === t)
+                    accuracy = add(accuracy, mass);
+            }
+    }
+    visit(0);
+    const conditional = evaluateEntropy(terms), privateConditional = evaluateEntropy(privateTerms);
+    const result = { ...metadata, status: 'measured', unit: 'bits',
+        value: Math.log2(n) - conditional, probabilitySum: pack(total), work: String(work),
+        loss: { exclusion: numeric(c) * Math.log2(n - 1), privateUncertainty: numeric(sub(one, c)) * privateConditional,
+            factorAmbiguity: conditional - numeric(c) * Math.log2(n - 1) - numeric(sub(one, c)) * privateConditional },
+        exactConditionalEntropy: [...terms.values()].map(({ mass, posterior }) => ({ mass: pack(mass), posterior: pack(posterior) })) };
+    if (!decisions)
+        return result;
+    const decisionTerms = new Map();
+    for (let answer = 0; answer < n; answer++) {
+        const mass = decisions.reduce((sum, row) => add(sum, row[answer]), zero);
+        if (mass[0] === 0n)
+            continue;
+        for (const row of decisions)
+            if (row[answer][0] !== 0n)
+                term(decisionTerms, row[answer], div(row[answer], mass));
+    }
+    return { ...result, decision: { rule, accuracy: pack(accuracy), information: Math.log2(n) - evaluateEntropy(decisionTerms),
+            joint: decisions.map(row => row.map(pack)), tiePolicy: 'uniform-over-maximizers' } };
+}

package/dist/measures/coincidence.d.ts

@@ -0,0 +1,111 @@
+import { type RationalInput } from './rational.ts';
+export type ValueReading = Readonly<{
+    event: string;
+    origin: string;
+    value: string;
+}>;
+export type TruthReading = Readonly<{
+    event: string;
+    value: string;
+    kind: 'truth';
+}>;
+export type CoincidenceReference = Readonly<{
+    model: 'independent-uniform-wrong@1';
+    values: readonly string[];
+}> & (Readonly<{
+    marginals: 'handed';
+    errors: readonly Readonly<{
+        origin: string;
+        probability: RationalInput;
+    }>[];
+}> | Readonly<{
+    marginals: 'estimated-by-truth';
+}>);
+export type CoincidencePolicy = Readonly<{
+    minEvents: number;
+    minEventsPerTruth: number;
+    budget: string;
+}>;
+export declare function coincidenceExcess(rows: readonly ValueReading[], truth: readonly TruthReading[], selection: readonly string[], reference: CoincidenceReference, policy: CoincidencePolicy): {
+    status: "unmeasured";
+    cause: string;
+    required: string;
+    reference: CoincidenceReference;
+    policy: Readonly<{
+        minEvents: number;
+        minEventsPerTruth: number;
+        budget: string;
+    }>;
+    selection: string[];
+    order: number;
+    interpretation: "coincidence relative to the declared reference; not causal identification";
+} | {
+    status: "unmeasured";
+    cause: string;
+    events: number;
+    reference: CoincidenceReference;
+    policy: Readonly<{
+        minEvents: number;
+        minEventsPerTruth: number;
+        budget: string;
+    }>;
+    selection: string[];
+    order: number;
+    interpretation: "coincidence relative to the declared reference; not causal identification";
+} | {
+    status: "measured";
+    events: number;
+    falseCoincidences: number;
+    observed: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    expected: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    delta: Readonly<{
+        numerator: string;
+        denominator: string;
+    }>;
+    ratio: {
+        status: "unmeasured";
+        cause: string;
+        value?: undefined;
+    } | {
+        status: "measured";
+        value: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        cause?: undefined;
+    };
+    strata: {
+        truth: string;
+        events: number;
+        marginals: {
+            origin: string;
+            error: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+        }[];
+        reference: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    }[];
+    uncertainty: {
+        status: "unmeasured";
+        cause: string;
+    };
+    reference: CoincidenceReference;
+    policy: Readonly<{
+        minEvents: number;
+        minEventsPerTruth: number;
+        budget: string;
+    }>;
+    selection: string[];
+    order: number;
+    interpretation: "coincidence relative to the declared reference; not causal identification";
+};

package/dist/measures/coincidence.js

@@ -0,0 +1,81 @@
+import { add, sub, mul, div, pow, q, zero, one, pack, probability } from "./rational.js";
+const refuse = (cause) => { throw new Error('REFUSE·coincidence ' + cause); };
+const named = (value) => typeof value === 'string' && value.length > 0;
+export function coincidenceExcess(rows, truth, selection, reference, policy) {
+    if (!Array.isArray(rows) || !Array.isArray(truth) || !Array.isArray(selection) || !selection.length ||
+        selection.some(id => !named(id)) || new Set(selection).size !== selection.length)
+        refuse('invalid selection or rows');
+    if (!reference || reference.model !== 'independent-uniform-wrong@1' || !Array.isArray(reference.values) ||
+        reference.values.length < 2 || reference.values.some(value => !named(value)) || new Set(reference.values).size !== reference.values.length)
+        refuse('invalid declared reference');
+    if (!policy || !Number.isSafeInteger(policy.minEvents) || policy.minEvents < 1 ||
+        !Number.isSafeInteger(policy.minEventsPerTruth) || policy.minEventsPerTruth < 1 || typeof policy.budget !== 'string' || !/^\d+$/.test(policy.budget))
+        refuse('invalid observation policy');
+    const required = BigInt(rows.length) * (BigInt(selection.length) + 1n) + BigInt(truth.length) + BigInt(reference.values.length) + BigInt(selection.length);
+    const metadata = { reference, policy, selection: [...selection].sort(), order: selection.length,
+        interpretation: 'coincidence relative to the declared reference; not causal identification' };
+    if (required > BigInt(policy.budget))
+        return { ...metadata, status: 'unmeasured', cause: 'coincidence/budget', required: String(required) };
+    const selected = new Set(selection), alphabet = new Set(reference.values), truthByEvent = new Map();
+    for (const row of truth) {
+        if (!row || row.kind !== 'truth' || !named(row.event) || !alphabet.has(row.value))
+            refuse('invalid truth; probes require a separate declared contract');
+        if (truthByEvent.has(row.event) && truthByEvent.get(row.event) !== row.value)
+            refuse('conflicting truth ' + row.event);
+        truthByEvent.set(row.event, row.value);
+    }
+    const events = new Map();
+    for (const row of rows) {
+        if (!row || !named(row.event) || !named(row.origin) || !alphabet.has(row.value))
+            refuse('invalid value reading');
+        if (!selected.has(row.origin))
+            continue;
+        const values = events.get(row.event) ?? new Map();
+        if (values.has(row.origin) && values.get(row.origin) !== row.value)
+            refuse('conflicting value ' + row.event + '/' + row.origin);
+        values.set(row.origin, row.value);
+        events.set(row.event, values);
+    }
+    const ordered = [...events.keys()].sort();
+    if (ordered.length < policy.minEvents)
+        return { ...metadata, status: 'unmeasured', cause: 'insufficient observed events', events: ordered.length };
+    if (ordered.some(event => events.get(event).size !== selection.length || !truthByEvent.has(event)))
+        return { ...metadata, status: 'unmeasured', cause: 'incomplete shared events or truth', events: ordered.length };
+    const origins = [...selection].sort(), groups = new Map();
+    let falseCoincidences = 0;
+    for (const event of ordered) {
+        const t = truthByEvent.get(event), values = origins.map(id => events.get(event).get(id));
+        if (values.every(value => value === values[0]) && values[0] !== t)
+            falseCoincidences++;
+        const group = groups.get(t) ?? { events: 0, errors: origins.map(() => 0) };
+        group.events++;
+        values.forEach((value, i) => { if (value !== t)
+            group.errors[i]++; });
+        groups.set(t, group);
+    }
+    let handed = [];
+    if (reference.marginals === 'handed') {
+        if (!Array.isArray(reference.errors) || reference.errors.length !== origins.length || reference.errors.some(row => !row) ||
+            new Set(reference.errors.map(row => row.origin)).size !== origins.length ||
+            reference.errors.some(row => !row || !selected.has(row.origin)))
+            refuse('marginals must name exactly the selection');
+        handed = origins.map(id => probability(reference.errors.find(row => row.origin === id).probability));
+    }
+    else if (reference.marginals !== 'estimated-by-truth')
+        refuse('unknown marginal procedure');
+    if (reference.marginals === 'estimated-by-truth' && [...groups.values()].some(group => group.events < policy.minEventsPerTruth))
+        return { ...metadata, status: 'unmeasured', cause: 'insufficient events per observed truth', events: ordered.length };
+    let expected = zero;
+    const strata = [...groups].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([value, group]) => {
+        const errors = reference.marginals === 'handed' ? handed : group.errors.map(count => q(BigInt(count), BigInt(group.events)));
+        const baseline = div(errors.reduce(mul, one), pow(q(BigInt(reference.values.length - 1)), origins.length - 1));
+        expected = add(expected, mul(q(BigInt(group.events), BigInt(ordered.length)), baseline));
+        return { truth: value, events: group.events, marginals: origins.map((origin, i) => ({ origin, error: pack(errors[i]) })), reference: pack(baseline) };
+    });
+    const observed = q(BigInt(falseCoincidences), BigInt(ordered.length));
+    return { ...metadata, status: 'measured', events: ordered.length, falseCoincidences, observed: pack(observed),
+        expected: pack(expected), delta: pack(sub(observed, expected)),
+        ratio: expected[0] === 0n ? { status: 'unmeasured', cause: 'zero reference mass' } :
+            { status: 'measured', value: pack(div(observed, expected)) }, strata,
+        uncertainty: { status: 'unmeasured', cause: 'descriptive population only; no sampling design handed' } };
+}

package/dist/measures/error-events.d.ts

@@ -0,0 +1,27 @@
+export type ErrorEvent = Readonly<{
+    event: string;
+    origin: string;
+    error: 0 | 1;
+}>;
+export type Unmeasured = Readonly<{
+    status: 'unmeasured';
+    cause: string;
+}>;
+export type ErrorMatrix = Readonly<{
+    status: 'measured';
+    origins: readonly string[];
+    events: readonly string[];
+    matrix: readonly (readonly number[])[];
+}>;
+export type Covariance = ErrorMatrix;
+export type Scalar = Readonly<{
+    status: 'measured';
+    value: number;
+}> | Unmeasured;
+export type ObservationPolicy = Readonly<{
+    minCells: number;
+}>;
+export declare function errorMatrix(rows: readonly ErrorEvent[], policy: ObservationPolicy, requested?: readonly string[]): ErrorMatrix | Unmeasured;
+export declare function covariance(reading: ErrorMatrix | Unmeasured): Covariance | Unmeasured;
+export declare const errorCovariance: (rows: readonly ErrorEvent[], policy: ObservationPolicy) => Covariance | Unmeasured;
+export declare function participationRatio(reading: Covariance | Unmeasured): Scalar;