Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

42.6 KB
Raw Blame
"""Deciding which expectation a movement of money settles.

**This module decides and never writes.** It touches no session, loads
nothing, and returns a decision plus the reasoning that produced it.
Applying that decision (creating an allocation, or upgrading a
placeholder in place) belongs to the caller, and is deliberately a
separate step: a function that mutates cannot be dry-run, and "show me
what would happen before it happens" is the whole point of putting this
in front of a person.

## What an expectation is

An invoice and a scheduled recurring occurrence are the same thing seen
from here: **a promise that money will move, waiting for the movement
that confirms it.** A workspace that never issues an invoice still has
promises (the rent leaving on the 5th, the retainer arriving on the
20th), and they want matching for exactly the same reason.

So both arrive here as an `Expectation` and are scored by the same
signals. What they do *not* share is what happens afterwards, and that
difference is real rather than cosmetic:

  - An invoice link is **N:N with an amount**, and both rows survive: one
    payout settles a dozen invoices net of fees.
  - A recurring occurrence is **1:1**, and the placeholder *is* the
    transaction: the real charge replaces it in place, so there is only
    ever one row.

Forcing those into one "apply" would produce a function with a mode
switch and two half-truths. They stay apart; only the decision is shared.

## Ports, not a boolean

`linked` · `suggested` · `unmatched`. The direction for automations is a
node graph rather than a bigger predicate builder, so this is shaped as a
node from the first line: named outputs, and a trace saying which
strategy fired and why the others did not.
"""
from __future__ import annotations

import uuid
import itertools
from dataclasses import dataclass, field
from datetime import date
from decimal import ROUND_DOWN, Decimal
from enum import Enum
from typing import Any, Literal, Optional

from app.services.text_similarity import names_account, token_overlap

#: What the decision came out of. Named rather than boolean so a node
#: graph can wire each one somewhere different later.
Port = Literal["linked", "suggested", "unmatched"]

#: Which kind of promise a candidate is. The engine treats them alike;
#: the caller uses this to pick how to apply the decision.
#:
#: `transaction` is the odd one and worth naming: the other two are
#: promises somebody wrote down, while this one is the other leg of a
#: transfer, which is a promise only by implication. Money leaving one
#: account **is** the expectation that the same money arrives in another,
#: so the leg is carried here with its direction flipped: a debit of 100
#: is an expectation of a credit of 100. That flip is what lets the
#: direction check below go on meaning what it says instead of needing a
#: mode for transfers.
ExpectationKind = Literal["invoice", "recurring", "transaction"]

#: **Which way round the match is being made.** Matching happens at two
#: different moments and they are not the same question.
#:
#:   - `money_arrives`: a payment lands and we look for the promise it
#:     answers. The promise came first and was waiting.
#:   - `invoice_issued`: a document is written and we look back at money
#:     that arrived before it existed: the client who pays and lets the
#:     nota follow.
#:
#: The evidence is weaker in the second: money that was already sitting
#: there had a life of its own, and might have been a refund or another
#: job. So a rule says which moments it is willing to run in, and that
#: choice is on the page rather than buried in whichever function happens
#: to be doing the looking.
Trigger = Literal["money_arrives", "invoice_issued", "both"]


class Reason(str, Enum):
    """Why a strategy did not fire, in words a UI can show.

    A rejected candidate is more useful than a silent one: "no strategy
    matched" tells a person nothing, while "the amount was right and the
    date was eleven days outside the window" tells them what to change.
    """

    DIRECTION = "direction_differs"
    CURRENCY = "currency_differs"
    COUNTERPARTY = "different_counterparty"
    #: Both legs are on the same account, so nothing moved between
    #: accounts. Its own reason rather than `COUNTERPARTY`, because a
    #: person reading a transfer's trace is asking about accounts and
    #: being told "different counterparty" would send them looking at
    #: payees.
    SAME_ACCOUNT = "same_account"
    #: Neither side's text names the other side's account, and this rule
    #: only trusts a pair that says where it is going.
    ACCOUNT_NOT_NAMED = "neither_description_names_the_other_account"
    #: The rule was written for legs on a particular kind of account (a
    #: credit card, typically) and neither of these is one.
    ACCOUNT_TYPE = "account_type_not_covered"
    #: It fitted, and another candidate fitted the same way while sitting
    #: closer in time. Not a failure of this pair so much as a statement
    #: that a better one was available, and worth saying in those words:
    #: *rejected* would send somebody looking for what was wrong with it.
    FURTHER_IN_TIME = "another_candidate_is_closer_in_time"
    AMOUNT = "amount_outside_tolerance"
    DATE = "date_outside_window"
    DESCRIPTION = "description_too_different"
    ALREADY_SETTLED = "nothing_left_to_settle"
    AMBIGUOUS = "several_candidates_matched"
    SOURCE_IGNORED = "transaction_source_ignored"
    #: The rule does not apply to this money at all: wrong account, wrong
    #: currency, outside the amount band, text that does not match. Kept
    #: apart from the comparison reasons above because it answers a
    #: different question: not "why did this pair fail" but "why was this
    #: rule not even consulted".
    OUT_OF_SCOPE = "rule_does_not_apply_here"
    #: The rule runs at the other moment: when money arrives rather than
    #: when a document is written, or the reverse.
    WRONG_MOMENT = "rule_runs_at_another_moment"
    #: More than one combination of promises adds up to this payment, and
    #: they are equally good. A person picks.
    AMBIGUOUS_SET = "several_combinations_add_up"
    #: Too many promises are open to work out which combination this
    #: payment covers without guessing.
    TOO_MANY_TO_COMBINE = "too_many_candidates_to_combine"


