tallyd 0.0.0-stage → 0.1.0

package/dist/reconcile/scoring.js

@@ -0,0 +1,319 @@
+/**
+ * How good is this match, and why?
+ *
+ * The "why" is not decoration. A reconciliation engine that emits a number and
+ * nothing else leaves a reviewer with two options: trust it blindly, or redo
+ * the work by hand. So every score comes with the rules that produced it, each
+ * carrying its own sub-score and how much it moved the total.
+ *
+ * Two of the rules are gates rather than contributions. A payment that differs
+ * by £40 is not a weak match, it is a different transaction; money in and money
+ * out are not a near miss. Both reject outright, and the caller is told which
+ * gate closed. The remaining rules — date proximity, description similarity,
+ * shared references — are weighted and averaged.
+ *
+ * The reference rule is dropped from the average when neither side carries a
+ * reference at all. Scoring a missing signal as zero would punish every cash
+ * transaction in the book for something it could never have had.
+ */
+import { Money } from "../money/money.js";
+import { daysBetween } from "../ledger/date.js";
+import { similarityBreakdown } from "./similarity.js";
+/**
+ * Amount and date carry most of the weight, and deliberately so. A bank
+ * descriptor and a narration are written by different people for different
+ * purposes; agreeing on the penny and the day is much stronger evidence than
+ * agreeing on the wording, and description is best used to break ties between
+ * candidates that already agree on the numbers.
+ */
+export const DEFAULT_WEIGHTS = Object.freeze({
+    amount: 0.3,
+    date: 0.25,
+    description: 0.3,
+    reference: 0.15,
+    // Level with description, and for a reason that is worth stating: a reviewer
+    // confirming a counterparty is a person asserting the identity the
+    // description rule is guessing at, so it should not count for less than the
+    // guess. It is deliberately not higher. Memory is evidence about *who*, not
+    // about *which transaction* — two payments to the same supplier in one week
+    // are remembered equally well — so it lifts a pair the numbers already agree
+    // on over the auto-accept line and cannot carry one there on its own.
+    memory: 0.3,
+});
+export function resolveScoringOptions(options = {}) {
+    return Object.freeze({
+        dateWindowDays: options.dateWindowDays ?? 7,
+        amountToleranceMinorUnits: options.amountToleranceMinorUnits ?? 0n,
+        weights: Object.freeze({ ...DEFAULT_WEIGHTS, ...(options.weights ?? {}) }),
+        autoAcceptScore: options.autoAcceptScore ?? 0.86,
+        suggestScore: options.suggestScore ?? 0.45,
+        memory: options.memory,
+    });
+}
+const abs = (value) => (value < 0n ? -value : value);
+function formatMinor(minorUnits, amount) {
+    return Money.ofMinor(minorUnits, amount.currency).toDecimalString();
+}
+/**
+ * Date proximity, decaying to zero at the edge of the window.
+ *
+ * The decay is quadratic rather than linear because settlement lag clusters
+ * hard at nought to two days: a three-day gap is much more suspicious than
+ * three times a one-day gap.
+ */
+function dateScore(gap, windowDays) {
+    const distance = Math.abs(gap);
+    if (distance === 0)
+        return 1;
+    if (windowDays <= 0)
+        return 0;
+    const fraction = distance / windowDays;
+    if (fraction >= 1)
+        return 0;
+    return (1 - fraction) ** 2;
+}
+function reject(rule, detail, reasons, dayGap, amountGap) {
+    return Object.freeze({
+        score: 0,
+        confidence: "rejected",
+        reasons: Object.freeze([
+            ...reasons,
+            Object.freeze({ rule, detail, score: 0, weight: 0, contribution: 0 }),
+        ]),
+        rejectedBy: rule,
+        dayGap,
+        amountGap,
+    });
+}
+function scoreSides(sides, resolved) {
+    const reasons = [];
+    const sameCurrency = sides.bookAmount.sameCurrency(sides.statementAmount);
+    const amountGap = sameCurrency
+        ? sides.statementAmount.minorUnits - sides.bookAmount.minorUnits
+        : 0n;
+    const dayGap = daysBetween(sides.bookDate, sides.statementDate);
+    if (!sameCurrency) {
+        return reject("amount", `${sides.bookAmount.currency.code} in the books against ${sides.statementAmount.currency.code} on the statement`, reasons, dayGap, 0n);
+    }
+    // --- gates -------------------------------------------------------------
+    if (abs(amountGap) > resolved.amountToleranceMinorUnits) {
+        return reject("amount", `off by ${formatMinor(amountGap, sides.bookAmount)}`, reasons, dayGap, amountGap);
+    }
+    const bookSign = sides.bookAmount.sign;
+    const statementSign = sides.statementAmount.sign;
+    if (bookSign !== 0 && statementSign !== 0 && bookSign !== statementSign) {
+        return reject("direction", bookSign === 1 ? "money in against money out" : "money out against money in", reasons, dayGap, amountGap);
+    }
+    if (Math.abs(dayGap) > resolved.dateWindowDays) {
+        return reject("date", `${Math.abs(dayGap)} days apart, outside the ${resolved.dateWindowDays} day window`, reasons, dayGap, amountGap);
+    }
+    const tolerance = resolved.amountToleranceMinorUnits;
+    const amountRuleScore = amountGap === 0n || tolerance === 0n
+        ? 1
+        : 1 - Number(abs(amountGap)) / Number(tolerance) / 2;
+    reasons.push(Object.freeze({
+        rule: "amount",
+        detail: amountGap === 0n
+            ? `exact at ${sides.statementAmount.toDecimalString()}`
+            : `within tolerance, off by ${formatMinor(amountGap, sides.bookAmount)}`,
+        score: amountRuleScore,
+        weight: resolved.weights.amount,
+        contribution: amountRuleScore * resolved.weights.amount,
+    }));
+    // --- weighted rules ----------------------------------------------------
+    const dateRuleScore = dateScore(dayGap, resolved.dateWindowDays);
+    reasons.push(Object.freeze({
+        rule: "date",
+        detail: dayGap === 0
+            ? "same day"
+            : `${Math.abs(dayGap)} day${Math.abs(dayGap) === 1 ? "" : "s"} ${dayGap > 0 ? "later" : "earlier"} on the statement`,
+        score: dateRuleScore,
+        weight: resolved.weights.date,
+        contribution: dateRuleScore * resolved.weights.date,
+    }));
+    // Compared on the normalised forms: "DD RENT, AUGUST 08" and "August rent"
+    // are the same event, and only the normalised text makes that visible.
+    const similarity = similarityBreakdown(sides.bookNormalised, sides.statementNormalised);
+    reasons.push(Object.freeze({
+        rule: "description",
+        detail: similarity.sharedTokens.length > 0
+            ? `shares ${similarity.sharedTokens.join(", ")}`
+            : `little in common ("${sides.bookNormalised}" / "${sides.statementNormalised}")`,
+        score: similarity.score,
+        weight: resolved.weights.description,
+        contribution: similarity.score * resolved.weights.description,
+    }));
+    const bookReferenceText = `${sides.bookDescription} ${sides.bookReference ?? ""}`;
+    const statementReferenceText = `${sides.statementDescription} ${sides.statementReference ?? ""}`;
+    const shared = sharedReferenceList(bookReferenceText, statementReferenceText);
+    const eitherHasReference = hasReference(bookReferenceText) || hasReference(statementReferenceText);
+    if (eitherHasReference) {
+        const referenceScore = shared.length > 0 ? 1 : 0;
+        reasons.push(Object.freeze({
+            rule: "reference",
+            detail: shared.length > 0 ? `reference ${shared.join(", ")}` : "references disagree",
+            score: referenceScore,
+            weight: resolved.weights.reference,
+            contribution: referenceScore * resolved.weights.reference,
+        }));
+    }
+    else {
+        reasons.push(Object.freeze({
+            rule: "reference",
+            detail: "neither side carries a reference",
+            score: 0,
+            weight: 0,
+            contribution: 0,
+        }));
+    }
+    // --- what the reviewer already told us ---------------------------------
+    //
+    // Weighted only when there is something to say. A pair involving a
+    // counterparty nobody has ever ruled on should score exactly as it did before
+    // memory existed, so an absent memory contributes nothing and is not averaged
+    // in — the same treatment the reference rule gets when neither side carries
+    // one.
+    const memoryVerdict = resolved.memory?.recall(sides.statementDescription, sides.bookDescription);
+    const remembered = memoryVerdict !== undefined && memoryVerdict.kind !== "unknown";
+    reasons.push(Object.freeze({
+        rule: "memory",
+        detail: memoryVerdict?.detail ?? "nothing remembered about this counterparty",
+        score: memoryVerdict?.score ?? 0,
+        weight: remembered ? resolved.weights.memory : 0,
+        contribution: remembered ? (memoryVerdict?.score ?? 0) * resolved.weights.memory : 0,
+    }));
+    const totalWeight = reasons.reduce((sum, reason) => sum + reason.weight, 0);
+    const averaged = totalWeight === 0 ? 0 : reasons.reduce((sum, reason) => sum + reason.contribution, 0) / totalWeight;
+    const referenceHit = shared.length > 0;
+    // A reviewer who has already refused this pairing outranks the evidence that
+    // would otherwise call it exact. Without this the floor below would restore
+    // the score to 0.95 and the refusal would have changed nothing, which is the
+    // one outcome guaranteed to make somebody stop using the review queue.
+    const vetoed = memoryVerdict?.kind === "rejected" || memoryVerdict?.kind === "contradicted";
+    const exact = !vetoed && amountGap === 0n && dayGap === 0 && (referenceHit || similarity.score >= 0.9);
+    // Same penny, same day, and an external reference both sides agree on is
+    // about as good as reconciliation evidence gets. When all three line up the
+    // wording cannot drag the score down; a bank that writes "SQ *SETTLEMENT
+    // 0805" where we wrote "Processor settlement" has still told us enough.
+    const score = exact ? Math.max(averaged, 0.95) : averaged;
+    let confidence;
+    if (exact)
+        confidence = "exact";
+    else if (score >= resolved.autoAcceptScore)
+        confidence = "high";
+    else if (score >= (resolved.autoAcceptScore + resolved.suggestScore) / 2)
+        confidence = "medium";
+    else if (score >= resolved.suggestScore)
+        confidence = "low";
+    else
+        confidence = "rejected";
+    return Object.freeze({
+        score,
+        confidence,
+        reasons: Object.freeze(reasons),
+        rejectedBy: null,
+        dayGap,
+        amountGap,
+    });
+}
+function hasReference(text) {
+    return /(?:^|[^A-Za-z0-9])[A-Za-z]*\d{3,}/.test(text);
+}
+function sharedReferenceList(left, right) {
+    return similarityBreakdown(left, right).sharedReferences;
+}
+/** Score one ledger movement against one statement line. */
+export function scorePair(book, line, options = {}) {
+    return scoreSides({
+        bookAmount: book.amount,
+        bookDate: book.date,
+        bookDescription: book.description,
+        bookNormalised: book.normalisedDescription,
+        bookReference: book.reference,
+        statementAmount: line.amount,
+        statementDate: line.date,
+        statementDescription: line.description,
+        statementNormalised: line.normalisedDescription,
+        statementReference: line.reference,
+    }, resolveScoringOptions(options));
+}
+/**
+ * Score a group: several ledger movements against several statement lines.
+ *
+ * The group is collapsed to its total, its earliest date, and its descriptions
+ * joined, then scored as though it were a single pair. Joining the text is the
+ * right move rather than a shortcut — a batch payment's bank descriptor often
+ * names one of the invoices in it, and the token-set similarity finds that
+ * inside the joined string.
+ */
+export function scoreGroup(books, lines, options = {}) {
+    if (books.length === 0 || lines.length === 0) {
+        return Object.freeze({
+            score: 0,
+            confidence: "rejected",
+            reasons: Object.freeze([
+                Object.freeze({
+                    rule: "amount",
+                    detail: "a group needs at least one line on each side",
+                    score: 0,
+                    weight: 0,
+                    contribution: 0,
+                }),
+            ]),
+            rejectedBy: "amount",
+            dayGap: 0,
+            amountGap: 0n,
+        });
+    }
+    const resolved = resolveScoringOptions(options);
+    const bookCurrency = books[0].amount.currency;
+    const lineCurrency = lines[0].amount.currency;
+    const bookTotal = books.reduce((sum, book) => sum + book.amount.minorUnits, 0n);
+    const lineTotal = lines.reduce((sum, line) => sum + line.amount.minorUnits, 0n);
+    const earliest = (values) => values.reduce((min, value) => (value < min ? value : min));
+    const scored = scoreSides({
+        bookAmount: Money.ofMinor(bookTotal, bookCurrency),
+        bookDate: earliest(books.map((b) => b.date)),
+        bookDescription: books.map((b) => b.description).join(" "),
+        bookNormalised: books.map((b) => b.normalisedDescription).join(" "),
+        bookReference: books.map((b) => b.reference).filter((r) => r !== null).join(" ") || null,
+        statementAmount: Money.ofMinor(lineTotal, lineCurrency),
+        statementDate: earliest(lines.map((l) => l.date)),
+        statementDescription: lines.map((l) => l.description).join(" "),
+        statementNormalised: lines.map((l) => l.normalisedDescription).join(" "),
+        statementReference: lines.map((l) => l.reference).filter((r) => r !== null).join(" ") || null,
+    }, resolved);
+    if (scored.rejectedBy !== null)
+        return scored;
+    // A group is a weaker claim than a pair — there are more ways to be
+    // accidentally right — so the wider it is, the more the score is discounted.
+    const width = books.length + lines.length;
+    const penalty = 1 - Math.min(0.18, 0.045 * (width - 2));
+    const score = scored.score * penalty;
+    const reasons = [
+        ...scored.reasons,
+        Object.freeze({
+            rule: "amount",
+            detail: `${books.length} ledger ${books.length === 1 ? "entry" : "entries"} against ${lines.length} statement ${lines.length === 1 ? "line" : "lines"}`,
+            score: penalty,
+            weight: 0,
+            contribution: 0,
+        }),
+    ];
+    let confidence = scored.confidence;
+    if (confidence === "exact")
+        confidence = "high";
+    if (score < resolved.suggestScore)
+        confidence = "rejected";
+    else if (score < (resolved.autoAcceptScore + resolved.suggestScore) / 2 && confidence !== "low") {
+        confidence = "low";
+    }
+    return Object.freeze({
+        score,
+        confidence,
+        reasons: Object.freeze(reasons),
+        rejectedBy: null,
+        dayGap: scored.dayGap,
+        amountGap: scored.amountGap,
+    });
+}

