@lapxo/obligations 0.4.0 → 0.4.2

package/dist/lattice/obligatory.js

@@ -18,6 +18,7 @@ export function restOf(c, world = new Map()) {
     const out = [];
     const held = new Set();
     const edge = [...c.restsOn];
+    const above = new Map();
     for (let i = 0; i < edge.length; i += 1) {
         const name = edge[i];
         if (name === own)
@@ -26,7 +27,34 @@ export function restOf(c, world = new Map()) {
             continue;
         held.add(name);
         out.push(name);
-        edge.push(...(world.get(name)?.restsOn ?? []));
+        const rests = world.get(name)?.restsOn ?? [];
+        above.set(name, rests);
+        for (const ancestor of rests)
+            edge.push(ancestor);
+    }
+    const status = new Map();
+    for (const name of out) {
+        if (status.has(name))
+            continue;
+        status.set(name, 'visiting');
+        const path = [{ name, next: 0 }];
+        while (path.length) {
+            const head = path[path.length - 1];
+            const rests = above.get(head.name);
+            if (head.next === rests.length) {
+                status.set(head.name, 'done');
+                path.pop();
+                continue;
+            }
+            const ancestor = rests[head.next++];
+            const seen = status.get(ancestor);
+            if (seen === 'visiting')
+                throw new UnitError('rest-cycle', `obligations: REFUSE·rest ${own} reaches a cycle at ${ancestor}: an order of rest with a cycle has no fold to reach`, { at: own });
+            if (seen === undefined) {
+                status.set(ancestor, 'visiting');
+                path.push({ name: ancestor, next: 0 });
+            }
+        }
     }
     return out;
 }

package/dist/measures/capacity.d.ts

@@ -0,0 +1,324 @@
+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 commonCauseCapacityBound(n: number, c: RationalInput, accuracy: RationalInput, policy: LogarithmPolicy): {
+    model: "single-covering-symmetric-cause@1";
+    parameters: {
+        n: number;
+        c: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        q: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+    };
+    policy: Readonly<{
+        logarithm: "binary64-log2";
+    }>;
+    status: "measured";
+    unit: "bits";
+    conditions: readonly ["uniform-truth", "cause-indicator-independent-of-truth", "active-cause-copies-one-symmetric-channel", "inactive-private-channel-unrestricted"];
+    value: number;
+    meaning: "upper bound after revealing cause indicator; copies do not add; no achievability claim";
+};
+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,184 @@
+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 commonCauseCapacityBound(n, c, accuracy, policy) {
+    cardinality(n);
+    logPolicy(policy);
+    if (accuracy === undefined || accuracy === null)
+        refuse('common-cause accuracy q required');
+    const factor = probability(c), correct = probability(accuracy), wrong = sub(one, correct);
+    const uniform = correct[0] * BigInt(n) === correct[1];
+    const channel = uniform ? 0 : correct[0] === 0n ? Math.log1p(1 / (n - 1)) / Math.LN2 :
+        Math.max(0, Math.log2(n) - entropy([correct, wrong]) - numeric(wrong) * Math.log2(n - 1));
+    return { model: 'single-covering-symmetric-cause@1',
+        parameters: { n, c: pack(factor), q: pack(correct) }, policy, status: 'measured', unit: 'bits',
+        conditions: ['uniform-truth', 'cause-indicator-independent-of-truth',
+            'active-cause-copies-one-symmetric-channel', 'inactive-private-channel-unrestricted'],
+        value: numeric(sub(one, factor)) * Math.log2(n) + numeric(factor) * channel,
+        meaning: 'upper bound after revealing cause indicator; copies do not add; no achievability claim' };
+}
+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";
+};