@dataclass(frozen=True)
class Movement:
    """The money that actually moved, reduced to what matching needs.

    Built from a `Transaction` by the caller. A value object rather than
    the ORM row so this module stays pure and trivially testable, and so
    a future intake that is not a `Transaction` (a gateway payout line,
    say) can be scored without pretending to be one.
    """

    amount: Decimal
    currency: str
    #: `credit` (money in) or `debit` (money out).
    direction: str
    when: date
    description: Optional[str] = None
    #: The counterparty exactly as the bank printed it, before anything of
    #: ours resolved it to a person. Kept apart from `payee_id` because a
    #: rule may need it long before the name has been mapped to anybody:
    #: a Pix description is generic and the payer's name arrives in its
    #: own field, so a rule that could only read `description` could not
    #: express "the transfers that come from this company", which is the
    #: identifying fact on the most common inflow there is.
    counterparty: Optional[str] = None
    payee_id: Optional[uuid.UUID] = None
    account_id: Optional[uuid.UUID] = None
    #: What the account is called, and what kind it is. Only transfer
    #: matching reads them, and it needs both: the name because the one
    #: signal that reliably tells two same-amount transfers apart is a
    #: description naming where the money went, and the kind because a
    #: leg on a credit card deserves a different answer from a leg
    #: between two checking accounts.
    account_name: Optional[str] = None
    account_type: Optional[str] = None
    #: `sync`, `ofx`, `csv`, `manual`, `recurring`. A policy may ignore
    #: some: the receivable node ignores `recurring`, because a
    #: generated placeholder is a promise and not the money itself.
    source: Optional[str] = None


@dataclass(frozen=True)
class Expectation:
    """A promise of money moving, waiting to be confirmed.

    `amount` is what is **still outstanding**, never the original total:
    an invoice half paid expects the other half, and matching it against
    its full value would miss every second instalment.
    """

    kind: ExpectationKind
    id: uuid.UUID
    amount: Decimal
    currency: str
    direction: str
    when: date
    description: Optional[str] = None
    #: As printed by the bank, when this expectation is itself a
    #: statement line. The identifying words land in whichever of the two
    #: fields the bank felt like using, so a signal that read only
    #: `description` would miss the half of them that use the other.
    counterparty: Optional[str] = None
    payee_id: Optional[uuid.UUID] = None
    #: Set for a recurring bill, which is charged to a known account.
    #: Null for an invoice, where the money may land anywhere.
    account_id: Optional[uuid.UUID] = None
    #: As on `Movement`, and read by the same rules. An invoice and a
    #: recurring bill leave them null; the other leg of a transfer is an
    #: account and fills both.
    account_name: Optional[str] = None
    account_type: Optional[str] = None
    #: When the promise came into existence, if that is a different day
    #: from when it comes due. An invoice has both and they are weeks
    #: apart; a recurring occurrence has one, and leaves this null.
    issued: Optional[date] = None
    #: The amounts at which this promise closes a whole part, smallest
    #: first, ending at `amount`. Set when the money was agreed in
    #: installments: a client paying the next one, or the next two at
    #: once, is paying exactly what was asked, and comparing that against
    #: the whole balance would call every installment a mismatch. Empty
    #: for a promise that is one amount on one date.
    stops: tuple[Decimal, ...] = ()

    def targets(self) -> tuple[Decimal, ...]:
        """What a movement's amount is compared against, in order."""
        return self.stops or (self.amount,)