package/dist/reconcile/similarity.d.ts

@@ -0,0 +1,88 @@
+/**
+ * How alike are two descriptions?
+ *
+ * The answer has to be graded, not boolean. "FPI ACME LTD — INV1001" and
+ * "Invoice 1001 settled" describe the same event and share almost no
+ * characters; "DD RENT, AUGUST 08" and "DD RENT, JULY 08" differ by one word
+ * and describe different events. A single distance metric gets both of these
+ * wrong, so three signals are combined:
+ *
+ * - character distance, which catches truncation and typos;
+ * - token overlap, which survives reordering and padding words;
+ * - reference tokens (`INV1001`, `SUB9931`), which are worth far more than an
+ *   ordinary word because banks pass them through unchanged.
+ *
+ * Everything here is pure text. Nothing knows about money, dates or matching.
+ */
+/** Split into comparable tokens: uppercase, alphanumeric, no runts. */
+export declare function tokenise(text: string): string[];
+/**
+ * Levenshtein edit distance, two-row DP.
+ *
+ * `maxDistance` turns it into a bounded check: once every cell in a row is
+ * over the ceiling no later row can come back under it, so the walk stops and
+ * returns `maxDistance + 1`. Callers comparing hundreds of pairs care.
+ */
+export declare function levenshtein(a: string, b: string, maxDistance?: number): number;
+/** Edit distance rescaled to `0..1`, where 1 is identical. */
+export declare function levenshteinRatio(a: string, b: string): number;
+/**
+ * Jaro similarity: transposition-aware, and much kinder than edit distance to
+ * strings that agree at the start and diverge later — which is how truncated
+ * bank descriptors fail.
+ */
+export declare function jaro(a: string, b: string): number;
+/**
+ * Jaro-Winkler: Jaro with a bonus for a shared prefix, capped at four
+ * characters. Bank descriptors put the merchant first, so the prefix carries
+ * more signal than the tail.
+ */
+export declare function jaroWinkler(a: string, b: string, prefixWeight?: number): number;
+/**
+ * A token that looks like an external reference rather than a word: it mixes
+ * letters and digits, or is a bare run of digits long enough to be an id.
+ */
+export declare function isReferenceToken(token: string): boolean;
+export declare function referenceTokens(text: string): string[];
+/**
+ * References the two sides agree on.
+ *
+ * Equality is deliberately loose: `INV1001` on our side and `1001` on the
+ * bank's side are the same reference, and one being a suffix of the other is
+ * the normal shape of that disagreement. Digit runs shorter than three are
+ * ignored — too many false hits.
+ */
+export declare function sharedReferences(left: string, right: string): string[];
+/**
+ * Weighted Sørensen-Dice over token sets.
+ *
+ * Weighting by token length is what stops "LTD" counting for as much as
+ * "TOOLCHAIN". Tokens pair up greedily on Jaro-Winkler above a cutoff, so
+ * near-misses ("SALARIES" / "SALARY") land as a partial hit rather than
+ * nothing, and each token can only be spent once — otherwise a description
+ * that says "RENT RENT" would look like a perfect match for "RENT".
+ *
+ * Dividing by the weight of *both* sides rather than the shorter one is what
+ * makes the result symmetric, and it means a two-word descriptor buried inside
+ * a ten-word one scores as the partial agreement it is.
+ */
+export declare function tokenOverlap(left: readonly string[], right: readonly string[]): number;
+export interface SimilarityBreakdown {
+    /** Combined score in `0..1`. */
+    readonly score: number;
+    readonly tokenScore: number;
+    readonly characterScore: number;
+    readonly sharedReferences: readonly string[];
+    readonly sharedTokens: readonly string[];
+}
+/**
+ * Full similarity with the working shown, so a reviewer can see which signal
+ * carried the match.
+ *
+ * A shared reference is treated as near-decisive: it lifts the floor to 0.9
+ * rather than being averaged away by two descriptions that otherwise share no
+ * words at all, which is exactly the "Invoice 1001 settled" case.
+ */
+export declare function similarityBreakdown(left: string, right: string): SimilarityBreakdown;
+/** The combined score alone. */
+export declare function descriptionSimilarity(left: string, right: string): number;

