Exchange::convert fails on a pair it could derive #47

Closed
opened 2026-08-18 00:38:58 +00:00 by rosa · 4 comments
Owner

Problem

Exchange::convert looks up one pair and stops. A table holding USD/EUR and
EUR/JPY cannot convert USD to JPY, even though ExchangeRate::cross_with
already combines two rates that share a currency and ExchangeRate::invert
already turns a rate around. The table has the parts and does not use them.

Proposal

When the direct pair is missing, convert derives the rate from the ones the
table does hold.

Open questions

  • Which paths count? Routing through one configured base currency is
    predictable. Searching for any shared currency makes the answer depend on
    the search order whenever two paths exist and disagree.
  • Does rate derive as well, or only convert? rate today answers what the
    table was told, and deriving there changes what a quote means.
  • May a hop run backwards through invert, or must every hop be quoted in the
    direction of travel? A desk that charges a spread quotes the two directions
    differently, so inverting invents a rate it never offered.
  • How many hops? One intermediate currency, or a path of any length?
  • Does a derived rate come back as an ExchangeRate like any other, with no
    record of how it was reached?

Out of scope

Dated rates, the provider trait, and two-sided quotes. Each is its own issue.

## Problem `Exchange::convert` looks up one pair and stops. A table holding USD/EUR and EUR/JPY cannot convert USD to JPY, even though `ExchangeRate::cross_with` already combines two rates that share a currency and `ExchangeRate::invert` already turns a rate around. The table has the parts and does not use them. ## Proposal When the direct pair is missing, `convert` derives the rate from the ones the table does hold. ## Open questions - Which paths count? Routing through one configured base currency is predictable. Searching for any shared currency makes the answer depend on the search order whenever two paths exist and disagree. - Does `rate` derive as well, or only `convert`? `rate` today answers what the table was told, and deriving there changes what a quote means. - May a hop run backwards through `invert`, or must every hop be quoted in the direction of travel? A desk that charges a spread quotes the two directions differently, so inverting invents a rate it never offered. - How many hops? One intermediate currency, or a path of any length? - Does a derived rate come back as an `ExchangeRate` like any other, with no record of how it was reached? ## Out of scope Dated rates, the provider trait, and two-sided quotes. Each is its own issue.
Author
Owner

This was generated by AI during triage.

#50 answers part of this issue's third open question

#50 has been designed out and moved to ready-for-agent. Its outcome changes
what triangulation is routing over, so this issue should be read against it
rather than against the table as it stands today.

"May a hop run backwards through invert?" — the answer splits by what
kind of quotation the hop holds.

Exchange will store a Quotation per pair: either one-way, which prices a
single direction, or two-way, which holds a Market and prices both. A hop
may run backwards through a two-way quotation, because both directions were
genuinely offered. A hop may never run backwards through a one-way one, since
inverting it invents a price nobody quoted. #50 also adds an ExchangeError
variant for exactly this case — a pair that is quoted, but not in the
direction asked — which gives the path search a precise thing to catch and
tells it apart from a pair that is absent entirely.