@dataclass(frozen=True)
class Settlement:
    """One promise, and how much of this movement goes against it.

    Exists because a payment does not always answer exactly one thing. A
    client clearing three of their own invoices in a single transfer is
    ordinary, and so is a commercial arrangement that settles a month's
    worth at once. The ledger has always been able to record that
    (allocations are many-to-many with an amount on each), but a decision
    that could only ever name one promise could never propose it.
    """

    expectation: Expectation
    amount: Decimal
    #: The part of the promise the amount was measured against: the next
    #: installment, say, rather than the whole balance. None when that is
    #: the balance itself.
    target: Optional[Decimal] = None


@dataclass
class Consideration:
    """One candidate, and what the engine made of it."""

    expectation_id: uuid.UUID
    strategy: Optional[str] = None
    rejected_by: Optional[Reason] = None
    score: float = 0.0


@dataclass
class Decision:
    """What to do, and the reasoning that got there.

    `trace` carries every candidate that was looked at, including the
    ones that lost. It is what lets the invoice screen answer "why is
    this linked" with the name of the rule that fired, and "why is this
    not" with the specific signal that failed.
    """

    port: Port
    #: Everything this movement settles. Usually one entry; several when a
    #: single payment answers several promises at once.
    settlements: list[Settlement] = field(default_factory=list)
    #: The first settlement, spelled out, because one promise is the
    #: overwhelming majority and every caller written before sets existed
    #: still reads these. Never a *different* answer from `settlements`:
    #: its head.
    expectation: Optional[Expectation] = None
    strategy: Optional[str] = None
    amount: Optional[Decimal] = None
    #: Set when a strategy matched a known fraction rather than the whole
    #: Brazilian withholding is the reason this exists. The caller
    #: books the difference; the engine only names it.
    difference: Optional[Decimal] = None
    difference_kind: Optional[str] = None
    #: How well the winner scored, 1.0 when the strategy carries no
    #: graded signal. A caller holding several movements for one
    #: expectation ranks them by this: the recurring matcher does, and
    #: has always taken the better-matching charge rather than refusing
    #: both. Exposed rather than dug out of the trace because it is also
    #: what a suggestion has to show a person to be worth showing. Zero
    #: when nothing was decided, so an unmatched result never sorts above
    #: a real one.
    score: float = 0.0
    trace: list[Consideration] = field(default_factory=list)


def _amount_verdict(
    movement: Decimal, expected: Decimal, rule: dict[str, Any], ratios: list[Decimal]
) -> tuple[bool, Optional[Decimal], Optional[str]]:
    """Does the money that moved answer the amount expected?

    Returns whether it matched, the unexplained difference, and what that
    difference is. `ratio` is the one that carries meaning: money arriving
    at a known fraction of the invoice is withholding, not an error, and
    the caller books it rather than asking a person about it.
    """
    match = rule.get("match", "exact")
    moved = abs(movement)
    want = abs(expected)

    if match == "exact":
        return moved == want, None, None

    if match == "tolerance":
        percent = Decimal(str(rule.get("percent", "0")))
        allowed = (want * percent / Decimal("100")).copy_abs()
        return abs(moved - want) <= allowed, None, None

    if match == "partial":
        # Money that covers *part* of what is owed. Two transactions
        # settling one invoice is ordinary (an instalment, a client
        # paying what they had), and the ledger has always supported it,
        # but without this mode nothing could ever propose the first half:
        # every other mode compares against the whole outstanding balance
        # and a half is simply not it.
        #
        # Strictly less than, so this and `exact` never both fire and a
        # trace never has to explain which one won.
        if moved >= want or moved <= Decimal("0"):
            return False, None, None

        floor = Decimal(str(rule.get("min_ratio", "0")))
        if floor > 0 and moved < (want * floor):
            # A token amount against a large invoice is noise, not an
            # instalment. Offering it would teach people to ignore the
            # queue.
            return False, None, None

        ceiling = Decimal(str(rule.get("max_ratio", "1")))
        if ceiling < 1 and moved > (want * ceiling):
            # Money that is *almost* the whole thing is not an instalment
            # either: it is a fee, a withholding, a rounding. Calling it
            # a part payment would put a confident wrong word on the
            # queue, and the tolerance rules are the ones written for it.
            return False, None, None

        return True, (want - moved), "part_payment"

    if match == "ratio":
        epsilon = Decimal(str(rule.get("epsilon", "0")))
        for ratio in ratios:
            target = (want * ratio).quantize(Decimal("0.01"))
            if abs(moved - target) <= epsilon:
                return True, (want - moved), rule.get("difference_kind")
        return False, None, None

    return False, None, None


