@lapxo/obligations 0.4.0 → 0.4.1

package/dist/measures/error-events.js

@@ -1,9 +1,11 @@
 export function errorMatrix(rows, policy, requested) {
-    if (!Number.isSafeInteger(policy.minCells) || policy.minCells < 2)
+    if (!policy || !Number.isSafeInteger(policy.minCells) || policy.minCells < 2)
         throw new Error('REFUSE·measure invalid minimum cells');
+    if (!Array.isArray(rows) || (requested !== undefined && !Array.isArray(requested)))
+        throw new Error('REFUSE·measure invalid event population');
     const cells = new Map();
     for (const row of rows) {
-        if (!row.event || !row.origin || (row.error !== 0 && row.error !== 1))
+        if (!row || typeof row.event !== 'string' || !row.event || typeof row.origin !== 'string' || !row.origin || (row.error !== 0 && row.error !== 1))
             throw new Error('REFUSE·measure invalid error event');
         const at = cells.get(row.event) ?? new Map();
         if (at.has(row.origin) && at.get(row.origin) !== row.error)
@@ -12,7 +14,7 @@ export function errorMatrix(rows, policy, requested) {
         cells.set(row.event, at);
     }
     const origins = [...new Set(requested ?? rows.map(row => row.origin))].sort();
-    if (origins.some(origin => !origin))
+    if (origins.some(origin => typeof origin !== 'string' || !origin))
         throw new Error('REFUSE·measure invalid origin');
     const events = [...cells.keys()].filter(event => origins.some(origin => cells.get(event).has(origin))).sort();
     if (events.length < policy.minCells || !origins.length)
@@ -22,10 +24,15 @@ export function errorMatrix(rows, policy, requested) {
     return { status: 'measured', origins, events, matrix: events.map(event => origins.map(origin => cells.get(event).get(origin))) };
 }
 export function covariance(reading) {
+    if (!reading || (reading.status !== 'measured' && reading.status !== 'unmeasured'))
+        throw new Error('REFUSE·measure invalid error matrix reading');
     if (reading.status === 'unmeasured')
         return reading;
+    if (!Array.isArray(reading.events) || !Array.isArray(reading.origins) || !Array.isArray(reading.matrix))
+        throw new Error('REFUSE·measure invalid error matrix');
     const n = reading.events.length, m = reading.origins.length;
-    if (!n || !m || reading.matrix.length !== n || reading.matrix.some(row => row.length !== m || row.some(x => x !== 0 && x !== 1)) || new Set(reading.events).size !== n || new Set(reading.origins).size !== m)
+    if (!n || !m || reading.events.some(event => typeof event !== 'string' || !event) || reading.origins.some(origin => typeof origin !== 'string' || !origin) ||
+        reading.matrix.length !== n || reading.matrix.some(row => !Array.isArray(row) || row.length !== m || row.some(x => x !== 0 && x !== 1)) || new Set(reading.events).size !== n || new Set(reading.origins).size !== m)
         throw new Error('REFUSE·measure invalid error matrix');
     const mean = reading.origins.map((_, i) => reading.matrix.reduce((sum, row) => sum + row[i], 0) / n);
     const matrix = Array.from({ length: m }, (_, i) => Array.from({ length: m }, (_, j) => reading.matrix.reduce((sum, row) => sum + (row[i] - mean[i]) * (row[j] - mean[j]), 0) / n));
@@ -33,8 +40,20 @@ export function covariance(reading) {
 }
 export const errorCovariance = (rows, policy) => covariance(errorMatrix(rows, policy));
 export function participationRatio(reading) {
+    if (!reading || (reading.status !== 'measured' && reading.status !== 'unmeasured'))
+        throw new Error('REFUSE·measure invalid covariance reading');
     if (reading.status === 'unmeasured')
         return reading;
+    const n = reading.origins?.length;
+    if (!n || !Array.isArray(reading.matrix) || reading.matrix.length !== n || reading.matrix.some(row => !Array.isArray(row) || row.length !== n || row.some(value => !Number.isFinite(value))))
+        throw new Error('REFUSE·measure invalid covariance matrix');
+    for (let i = 0; i < n; i++) {
+        if (reading.matrix[i][i] < 0)
+            throw new Error('REFUSE·measure negative covariance diagonal');
+        for (let j = 0; j < n; j++)
+            if (reading.matrix[i][j] !== reading.matrix[j][i])
+                throw new Error('REFUSE·measure nonsymmetric covariance');
+    }
     const trace = reading.matrix.reduce((sum, row, i) => sum + row[i], 0);
     const square = reading.matrix.reduce((sum, row) => sum + row.reduce((n, value) => n + value * value, 0), 0);
     if (square === 0)

package/dist/measures/fitting.d.ts

@@ -165,7 +165,7 @@ export declare function fitM3(rows: readonly ErrorEvent[], structure: FitStructu
     procedure: "constrained-log-least-squares/active-set@1";
 } | {
     bootstrap: {
-        status: "unmeasured" | "measured";
+        status: "measured" | "unmeasured";
         cause: string | undefined;
         words: number;
         replicates: ({

package/dist/measures/index.d.ts

@@ -16,3 +16,9 @@ export { experimentM3 } from './m3-experiment.ts';
 export type { M3ExperimentPolicy } from './m3-experiment.ts';
 export { fitM3 } from './fitting.ts';
 export type { FitStructure, FitPolicy } from './fitting.ts';
+export { capacityBound, capacityP0, mutualInformation, unanimityNoFactor, decisionInformation } from './capacity.ts';
+export type { CapacityModel, LogarithmPolicy, CapacityPolicy, DecisionRule } from './capacity.ts';
+export { fitUnanimityModel } from './unanimity-fit.ts';
+export type { UnanimityCount, UnanimityGroup, UnanimityCurve, UnanimityFitPolicy } from './unanimity-fit.ts';
+export { coincidenceExcess } from './coincidence.ts';
+export type { ValueReading, TruthReading, CoincidenceReference, CoincidencePolicy } from './coincidence.ts';

package/dist/measures/index.js

@@ -7,3 +7,6 @@ export { roundHalfEven } from "./rational.js";
 export { identifyM3 } from "./identification.js";
 export { experimentM3 } from "./m3-experiment.js";
 export { fitM3 } from "./fitting.js";
+export { capacityBound, capacityP0, mutualInformation, unanimityNoFactor, decisionInformation } from "./capacity.js";
+export { fitUnanimityModel } from "./unanimity-fit.js";
+export { coincidenceExcess } from "./coincidence.js";

package/dist/measures/unanimity-fit.d.ts

@@ -0,0 +1,156 @@
+import { type RationalInput } from './rational.ts';
+export type UnanimityCount = Readonly<{
+    k: number;
+    unanimous: number;
+    trials: number;
+}>;
+export type UnanimityGroup = Readonly<{
+    id: string;
+    outcomes: readonly Readonly<{
+        k: number;
+        unanimous: boolean;
+    }>[];
+}>;
+export type UnanimityCurve = Readonly<{
+    n: number;
+    lineage: string;
+    counts: readonly UnanimityCount[];
+    groups?: readonly UnanimityGroup[];
+}>;
+export type UnanimityFitPolicy = Readonly<{
+    procedure: 'exact-c-slices-on-declared-p-grid@1';
+    p: readonly RationalInput[];
+    tolerance: RationalInput;
+    budget: string;
+    bootstrap: Readonly<{
+        B: number;
+        seed: number;
+        prng: 'xorshift32';
+        randomWords: number;
+    }>;
+}>;
+export declare function fitUnanimityModel(curve: UnanimityCurve, policy: UnanimityFitPolicy): {
+    status: "unmeasured";
+    cause: string;
+    required: string;
+    model: "single-dominant-factor@1";
+    lineage: string;
+    cardinality: number;
+    policy: Readonly<{
+        procedure: "exact-c-slices-on-declared-p-grid@1";
+        p: readonly RationalInput[];
+        tolerance: RationalInput;
+        budget: string;
+        bootstrap: Readonly<{
+            B: number;
+            seed: number;
+            prng: "xorshift32";
+            randomWords: number;
+        }>;
+    }>;
+    meaning: "compatible with (c,p) under the declared model, on the declared p slices only";
+    workUnit: "rational-bit-and-group-bound";
+} | {
+    compatible: {
+        p: Readonly<{
+            numerator: string;
+            denominator: string;
+        }>;
+        c: {
+            lo: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+            hi: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+        };
+        residuals: {
+            k: number;
+            at: "slice-midpoint";
+            predicted: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+            observed: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+            residual: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+        }[];
+    }[];
+    identification: {
+        status: "unmeasured";
+        cause: string;
+        diagnostics: string[];
+    };
+    uncertainty: {
+        status: "unmeasured";
+        cause: string;
+        words: number;
+        procedure?: undefined;
+        replicas?: undefined;
+        interpretation?: undefined;
+    } | {
+        status: "measured";
+        procedure: "paired-group-bootstrap-regions@1";
+        replicas: {
+            p: Readonly<{
+                numerator: string;
+                denominator: string;
+            }>;
+            c: {
+                lo: Readonly<{
+                    numerator: string;
+                    denominator: string;
+                }>;
+                hi: Readonly<{
+                    numerator: string;
+                    denominator: string;
+                }>;
+            };
+            residuals: {
+                k: number;
+                at: "slice-midpoint";
+                predicted: Readonly<{
+                    numerator: string;
+                    denominator: string;
+                }>;
+                observed: Readonly<{
+                    numerator: string;
+                    denominator: string;
+                }>;
+                residual: Readonly<{
+                    numerator: string;
+                    denominator: string;
+                }>;
+            }[];
+        }[][];
+        words: number;
+        interpretation: "empirical replicate regions; not a guaranteed confidence set";
+        cause?: undefined;
+    };
+    cause?: string | undefined;
+    status: "measured" | "unmeasured";
+    model: "single-dominant-factor@1";
+    lineage: string;
+    cardinality: number;
+    policy: Readonly<{
+        procedure: "exact-c-slices-on-declared-p-grid@1";
+        p: readonly RationalInput[];
+        tolerance: RationalInput;
+        budget: string;
+        bootstrap: Readonly<{
+            B: number;
+            seed: number;
+            prng: "xorshift32";
+            randomWords: number;
+        }>;
+    }>;
+    meaning: "compatible with (c,p) under the declared model, on the declared p slices only";
+    workUnit: "rational-bit-and-group-bound";
+};

package/dist/measures/unanimity-fit.js

@@ -0,0 +1,133 @@
+import { add, sub, mul, div, q, pow, zero, one, pack, probability } from "./rational.js";
+const refuse = (cause) => { throw new Error('REFUSE·unanimity-fit ' + cause); };
+const compare = (a, b) => a[0] * b[1] < b[0] * a[1] ? -1 : a[0] * b[1] > b[0] * a[1] ? 1 : 0;
+function privateRate(k, n, p) {
+    return add(pow(sub(one, p), k), div(pow(p, k), pow(q(BigInt(n - 1)), k - 1)));
+}
+function slices(counts, n, grid, tolerance) {
+    return grid.flatMap(p => {
+        let lo = zero, hi = one;
+        for (const row of counts) {
+            const observed = q(BigInt(row.unanimous), BigInt(row.trials)), a = privateRate(row.k, n, p), b = sub(one, a);
+            if (b[0] === 0n) {
+                if (compare(observed, sub(one, tolerance)) < 0)
+                    return [];
+                continue;
+            }
+            const lower = div(sub(sub(observed, tolerance), a), b), upper = div(sub(add(observed, tolerance), a), b);
+            if (compare(lower, lo) > 0)
+                lo = lower;
+            if (compare(upper, hi) < 0)
+                hi = upper;
+            if (compare(lo, hi) > 0)
+                return [];
+        }
+        const midpoint = div(add(lo, hi), q(2n));
+        return [{ p: pack(p), c: { lo: pack(lo), hi: pack(hi) }, residuals: counts.map(row => {
+                    const predicted = add(midpoint, mul(sub(one, midpoint), privateRate(row.k, n, p)));
+                    return { k: row.k, at: 'slice-midpoint', predicted: pack(predicted),
+                        observed: pack(q(BigInt(row.unanimous), BigInt(row.trials))),
+                        residual: pack(sub(q(BigInt(row.unanimous), BigInt(row.trials)), predicted)) };
+                }) }];
+    });
+}
+export function fitUnanimityModel(curve, policy) {
+    if (!curve || !Number.isSafeInteger(curve.n) || curve.n < 2 || typeof curve.lineage !== 'string' || !curve.lineage ||
+        !Array.isArray(curve.counts) || !curve.counts.length)
+        refuse('one declared lineage, cardinality and counts required');
+    if (curve.counts.some(row => !row || !Number.isSafeInteger(row.k) || row.k < 1 || !Number.isSafeInteger(row.trials) || row.trials < 1 ||
+        !Number.isSafeInteger(row.unanimous) || row.unanimous < 0 || row.unanimous > row.trials))
+        refuse('invalid size counts');
+    const counts = [...curve.counts].sort((a, b) => a.k - b.k);
+    if (new Set(counts.map(row => row.k)).size !== counts.length)
+        refuse('invalid or duplicate size counts');
+    if (!policy || policy.procedure !== 'exact-c-slices-on-declared-p-grid@1' || !Array.isArray(policy.p) || !policy.p.length ||
+        typeof policy.budget !== 'string' || !/^\d+$/.test(policy.budget))
+        refuse('declared fitting procedure and budget required');
+    const grid = policy.p.map(probability).sort(compare), tolerance = probability(policy.tolerance), bootstrap = policy.bootstrap;
+    if (new Set(grid.map(p => p.join('/'))).size !== grid.length)
+        refuse('duplicate p slice');
+    if (!bootstrap || bootstrap.prng !== 'xorshift32' || !Number.isInteger(bootstrap.seed) || bootstrap.seed < 1 || bootstrap.seed > 0xffffffff ||
+        !Number.isSafeInteger(bootstrap.B) || bootstrap.B < 0 || !Number.isSafeInteger(bootstrap.randomWords) || bootstrap.randomWords < 0)
+        refuse('invalid bootstrap declaration');
+    const work = grid.reduce((sum, p) => sum + counts.reduce((total, row) => total + BigInt(row.k) *
+        (BigInt(p[1].toString(2).length) + BigInt(BigInt(curve.n - 1).toString(2).length) + 2n), 0n), 0n) * (BigInt(bootstrap.B) + 1n) +
+        BigInt(curve.groups?.length ?? 0) * (BigInt(counts.length) + 1n) * (BigInt(bootstrap.B) + 1n);
+    const metadata = { model: 'single-dominant-factor@1', lineage: curve.lineage, cardinality: curve.n, policy,
+        meaning: 'compatible with (c,p) under the declared model, on the declared p slices only',
+        workUnit: 'rational-bit-and-group-bound' };
+    if (work > BigInt(policy.budget))
+        return { ...metadata, status: 'unmeasured', cause: 'unanimity-fit/budget', required: String(work) };
+    const compatible = slices(counts, curve.n, grid, tolerance);
+    let groups;
+    if (curve.groups !== undefined) {
+        if (!Array.isArray(curve.groups) || !curve.groups.length || curve.groups.some(group => !group) || new Set(curve.groups.map(group => group.id)).size !== curve.groups.length)
+            refuse('invalid or duplicate sampling groups');
+        for (const group of curve.groups) {
+            if (!group || typeof group.id !== 'string' || !group.id || !Array.isArray(group.outcomes) || group.outcomes.length !== counts.length ||
+                group.outcomes.some((item) => !item || typeof item.unanimous !== 'boolean' || !counts.some(row => row.k === item.k)) ||
+                new Set(group.outcomes.map((item) => item.k)).size !== counts.length)
+                refuse('complete paired size outcomes required');
+        }
+        groups = [...curve.groups].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        for (const row of counts)
+            if (row.trials !== groups.length || row.unanimous !== groups.filter(group => group.outcomes.find(item => item.k === row.k).unanimous).length)
+                refuse('group outcomes do not reproduce counts');
+    }
+    const causes = [];
+    if (counts.filter(row => row.k > 1).length < 2)
+        causes.push('too few informative sizes');
+    if (counts.every(row => row.unanimous === row.trials))
+        causes.push('perfect unanimity cannot distinguish p=0 from c=1');
+    if (curve.n === 2 && compatible.some(slice => compatible.some(other => compare(add([BigInt(slice.p.numerator), BigInt(slice.p.denominator)], [BigInt(other.p.numerator), BigInt(other.p.denominator)]), one) === 0 &&
+        slice.p.numerator + '/' + slice.p.denominator !== other.p.numerator + '/' + other.p.denominator)))
+        causes.push('binary p versus 1-p ambiguity');
+    if (!compatible.length)
+        causes.push('no compatible parameter slice under the declared tolerance');
+    const replicas = [], wordsLimit = bootstrap.randomWords;
+    let x = bootstrap.seed >>> 0, words = 0;
+    const exhausted = Symbol('unanimity-fit/random-words');
+    function index(N) {
+        const limit = Math.floor(4294967296 / N) * N;
+        for (;;) {
+            if (words >= wordsLimit)
+                throw exhausted;
+            words++;
+            x ^= x << 13;
+            x ^= x >>> 17;
+            x ^= x << 5;
+            const value = x >>> 0;
+            if (value < limit)
+                return value % N;
+        }
+    }
+    let uncertaintyCause;
+    if (!groups || bootstrap.B === 0)
+        uncertaintyCause = groups ? 'bootstrap not requested' : 'sampling groups not handed; size dependence unknown';
+    else {
+        if (groups.length > 4294967296)
+            refuse('sampling population exceeds declared PRNG index range');
+        try {
+            for (let b = 0; b < bootstrap.B; b++) {
+                const hits = counts.map(() => 0);
+                for (let i = 0; i < groups.length; i++) {
+                    const group = groups[index(groups.length)];
+                    counts.forEach((row, j) => { if (group.outcomes.find(item => item.k === row.k).unanimous)
+                        hits[j]++; });
+                }
+                replicas.push(slices(counts.map((row, i) => ({ ...row, unanimous: hits[i] })), curve.n, grid, tolerance));
+            }
+        }
+        catch (error) {
+            if (error !== exhausted)
+                throw error;
+            uncertaintyCause = 'unanimity-fit/random-words';
+        }
+    }
+    return { ...metadata, status: causes.length ? 'unmeasured' : 'measured',
+        ...(causes.length ? { cause: causes.join('; ') } : {}), compatible,
+        identification: { status: 'unmeasured', cause: 'finite slices do not certify continuous parameter identification', diagnostics: causes },
+        uncertainty: uncertaintyCause ? { status: 'unmeasured', cause: uncertaintyCause, words } :
+            { status: 'measured', procedure: 'paired-group-bootstrap-regions@1', replicas, words,
+                interpretation: 'empirical replicate regions; not a guaranteed confidence set' } };
+}

package/docs/img/cell.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 178" width="640" height="178" role="img" aria-labelledby="title desc">
+<title id="title">A cell</title>
+<desc id="desc">Two origins on one scale: a claims 2 to 9 and b claims 5 to 12; what they hold together runs from a floor of 5 to a ceiling of 9.</desc>
+<style>
+text{font:14px ui-sans-serif,-apple-system,"Segoe UI",Helvetica,Arial,sans-serif;fill:#59636e}
+.claim{fill:#8c959f}.held{fill:#2da44e}.pole{fill:#2da44e;font-weight:600}.axis,.tick{stroke:#8c959f;stroke-width:1}.touch{stroke:#2da44e;stroke-width:1;stroke-dasharray:3 3}
+@media (prefers-color-scheme:dark){text{fill:#9198a1}}
+</style>
+<line class="touch" x1="269.3" y1="12" x2="269.3" y2="126"/>
+<line class="touch" x1="442.7" y1="12" x2="442.7" y2="126"/>
+<text x="82" y="32" text-anchor="end">a</text>
+<rect class="claim" x="139.3" y="18" width="303.4" height="18" rx="4"/>
+<text x="82" y="66" text-anchor="end">b</text>
+<rect class="claim" x="269.3" y="52" width="303.4" height="18" rx="4"/>
+<text x="82" y="100" text-anchor="end">held</text>
+<rect class="held" x="269.3" y="86" width="173.4" height="18" rx="4"/>
+<line class="axis" x1="96" y1="126" x2="616" y2="126"/>
+<line class="tick" x1="139.3" y1="126" x2="139.3" y2="131"/>
+<text x="139.3" y="148" text-anchor="middle">2</text>
+<line class="tick" x1="269.3" y1="126" x2="269.3" y2="131"/>
+<text x="269.3" y="148" text-anchor="middle">5</text>
+<line class="tick" x1="442.7" y1="126" x2="442.7" y2="131"/>
+<text x="442.7" y="148" text-anchor="middle">9</text>
+<line class="tick" x1="572.7" y1="126" x2="572.7" y2="131"/>
+<text x="572.7" y="148" text-anchor="middle">12</text>
+<text class="pole" x="269.3" y="168" text-anchor="middle">floor</text>
+<text class="pole" x="442.7" y="168" text-anchor="middle">ceiling</text>
+</svg>

package/docs/img/logo-fork.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-labelledby="title">
+<title id="title">2 origins and the bond where they touch</title>
+<path d="M32 17.58 A17 17 0 0 1 32 46.42 A17 17 0 0 1 32 17.58 Z" fill="#cf222e"/>
+<path d="M32 17.58 A17 17 0 1 0 32 46.42" fill="none" stroke="#8c959f" stroke-width="4" stroke-linecap="round"/>
+<path d="M32 17.58 A17 17 0 1 1 32 46.42" fill="none" stroke="#8c959f" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/docs/img/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-labelledby="title">
+<title id="title">2 origins and the bond where they touch</title>
+<path d="M32 17.58 A17 17 0 0 1 32 46.42 A17 17 0 0 1 32 17.58 Z" fill="#2da44e"/>
+<path d="M32 17.58 A17 17 0 1 0 32 46.42" fill="none" stroke="#8c959f" stroke-width="4" stroke-linecap="round"/>
+<path d="M32 17.58 A17 17 0 1 1 32 46.42" fill="none" stroke="#8c959f" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/docs/img/price.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 178" width="640" height="178" role="img" aria-labelledby="title desc">
+<title id="title">A cell</title>
+<desc id="desc">Two origins on one scale: seller claims 2 to 9 and buyer claims 5 to 12; what they hold together runs from a floor of 5 to a ceiling of 9.</desc>
+<style>
+text{font:14px ui-sans-serif,-apple-system,"Segoe UI",Helvetica,Arial,sans-serif;fill:#59636e}
+.claim{fill:#8c959f}.held{fill:#2da44e}.pole{fill:#2da44e;font-weight:600}.axis,.tick{stroke:#8c959f;stroke-width:1}.touch{stroke:#2da44e;stroke-width:1;stroke-dasharray:3 3}
+@media (prefers-color-scheme:dark){text{fill:#9198a1}}
+</style>
+<line class="touch" x1="269.3" y1="12" x2="269.3" y2="126"/>
+<line class="touch" x1="442.7" y1="12" x2="442.7" y2="126"/>
+<text x="82" y="32" text-anchor="end">seller</text>
+<rect class="claim" x="139.3" y="18" width="303.4" height="18" rx="4"/>
+<text x="82" y="66" text-anchor="end">buyer</text>
+<rect class="claim" x="269.3" y="52" width="303.4" height="18" rx="4"/>
+<text x="82" y="100" text-anchor="end">held</text>
+<rect class="held" x="269.3" y="86" width="173.4" height="18" rx="4"/>
+<line class="axis" x1="96" y1="126" x2="616" y2="126"/>
+<line class="tick" x1="139.3" y1="126" x2="139.3" y2="131"/>
+<text x="139.3" y="148" text-anchor="middle">2</text>
+<line class="tick" x1="269.3" y1="126" x2="269.3" y2="131"/>
+<text x="269.3" y="148" text-anchor="middle">5</text>
+<line class="tick" x1="442.7" y1="126" x2="442.7" y2="131"/>
+<text x="442.7" y="148" text-anchor="middle">9</text>
+<line class="tick" x1="572.7" y1="126" x2="572.7" y2="131"/>
+<text x="572.7" y="148" text-anchor="middle">12</text>
+<text class="pole" x="269.3" y="168" text-anchor="middle">floor</text>
+<text class="pole" x="442.7" y="168" text-anchor="middle">ceiling</text>
+</svg>

package/docs/img/thermometer.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 228" width="640" height="228" role="img" aria-labelledby="title desc">
+<title id="title">A cell</title>
+<desc id="desc">Four origins on one scale: a claims 19.8 to 20.2, b claims 19.9 to 20.3, c claims 19.7 to 20.1 and d claims 24 to 24.4; their claims do not meet.</desc>
+<style>
+text{font:14px ui-sans-serif,-apple-system,"Segoe UI",Helvetica,Arial,sans-serif;fill:#59636e}
+.claim{fill:#8c959f}.held{fill:#2da44e}.pole{fill:#2da44e;font-weight:600}.axis,.tick{stroke:#8c959f;stroke-width:1}.touch{stroke:#2da44e;stroke-width:1;stroke-dasharray:3 3}
+@media (prefers-color-scheme:dark){text{fill:#9198a1}}
+</style>
+<text x="82" y="32" text-anchor="end">a</text>
+<rect class="claim" x="181.4" y="18" width="31" height="18" rx="4"/>
+<text x="82" y="66" text-anchor="end">b</text>
+<rect class="claim" x="189.1" y="52" width="31.1" height="18" rx="4"/>
+<text x="82" y="100" text-anchor="end">c</text>
+<rect class="claim" x="173.6" y="86" width="31.1" height="18" rx="4"/>
+<text x="82" y="134" text-anchor="end">d</text>
+<rect class="claim" x="507.3" y="120" width="31.1" height="18" rx="4"/>
+<text x="82" y="168" text-anchor="end">held</text>
+<text x="96" y="168">their claims do not meet</text>
+<line class="axis" x1="96" y1="194" x2="616" y2="194"/>
+<line class="tick" x1="173.6" y1="194" x2="173.6" y2="199"/>
+<text x="173.6" y="216" text-anchor="middle">19.7</text>
+<line class="tick" x1="204.7" y1="194" x2="204.7" y2="199"/>
+<text x="204.7" y="216" text-anchor="middle">20.1</text>
+<line class="tick" x1="507.3" y1="194" x2="507.3" y2="199"/>
+<text x="507.3" y="216" text-anchor="middle">24</text>
+<line class="tick" x1="538.4" y1="194" x2="538.4" y2="199"/>
+<text x="538.4" y="216" text-anchor="middle">24.4</text>
+</svg>

package/docs/img/withdrawal.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 178" width="640" height="178" role="img" aria-labelledby="title desc">
+<title id="title">A cell</title>
+<desc id="desc">Two origins on one scale: a claims 2 to 9 and b claims 5 to 12; what they hold together runs from a floor of 5 to a ceiling of 9.</desc>
+<style>
+text{font:14px ui-sans-serif,-apple-system,"Segoe UI",Helvetica,Arial,sans-serif;fill:#59636e}
+.claim{fill:#8c959f}.held{fill:#2da44e}.pole{fill:#2da44e;font-weight:600}.axis,.tick{stroke:#8c959f;stroke-width:1}.touch{stroke:#2da44e;stroke-width:1;stroke-dasharray:3 3}
+@media (prefers-color-scheme:dark){text{fill:#9198a1}}
+</style>
+<line class="touch" x1="269.3" y1="12" x2="269.3" y2="126"/>
+<line class="touch" x1="442.7" y1="12" x2="442.7" y2="126"/>
+<text x="82" y="32" text-anchor="end">a</text>
+<rect class="claim" x="139.3" y="18" width="303.4" height="18" rx="4"/>
+<text x="82" y="66" text-anchor="end">b</text>
+<rect class="claim" x="269.3" y="52" width="303.4" height="18" rx="4"/>
+<text x="82" y="100" text-anchor="end">held</text>
+<rect class="held" x="269.3" y="86" width="173.4" height="18" rx="4"/>
+<line class="axis" x1="96" y1="126" x2="616" y2="126"/>
+<line class="tick" x1="139.3" y1="126" x2="139.3" y2="131"/>
+<text x="139.3" y="148" text-anchor="middle">2</text>
+<line class="tick" x1="269.3" y1="126" x2="269.3" y2="131"/>
+<text x="269.3" y="148" text-anchor="middle">5</text>
+<line class="tick" x1="442.7" y1="126" x2="442.7" y2="131"/>
+<text x="442.7" y="148" text-anchor="middle">9</text>
+<line class="tick" x1="572.7" y1="126" x2="572.7" y2="131"/>
+<text x="572.7" y="148" text-anchor="middle">12</text>
+<text class="pole" x="269.3" y="168" text-anchor="middle">floor</text>
+<text class="pole" x="442.7" y="168" text-anchor="middle">ceiling</text>
+</svg>

package/docs/learn/in-phase.md

@@ -0,0 +1,46 @@
+# In phase
+
+A claim carries a size and a direction, how much it narrows and the turn it landed on, and a withdrawal is the same size the other way: two hundred claims in phase make the square of their number and the same two hundred strewn make its order, while a write and its withdrawal at one epoch leave nothing and at different epochs do not cancel.
+
+## Run it
+
+```ts
+import { coherence, interfere } from '@lapxo/obligations/views/field';
+
+const span = { lo: 0, hi: 0 };
+let held = 11;
+const next = (): number => { held = (held * 1103515245 + 12345) % 2147483648; return held / 2147483648; };
+const together = Array.from({ length: 32 }, (_, i) => ({ origin: `o${i}`, epoch: 8, span }));
+const strewn = Array.from({ length: 32 }, (_, i) => ({ origin: `o${i}`, epoch: Math.floor(next() * 8), span }));
+
+console.log('in phase  ', interfere(together, 8), 'coherence', coherence(together, 8).toFixed(2));
+console.log('strewn    ', interfere(strewn, 8).toFixed(0), 'coherence', coherence(strewn, 8).toFixed(2));
+console.log('their number is 32, and its square is', 32 ** 2);
+console.log('why       claims that land at one turn of the period add as the square of their number, and the same claims strewn across it add as its order');
+```
+
+```
+in phase   1024 coherence 1.00
+strewn     50 coherence 0.22
+their number is 32, and its square is 1024
+why       claims that land at one turn of the period add as the square of their number, and the same claims strewn across it add as its order
+```
+
+Its origins meet.
+
+## What it rests on
+
+```mermaid
+flowchart LR
+  c0["coherence"]
+  c1["interfere"]
+  l0(["amplitude has sign and phase"])
+  c0 --> l0
+  c1 --> l0
+  classDef shown fill:#2da44e,color:#ffffff,stroke:#2da44e
+  class l0 shown
+```
+
+## Source
+
+[Its source](../../examples/release/in-phase.ts) is one of the examples of obligations, and it runs as it is written, against the built package, with nothing compiled for it.

package/docs/learn/price.md

@@ -0,0 +1,52 @@
+# Price
+
+<p align="center"><img src="../img/price.svg" alt="Two origins on one scale: seller claims 2 to 9 and buyer claims 5 to 12; what they hold together runs from a floor of 5 to a ceiling of 9." width="640"></p>
+
+A claim from one origin is potential; a cell is information only where two independent origins touch it and their intervals meet.
+
+## Run it
+
+```ts
+import { chain, disagree, freedom, meetAt, origins, point, unit } from '@lapxo/obligations';
+
+const said = (cell: Parameters<typeof meetAt>[0]): string =>
+  (origins(cell) < 2 ? 'grey' : disagree(cell) ? 'split' : 'agreed');
+
+const price = point('price', 0, [
+  { origin: 'seller', span: { lo: 2, hi: 9 } },
+  { origin: 'buyer', span: { lo: 5, hi: 12 } },
+]);
+const scale = chain(Array.from({ length: 16 }, (_, i) => `l${i}`));
+
+console.log('verdict   ', said(price));
+console.log('they hold ', JSON.stringify(meetAt(price)));
+console.log('still free', freedom(scale, unit('price', { floor: 'l5', ceiling: 'l9' })).toFixed(2), 'bits');
+console.log('why       a seller and a buyer are two origins; where their marks meet is a price, and what is left between the marks is what nobody has decided yet');
+```
+
+```
+verdict    agreed
+they hold  {"lo":5,"hi":9}
+still free 2.32 bits
+why       a seller and a buyer are two origins; where their marks meet is a price, and what is left between the marks is what nobody has decided yet
+```
+
+Its origins meet.
+
+## What it rests on
+
+```mermaid
+flowchart LR
+  c0["point"]
+  c1["unit"]
+  l0(["encounter"])
+  l1(["debit in bits"])
+  c0 --> l0
+  c1 --> l1
+  classDef shown fill:#2da44e,color:#ffffff,stroke:#2da44e
+  class l0 shown
+```
+
+## Source
+
+[Its source](../../examples/release/price.ts) is one of the examples of obligations, and it runs as it is written, against the built package, with nothing compiled for it.