@crewhaus/tool-money 0.7.0 → 0.8.1

package/dist/lib/controls.js

@@ -2,14 +2,18 @@
  * Spending controls and refund-abuse signals.
  *
  * An unattended harness that can move money needs a limit it cannot talk
- * itself past. A limit a model is asked to respect is a suggestion; a limit
- * computed from the record of what has already been spent is a limit.
+ * itself past, and a function cannot be that limit on its own: it computes
+ * over the history, limits and clock it is handed. When a model hands them
+ * over, the verdict is advisory. It is a control only where those inputs come
+ * from a record the model cannot edit, and a limit that must hold belongs in
+ * the policy of whatever actually moves the money.
  *
  * Both functions take the history as an argument and the clock as a
  * parameter. Nothing here reads a database or the time, so the same facts
  * always give the same verdict — which is what makes a refusal explicable
  * afterwards.
  */
+import { addExact, mathRound, sumExact, toNumber } from "./exact";
 function instant(value, what) {
     if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value.trim())) {
         throw new Error(`${what} ("${value}") has no UTC offset`);
@@ -25,21 +29,21 @@ const WEEK = 7 * DAY;
 export function checkSpendLimit(proposed, history, limits, nowMs) {
     const entries = history.map((s) => ({ ...s, atMs: instant(s.at, `spend "${s.id}" at`) }));
     const since = (ms) => entries.filter((e) => nowMs - e.atMs < ms && e.atMs <= nowMs);
-    const sum = (list) => list.reduce((t, e) => t + e.amountMinor, 0);
+    const sum = (list, what) => sumExact(list.map((e) => e.amountMinor), what);
     const hour = since(HOUR);
     const day = since(DAY);
     const week = since(WEEK);
     const windows = {
-        hourMinor: sum(hour),
-        dayMinor: sum(day),
-        weekMinor: sum(week),
+        hourMinor: sum(hour, "the spend in the last hour"),
+        dayMinor: sum(day, "the spend in the last day"),
+        weekMinor: sum(week, "the spend in the last week"),
         hourCount: hour.length,
     };
     const violations = [];
     const check = (name, cap, spent) => {
         if (cap === undefined)
             return;
-        const wouldBe = spent + proposed.amountMinor;
+        const wouldBe = addExact(spent, proposed.amountMinor, `the ${name} spend with this payment`);
         if (wouldBe > cap) {
             violations.push({
                 limit: name,
@@ -62,7 +66,7 @@ export function checkSpendLimit(proposed, history, limits, nowMs) {
     check("perDay", limits.perDayMinor, windows.dayMinor);
     check("perWeek", limits.perWeekMinor, windows.weekMinor);
     if (limits.perCounterpartyPerDayMinor !== undefined && proposed.counterparty !== undefined) {
-        const spent = sum(day.filter((e) => e.counterparty === proposed.counterparty));
+        const spent = sum(day.filter((e) => e.counterparty === proposed.counterparty), "the spend to this counterparty in the last day");
         check(`perCounterpartyPerDay:${proposed.counterparty}`, limits.perCounterpartyPerDayMinor, spent);
     }
     if (limits.maxTransactionsPerHour !== undefined &&
@@ -116,11 +120,12 @@ export function checkSpendLimit(proposed, history, limits, nowMs) {
     }
     // Headroom is the tightest remaining amount limit, which is the number a
     // caller needs to propose something that would pass.
+    const room = (cap, spent, what) => cap === undefined ? undefined : addExact(cap, -spent, what);
     const caps = [
         limits.perTransactionMinor,
-        limits.perHourMinor === undefined ? undefined : limits.perHourMinor - windows.hourMinor,
-        limits.perDayMinor === undefined ? undefined : limits.perDayMinor - windows.dayMinor,
-        limits.perWeekMinor === undefined ? undefined : limits.perWeekMinor - windows.weekMinor,
+        room(limits.perHourMinor, windows.hourMinor, "the hourly headroom"),
+        room(limits.perDayMinor, windows.dayMinor, "the daily headroom"),
+        room(limits.perWeekMinor, windows.weekMinor, "the weekly headroom"),
     ].filter((v) => v !== undefined);
     return {
         allowed: violations.length === 0,
@@ -141,8 +146,8 @@ export function refundAbuseSignals(refunds, orders, nowMs, thresholds = {}) {
         const cutoff = nowMs - days * DAY;
         const r = refunds.filter((x) => instant(x.at, `refund "${x.id}" at`) >= cutoff);
         const o = orders.filter((x) => instant(x.at, `order "${x.id}" at`) >= cutoff);
-        const refundedMinor = r.reduce((s, x) => s + x.amountMinor, 0);
-        const spentMinor = o.reduce((s, x) => s + x.amountMinor, 0);
+        const refundedMinor = sumExact(r.map((x) => x.amountMinor), `the refunds in ${days} days`);
+        const spentMinor = sumExact(o.map((x) => x.amountMinor), `the orders in ${days} days`);
         return {
             days,
             refunds: r.length,
@@ -151,7 +156,9 @@ export function refundAbuseSignals(refunds, orders, nowMs, thresholds = {}) {
             spentMinor,
             // Undefined rather than infinite when nothing was spent: a ratio
             // against zero is not a large number, it is not a number.
-            ratioBps: spentMinor === 0 ? null : Math.round((refundedMinor * 10_000) / spentMinor),
+            ratioBps: spentMinor === 0
+                ? null
+                : toNumber(mathRound(BigInt(refundedMinor) * 10000n, BigInt(spentMinor)), `the ${days}-day refund ratio`),
         };
     });
     const flags = [];

package/dist/lib/exact.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Exact integer money in a language whose numbers are doubles.
+ *
+ * A double holds every integer up to 2^53 − 1 (9,007,199,254,740,991) and
+ * then starts skipping them. An amount past that arrives already rounded, and
+ * a sum or a product that crosses it rounds without saying so: [2^53 − 1, 2]
+ * totalled 9,007,199,254,740,992, and a tax of 19.99% on 1,595,908,809,793,069
+ * came out a unit high because the product `amount × bps` was past the line
+ * even though the amount and the answer were not.
+ *
+ * So the arithmetic is done in `bigint`, where it is exact, and a figure goes
+ * back into a JSON number only when it fits. One that does not is refused,
+ * by name — a tool whose whole job is the exact figure does not hand back an
+ * approximate one.
+ */
+/** Why a figure was refused rather than reported. */
+export declare class InexactAmountError extends Error {
+    readonly name = "InexactAmountError";
+}
+/** An input amount, as a bigint. It must be a safe integer: past that it arrived rounded. */
+export declare function big(value: number, what: string): bigint;
+/** A result, back as a JSON number — or a refusal when it does not fit exactly. */
+export declare function toNumber(value: bigint, what: string): number;
+/** The exact sum of integer amounts. */
+export declare function sumExact(values: Iterable<number>, what: string): number;
+/** `a` combined with `b` exactly, for a sum or difference of two amounts. */
+export declare function addExact(a: number, b: number, what: string): number;
+/** Floor division (bigint division truncates toward zero; this rounds toward −∞). */
+export declare function floorDiv(a: bigint, b: bigint): bigint;
+/**
+ * `num / den` rounded the way `Math.round` rounds — to the nearest integer,
+ * a half toward +∞ — but exactly, however large the operands.
+ */
+export declare function mathRound(num: bigint, den: bigint): bigint;
+/**
+ * A quantity as the decimal it is written as: `units / 10^scale`, exactly.
+ *
+ * Quantities (kilograms, hours, 0.37 of a coin) are decimals, and a double
+ * cannot hold most of them: 2.3 × 1001 is 2302.2999999999997 in binary. So a
+ * quantity is read as the SHORTEST text that reads back as the same double —
+ * which is the decimal the caller wrote (0.1, 1e-7, 10000000000) — and
+ * counted as a bigint on a decimal scale, where sums, differences and
+ * products with an integer price are exact however many digits they carry.
+ */
+export type Decimal = {
+    readonly units: bigint;
+    readonly scale: number;
+};
+export declare function decimalOf(value: number, what: string): Decimal;
+/** `d`'s units on a finer (or equal) `scale`. */
+export declare function atScale(d: Decimal, scale: number): bigint;
+/** The exact sum (or, with `sign` −1, difference) of two decimals. */
+export declare function addDecimal(a: Decimal, b: Decimal, sign?: 1n | -1n): Decimal;
+/** Negative, zero or positive as `a` is below, equal to or above `b`. */
+export declare function compareDecimal(a: Decimal, b: Decimal): number;
+/**
+ * A decimal back as a JSON number — or a refusal when no double is exactly
+ * it. A quantity is reported as a number, and one that would come back as a
+ * different decimal (1234567890123457 − 0.1) is refused by name rather than
+ * reported off by what the double could not hold.
+ */
+export declare function decimalNumber(d: Decimal, what: string): number;
+/**
+ * `num / den` rounded to whole minor units: to the nearest, a half away from
+ * zero, exactly. A fractional quantity times an integer price is a fraction
+ * of a minor unit; this is how it becomes a whole one.
+ */
+export declare function roundHalfAwayFromZero(num: bigint, den: bigint): bigint;

package/dist/lib/exact.js

@@ -0,0 +1,122 @@
+/**
+ * Exact integer money in a language whose numbers are doubles.
+ *
+ * A double holds every integer up to 2^53 − 1 (9,007,199,254,740,991) and
+ * then starts skipping them. An amount past that arrives already rounded, and
+ * a sum or a product that crosses it rounds without saying so: [2^53 − 1, 2]
+ * totalled 9,007,199,254,740,992, and a tax of 19.99% on 1,595,908,809,793,069
+ * came out a unit high because the product `amount × bps` was past the line
+ * even though the amount and the answer were not.
+ *
+ * So the arithmetic is done in `bigint`, where it is exact, and a figure goes
+ * back into a JSON number only when it fits. One that does not is refused,
+ * by name — a tool whose whole job is the exact figure does not hand back an
+ * approximate one.
+ */
+/** Why a figure was refused rather than reported. */
+export class InexactAmountError extends Error {
+    name = "InexactAmountError";
+}
+const LIMIT_TEXT = "2^53 − 1 (9007199254740991)";
+/** An input amount, as a bigint. It must be a safe integer: past that it arrived rounded. */
+export function big(value, what) {
+    if (!Number.isSafeInteger(value)) {
+        throw new InexactAmountError(`${what} (${value}) is not an integer within ±${LIMIT_TEXT}, the largest amount this computes exactly — express it in a larger unit`);
+    }
+    return BigInt(value);
+}
+/** A result, back as a JSON number — or a refusal when it does not fit exactly. */
+export function toNumber(value, what) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+        throw new InexactAmountError(`${what} comes to ${value}, past ±${LIMIT_TEXT}, so it cannot be reported exactly as a number — express the amounts in a larger unit`);
+    }
+    return Number(value);
+}
+/** The exact sum of integer amounts. */
+export function sumExact(values, what) {
+    let total = 0n;
+    for (const value of values)
+        total += big(value, what);
+    return toNumber(total, what);
+}
+/** `a` combined with `b` exactly, for a sum or difference of two amounts. */
+export function addExact(a, b, what) {
+    return toNumber(big(a, what) + big(b, what), what);
+}
+/** Floor division (bigint division truncates toward zero; this rounds toward −∞). */
+export function floorDiv(a, b) {
+    const q = a / b;
+    return a % b !== 0n && a < 0n !== b < 0n ? q - 1n : q;
+}
+/**
+ * `num / den` rounded the way `Math.round` rounds — to the nearest integer,
+ * a half toward +∞ — but exactly, however large the operands.
+ */
+export function mathRound(num, den) {
+    if (den === 0n)
+        throw new Error("denominator must not be zero");
+    const [n, d] = den < 0n ? [-num, -den] : [num, den];
+    return floorDiv(2n * n + d, 2n * d);
+}
+export function decimalOf(value, what) {
+    const match = /^(-?)(\d+)(?:\.(\d+))?(?:e([+-]\d+))?$/.exec(String(value));
+    if (match === null)
+        throw new InexactAmountError(`${what} (${value}) is not a finite decimal`);
+    const fraction = match[3] ?? "";
+    let digits = `${match[2]}${fraction}`;
+    let scale = fraction.length - Number(match[4] ?? 0);
+    if (scale < 0) {
+        digits += "0".repeat(-scale);
+        scale = 0;
+    }
+    const units = BigInt(digits);
+    return { units: match[1] === "-" ? -units : units, scale };
+}
+/** `d`'s units on a finer (or equal) `scale`. */
+export function atScale(d, scale) {
+    return d.units * 10n ** BigInt(scale - d.scale);
+}
+/** The exact sum (or, with `sign` −1, difference) of two decimals. */
+export function addDecimal(a, b, sign = 1n) {
+    const scale = Math.max(a.scale, b.scale);
+    return { units: atScale(a, scale) + sign * atScale(b, scale), scale };
+}
+/** Negative, zero or positive as `a` is below, equal to or above `b`. */
+export function compareDecimal(a, b) {
+    const scale = Math.max(a.scale, b.scale);
+    const left = atScale(a, scale);
+    const right = atScale(b, scale);
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * A decimal back as a JSON number — or a refusal when no double is exactly
+ * it. A quantity is reported as a number, and one that would come back as a
+ * different decimal (1234567890123457 − 0.1) is refused by name rather than
+ * reported off by what the double could not hold.
+ */
+export function decimalNumber(d, what) {
+    const negative = d.units < 0n;
+    const magnitude = (negative ? -d.units : d.units).toString();
+    const text = d.scale === 0
+        ? magnitude
+        : `${magnitude.padStart(d.scale + 1, "0").slice(0, -d.scale)}.${magnitude
+            .padStart(d.scale + 1, "0")
+            .slice(-d.scale)}`;
+    const value = Number(`${negative ? "-" : ""}${text}`);
+    if (!Number.isFinite(value) || compareDecimal(decimalOf(value, what), d) !== 0) {
+        throw new InexactAmountError(`${what} comes to ${negative ? "-" : ""}${text}, which a JSON number cannot hold exactly — express the quantities in a coarser unit`);
+    }
+    return value === 0 ? 0 : value;
+}
+/**
+ * `num / den` rounded to whole minor units: to the nearest, a half away from
+ * zero, exactly. A fractional quantity times an integer price is a fraction
+ * of a minor unit; this is how it becomes a whole one.
+ */
+export function roundHalfAwayFromZero(num, den) {
+    if (den === 0n)
+        throw new Error("denominator must not be zero");
+    const [n, d] = den < 0n ? [-num, -den] : [num, den];
+    const magnitude = (2n * (n < 0n ? -n : n) + d) / (2n * d);
+    return n < 0n ? -magnitude : magnitude;
+}

package/dist/lib/lots.d.ts

@@ -11,6 +11,13 @@
  * as an integer remainder and the final consumption takes whatever is left,
  * so a fully consumed lot always accounts for exactly its cost with no
  * rounding drift.
+ *
+ * Quantities are counted as exact decimals, not as doubles. Each is read as
+ * the decimal it is written as (0.1 is one tenth, not the binary fraction
+ * nearest it), and every lot and disposal is scaled to the same number of
+ * decimal places as a bigint. So ten disposals of 0.1 leave nothing of a lot
+ * of 1, and five units left of a lot of ten billion stay five units — where a
+ * tolerance for binary noise would have to guess which remainders are real.
  */
 export declare const LOT_METHODS: readonly ["fifo", "lifo", "hifo", "specific"];
 export type LotMethod = (typeof LOT_METHODS)[number];

package/dist/lib/lots.js

@@ -11,9 +11,59 @@
  * as an integer remainder and the final consumption takes whatever is left,
  * so a fully consumed lot always accounts for exactly its cost with no
  * rounding drift.
+ *
+ * Quantities are counted as exact decimals, not as doubles. Each is read as
+ * the decimal it is written as (0.1 is one tenth, not the binary fraction
+ * nearest it), and every lot and disposal is scaled to the same number of
+ * decimal places as a bigint. So ten disposals of 0.1 leave nothing of a lot
+ * of 1, and five units left of a lot of ten billion stay five units — where a
+ * tolerance for binary noise would have to guess which remainders are real.
  */
+import { addExact, big, decimalOf, mathRound, sumExact, toNumber } from "./exact";
 export const LOT_METHODS = ["fifo", "lifo", "hifo", "specific"];
 const YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+/*
+ * A disposal may come up short of the lots by up to 1e-9 units and still be
+ * read as consuming them: a caller's own float sum (0.1 + 0.2 is
+ * 0.30000000000000004) is not a claim to hold more than was bought.
+ */
+/** `units / 10^scale` back as a number: the double nearest the exact decimal. */
+function quantityNumber(units, scale) {
+    if (scale === 0)
+        return Number(units);
+    const negative = units < 0n;
+    const text = (negative ? -units : units).toString().padStart(scale + 1, "0");
+    const value = Number(`${text.slice(0, -scale)}.${text.slice(-scale)}`);
+    return negative ? -value : value;
+}
+/**
+ * Move `heap[at]` down past every child taken before it. `before(a, b)` is
+ * negative when `a` is taken first; no two lots tie.
+ */
+function siftDown(heap, at, before) {
+    const item = heap[at];
+    let i = at;
+    for (;;) {
+        const left = 2 * i + 1;
+        if (left >= heap.length)
+            break;
+        const right = left + 1;
+        const first = right < heap.length && before(heap[right], heap[left]) < 0 ? right : left;
+        if (before(heap[first], item) >= 0)
+            break;
+        heap[i] = heap[first];
+        i = first;
+    }
+    heap[i] = item;
+}
+/** Drop the top of the heap. */
+function popTop(heap, before) {
+    const last = heap.pop();
+    if (heap.length === 0)
+        return;
+    heap[0] = last;
+    siftDown(heap, 0, before);
+}
 function instant(value, what) {
     if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value.trim())) {
         throw new Error(`${what} ("${value}") has no UTC offset — an offset-less timestamp means local time and would put a holding period on the wrong side of a year boundary depending on the machine`);
@@ -33,87 +83,133 @@ export function computeCostBasis(lots, disposals, method) {
             throw new Error(`lot "${lot.id}" has quantity ${lot.quantity}`);
         if (!Number.isInteger(lot.costMinor))
             throw new Error(`lot "${lot.id}" cost must be minor units`);
+        big(lot.costMinor, `lot "${lot.id}" costMinor`);
         instant(lot.acquiredAt, `lot "${lot.id}" acquiredAt`);
     }
+    for (const disposal of disposals) {
+        if (disposal.quantity <= 0) {
+            throw new Error(`disposal "${disposal.id}" has quantity ${disposal.quantity}`);
+        }
+    }
+    // Every quantity on one decimal scale, so each subtraction is exact.
+    const quantities = [
+        ...lots.map((l) => decimalOf(l.quantity, `lot "${l.id}" quantity`)),
+        ...disposals.map((d) => decimalOf(d.quantity, `disposal "${d.id}" quantity`)),
+    ];
+    const scale = quantities.reduce((most, q) => Math.max(most, q.scale), 0);
+    const scaled = (value, what) => {
+        const q = decimalOf(value, what);
+        return q.units * 10n ** BigInt(scale - q.scale);
+    };
+    // SHORTFALL_TOLERANCE on this scale; nothing when the scale is coarser.
+    const shortfallAllowed = scale >= 9 ? 10n ** BigInt(scale - 9) : 0n;
     // Working copies: remaining cost is an integer so a lot cannot drift.
     const open = lots.map((lot) => ({
         ...lot,
-        remainingQuantity: lot.quantity,
+        remainingUnits: scaled(lot.quantity, `lot "${lot.id}" quantity`),
         remainingCostMinor: lot.costMinor,
         acquiredMs: instant(lot.acquiredAt, "acquiredAt"),
     }));
     const results = [];
+    const byId = (a, b) => (a.id < b.id ? -1 : 1);
+    const takenBefore = method === "fifo"
+        ? (a, b) => a.acquiredMs - b.acquiredMs || byId(a, b)
+        : method === "lifo"
+            ? (a, b) => b.acquiredMs - a.acquiredMs || byId(a, b)
+            : method === "hifo"
+                ? (a, b) => {
+                    // Highest cost per unit first, which realizes the smallest
+                    // gain — compared by cross-multiplying, so two lots a float
+                    // would call equal are still told apart.
+                    const left = BigInt(b.remainingCostMinor) * a.remainingUnits;
+                    const right = BigInt(a.remainingCostMinor) * b.remainingUnits;
+                    return left > right ? 1 : left < right ? -1 : byId(a, b);
+                }
+                : undefined;
+    // The open lots as a binary heap in that order, the next lot to take at
+    // the top. A disposal takes lots off the top; the only lot whose place can
+    // change is the one it took part of (its cost per unit moves by the
+    // rounding of that part), and that one is sifted to where it now belongs.
+    // Re-sorting every open lot for every disposal made HIFO quadratic in the
+    // lots at the schema's limit, and so did moving the part-taken lot within
+    // a sorted list: rounding can send it from the front to the back. A list
+    // sorted once is already a heap.
+    const heap = takenBefore === undefined ? [] : [...open].sort(takenBefore);
+    // Every lot by its id, built once, for the specific method. A lot is open
+    // while it has units left; that is read at lookup, where an index of the
+    // open lots rebuilt for every disposal cost the lots times the disposals.
+    const lotById = new Map(method === "specific" ? open.map((lot) => [lot.id, lot]) : []);
     for (const disposal of disposals) {
         const disposedMs = instant(disposal.disposedAt, `disposal "${disposal.id}" disposedAt`);
-        if (disposal.quantity <= 0) {
-            throw new Error(`disposal "${disposal.id}" has quantity ${disposal.quantity}`);
-        }
-        let order = open.filter((l) => l.remainingQuantity > 0);
+        let named = [];
         if (method === "specific") {
             const wanted = disposal.lotIds;
             if (!wanted || wanted.length === 0) {
                 throw new Error(`disposal "${disposal.id}" uses the specific-identification method but names no lots`);
             }
-            const index = new Map(order.map((l) => [l.id, l]));
-            order = wanted.map((id) => {
-                const lot = index.get(id);
-                if (!lot) {
+            named = wanted.map((id) => {
+                const lot = lotById.get(id);
+                if (lot === undefined || lot.remainingUnits <= 0n) {
                     throw new Error(`disposal "${disposal.id}" names lot "${id}", which is not open`);
                 }
                 return lot;
             });
         }
-        else if (method === "fifo") {
-            order = [...order].sort((a, b) => a.acquiredMs - b.acquiredMs || (a.id < b.id ? -1 : 1));
-        }
-        else if (method === "lifo") {
-            order = [...order].sort((a, b) => b.acquiredMs - a.acquiredMs || (a.id < b.id ? -1 : 1));
-        }
-        else {
-            // Highest cost per unit first, which realizes the smallest gain.
-            order = [...order].sort((a, b) => b.remainingCostMinor / b.remainingQuantity - a.remainingCostMinor / a.remainingQuantity ||
-                (a.id < b.id ? -1 : 1));
-        }
-        let toConsume = disposal.quantity;
+        const disposalUnits = scaled(disposal.quantity, `disposal "${disposal.id}" quantity`);
+        let toConsume = disposalUnits;
         const consumed = [];
         let costMinor = 0;
-        for (const lot of order) {
-            if (toConsume <= 0)
+        // The named lots in turn, or the top of the heap until the disposal is
+        // met: a lot taken whole leaves the heap, and the one taken in part is
+        // sifted down from the top to its new place.
+        for (let at = 0; toConsume > 0n; at++) {
+            const lot = takenBefore === undefined ? named[at] : heap[0];
+            if (lot === undefined)
                 break;
-            const take = Math.min(toConsume, lot.remainingQuantity);
             // Taking the whole remainder consumes the whole remaining cost. That
             // is what keeps a lot's costs summing to exactly what it cost, however
             // many partial disposals came before.
-            const takeCost = take === lot.remainingQuantity
+            const whole = toConsume >= lot.remainingUnits;
+            const take = whole ? lot.remainingUnits : toConsume;
+            const takeCost = whole
                 ? lot.remainingCostMinor
-                : Math.round((lot.remainingCostMinor * take) / lot.remainingQuantity);
-            lot.remainingQuantity -= take;
-            lot.remainingCostMinor -= takeCost;
+                : toNumber(mathRound(BigInt(lot.remainingCostMinor) * take, lot.remainingUnits), `disposal "${disposal.id}" cost`);
+            lot.remainingUnits -= take;
+            lot.remainingCostMinor = addExact(lot.remainingCostMinor, -takeCost, `lot "${lot.id}" remaining cost`);
             toConsume -= take;
-            costMinor += takeCost;
+            costMinor = addExact(costMinor, takeCost, `disposal "${disposal.id}" cost`);
             consumed.push({
                 lotId: lot.id,
-                quantity: take,
+                quantity: quantityNumber(take, scale),
+                units: take,
                 costMinor: takeCost,
                 acquiredAt: lot.acquiredAt,
                 longTerm: disposedMs - lot.acquiredMs > YEAR_MS,
             });
+            if (takenBefore !== undefined) {
+                if (lot.remainingUnits === 0n)
+                    popTop(heap, takenBefore);
+                else
+                    siftDown(heap, 0, takenBefore);
+            }
         }
-        if (toConsume > 1e-9) {
-            throw new Error(`disposal "${disposal.id}" needs ${disposal.quantity} but only ${disposal.quantity - toConsume} was open — a disposal cannot exceed the lots held`);
+        if (toConsume > shortfallAllowed) {
+            throw new Error(`disposal "${disposal.id}" needs ${disposal.quantity} but only ${quantityNumber(disposalUnits - toConsume, scale)} was open — a disposal cannot exceed the lots held`);
         }
         // Proceeds follow the units, so the split between short and long term is
         // allocated by quantity rather than by cost.
-        const gainMinor = disposal.proceedsMinor - costMinor;
-        let longTermProceeds = 0;
-        let longTermCost = 0;
+        const what = `disposal "${disposal.id}"`;
+        const proceeds = big(disposal.proceedsMinor, `${what} proceedsMinor`);
+        const gainMinor = toNumber(proceeds - big(costMinor, what), `${what} gain`);
+        let longTermProceeds = 0n;
+        let longTermCost = 0n;
         for (const entry of consumed) {
             if (!entry.longTerm)
                 continue;
-            longTermProceeds += Math.round((disposal.proceedsMinor * entry.quantity) / disposal.quantity);
-            longTermCost += entry.costMinor;
+            longTermProceeds += mathRound(proceeds * entry.units, disposalUnits);
+            longTermCost += big(entry.costMinor, what);
         }
-        const longTermGainMinor = longTermProceeds - longTermCost;
+        const longTermGainMinor = toNumber(longTermProceeds - longTermCost, `${what} long-term gain`);
         results.push({
             id: disposal.id,
             quantity: disposal.quantity,
@@ -121,22 +217,22 @@ export function computeCostBasis(lots, disposals, method) {
             costMinor,
             gainMinor,
             longTermGainMinor,
-            shortTermGainMinor: gainMinor - longTermGainMinor,
-            consumed,
+            shortTermGainMinor: addExact(gainMinor, -longTermGainMinor, `${what} short-term gain`),
+            consumed: consumed.map(({ units: _units, ...entry }) => entry),
         });
     }
-    const remaining = open.filter((l) => l.remainingQuantity > 0);
+    const remaining = open.filter((l) => l.remainingUnits > 0n);
     return {
         method,
         disposals: results,
-        realizedGainMinor: results.reduce((s, r) => s + r.gainMinor, 0),
+        realizedGainMinor: sumExact(results.map((r) => r.gainMinor), "the realized gain"),
         remainingLots: remaining.map((l) => ({
             id: l.id,
             acquiredAt: l.acquiredAt,
-            quantity: l.remainingQuantity,
+            quantity: quantityNumber(l.remainingUnits, scale),
             costMinor: l.remainingCostMinor,
         })),
-        remainingQuantity: remaining.reduce((s, l) => s + l.remainingQuantity, 0),
-        remainingCostMinor: remaining.reduce((s, l) => s + l.remainingCostMinor, 0),
+        remainingQuantity: quantityNumber(remaining.reduce((sum, l) => sum + l.remainingUnits, 0n), scale),
+        remainingCostMinor: sumExact(remaining.map((l) => l.remainingCostMinor), "the remaining cost"),
     };
 }

package/dist/lib/match.d.ts

@@ -38,7 +38,11 @@ export type MatchPair = {
     readonly poQuantity: number;
     readonly receivedQuantity: number | null;
     readonly quantityDelta: number;
-    /** What the variance costs, positive when the invoice asks for more. */
+    /**
+     * What the variance costs, positive when the invoice asks for more. With a
+     * fractional quantity (kilograms, hours) the figure is rounded to whole
+     * minor units, half away from zero.
+     */
     readonly exposureMinor: number;
     readonly reasons: ReadonlyArray<string>;
 };