def _within_window(
    movement_date: date,
    expected: date,
    rule: dict[str, Any],
    issued: Optional[date] = None,
) -> bool:
    """Is this money close enough in time to be this promise's?

    Asymmetric on purpose: money arrives *after* a due date far more
    often than before it, and a symmetric window either misses the late
    ones or reaches into the neighbouring occurrence.

    The two sides are also measured from different days when the
    expectation has both. **Late is late by reference to the due date;
    early is early by reference to the day the promise was made.** An
    invoice due on the 30th and issued on the 1st is not "29 days paid
    early" when the client pays on the 2nd: it is paid the day after it
    was issued, which is the best case there is. Collapsing both onto the
    due date is what would push every deposit and every pay-then-invoice
    into the rejected pile. A recurring occurrence has no separate issue
    date, leaves `issued` null, and keeps the single-anchor behaviour it
    has always had.
    """
    before = int(rule.get("before_days", 0))
    after = int(rule.get("after_days", 0))
    return (
        ((issued or expected) - movement_date).days <= before
        and (movement_date - expected).days <= after
    )


#: How many open promises a set rule will consider at once, and how many
#: it will put in one answer. Both are hard limits rather than
#: preferences: finding which invoices add up to a payment is subset-sum,
#: which grows explosively, and a sync that hangs is worse than a match
#: that is not made. Beyond these the engine says so and stops.
MAX_SET_CANDIDATES = 12
MAX_SET_SIZE = 6


def _combinations_that_add_up(
    moved: Decimal,
    candidates: list[Expectation],
    percent: Decimal,
    max_size: int,
) -> list[list[Expectation]]:
    """Which groups of promises this payment could be covering.

    Every group that fits, not the first one found, because the number of
    answers *is* the finding. One combination is a match; two are a
    question, and picking the first would be inventing certainty exactly
    where the single-promise path refuses to.

    Search order is smallest group first, so a payment that settles one
    invoice exactly is never reported as also settling three that happen
    to sum to the same figure.
    """
    found: list[list[Expectation]] = []
    usable = [c for c in candidates if c.amount > Decimal("0")]
    if len(usable) > MAX_SET_CANDIDATES:
        return []

    for size in range(2, min(max_size, len(usable)) + 1):
        for group in itertools.combinations(usable, size):
            total = sum((c.amount for c in group), Decimal("0"))
            # The allowance is a share of what the invoices are worth, not
            # of what arrived. A gateway's cut is a percentage of the
            # gross, and "two per cent" should mean the thing a person
            # means by it rather than two per cent of the figure left
            # after the cut.
            tolerance = (total * percent / Decimal("100")).copy_abs()
            if abs(total - moved) <= tolerance:
                found.append(list(group))
                # Two is already an answer of "ask a person", so there is
                # nothing to learn from finding a third.
                if len(found) > 1:
                    return found
    return found


def _in_scope(
    movement: Movement, rule: dict[str, Any], base_currency: Optional[str]
) -> bool:
    """Does this rule apply to this money at all?

    Separate from the comparisons below, and worth naming as its own idea.
    Every other signal asks *how well the pair fits*; these ask *whether
    the rule was written for money like this*: a specific account, a
    currency that is not the one you normally deal in, an amount above the
    threshold where you stop trusting an automatic match, a statement line
    whose text you recognise.

    That distinction is what the rule tools converged on independently:
    they let a rule name its bank account, its direction
    and a text fragment before any comparison happens. Without it a rule
    can only say "money like this matches invoices like that", and every
    real request (*only for dollars*, *only above ten thousand*, *only
    this client*) is inexpressible.

    All conditions must hold. Deliberately no ANY/OR mode, unlike the
    categorization rules: those pick a label and a wrong guess is a
    mislabelled row, while these bind money to a debt. "The amount matches
    OR the date is close" is a sentence with no safe reading.
    """
    accounts = rule.get("accounts", {}).get("in")
    if accounts and str(movement.account_id) not in {str(a) for a in accounts}:
        return False

    payees = rule.get("payees", {}).get("in")
    if payees and str(movement.payee_id) not in {str(p) for p in payees}:
        return False

    direction = rule.get("direction")
    if direction and direction != "any" and movement.direction != direction:
        return False

    currency = rule.get("currency", {})
    allowed = currency.get("in")
    if allowed and movement.currency not in set(allowed):
        return False
    if currency.get("foreign"):
        # "Foreign" is relative to the workspace, so without knowing the
        # base currency the honest answer is that the rule does not apply,
        # never that everything is foreign.
        if not base_currency or movement.currency == base_currency:
            return False

    amount_rule = rule.get("amount", {})
    moved = abs(movement.amount)
    minimum = amount_rule.get("min")
    if minimum not in (None, "") and moved < Decimal(str(minimum)):
        return False
    maximum = amount_rule.get("max")
    if maximum not in (None, "") and moved > Decimal(str(maximum)):
        return False

    text = rule.get("text", {})
    if text:
        # Both fields, as one haystack. The identifying words land in
        # whichever of the two the bank felt like using, and asking a
        # person which field their bank prefers is asking them to know
        # something about our data model.
        printed = " ".join(
            part.lower()
            for part in (movement.description, movement.counterparty)
            if part
        )
        wanted = _as_list(text.get("contains"))
        # Any of them, not all: somebody receiving through three acquirers
        # wants one rule saying "a payout from any of these", not three
        # rules that differ by a word.
        if wanted and not any(word.lower() in printed for word in wanted):
            return False
        for word in _as_list(text.get("not_contains")):
            if word.lower() in printed:
                return False

    return True