package/dist/reconcile/similarity.js

@@ -0,0 +1,272 @@
+/**
+ * How alike are two descriptions?
+ *
+ * The answer has to be graded, not boolean. "FPI ACME LTD — INV1001" and
+ * "Invoice 1001 settled" describe the same event and share almost no
+ * characters; "DD RENT, AUGUST 08" and "DD RENT, JULY 08" differ by one word
+ * and describe different events. A single distance metric gets both of these
+ * wrong, so three signals are combined:
+ *
+ * - character distance, which catches truncation and typos;
+ * - token overlap, which survives reordering and padding words;
+ * - reference tokens (`INV1001`, `SUB9931`), which are worth far more than an
+ *   ordinary word because banks pass them through unchanged.
+ *
+ * Everything here is pure text. Nothing knows about money, dates or matching.
+ */
+/** Split into comparable tokens: uppercase, alphanumeric, no runts. */
+export function tokenise(text) {
+    return text
+        .toUpperCase()
+        .split(/[^A-Z0-9]+/)
+        .filter((token) => token.length > 0);
+}
+/**
+ * Levenshtein edit distance, two-row DP.
+ *
+ * `maxDistance` turns it into a bounded check: once every cell in a row is
+ * over the ceiling no later row can come back under it, so the walk stops and
+ * returns `maxDistance + 1`. Callers comparing hundreds of pairs care.
+ */
+export function levenshtein(a, b, maxDistance) {
+    if (a === b)
+        return 0;
+    // The ceiling is applied before the trivial cases, so a caller asking "is
+    // this within 2?" gets the same answer shape however the two strings differ.
+    const ceiling = maxDistance ?? Number.POSITIVE_INFINITY;
+    if (Math.abs(a.length - b.length) > ceiling)
+        return Math.floor(ceiling) + 1;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Iterate over the shorter string in the inner loop.
+    const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+    let previous = new Array(short.length + 1);
+    let current = new Array(short.length + 1);
+    for (let j = 0; j <= short.length; j++)
+        previous[j] = j;
+    for (let i = 1; i <= long.length; i++) {
+        current[0] = i;
+        let rowMinimum = i;
+        const longChar = long.charCodeAt(i - 1);
+        for (let j = 1; j <= short.length; j++) {
+            const substitution = previous[j - 1] + (longChar === short.charCodeAt(j - 1) ? 0 : 1);
+            const deletion = previous[j] + 1;
+            const insertion = current[j - 1] + 1;
+            const best = Math.min(substitution, deletion, insertion);
+            current[j] = best;
+            if (best < rowMinimum)
+                rowMinimum = best;
+        }
+        if (rowMinimum > ceiling)
+            return Math.floor(ceiling) + 1;
+        const swap = previous;
+        previous = current;
+        current = swap;
+    }
+    return previous[short.length];
+}
+/** Edit distance rescaled to `0..1`, where 1 is identical. */
+export function levenshteinRatio(a, b) {
+    const longest = Math.max(a.length, b.length);
+    if (longest === 0)
+        return 1;
+    return 1 - levenshtein(a, b) / longest;
+}
+/**
+ * Jaro similarity: transposition-aware, and much kinder than edit distance to
+ * strings that agree at the start and diverge later — which is how truncated
+ * bank descriptors fail.
+ */
+export function jaro(a, b) {
+    if (a === b)
+        return 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const window = Math.max(0, Math.floor(Math.max(a.length, b.length) / 2) - 1);
+    const aMatched = new Array(a.length).fill(false);
+    const bMatched = new Array(b.length).fill(false);
+    let matches = 0;
+    for (let i = 0; i < a.length; i++) {
+        const from = Math.max(0, i - window);
+        const to = Math.min(i + window + 1, b.length);
+        for (let j = from; j < to; j++) {
+            if (bMatched[j] === true)
+                continue;
+            if (a[i] !== b[j])
+                continue;
+            aMatched[i] = true;
+            bMatched[j] = true;
+            matches++;
+            break;
+        }
+    }
+    if (matches === 0)
+        return 0;
+    let transpositions = 0;
+    let k = 0;
+    for (let i = 0; i < a.length; i++) {
+        if (aMatched[i] !== true)
+            continue;
+        while (bMatched[k] !== true)
+            k++;
+        if (a[i] !== b[k])
+            transpositions++;
+        k++;
+    }
+    const half = transpositions / 2;
+    return (matches / a.length + matches / b.length + (matches - half) / matches) / 3;
+}
+/**
+ * Jaro-Winkler: Jaro with a bonus for a shared prefix, capped at four
+ * characters. Bank descriptors put the merchant first, so the prefix carries
+ * more signal than the tail.
+ */
+export function jaroWinkler(a, b, prefixWeight = 0.1) {
+    const base = jaro(a, b);
+    if (base === 0)
+        return 0;
+    let prefix = 0;
+    const limit = Math.min(4, a.length, b.length);
+    while (prefix < limit && a[prefix] === b[prefix])
+        prefix++;
+    return base + prefix * prefixWeight * (1 - base);
+}
+/**
+ * A token that looks like an external reference rather than a word: it mixes
+ * letters and digits, or is a bare run of digits long enough to be an id.
+ */
+export function isReferenceToken(token) {
+    if (token.length < 3)
+        return false;
+    const hasDigit = /[0-9]/.test(token);
+    if (!hasDigit)
+        return false;
+    const hasLetter = /[A-Z]/.test(token);
+    if (hasLetter)
+        return true;
+    return token.length >= 4;
+}
+export function referenceTokens(text) {
+    return tokenise(text).filter(isReferenceToken);
+}
+/** The digits inside a reference, which is the part banks preserve. */
+function digitsOf(token) {
+    return token.replace(/[^0-9]/g, "");
+}
+/**
+ * References the two sides agree on.
+ *
+ * Equality is deliberately loose: `INV1001` on our side and `1001` on the
+ * bank's side are the same reference, and one being a suffix of the other is
+ * the normal shape of that disagreement. Digit runs shorter than three are
+ * ignored — too many false hits.
+ */
+export function sharedReferences(left, right) {
+    const leftRefs = referenceTokens(left);
+    const rightRefs = referenceTokens(right);
+    if (leftRefs.length === 0 || rightRefs.length === 0)
+        return [];
+    const shared = [];
+    for (const l of leftRefs) {
+        for (const r of rightRefs) {
+            if (l === r) {
+                shared.push(l);
+                continue;
+            }
+            const ld = digitsOf(l);
+            const rd = digitsOf(r);
+            if (ld.length >= 3 && rd.length >= 3 && (ld.endsWith(rd) || rd.endsWith(ld))) {
+                // Report the barer of the two spellings, so the same agreement is
+                // named the same way whichever side it is read from.
+                shared.push(l.length <= r.length ? l : r);
+            }
+        }
+    }
+    return [...new Set(shared)].sort();
+}
+const tokenWeight = (token) => Math.min(token.length, 12);
+/**
+ * Weighted Sørensen-Dice over token sets.
+ *
+ * Weighting by token length is what stops "LTD" counting for as much as
+ * "TOOLCHAIN". Tokens pair up greedily on Jaro-Winkler above a cutoff, so
+ * near-misses ("SALARIES" / "SALARY") land as a partial hit rather than
+ * nothing, and each token can only be spent once — otherwise a description
+ * that says "RENT RENT" would look like a perfect match for "RENT".
+ *
+ * Dividing by the weight of *both* sides rather than the shorter one is what
+ * makes the result symmetric, and it means a two-word descriptor buried inside
+ * a ten-word one scores as the partial agreement it is.
+ */
+export function tokenOverlap(left, right) {
+    if (left.length === 0 || right.length === 0)
+        return 0;
+    // Iterate the shorter side, breaking ties canonically so that swapping the
+    // arguments cannot change the greedy pairing.
+    const leftFirst = left.length < right.length ||
+        (left.length === right.length && left.join(" ") <= right.join(" "));
+    const [shorter, longer] = leftFirst ? [left, right] : [right, left];
+    const taken = new Array(longer.length).fill(false);
+    let matched = 0;
+    for (const token of shorter) {
+        let bestScore = 0;
+        let bestIndex = -1;
+        for (let i = 0; i < longer.length; i++) {
+            if (taken[i] === true)
+                continue;
+            const score = jaroWinkler(token, longer[i]);
+            if (score > bestScore) {
+                bestScore = score;
+                bestIndex = i;
+            }
+        }
+        if (bestIndex >= 0 && bestScore >= 0.82) {
+            taken[bestIndex] = true;
+            matched += Math.min(tokenWeight(token), tokenWeight(longer[bestIndex])) * bestScore;
+        }
+    }
+    const total = left.reduce((sum, t) => sum + tokenWeight(t), 0) +
+        right.reduce((sum, t) => sum + tokenWeight(t), 0);
+    return total === 0 ? 0 : Math.min(1, (2 * matched) / total);
+}
+/**
+ * Full similarity with the working shown, so a reviewer can see which signal
+ * carried the match.
+ *
+ * A shared reference is treated as near-decisive: it lifts the floor to 0.9
+ * rather than being averaged away by two descriptions that otherwise share no
+ * words at all, which is exactly the "Invoice 1001 settled" case.
+ */
+export function similarityBreakdown(left, right) {
+    const leftTokens = tokenise(left);
+    const rightTokens = tokenise(right);
+    if (leftTokens.length === 0 || rightTokens.length === 0) {
+        return Object.freeze({
+            score: 0,
+            tokenScore: 0,
+            characterScore: 0,
+            sharedReferences: Object.freeze([]),
+            sharedTokens: Object.freeze([]),
+        });
+    }
+    const tokenScore = tokenOverlap(leftTokens, rightTokens);
+    const characterScore = jaroWinkler(leftTokens.join(" "), rightTokens.join(" "));
+    const refs = sharedReferences(left, right);
+    const shared = leftTokens.filter((t) => rightTokens.includes(t));
+    let score = 0.65 * tokenScore + 0.35 * characterScore;
+    if (refs.length > 0)
+        score = Math.max(score, 0.9);
+    return Object.freeze({
+        score: Math.min(1, score),
+        tokenScore,
+        characterScore,
+        sharedReferences: Object.freeze(refs),
+        sharedTokens: Object.freeze([...new Set(shared)].sort()),
+    });
+}
+/** The combined score alone. */
+export function descriptionSimilarity(left, right) {
+    return similarityBreakdown(left, right).score;
+}