@crewhaus/tool-money 0.7.0 → 0.8.0

package/dist/lib/allocate.js

@@ -9,6 +9,7 @@
  * Largest-remainder allocation fixes that by construction: the shares always
  * sum to the total, exactly, whatever the weights.
  */
+import { big, toNumber } from "./exact";
 /**
  * Split `totalMinor` across `weights` so the parts sum to it exactly.
  *
@@ -20,33 +21,43 @@
 export function allocateProportional(totalMinor, weights) {
     if (!Number.isInteger(totalMinor))
         throw new Error("totalMinor must be an integer");
+    if (weights.some((w) => w < 0))
+        throw new Error("weights must not be negative");
+    return allocateExact(big(totalMinor, "totalMinor"), weights.map((w, i) => big(w, `weight ${i}`))).map((part, i) => toNumber(part, `share ${i}`));
+}
+/**
+ * {@link allocateProportional} in exact integers. Each share's exact value is
+ * a quotient and a remainder over the weights' sum, so the largest remainders
+ * are compared exactly: a double's `magnitude × weight` passes 2^53 on an
+ * ordinary invoice's cents times its lines' values.
+ */
+export function allocateExact(total, weights) {
     if (weights.length === 0)
         return [];
-    if (weights.some((w) => w < 0))
+    if (weights.some((w) => w < 0n))
         throw new Error("weights must not be negative");
-    const sum = weights.reduce((a, b) => a + b, 0);
-    const negative = totalMinor < 0;
-    const magnitude = Math.abs(totalMinor);
-    if (sum === 0) {
+    const sum = weights.reduce((a, b) => a + b, 0n);
+    const negative = total < 0n;
+    const magnitude = negative ? -total : total;
+    const count = BigInt(weights.length);
+    if (sum === 0n) {
         // Nothing to weigh by. Spread evenly rather than returning zeros, which
         // would drop the amount entirely.
-        const base = Math.floor(magnitude / weights.length);
-        const parts = weights.map(() => base);
-        let leftover = magnitude - base * weights.length;
-        for (let i = 0; leftover > 0; i = (i + 1) % weights.length, leftover--) {
-            parts[i] = parts[i] + 1;
-        }
+        const base = magnitude / count;
+        const leftover = magnitude - base * count;
+        const parts = weights.map((_, i) => (BigInt(i) < leftover ? base + 1n : base));
         return negative ? parts.map((p) => -p) : parts;
     }
-    const exact = weights.map((w) => (magnitude * w) / sum);
-    const parts = exact.map((value) => Math.floor(value));
-    let leftover = magnitude - parts.reduce((a, b) => a + b, 0);
-    const order = exact
-        .map((value, index) => ({ index, remainder: value - Math.floor(value) }))
-        .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
-    for (let i = 0; leftover > 0; i++, leftover--) {
-        const target = order[i % order.length]?.index;
-        parts[target] = parts[target] + 1;
+    const parts = weights.map((w) => (magnitude * w) / sum);
+    const leftover = magnitude - parts.reduce((a, b) => a + b, 0n);
+    // The leftover is smaller than the number of shares, so it goes one unit
+    // each to the largest remainders, ties broken by position.
+    const order = weights
+        .map((w, index) => ({ index, remainder: (magnitude * w) % sum }))
+        .sort((a, b) => a.remainder === b.remainder ? a.index - b.index : a.remainder > b.remainder ? -1 : 1);
+    for (let i = 0n; i < leftover; i++) {
+        const target = order[Number(i) % order.length]?.index;
+        parts[target] = parts[target] + 1n;
     }
     return negative ? parts.map((p) => -p) : parts;
 }
@@ -72,36 +83,55 @@ export function computeRefund(lines, returned, options = {}) {
             throw new Error(`returned line "${item.lineId}" returns ${item.quantity} of ${line.quantity} ordered`);
         }
     }
+    // Exact throughout (see ./exact): a line's value is quantity × price, and
+    // the allocations multiply amounts by values again.
+    const unitPrice = (l) => big(l.unitPriceMinor, `line "${l.id}" unitPriceMinor`);
+    const lineGross = (l) => big(l.quantity, `line "${l.id}" quantity`) * unitPrice(l);
     // The order discount is spread over ALL lines by their net value, then the
     // returned fraction of each line's share comes back. Spreading it over the
     // returned lines only would refund the whole discount on a partial return.
-    const lineNet = lines.map((l) => l.quantity * l.unitPriceMinor - (l.discountMinor ?? 0));
-    const orderDiscountShares = allocateProportional(options.orderDiscountMinor ?? 0, lineNet);
+    const lineNet = lines.map((l) => lineGross(l) - big(l.discountMinor ?? 0, `line "${l.id}" discountMinor`));
+    if (lineNet.some((net) => net < 0n))
+        throw new Error("weights must not be negative");
+    const orderDiscountShares = allocateExact(big(options.orderDiscountMinor ?? 0, "orderDiscountMinor"), lineNet);
     const shareByLine = new Map(lines.map((l, i) => [l.id, orderDiscountShares[i]]));
     const results = [];
+    let subtotal = 0n;
+    let taxTotal = 0n;
     for (const item of returned) {
         const line = index.get(item.lineId);
-        const fraction = [item.quantity, line.quantity];
-        const gross = line.unitPriceMinor * item.quantity;
-        const lineDiscount = splitByQuantity(line.discountMinor ?? 0, fraction);
-        const orderDiscount = splitByQuantity(shareByLine.get(line.id) ?? 0, fraction);
-        const tax = splitByQuantity(line.taxMinor ?? 0, fraction);
+        const fraction = [BigInt(item.quantity), BigInt(line.quantity)];
+        const gross = unitPrice(line) * BigInt(item.quantity);
+        const lineDiscount = splitByQuantity(big(line.discountMinor ?? 0, "discountMinor"), fraction);
+        const orderDiscount = splitByQuantity(shareByLine.get(line.id) ?? 0n, fraction);
+        const tax = splitByQuantity(big(line.taxMinor ?? 0, "taxMinor"), fraction);
+        subtotal += gross - lineDiscount - orderDiscount;
+        taxTotal += tax;
+        const what = `returned line "${line.id}"`;
         results.push({
             lineId: line.id,
             quantity: item.quantity,
-            grossMinor: gross,
-            lineDiscountMinor: lineDiscount,
-            orderDiscountMinor: orderDiscount,
-            taxMinor: tax,
-            refundMinor: gross - lineDiscount - orderDiscount + tax,
+            grossMinor: toNumber(gross, `${what} gross`),
+            lineDiscountMinor: toNumber(lineDiscount, `${what} line discount`),
+            orderDiscountMinor: toNumber(orderDiscount, `${what} order discount`),
+            taxMinor: toNumber(tax, `${what} tax`),
+            refundMinor: toNumber(gross - lineDiscount - orderDiscount + tax, `${what} refund`),
         });
     }
-    const fullReturn = lines.every((l) => (returned.find((r) => r.lineId === l.id)?.quantity ?? 0) === l.quantity);
+    // The quantity returned of each line, by id: the first entry naming it, as
+    // a search of the returned lines finds. Searching them once per order line
+    // cost the lines times the returned lines.
+    const returnedOf = new Map();
+    for (const item of returned) {
+        if (!returnedOf.has(item.lineId))
+            returnedOf.set(item.lineId, item.quantity);
+    }
+    const fullReturn = lines.every((l) => (returnedOf.get(l.id) ?? 0) === l.quantity);
     const policy = options.shippingPolicy ?? "none";
-    const shippingTotal = options.shippingMinor ?? 0;
-    let shippingMinor = 0;
+    const shippingTotal = big(options.shippingMinor ?? 0, "shippingMinor");
+    let shipping = 0n;
     if (policy === "full" || (policy === "proportional" && fullReturn)) {
-        shippingMinor = shippingTotal;
+        shipping = shippingTotal;
     }
     else if (policy === "proportional") {
         // Spread the shipping over EVERY line by its value, then take only the
@@ -109,24 +139,25 @@ export function computeRefund(lines, returned, options = {}) {
         // and summing the parts gives back the whole amount every time — an
         // allocation's parts always sum to what was allocated — so a one-item
         // return refunded the entire shipping charge.
-        const shares = allocateProportional(shippingTotal, lines.map((l) => l.quantity * l.unitPriceMinor));
-        shippingMinor = lines.reduce((total, line, i) => {
-            const returnedQuantity = returned.find((r) => r.lineId === line.id)?.quantity ?? 0;
+        const shares = allocateExact(shippingTotal, lines.map(lineGross));
+        lines.forEach((line, i) => {
+            const returnedQuantity = returnedOf.get(line.id) ?? 0;
             if (returnedQuantity === 0)
-                return total;
-            return total + splitByQuantity(shares[i], [returnedQuantity, line.quantity]);
-        }, 0);
+                return;
+            shipping += splitByQuantity(shares[i], [
+                BigInt(returnedQuantity),
+                BigInt(line.quantity),
+            ]);
+        });
     }
-    const subtotalMinor = results.reduce((s, r) => s + r.grossMinor - r.lineDiscountMinor - r.orderDiscountMinor, 0);
-    const taxMinor = results.reduce((s, r) => s + r.taxMinor, 0);
-    const restockingFeeMinor = options.restockingFeeMinor ?? 0;
+    const restocking = big(options.restockingFeeMinor ?? 0, "restockingFeeMinor");
     return {
         lines: results,
-        shippingMinor,
-        restockingFeeMinor,
-        subtotalMinor,
-        taxMinor,
-        totalMinor: subtotalMinor + taxMinor + shippingMinor - restockingFeeMinor,
+        shippingMinor: toNumber(shipping, "the refunded shipping"),
+        restockingFeeMinor: toNumber(restocking, "the restocking fee"),
+        subtotalMinor: toNumber(subtotal, "the refund subtotal"),
+        taxMinor: toNumber(taxTotal, "the refunded tax"),
+        totalMinor: toNumber(subtotal + taxTotal + shipping - restocking, "the refund total"),
         fullReturn,
     };
 }
@@ -137,9 +168,18 @@ export function computeRefund(lines, returned, options = {}) {
  * than multiplying by a fraction and rounding — is what makes the parts of a
  * fully returned line add back up to the whole.
  */
-function splitByQuantity(amountMinor, [returned, total]) {
-    if (total <= 0 || amountMinor === 0)
-        return 0;
-    const perUnit = allocateProportional(amountMinor, new Array(total).fill(1));
-    return perUnit.slice(0, returned).reduce((a, b) => a + b, 0);
+function splitByQuantity(amount, [returned, total]) {
+    if (total <= 0n || amount === 0n)
+        return 0n;
+    // The per-unit allocation of `amount` over `total` equal units, summed over
+    // the first `returned` of them — in closed form. Every unit gets the same
+    // floor share and the leftover goes one unit each to the first ones (equal
+    // remainders break ties by position). 0.7.0 built that array of `total`
+    // units, so a line with a quantity in the millions allocated millions.
+    const negative = amount < 0n;
+    const magnitude = negative ? -amount : amount;
+    const base = magnitude / total;
+    const leftover = magnitude - base * total;
+    const part = returned * base + (returned < leftover ? returned : leftover);
+    return negative ? -part : part;
 }

package/dist/lib/coding.d.ts

@@ -10,7 +10,7 @@
  * Conditions are `@crewhaus/tool-schema`'s check grammar, the same one
  * `Assert` and `Branch` use.
  */
-import { type Check } from "@crewhaus/tool-schema";
+import { type Check, RegexAnswers, type RegexRunContext } from "@crewhaus/tool-schema";
 export type CodingRule = {
     readonly id: string;
     readonly when: ReadonlyArray<Check>;
@@ -31,6 +31,13 @@ export type CodedLine = {
     readonly ambiguous: boolean;
     readonly needsReview: boolean;
     readonly reason: string;
+    /**
+     * Rules whose conditions could not be evaluated on this line (a pattern
+     * that could not be run to an answer, or one refused as invalid), when
+     * any could have decided it. The line then goes to review uncoded: a
+     * rule that might have matched is not a rule that did not.
+     */
+    readonly undetermined?: ReadonlyArray<string>;
 };
 export type CodingResult = {
     readonly lines: ReadonlyArray<CodedLine>;
@@ -42,9 +49,44 @@ export type CodingResult = {
         readonly lines: number;
     }>;
 };
-export declare function codeLines(lines: ReadonlyArray<{
-    readonly id: string;
-} & Record<string, unknown>>, rules: ReadonlyArray<CodingRule>, options?: {
+type CodeOptions = {
     readonly version?: string;
     readonly defaultAccount?: string;
+};
+export declare function codeLines(lines: ReadonlyArray<{
+    readonly id: string;
+} & Record<string, unknown>>, rules: ReadonlyArray<CodingRule>, options?: CodeOptions & {
+    /**
+     * The rules' `matches` patterns, answered in the regex worker (see
+     * tool-schema's `askCheckPatterns`). Without it they run bounded on this
+     * thread. {@link codeLinesAnsweringPatterns} asks and answers them.
+     */
+    readonly regex?: RegexAnswers;
 }): CodingResult;
+/**
+ * {@link codeLines} with the rules' patterns answered in the regex worker, a
+ * chunk of lines at a time.
+ *
+ * One `RegexAnswers` takes at most tool-schema's `MAX_PATTERN_QUESTIONS`
+ * distinct pattern questions and answers any past that as undetermined. A
+ * line asks one per pattern condition, so 5 000 lines under 201 one-pattern
+ * rules — well inside the schema's 5 000 lines and 1 000 rules — asked more,
+ * and every line past the cap went to review uncoded where 0.7.0 coded it
+ * (bounds review). So the lines are cut into chunks that cannot ask more
+ * than the cap (`maxQuestions`, for tests), each asked, answered and coded
+ * in turn.
+ *
+ * The patterns share one budget, counted only while they run: tool-schema's
+ * `CALLER_PATTERN_DEADLINE_MS` per chunk, for at most
+ * {@link MAX_BUDGETED_CHUNKS} chunks (`deadlineMs` overrides it). Lines
+ * reached after it ran out, or after the call was cancelled, are not asked
+ * about: their pattern conditions are undetermined, and they go to review.
+ */
+export declare function codeLinesAnsweringPatterns(lines: ReadonlyArray<{
+    readonly id: string;
+} & Record<string, unknown>>, rules: ReadonlyArray<CodingRule>, options?: CodeOptions & {
+    readonly run?: RegexRunContext;
+    readonly deadlineMs?: number;
+    readonly maxQuestions?: number;
+}): Promise<CodingResult>;
+export {};

package/dist/lib/coding.js

@@ -10,8 +10,54 @@
  * Conditions are `@crewhaus/tool-schema`'s check grammar, the same one
  * `Assert` and `Branch` use.
  */
-import { runChecks } from "@crewhaus/tool-schema";
-export function codeLines(lines, rules, options = {}) {
+import { CALLER_PATTERN_DEADLINE_MS, MAX_PATTERN_QUESTIONS, RegexAnswers, askCheckPatterns, runChecks, testPatternSync, } from "@crewhaus/tool-schema";
+/**
+ * Whether `check` gets as far as running its pattern on `line`: its path
+ * resolves to a string. Asked of the evaluator itself (tool-schema's
+ * `askCheckPatterns` asks exactly the questions `runChecks` will), so the
+ * two cannot disagree.
+ */
+function reachesPattern(line, check) {
+    const probe = new RegexAnswers();
+    askCheckPatterns(line, [check], probe);
+    return probe.pending > 0;
+}
+/**
+ * Whether `rule` holds for `line`, three ways. A condition whose pattern
+ * could not be run to an answer is undetermined, and so is one whose
+ * pattern the screen refused: the rule is malformed, and reading it as "did
+ * not match" let a lower-priority rule code the line (C073). A condition
+ * that definitely failed still decides the rule, and so does one that fails
+ * before its pattern would run — the field is absent, or not a string — as
+ * it did on 0.7.0, whatever the pattern (bounds review).
+ */
+function ruleVerdict(line, rule, regex, refused) {
+    const report = runChecks(line, rule.when, regex === undefined ? {} : { regex });
+    if (report.ok)
+        return { verdict: "pass" };
+    const open = [];
+    for (const failure of report.failures) {
+        const check = rule.when[failure.index];
+        if (failure.undetermined === true) {
+            open.push(failure.reason);
+            continue;
+        }
+        const refusal = refused(check);
+        if (refusal !== undefined && reachesPattern(line, check))
+            open.push(refusal);
+        else
+            return { verdict: "fail" };
+    }
+    return { verdict: "undetermined", reason: open.join("; ") };
+}
+/** Blocking rules a review reason names with their reasons; the rest are counted. */
+const NAMED_IN_REASON = 3;
+/**
+ * Validate the rules once, and return the screen's verdict per pattern: a
+ * refused pattern is refused whatever it is run on, so each is screened
+ * once, on the empty string.
+ */
+function prepareRules(rules) {
     const seen = new Set();
     for (const rule of rules) {
         if (rule.when.length === 0) {
@@ -21,47 +67,182 @@ export function codeLines(lines, rules, options = {}) {
             throw new Error(`two rules share the id "${rule.id}"`);
         seen.add(rule.id);
     }
-    const results = [];
-    for (const line of lines) {
-        const matches = rules
-            .filter((rule) => runChecks(line, rule.when).ok)
-            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-        if (matches.length === 0) {
-            results.push({
-                lineId: line.id,
-                account: options.defaultAccount ?? null,
-                costCenter: null,
-                taxCode: null,
-                matched: [],
-                ambiguous: false,
-                // A default account is a place to put it, not a coding decision, so
-                // the line still goes to review rather than quietly landing in a
-                // suspense account nobody looks at.
-                needsReview: true,
-                reason: "no rule matched",
-            });
-            continue;
+    const refusals = new Map();
+    return (check) => {
+        if (check.op !== "matches" && check.op !== "notMatches")
+            return undefined;
+        if (typeof check.expected !== "string")
+            return undefined;
+        const flags = check.flags ?? "";
+        const key = `${flags}\u0000${check.expected}`;
+        if (!refusals.has(key)) {
+            const answer = testPatternSync(check.expected, flags, "");
+            refusals.set(key, typeof answer === "object" && "refused" in answer
+                ? `invalid regex /${check.expected}/${flags}: ${answer.refused}`
+                : undefined);
+        }
+        return refusals.get(key);
+    };
+}
+export function codeLines(lines, rules, options = {}) {
+    const refused = prepareRules(rules);
+    return summarize(lines.map((line) => codeLine(line, rules, options.regex, refused, options.defaultAccount)), options.version);
+}
+/** Answers every question as undetermined, for lines reached after the pattern budget ran out. */
+class Unanswered extends RegexAnswers {
+    why;
+    constructor(why) {
+        super();
+        this.why = why;
+    }
+    lookup() {
+        return { undetermined: this.why };
+    }
+}
+/**
+ * Chunks whose patterns get tool-schema's per-call budget each, at most: a
+ * batch of benign patterns is answered in full up to the schema's limits,
+ * and a runaway pattern costs a worker thirty seconds at worst (0.7.0 ran
+ * the same batch on the caller's thread with no bound at all).
+ */
+const MAX_BUDGETED_CHUNKS = 6;
+/**
+ * {@link codeLines} with the rules' patterns answered in the regex worker, a
+ * chunk of lines at a time.
+ *
+ * One `RegexAnswers` takes at most tool-schema's `MAX_PATTERN_QUESTIONS`
+ * distinct pattern questions and answers any past that as undetermined. A
+ * line asks one per pattern condition, so 5 000 lines under 201 one-pattern
+ * rules — well inside the schema's 5 000 lines and 1 000 rules — asked more,
+ * and every line past the cap went to review uncoded where 0.7.0 coded it
+ * (bounds review). So the lines are cut into chunks that cannot ask more
+ * than the cap (`maxQuestions`, for tests), each asked, answered and coded
+ * in turn.
+ *
+ * The patterns share one budget, counted only while they run: tool-schema's
+ * `CALLER_PATTERN_DEADLINE_MS` per chunk, for at most
+ * {@link MAX_BUDGETED_CHUNKS} chunks (`deadlineMs` overrides it). Lines
+ * reached after it ran out, or after the call was cancelled, are not asked
+ * about: their pattern conditions are undetermined, and they go to review.
+ */
+export async function codeLinesAnsweringPatterns(lines, rules, options = {}) {
+    const refused = prepareRules(rules);
+    let perLine = 0;
+    for (const rule of rules) {
+        for (const check of rule.when) {
+            if ((check.op === "matches" || check.op === "notMatches") &&
+                typeof check.expected === "string") {
+                perLine += 1;
+            }
+        }
+    }
+    const cap = Math.max(1, options.maxQuestions ?? MAX_PATTERN_QUESTIONS);
+    const perChunk = perLine === 0 ? lines.length : Math.max(1, Math.floor(cap / perLine));
+    const chunks = Math.max(1, Math.ceil(lines.length / Math.max(1, perChunk)));
+    const size = Math.max(1, Math.ceil(lines.length / chunks));
+    const budgetMs = options.deadlineMs ?? CALLER_PATTERN_DEADLINE_MS * Math.min(chunks, MAX_BUDGETED_CHUNKS);
+    const run = options.run ?? {};
+    let spent = 0;
+    const coded = [];
+    for (let from = 0; from < lines.length; from += size) {
+        const chunk = lines.slice(from, from + size);
+        const left = Math.floor(budgetMs - spent);
+        let regex;
+        if (perLine > 0 && run.signal?.aborted === true) {
+            regex = new Unanswered("the call was cancelled before this line's patterns could run");
         }
-        const top = matches[0];
-        const topPriority = top.priority ?? 0;
-        const tied = matches.filter((r) => (r.priority ?? 0) === topPriority);
-        // Two rules at the same priority disagreeing is a rule-set bug. Picking
-        // one would hide it, and the wrong account is found in an audit, not in
-        // a test.
-        const conflicting = tied.some((r) => r.account !== top.account);
-        results.push({
+        else if (perLine > 0 && left < 1) {
+            regex = new Unanswered(`the call's ${budgetMs} ms for running patterns ran out before this line's could run`);
+        }
+        else {
+            regex = new RegexAnswers();
+            if (perLine > 0) {
+                for (const line of chunk) {
+                    for (const rule of rules)
+                        askCheckPatterns(line, rule.when, regex);
+                }
+                const began = performance.now();
+                await regex.resolve(run, { deadlineMs: left });
+                spent += performance.now() - began;
+            }
+        }
+        for (const line of chunk) {
+            coded.push(codeLine(line, rules, regex, refused, options.defaultAccount));
+        }
+    }
+    return summarize(coded, options.version);
+}
+function codeLine(line, rules, regex, refused, defaultAccount) {
+    const verdicts = rules.map((rule) => ({
+        rule,
+        ...ruleVerdict(line, rule, regex, refused),
+    }));
+    const matches = verdicts
+        .filter((v) => v.verdict === "pass")
+        .map((v) => v.rule)
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    // A rule that could not be evaluated decides nothing, but it could have:
+    // when it would outrank (or tie) whatever did match, or when nothing
+    // did, the line is not coded.
+    const bar = matches.length === 0 ? Number.NEGATIVE_INFINITY : (matches[0]?.priority ?? 0);
+    const blocking = verdicts.filter((v) => v.verdict === "undetermined" && (v.rule.priority ?? 0) >= bar);
+    if (blocking.length > 0) {
+        // A few named with their reasons; every one is in `undetermined`. A
+        // batch whose patterns all went unanswered would otherwise repeat a
+        // reason per rule on every line.
+        const shown = blocking.slice(0, NAMED_IN_REASON).map((v) => `"${v.rule.id}" (${v.reason})`);
+        const more = blocking.length - shown.length;
+        const named = more > 0 ? `${shown.join(", ")} and ${more} more (see undetermined)` : shown.join(", ");
+        return {
             lineId: line.id,
-            account: conflicting ? null : top.account,
-            costCenter: conflicting ? null : (top.costCenter ?? null),
-            taxCode: conflicting ? null : (top.taxCode ?? null),
+            account: null,
+            costCenter: null,
+            taxCode: null,
             matched: matches.map((r) => r.id),
-            ambiguous: conflicting,
-            needsReview: conflicting,
-            reason: conflicting
-                ? `rules ${tied.map((r) => `"${r.id}"`).join(", ")} match at the same priority and disagree on the account`
-                : "",
-        });
+            ambiguous: false,
+            needsReview: true,
+            reason: matches.length === 0
+                ? `no rule definitely matched, and these could not be evaluated: ${named}`
+                : `rule "${matches[0].id}" matched, but these could not be evaluated and would outrank or tie it: ${named}`,
+            undetermined: blocking.map((v) => v.rule.id),
+        };
     }
+    if (matches.length === 0) {
+        return {
+            lineId: line.id,
+            account: defaultAccount ?? null,
+            costCenter: null,
+            taxCode: null,
+            matched: [],
+            ambiguous: false,
+            // A default account is a place to put it, not a coding decision, so
+            // the line still goes to review rather than quietly landing in a
+            // suspense account nobody looks at.
+            needsReview: true,
+            reason: "no rule matched",
+        };
+    }
+    const top = matches[0];
+    const topPriority = top.priority ?? 0;
+    const tied = matches.filter((r) => (r.priority ?? 0) === topPriority);
+    // Two rules at the same priority disagreeing is a rule-set bug. Picking
+    // one would hide it, and the wrong account is found in an audit, not in
+    // a test.
+    const conflicting = tied.some((r) => r.account !== top.account);
+    return {
+        lineId: line.id,
+        account: conflicting ? null : top.account,
+        costCenter: conflicting ? null : (top.costCenter ?? null),
+        taxCode: conflicting ? null : (top.taxCode ?? null),
+        matched: matches.map((r) => r.id),
+        ambiguous: conflicting,
+        needsReview: conflicting,
+        reason: conflicting
+            ? `rules ${tied.map((r) => `"${r.id}"`).join(", ")} match at the same priority and disagree on the account`
+            : "",
+    };
+}
+function summarize(results, version) {
     const tally = new Map();
     for (const line of results) {
         if (line.account === null || line.needsReview)
@@ -72,7 +253,7 @@ export function codeLines(lines, rules, options = {}) {
         lines: results,
         coded: results.filter((l) => !l.needsReview).length,
         needsReview: results.filter((l) => l.needsReview).length,
-        version: options.version ?? null,
+        version: version ?? null,
         byAccount: [...tally.entries()]
             .map(([account, count]) => ({ account, lines: count }))
             .sort((a, b) => b.lines - a.lines || (a.account < b.account ? -1 : 1)),

package/dist/lib/controls.d.ts

@@ -2,8 +2,11 @@
  * 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