def _as_list(value: Any) -> list[str]:
    """One word or several, read the same way.

    Stored as a list once a rule names alternatives; a plain string is
    still accepted because every rule written before this said one word.
    """
    if value in (None, ""):
        return []
    if isinstance(value, str):
        return [value]
    return [str(item) for item in value if str(item).strip()]


def _eligible_for_set(
    movement: Movement, candidate: Expectation, rule: dict[str, Any]
) -> bool:
    """Whether a promise may take part in a combination at all.

    Every condition except the amount, because the amount is the one being
    asked about the group rather than the member. Narrowing first is also
    what keeps the search tractable: a rule that demands the same client
    usually leaves three or four candidates, not four hundred.
    """
    if candidate.direction != movement.direction:
        return False
    if candidate.amount <= Decimal("0"):
        return False
    if candidate.currency != movement.currency:
        return False
    if rule.get("counterparty") == "same_payee":
        if not movement.payee_id or movement.payee_id != candidate.payee_id:
            return False
    if rule.get("same_account") and movement.account_id != candidate.account_id:
        return False
    if not _within_window(movement.when, candidate.when, rule.get("date", {}), candidate.issued):
        return False
    return True


ZERO = Decimal("0")
#: Money is stored to two places, so a share of it has to land there too.
CENTS = Decimal("0.01")

def _share_out(moved: Decimal, chosen: list[Expectation]) -> list[Settlement]:
    """Split what arrived across the promises it answers.

    The single-candidate path settles `min(what moved, what is owed)`, and
    this is the same rule for a group: a payment can never write more than
    it carried. Without it a tolerance-based group was allowed to settle
    every invoice at its full value, so 980 arriving against two invoices
    of 500 wrote 1.000 of allocations. `allocate` would not catch it: it
    guards each invoice's own balance and knows nothing about how much of
    the transaction earlier members of the group already spent.

    Short payments are shared **in proportion**, because that is what the
    shortfall usually is: a gateway's cut is a percentage of the gross, so
    the larger invoice gives up the larger part of it. The rounding
    residue lands on the last settlement, which keeps the parts summing to
    exactly what moved rather than to a figure a cent away from it.

    A payment larger than the group (interest, a late fee) is not shared
    out at all. Each invoice closes at its value and the surplus stays on
    the transaction, where `difference` names it.
    """
    total = sum((c.amount for c in chosen), Decimal("0"))
    if total <= moved or total <= ZERO:
        return [Settlement(expectation=c, amount=c.amount) for c in chosen]

    settlements: list[Settlement] = []
    spent = Decimal("0")
    for candidate in chosen[:-1]:
        share = (moved * candidate.amount / total).quantize(CENTS, rounding=ROUND_DOWN)
        settlements.append(Settlement(expectation=candidate, amount=share))
        spent += share
    settlements.append(Settlement(expectation=chosen[-1], amount=moved - spent))
    return settlements