"Does a derived rate come back with no record of how it was reached?" —
#50 settled the same question for crossed markets and landed on no
provenance. Market::cross_with compounds spreads and returns an ordinary
Market. Provenance was ruled out on the grounds that it belongs to the
dated-rate (#48) and provider (#49) work, and that half a provenance system
built early would sit in the wrong place. Answering this issue differently
would leave the crate with two conventions.

What this issue now routes over. The path search operates on quotations
rather than bare rates, and len() counts quotations, so a two-way pair is
one entry rather than two. A crossed path through two two-way quotations has
a defined result: the spreads compound, low times low and high times high.

The remaining open questions here — which paths count, whether rate derives
or only convert, and how many hops — are untouched by #50 and still need
settling.

See CONTEXT.md for the settled vocabulary and
docs/adr/0001-a-market-is-ordered-not-checked.md for why a market is
ordered rather than checked.

> *This was generated by AI during triage.* ## #50 answers part of this issue's third open question #50 has been designed out and moved to `ready-for-agent`. Its outcome changes what triangulation is routing over, so this issue should be read against it rather than against the table as it stands today. **"May a hop run backwards through `invert`?"** — the answer splits by what kind of quotation the hop holds. `Exchange` will store a `Quotation` per pair: either one-way, which prices a single direction, or two-way, which holds a `Market` and prices both. A hop may run backwards through a two-way quotation, because both directions were genuinely offered. A hop may never run backwards through a one-way one, since inverting it invents a price nobody quoted. #50 also adds an `ExchangeError` variant for exactly this case — a pair that is quoted, but not in the direction asked — which gives the path search a precise thing to catch and tells it apart from a pair that is absent entirely. **"Does a derived rate come back with no record of how it was reached?"** — #50 settled the same question for crossed markets and landed on no provenance. `Market::cross_with` compounds spreads and returns an ordinary `Market`. Provenance was ruled out on the grounds that it belongs to the dated-rate (#48) and provider (#49) work, and that half a provenance system built early would sit in the wrong place. Answering this issue differently would leave the crate with two conventions. **What this issue now routes over.** The path search operates on quotations rather than bare rates, and `len()` counts quotations, so a two-way pair is one entry rather than two. A crossed path through two two-way quotations has a defined result: the spreads compound, low times low and high times high. The remaining open questions here — which paths count, whether `rate` derives or only `convert`, and how many hops — are untouched by #50 and still need settling. See `CONTEXT.md` for the settled vocabulary and `docs/adr/0001-a-market-is-ordered-not-checked.md` for why a market is ordered rather than checked.
Author
Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add Exchange::rate_crossed and Exchange::convert_crossed, which
price a pair the table does not quote directly by combining the quotations it
does hold.

Current behavior:

Exchange::rate reads one entry and prices one direction from it.
Exchange::convert does the same and fails with ExchangeError::Unquoted when
no entry covers the two currencies, even where the table holds quotations that
lead from one to the other. Quotation::cross_with combines two quotations that
share a currency, and Quotation::invert turns one around, so the parts exist —
the table's own documentation tells callers to do the crossing themselves.

Desired behavior:

Two new methods on Exchange. Neither changes get, rate or convert, which
keep their current behavior exactly.

rate_crossed takes a pair — as a Pair or as the two currencies, base first,
like every other lookup — and returns Option<Quotation>. It searches for a
route from the base currency to the quote through currencies the table quotes,
under these rules:

  • Shortest route wins. The search is breadth-first, so it finds a route with
    the fewest quotations in it. There is no cap on route length; the search stops
    at the first length that yields any route at all.
  • A directly quoted pair wins outright. The direct pair is the shortest route
    there is, so whenever the table prices the direction asked, rate_crossed
    returns exactly what rate returns. Crossing never overrules a stated price.
  • Each step runs in the direction of travel. A step is oriented the way
    rate orients a lookup: a two-way quotation prices both directions, a one-way
    quotation prices only the direction it was quoted in. A one-way quotation asked
    backwards blocks that step. It is never inverted, because inverting it would
    invent a price nobody quoted.
  • No currency appears twice in a route. This includes the endpoints, so a
    route never returns to the currency it started from. A pair of one currency is
    answered by a stored quotation — Quotation::identity for par, a one-currency
    quotation for a fee — or not at all.
  • Among routes of the same length, the lowest price for the direction asked
    wins.
    Exact ties break by the intermediate currencies, compared in order by
    currency code, so the answer depends on what the table holds and not on how it
    was searched.
  • A route that cannot be crossed is skipped. Quotation::cross_with fails
    when a combined price is too large for a Decimal, or too small to be quoted.
    Such a route is not a route; the search passes over it and carries on.
  • The result is one-way. Even where every step is two-way and cross_with
    yields a two-way quotation, rate_crossed returns a one-way quotation for the
    pair asked. The route was chosen by its price in one direction, so the result
    states that direction and no other. A caller wanting the way back asks for the
    reverse pair, which may well be priced by a different route.
  • None when no route survives.

convert_crossed takes an amount and a currency, like convert, and returns
Result<Money, ExchangeError>. It prices the amount at what rate_crossed
gives for the two currencies. Its errors reuse the existing variants with their
current meanings:

  • Unpriced when the table quotes the two currencies directly but not in the
    direction asked, and no route replaced it.
  • Unquoted when no route prices the two currencies at all. This still includes
    a currency against itself with no quotation set.
  • Convert forwarding a ConvertError from the conversion itself.

History gains nothing. A caller crossing at a moment reads the exchange in
effect and crosses on that, so the search exists in one place.

Key interfaces:

  • Exchange::rate_crossed<P: Into<Pair>>(&self, pair: P) -> Option<Quotation> —
    new. Mirrors rate's signature.
  • Exchange::convert_crossed(&self, money: Money, into: Currency) -> Result<Money, ExchangeError> —
    new. Mirrors convert's signature. A thin call over rate_crossed.
  • ExchangeError — no new variants. #[non_exhaustive] leaves room to
    distinguish "connected but every route blocked" later, if a caller ever needs
    it.
  • Quotation::cross_with, Quotation::rate, Quotation::invert — unchanged,
    and the pieces the search is built from.
  • Exchange's own documentation currently tells callers that crossing a pair the
    table does not quote is work the table does not do. That claim is now wrong and
    needs rewriting.

Acceptance criteria:

  • A table holding two-way USD/EUR and EUR/JPY converts USD to JPY, at the
    price cross_with gives for the two.
  • rate_crossed on a directly quoted pair returns the same quotation rate
    does, even where a longer route would price it lower.
  • rate_crossed returns a one-way quotation when every step is two-way.
  • A route blocked by a one-way quotation asked backwards is not used, and no
    quotation is inverted to unblock it.
  • With two routes of equal length and different prices, the lower price for
    the direction asked wins. Reversing the order the quotations were added
    does not change the answer.
  • With two routes of equal length and equal price, the answer is the same
    whichever order the quotations were added in.
  • A three-step route is found when no two-step route exists.
  • rate_crossed for a currency against itself returns None unless the pair
    is quoted, and does not route out and back through another currency.
  • convert_crossed returns Unpriced for a pair quoted only the other way
    with no route, and Unquoted for two currencies nothing connects.
  • rate, convert and get return exactly what they return today for every
    existing test and doctest.
  • Both new methods carry doctests, as every public method in the crate does.
  • mise run ci passes.

Out of scope:

  • Any change to rate, convert or get. Crossing is opt-in and lives behind
    its own name.
  • Adding a crossing method to History. Delegating to the exchange in effect
    would be a method that only forwards.
  • A configured base currency, or any policy stored on the table. Exchange stays
    a set of quotations and serializes as one.
  • Caching a route or a crossed price between calls.
  • Reporting which route produced a price. #50 settled that a crossed quotation
    carries no record of how it was reached; a crossed rate here follows.
  • Dated rates (#48) and a rate provider trait (#49, recorded as out of scope).
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Add `Exchange::rate_crossed` and `Exchange::convert_crossed`, which price a pair the table does not quote directly by combining the quotations it does hold. **Current behavior:** `Exchange::rate` reads one entry and prices one direction from it. `Exchange::convert` does the same and fails with `ExchangeError::Unquoted` when no entry covers the two currencies, even where the table holds quotations that lead from one to the other. `Quotation::cross_with` combines two quotations that share a currency, and `Quotation::invert` turns one around, so the parts exist — the table's own documentation tells callers to do the crossing themselves. **Desired behavior:** Two new methods on `Exchange`. Neither changes `get`, `rate` or `convert`, which keep their current behavior exactly. `rate_crossed` takes a pair — as a `Pair` or as the two currencies, base first, like every other lookup — and returns `Option<Quotation>`. It searches for a route from the base currency to the quote through currencies the table quotes, under these rules: - **Shortest route wins.** The search is breadth-first, so it finds a route with the fewest quotations in it. There is no cap on route length; the search stops at the first length that yields any route at all. - **A directly quoted pair wins outright.** The direct pair is the shortest route there is, so whenever the table prices the direction asked, `rate_crossed` returns exactly what `rate` returns. Crossing never overrules a stated price. - **Each step runs in the direction of travel.** A step is oriented the way `rate` orients a lookup: a two-way quotation prices both directions, a one-way quotation prices only the direction it was quoted in. A one-way quotation asked backwards blocks that step. It is never inverted, because inverting it would invent a price nobody quoted. - **No currency appears twice in a route.** This includes the endpoints, so a route never returns to the currency it started from. A pair of one currency is answered by a stored quotation — `Quotation::identity` for par, a one-currency quotation for a fee — or not at all. - **Among routes of the same length, the lowest price for the direction asked wins.** Exact ties break by the intermediate currencies, compared in order by currency code, so the answer depends on what the table holds and not on how it was searched. - **A route that cannot be crossed is skipped.** `Quotation::cross_with` fails when a combined price is too large for a `Decimal`, or too small to be quoted. Such a route is not a route; the search passes over it and carries on. - **The result is one-way.** Even where every step is two-way and `cross_with` yields a two-way quotation, `rate_crossed` returns a one-way quotation for the pair asked. The route was chosen by its price in one direction, so the result states that direction and no other. A caller wanting the way back asks for the reverse pair, which may well be priced by a different route. - **`None` when no route survives.** `convert_crossed` takes an amount and a currency, like `convert`, and returns `Result<Money, ExchangeError>`. It prices the amount at what `rate_crossed` gives for the two currencies. Its errors reuse the existing variants with their current meanings: - `Unpriced` when the table quotes the two currencies directly but not in the direction asked, and no route replaced it. - `Unquoted` when no route prices the two currencies at all. This still includes a currency against itself with no quotation set. - `Convert` forwarding a `ConvertError` from the conversion itself. `History` gains nothing. A caller crossing at a moment reads the exchange in effect and crosses on that, so the search exists in one place. **Key interfaces:** - `Exchange::rate_crossed<P: Into<Pair>>(&self, pair: P) -> Option<Quotation>` — new. Mirrors `rate`'s signature. - `Exchange::convert_crossed(&self, money: Money, into: Currency) -> Result<Money, ExchangeError>` — new. Mirrors `convert`'s signature. A thin call over `rate_crossed`. - `ExchangeError` — no new variants. `#[non_exhaustive]` leaves room to distinguish "connected but every route blocked" later, if a caller ever needs it. - `Quotation::cross_with`, `Quotation::rate`, `Quotation::invert` — unchanged, and the pieces the search is built from. - `Exchange`'s own documentation currently tells callers that crossing a pair the table does not quote is work the table does not do. That claim is now wrong and needs rewriting. **Acceptance criteria:** - [ ] A table holding two-way `USD/EUR` and `EUR/JPY` converts USD to JPY, at the price `cross_with` gives for the two. - [ ] `rate_crossed` on a directly quoted pair returns the same quotation `rate` does, even where a longer route would price it lower. - [ ] `rate_crossed` returns a one-way quotation when every step is two-way. - [ ] A route blocked by a one-way quotation asked backwards is not used, and no quotation is inverted to unblock it. - [ ] With two routes of equal length and different prices, the lower price for the direction asked wins. Reversing the order the quotations were added does not change the answer. - [ ] With two routes of equal length and equal price, the answer is the same whichever order the quotations were added in. - [ ] A three-step route is found when no two-step route exists. - [ ] `rate_crossed` for a currency against itself returns `None` unless the pair is quoted, and does not route out and back through another currency. - [ ] `convert_crossed` returns `Unpriced` for a pair quoted only the other way with no route, and `Unquoted` for two currencies nothing connects. - [ ] `rate`, `convert` and `get` return exactly what they return today for every existing test and doctest. - [ ] Both new methods carry doctests, as every public method in the crate does. - [ ] `mise run ci` passes. **Out of scope:** - Any change to `rate`, `convert` or `get`. Crossing is opt-in and lives behind its own name. - Adding a crossing method to `History`. Delegating to the exchange in effect would be a method that only forwards. - A configured base currency, or any policy stored on the table. `Exchange` stays a set of quotations and serializes as one. - Caching a route or a crossed price between calls. - Reporting which route produced a price. #50 settled that a crossed quotation carries no record of how it was reached; a crossed rate here follows. - Dated rates (#48) and a rate provider trait (#49, recorded as out of scope).
Author
Owner

This was generated by AI during triage.

Vocabulary for the brief above

CONTEXT.md now defines route and hop, so the brief's wording resolves
against the glossary rather than against itself.

  • Route — the currencies an amount passes through on its way from one
    currency to another, in order. A route names two or more currencies, and no
    currency twice. A directly quoted pair is a route of two currencies.
  • Hop — one quotation along a route, priced in the direction an amount
    travels. A route of three currencies has two hops. This is the meaning
    Quotation::cross_with already documents.
  • Cross rate — now reached along a route of three or more currencies, rather
    than by combining exactly two quotations.

Two consequences for the brief:

  • Where it says "each step runs in the direction of travel", read hop.
    CODING_STANDARDS.md treats a name that contradicts the glossary as wrong, so
    the implementation and its docs should say hop.
  • "No currency appears twice in a route" is now part of what route means, not
    an extra rule the search applies. The search cannot produce a repeat, because
    a sequence with one is not a route.

No behavior in the brief changes.

> *This was generated by AI during triage.* ## Vocabulary for the brief above `CONTEXT.md` now defines *route* and *hop*, so the brief's wording resolves against the glossary rather than against itself. - **Route** — the currencies an amount passes through on its way from one currency to another, in order. A route names two or more currencies, and no currency twice. A directly quoted pair is a route of two currencies. - **Hop** — one quotation along a route, priced in the direction an amount travels. A route of three currencies has two hops. This is the meaning `Quotation::cross_with` already documents. - **Cross rate** — now reached along a route of three or more currencies, rather than by combining exactly two quotations. Two consequences for the brief: - Where it says "each **step** runs in the direction of travel", read **hop**. `CODING_STANDARDS.md` treats a name that contradicts the glossary as wrong, so the implementation and its docs should say *hop*. - "No currency appears twice in a route" is now part of what *route* means, not an extra rule the search applies. The search cannot produce a repeat, because a sequence with one is not a route. No behavior in the brief changes.
Author
Owner

Closing this as out of scope, recorded in .out-of-scope/crossing-a-route.md.

Choosing a route is policy. Which of two routes wins, whether a hop may run
backwards through invert, how many hops are too many, and whether the answer
says which currencies it passed through are all questions about a desk, not
about the crate. The open questions on this issue were never gaps in a design —
they were the caller's facts, and the crate would have had to guess at them.

The parts stay public: Exchange::get reads a quotation,
Quotation::cross_with combines two that share a currency, and
Quotation::invert turns one around. A caller who knows their own rules writes
the search over those.

A route the caller names — cross along [USD, EUR, JPY], fail on the first hop
that cannot be priced — makes no such choices, and the note says so. That is a
separate issue if it is ever wanted.

Closing this as out of scope, recorded in `.out-of-scope/crossing-a-route.md`. Choosing a route is policy. Which of two routes wins, whether a hop may run backwards through `invert`, how many hops are too many, and whether the answer says which currencies it passed through are all questions about a desk, not about the crate. The open questions on this issue were never gaps in a design — they were the caller's facts, and the crate would have had to guess at them. The parts stay public: `Exchange::get` reads a quotation, `Quotation::cross_with` combines two that share a currency, and `Quotation::invert` turns one around. A caller who knows their own rules writes the search over those. A route the caller names — cross along `[USD, EUR, JPY]`, fail on the first hop that cannot be priced — makes no such choices, and the note says so. That is a separate issue if it is ever wanted.
rosa closed this issue 2026-08-22 15:45:44 +00:00
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rosa/lucre#47
No description provided.