def _evaluate_set(
    movement: Movement,
    candidates: list[Expectation],
    strategy: dict[str, Any],
    rule: dict[str, Any],
    policy: dict[str, Any],
    base_currency: Optional[str],
    trace: list[Consideration],
) -> Optional[Decision]:
    """One payment against several promises.

    Returns a decision when this rule has something to say, and nothing
    when it does not, so the strategies after it still get their turn.

    The whole design of the rest of this module carries over unchanged:
    **one answer is a match, more than one is a question.** Three invoices
    of a thousand and a credit of two thousand admit three equally good
    readings, and choosing among them is a person's job.
    """
    amount_rule = rule.get("amount", {})
    eligible = [c for c in candidates if _eligible_for_set(movement, c, rule)]
    moved = abs(movement.amount)

    if len(eligible) < 2:
        return None

    if len(eligible) > MAX_SET_CANDIDATES:
        # Refusing loudly. Silently searching a space this size would make
        # a sync unpredictable, and silently skipping it would leave
        # somebody wondering why their payout never matched.
        trace.append(
            Consideration(
                expectation_id=eligible[0].id,
                strategy=strategy["id"],
                rejected_by=Reason.TOO_MANY_TO_COMBINE,
            )
        )
        return None

    percent = Decimal(str(amount_rule.get("percent", "0")))
    max_size = min(int(amount_rule.get("max_invoices", MAX_SET_SIZE)), MAX_SET_SIZE)

    groups = _combinations_that_add_up(moved, eligible, percent, max_size)
    if not groups:
        for candidate in eligible:
            trace.append(
                Consideration(
                    expectation_id=candidate.id,
                    strategy=strategy["id"],
                    rejected_by=Reason.AMOUNT,
                )
            )
        return None

    outcome = strategy.get("outcome", "suggest")
    if len(groups) > 1:
        # Several combinations fit. Which one is a question about intent,
        # not about arithmetic, so it goes to a person.
        outcome = policy.get("on_ambiguity", "suggest")
        for candidate in eligible:
            trace.append(
                Consideration(
                    expectation_id=candidate.id,
                    strategy=strategy["id"],
                    rejected_by=Reason.AMBIGUOUS_SET,
                )
            )

    chosen = groups[0]
    settlements = _share_out(moved, chosen)
    # The gap is measured against what the invoices are **worth**, not
    # against what was written. Sharing out caps the allocations at what
    # arrived, so comparing with those would report a gap of zero and the
    # gateway's cut would go unnamed: the one number a later deduction
    # has to book.
    promised = sum((c.amount for c in chosen), Decimal("0"))

    for candidate in chosen:
        trace.append(
            Consideration(
                expectation_id=candidate.id, strategy=strategy["id"], score=1.0
            )
        )

    return Decision(
        port="linked" if outcome == "link" else "suggested",
        settlements=settlements,
        expectation=settlements[0].expectation,
        strategy=strategy["id"],
        amount=settlements[0].amount,
        # What the payment carried beyond the invoices it covers: a
        # gateway fee, a bank charge, a rounding. Named rather than
        # swallowed, so the caller can book it instead of leaving money
        # unexplained.
        difference=(moved - promised) if moved != promised else None,
        difference_kind="set_difference" if moved != promised else None,
        score=1.0,
        trace=trace,
    )


def evaluate(
    movement: Movement,
    candidates: list[Expectation],
    policy: dict[str, Any],
    *,
    withholding_ratios: Optional[list[Decimal]] = None,
    base_currency: Optional[str] = None,
    trigger: str = "money_arrives",
) -> Decision:
    """Which expectation this movement settles, if any.

    Strategies are ordered and the first one to match wins; the same
    precedence `rules.priority` already has, so there is one mental model
    for "which rule applied" across the product.

    `base_currency` is what the workspace normally deals in, and is only
    consulted by rules that say "foreign": what counts as foreign is a
    fact about the workspace, not about the money.

    `trigger` says which of the two moments this is (money arriving, or a
    document being written), and rules that were not written for this
    moment sit it out.
    """
    trace: list[Consideration] = []
    ratios = withholding_ratios or []

    ignored = set(policy.get("scope", {}).get("ignore_transaction_sources", []))
    if movement.source and movement.source in ignored:
        # A generated placeholder is a promise, not the money. Matching a
        # promise against a promise would settle an invoice with nothing.
        return Decision(port="unmatched", trace=[])

    for strategy in policy.get("strategies", []):
        if not strategy.get("enabled", True):
            continue
        # Written for the other moment. Looking back at money that was
        # already there is weaker evidence than answering a promise that
        # was waiting, so a rule is allowed to say it only trusts one of
        # them, and saying so on the page beats the same restriction
        # hardcoded into whichever function does the looking.
        wanted = strategy.get("trigger", "money_arrives")
        if wanted != "both" and wanted != trigger:
            trace.append(
                Consideration(
                    expectation_id=candidates[0].id if candidates else uuid.uuid4(),
                    strategy=strategy["id"],
                    rejected_by=Reason.WRONG_MOMENT,
                )
            )
            continue

        rule = strategy.get("when", {})
        if not _in_scope(movement, rule, base_currency):
            # Not written for money like this. One note rather than one per
            # candidate: the rule was never consulted, so there is nothing
            # to say about any particular promise.
            trace.append(
                Consideration(
                    expectation_id=candidates[0].id if candidates else uuid.uuid4(),
                    strategy=strategy["id"],
                    rejected_by=Reason.OUT_OF_SCOPE,
                )
            )
            continue
        # A payment that answers several promises at once. Kept as its own
        # branch because it asks a different question of the candidates:
        # not "which one of you is this" but "which of you, together".
        if rule.get("amount", {}).get("match") == "set":
            decision = _evaluate_set(
                movement, candidates, strategy, rule, policy, base_currency, trace
            )
            if decision is not None:
                return decision
            continue

        matched: list[
            tuple[Expectation, Optional[Decimal], Optional[str], float, Optional[Decimal]]
        ] = []

        for candidate in candidates:
            note = Consideration(expectation_id=candidate.id, strategy=strategy["id"])

            if candidate.direction != movement.direction:
                note.rejected_by = Reason.DIRECTION
                trace.append(note)
                continue

            if candidate.amount <= Decimal("0"):
                note.rejected_by = Reason.ALREADY_SETTLED
                trace.append(note)
                continue

            # Always, and not a setting.
            #
            # There was a `currency.conversion` knob here whose "allow"
            # value read as *convert and compare*. It did no such thing:
            # this module is pure and holds no session, so it cannot look
            # up a rate. All "allow" did was stop comparing currencies,
            # which made a $3.000 payment an **exact** match for a €3.000
            # invoice and settled the euros with the dollars.
            #
            # Matching across currencies needs three things this does not
            # have: a rate, a date to take it on (the invoice's or the
            # bank's, and they differ), and somewhere to put the leftover
            # difference. The third is the same booking problem as
            # withholding, which is why it belongs with deductions rather
            # than here.
            if candidate.currency != movement.currency:
                note.rejected_by = Reason.CURRENCY
                trace.append(note)
                continue

            if rule.get("counterparty") == "same_payee":
                if not movement.payee_id or movement.payee_id != candidate.payee_id:
                    note.rejected_by = Reason.COUNTERPARTY
                    trace.append(note)
                    continue

            if rule.get("same_account") and movement.account_id != candidate.account_id:
                note.rejected_by = Reason.COUNTERPARTY
                trace.append(note)
                continue

            # The inverse, and the defining condition of a transfer:
            # money that left one account and arrived in another. Its own
            # key rather than a value on `same_account`, so that a rule
            # reads as a list of things that must be true and never as a
            # flag whose meaning depends on how it is set.
            if rule.get("different_account") and (
                movement.account_id is None
                or movement.account_id == candidate.account_id
            ):
                note.rejected_by = Reason.SAME_ACCOUNT
                trace.append(note)
                continue

            wanted_types = _as_list(rule.get("account_types"))
            if wanted_types and not (
                movement.account_type in wanted_types
                or candidate.account_type in wanted_types
            ):
                # Either leg is enough. A rule that exists to be careful
                # about credit cards has to fire whichever end the card
                # is on, and asking somebody to write the rule twice
                # would be asking them to know which side we happen to
                # examine first.
                note.rejected_by = Reason.ACCOUNT_TYPE
                trace.append(note)
                continue

            # How strongly the two texts point at each other. **Graded,
            # not a yes or no**, and that is the whole of why the
            # wrong-counterpart case comes out right.
            #
            # Two transfers leave one account on the same day and the
            # incoming line reads `Transfer from BNP`. That names the
            # source, so on its own it fits *both* debits equally and
            # decides nothing. What separates them is that one of the
            # two also reads `To FORTUNEO ACCOUNT`, so that pair names
            # itself from both ends and the other only from one.
            #
            # A boolean would have called both a match and handed the
            # choice back to the tie-break, which has nothing to go on
            # when the dates are identical. Counting the directions puts
            # the better pair in front, where `tie_break` can see it.
            naming: Optional[float] = None
            if rule.get("account_name_in_description"):
                sides = (
                    names_account(movement.description, candidate.account_name)
                    or names_account(movement.counterparty, candidate.account_name),
                    names_account(candidate.description, movement.account_name)
                    or names_account(candidate.counterparty, movement.account_name),
                )
                if not any(sides):
                    note.rejected_by = Reason.ACCOUNT_NOT_NAMED
                    trace.append(note)
                    continue
                naming = sum(1 for side in sides if side) / 2.0

            # Against each whole part in turn, next installment first,
            # so the smallest honest reading wins: a payment of exactly
            # one installment is that installment, not a part of the rest.
            ok, difference, difference_kind, target = False, None, None, None
            for target in candidate.targets():
                ok, difference, difference_kind = _amount_verdict(
                    movement.amount, target, rule.get("amount", {}), ratios
                )
                if ok:
                    break
            if not ok:
                note.rejected_by = Reason.AMOUNT
                trace.append(note)
                continue

            if not _within_window(
                movement.when, candidate.when, rule.get("date", {}), candidate.issued
            ):
                note.rejected_by = Reason.DATE
                trace.append(note)
                continue

            score = 1.0
            similarity = rule.get("description_similarity")
            if similarity:
                score = token_overlap(movement.description, candidate.description)
                if score < float(similarity.get("min", 0)):
                    note.rejected_by = Reason.DESCRIPTION
                    note.score = score
                    trace.append(note)
                    continue
            elif naming is not None:
                # Only when nothing else grades the pair. A rule asking
                # for both would be asking two questions of one number,
                # and no rule does.
                score = naming

            note.score = score
            trace.append(note)
            matched.append((candidate, difference, difference_kind, score, target))

        if not matched:
            continue

        outcome = strategy.get("outcome", "suggest")

        if len(matched) > 1 and rule.get("tie_break") == "closest_date":
            # **Two different meanings of "more than one candidate", and
            # collapsing them loses a signal people rely on.**
            #
            # Transfers are where this shows. Money leaves an account
            # today and two credits of the same value sit in the
            # destination, one today and one two days out: the same-day
            # one is the transfer and the other is somebody paying you
            # back. Refusing both because there were two would throw away
            # the very signal the old detector was built on, and it was
            # right about it.
            #
            # What it was wrong about is the case where nothing separates
            # them. Two debits leaving on the same day for different
            # destinations are equidistant from the credit, and there the
            # answer has to be a question.
            #
            # So this narrows to the candidates tied at the front, and
            # whatever `unique_candidate` says next applies to those. A
            # clear winner is one candidate and links; a genuine tie is
            # still several and does not.
            def _closeness(entry: tuple[Expectation, Any, Any, float, Any]):
                return (-entry[3], abs((movement.when - entry[0].when).days))

            ranked = sorted(matched, key=_closeness)
            front = _closeness(ranked[0])
            tied = [entry for entry in ranked if _closeness(entry) == front]
            if len(tied) < len(matched):
                beaten = {id(entry) for entry in matched} - {id(e) for e in tied}
                for note in trace:
                    if (
                        note.strategy == strategy["id"]
                        and note.rejected_by is None
                        and any(
                            entry[0].id == note.expectation_id
                            for entry in matched
                            if id(entry) in beaten
                        )
                    ):
                        note.rejected_by = Reason.FURTHER_IN_TIME
            matched = tied

        if len(matched) > 1:
            if rule.get("unique_candidate", False):
                # Several answers to a question that admits one. Downgrade
                # rather than guess: picking the highest score here would
                # be inventing certainty the signals do not carry.
                outcome = policy.get("on_ambiguity", "suggest")
                for note in trace:
                    if note.strategy == strategy["id"] and note.rejected_by is None:
                        note.rejected_by = Reason.AMBIGUOUS
            matched.sort(key=lambda m: m[3], reverse=True)

        winner, difference, difference_kind, score, target = matched[0]
        settled = min(abs(movement.amount), winner.amount)
        return Decision(
            port="linked" if outcome == "link" else "suggested",
            # Always a set, even when it holds one. A caller that has to
            # ask "is this the single kind or the several kind" before it
            # can write anything is a caller that will one day forget to.
            settlements=[
                Settlement(
                    expectation=winner,
                    amount=settled,
                    target=target if target != winner.amount else None,
                )
            ],
            expectation=winner,
            strategy=strategy["id"],
            amount=settled,
            difference=difference,
            difference_kind=difference_kind,
            score=score,
            trace=trace,
        )

    return Decision(port="unmatched", trace=trace)