A rate is one number, so it cannot hold both sides of a quote #50

Closed
opened 2026-08-18 00:39:39 +00:00 by rosa · 1 comment
Owner

Problem

A real quote has two sides: a desk buys at one number and sells at another.
ExchangeRate holds a single multiplier, so a caller holding a two-sided
quote has to pick a side or average the two, and the result records neither
choice. set_rate_both_ways prices both directions from one number, which is
the no-spread case.

Side is not this. It names which currency of a Pair is meant, the base or
the quote. A two-sided quote needs its own name, or one word carries two
meanings.

Proposal

A rate type that holds both sides. Conversion picks the side that matches the
direction being converted, so the caller does not choose.

Open questions

  • What does the new type add over two one-sided rates? A bid and an ask are
    already the pair and its inverse, so setting both directions in the table
    expresses a spread today. The gain has to be in what the type rules out or
    states plainly.
  • Which side applies in which direction, written so a caller never has to work
    it out?
  • Do spreads compound across a derived cross rate, and does the wide side of
    each hop combine?
  • Does one table hold two-sided and one-sided quotes together, or are they
    separate tables?
  • Is a crossed or inverted spread still a quote anyone offered, or a number
    the crate made up?

Out of scope

Triangulation, dated rates, and the provider trait. Each is its own issue.

## Problem A real quote has two sides: a desk buys at one number and sells at another. `ExchangeRate` holds a single multiplier, so a caller holding a two-sided quote has to pick a side or average the two, and the result records neither choice. `set_rate_both_ways` prices both directions from one number, which is the no-spread case. `Side` is not this. It names which currency of a `Pair` is meant, the base or the quote. A two-sided quote needs its own name, or one word carries two meanings. ## Proposal A rate type that holds both sides. Conversion picks the side that matches the direction being converted, so the caller does not choose. ## Open questions - What does the new type add over two one-sided rates? A bid and an ask are already the pair and its inverse, so setting both directions in the table expresses a spread today. The gain has to be in what the type rules out or states plainly. - Which side applies in which direction, written so a caller never has to work it out? - Do spreads compound across a derived cross rate, and does the wide side of each hop combine? - Does one table hold two-sided and one-sided quotes together, or are they separate tables? - Is a crossed or inverted spread still a quote anyone offered, or a number the crate made up? ## Out of scope Triangulation, dated rates, and the provider trait. Each is its own issue.
Author
Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add a two-sided rate type whose ordering makes a self-arbitraging quote unconstructible, and make the rate table hold it.

Current behavior:

ExchangeRate holds one multiplier for one direction. A spread is expressed
by setting each direction separately, which leaves the two numbers unrelated:
nothing stops USD/EUR at 0.80 sitting beside EUR/USD at 1.30, so a
round trip of 100 USD returns 104 USD out of thin air. set_rate_both_ways
prices both directions from one number, which is the no-spread case.

Desired behavior:

A new Market type holds a pair and two prices of the base currency in the
quote currency — a low and a high, with low <= high. Ordering two same-scale
numbers is the entire guarantee: there is no product to compute, no division
to round, and a crossed market cannot be built. Going base-to-quote multiplies
by the low price; coming back divides by the high price.

The guarantee has to bind the table, not just the value. Exchange stores a
Quotation per pair — either OneWay(ExchangeRate) or TwoWay(Market) — as
a single entry keyed on a canonical orientation, so a market quoted as
USD/EUR answers a lookup for EUR/USD without a second probe. Setting one
direction of a pair already quoted two-way drops the other side rather than
leaving half a market behind.

Naming follows dealer vocabulary. The two prices are low and high, never
bid/ask or buy/sell: the crate's callers are as often a desk's customer as
the desk, and a perspective-named accessor makes every caller work out which
side is theirs. The directional rates are named for the direction they
convert.

Key interfaces:

  • Market — pair plus low and high prices of the base currency.
    Construction requires low <= high, both prices above zero, and high
    below 2e28. That last bound is what makes both directional accessors
    infallible: quote_to_base is 1 / high, and one divided by 2e28 or
    more rounds away to zero. Rejecting it at the door removes the Result
    from every accessor.
  • Market::low() / high() — the two prices.
  • Market::base_to_quote() / quote_to_base() — infallible ExchangeRates.
  • Market::convert(Money) — reads the money's currency and picks the side.
    Fails when the money is in neither of the pair's currencies. The existing
    ConvertError::CurrencyMismatch text assumes a single base currency and
    reads wrong here; it needs rewording or a variant of its own.
  • Market::invert() — total, no Result. low' = 1/high, high' = 1/low.
    Ordering survives because low <= high. Both bounds survive too:
    Decimal's smallest positive is 1e-28, so 1/low is at most 1e28,
    under the 2e28 bound. Worth a doc line, since it isn't visible in the
    signature.
  • Market::cross_with(Market) — returns a Market. Spreads compound:
    low times low, high times high. The wider result is the honest cost of two
    hops, not an invention.
  • Market::flat(pair, rate) — the no-spread market, low == high.
  • MarketError — InvalidPrice (a price at or below zero), Crossed (low
    above high), Underflow (high at or above 2e28, leaving no price the
    other way). Underflow deliberately repeats the word InvertError already
    uses for the same mechanism; the message carries the difference and should
    name the offending high price.
  • Quotation — OneWay(ExchangeRate) / TwoWay(Market). Its doc comment
    must say which axis it names: one-way versus two-way, not the direct
    versus indirect quotation distinction an FX reader may expect.
  • Exchange — set_rate and set_market write; rate(pair) answers a
    directional rate whichever kind is stored; quotation(pair) answers the
    entry; remove_quotation(pair) takes the whole entry. len() counts
    quotations, so a two-way pair counts once. Rates and IntoRates become
    Quotations and IntoQuotations, yielding Quotation.
  • ExchangeError — a new variant for a pair that is quoted, but not in the
    direction asked. Distinct from Unquoted: a half-filled board is a
    different fact from an empty one, and it gives triangulation something
    precise to catch later.
  • Display for Market — USD/EUR 1.0850/1.0855. Unambiguous to read back,
    since a pair already takes the first slash as its divider.
  • Serde — a table value is always an object: {"rate": 144} for one-way,
    {"low": 0.85, "high": 0.86} for two-way. Standalone Market is
    {base, quote, low, high}, matching ExchangeRate's existing shape.
    Quotation serializes untagged, so the enum never appears in a document.
  • set_rate_both_ways is removed. Its documentation exists only to explain
    that it is the no-spread case and that a desk charging a spread should do
    something else; a zero-spread Market says both, and the prose deletes
    itself.

Acceptance criteria:

  • Market cannot be constructed with a low price above its high, with a
    price at or below zero, or with a high price at or above 2e28, and
    each refusal is its own MarketError variant naming the offending
    number.
  • Neither directional accessor on Market returns a Result.
  • Market::invert() returns a Market with no Result, and a property
    test shows the ordering holds for any constructible market.
  • A property test shows that for any constructible Market, converting an
    amount out and back never returns more than it started with.
  • Market::cross_with returns a market whose spread is at least as wide
    as either input's.
  • Exchange::len() counts quotations: a table holding one two-way pair
    reports 1.
  • A market quoted as USD/EUR answers rate((EUR, USD)) and converts
    EUR into USD.
  • Setting a one-way rate over one direction of a two-way pair leaves no
    trace of the other direction.
  • Converting a direction that a one-way quotation does not price gives the
    new ExchangeError variant, not Unquoted.
  • Market round-trips through serde, and a table mixing one-way and
    two-way entries round-trips.
  • Market displays as USD/EUR 1.0850/1.0855.
  • set_rate_both_ways no longer exists.
  • mise run fmtcheck, mise run ci, and mise run clippy pass.

Out of scope:

  • Triangulation (#47), dated rates (#48), and the provider trait (#49).
  • Recording that a crossed rate was derived rather than quoted. Provenance
    belongs to the dated-rate and provider work; half a provenance system built
    here would be in the wrong place.
  • Rewriting the hand-written serde visitors. #34 wants them replaced by
    derives, and this work necessarily adds to them — leave that swap to #34
    rather than doing half of it here.
  • Folding ExchangeRate into Market. It was considered and rejected: a
    one-way quotation must stay expressible, and a single required-both-sides
    type would make every reverse conversion succeed at a price nobody offered.

Two naming notes for whoever picks this up:

Quotation is a near-neighbour of the noun #16 was closed to reserve. It
earns its place because it names something Rates cannot — an entry that may
price one direction or two — where the old Quotes was only ever a second
word for rates. This is not a reversal of #16.

Crossed (a market whose low is above its high) and cross_with (combining
two rates through a shared currency) are unrelated senses of the same word.
Both are standard finance terms, so both stay, but the doc comments should
keep them apart rather than let a reader assume they are related.

> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Add a two-sided rate type whose ordering makes a self-arbitraging quote unconstructible, and make the rate table hold it. **Current behavior:** `ExchangeRate` holds one multiplier for one direction. A spread is expressed by setting each direction separately, which leaves the two numbers unrelated: nothing stops `USD/EUR` at `0.80` sitting beside `EUR/USD` at `1.30`, so a round trip of 100 USD returns 104 USD out of thin air. `set_rate_both_ways` prices both directions from one number, which is the no-spread case. **Desired behavior:** A new `Market` type holds a pair and two prices of the base currency in the quote currency — a low and a high, with `low <= high`. Ordering two same-scale numbers is the entire guarantee: there is no product to compute, no division to round, and a crossed market cannot be built. Going base-to-quote multiplies by the low price; coming back divides by the high price. The guarantee has to bind the table, not just the value. `Exchange` stores a `Quotation` per pair — either `OneWay(ExchangeRate)` or `TwoWay(Market)` — as a single entry keyed on a canonical orientation, so a market quoted as `USD/EUR` answers a lookup for `EUR/USD` without a second probe. Setting one direction of a pair already quoted two-way drops the other side rather than leaving half a market behind. Naming follows dealer vocabulary. The two prices are `low` and `high`, never bid/ask or buy/sell: the crate's callers are as often a desk's customer as the desk, and a perspective-named accessor makes every caller work out which side is theirs. The directional rates are named for the direction they convert. **Key interfaces:** - `Market` — pair plus `low` and `high` prices of the base currency. Construction requires `low <= high`, both prices above zero, and `high` below `2e28`. That last bound is what makes both directional accessors infallible: `quote_to_base` is `1 / high`, and one divided by `2e28` or more rounds away to zero. Rejecting it at the door removes the `Result` from every accessor. - `Market::low()` / `high()` — the two prices. - `Market::base_to_quote()` / `quote_to_base()` — infallible `ExchangeRate`s. - `Market::convert(Money)` — reads the money's currency and picks the side. Fails when the money is in neither of the pair's currencies. The existing `ConvertError::CurrencyMismatch` text assumes a single base currency and reads wrong here; it needs rewording or a variant of its own. - `Market::invert()` — total, no `Result`. `low' = 1/high`, `high' = 1/low`. Ordering survives because `low <= high`. Both bounds survive too: `Decimal`'s smallest positive is `1e-28`, so `1/low` is at most `1e28`, under the `2e28` bound. Worth a doc line, since it isn't visible in the signature. - `Market::cross_with(Market)` — returns a `Market`. Spreads compound: low times low, high times high. The wider result is the honest cost of two hops, not an invention. - `Market::flat(pair, rate)` — the no-spread market, `low == high`. - `MarketError` — `InvalidPrice` (a price at or below zero), `Crossed` (low above high), `Underflow` (high at or above `2e28`, leaving no price the other way). `Underflow` deliberately repeats the word `InvertError` already uses for the same mechanism; the message carries the difference and should name the offending high price. - `Quotation` — `OneWay(ExchangeRate)` / `TwoWay(Market)`. Its doc comment must say which axis it names: one-way versus two-way, *not* the direct versus indirect quotation distinction an FX reader may expect. - `Exchange` — `set_rate` and `set_market` write; `rate(pair)` answers a directional rate whichever kind is stored; `quotation(pair)` answers the entry; `remove_quotation(pair)` takes the whole entry. `len()` counts quotations, so a two-way pair counts once. `Rates` and `IntoRates` become `Quotations` and `IntoQuotations`, yielding `Quotation`. - `ExchangeError` — a new variant for a pair that is quoted, but not in the direction asked. Distinct from `Unquoted`: a half-filled board is a different fact from an empty one, and it gives triangulation something precise to catch later. - `Display` for `Market` — `USD/EUR 1.0850/1.0855`. Unambiguous to read back, since a pair already takes the first slash as its divider. - Serde — a table value is always an object: `{"rate": 144}` for one-way, `{"low": 0.85, "high": 0.86}` for two-way. Standalone `Market` is `{base, quote, low, high}`, matching `ExchangeRate`'s existing shape. `Quotation` serializes untagged, so the enum never appears in a document. - `set_rate_both_ways` is removed. Its documentation exists only to explain that it is the no-spread case and that a desk charging a spread should do something else; a zero-spread `Market` says both, and the prose deletes itself. **Acceptance criteria:** - [ ] `Market` cannot be constructed with a low price above its high, with a price at or below zero, or with a high price at or above `2e28`, and each refusal is its own `MarketError` variant naming the offending number. - [ ] Neither directional accessor on `Market` returns a `Result`. - [ ] `Market::invert()` returns a `Market` with no `Result`, and a property test shows the ordering holds for any constructible market. - [ ] A property test shows that for any constructible `Market`, converting an amount out and back never returns more than it started with. - [ ] `Market::cross_with` returns a market whose spread is at least as wide as either input's. - [ ] `Exchange::len()` counts quotations: a table holding one two-way pair reports `1`. - [ ] A market quoted as `USD/EUR` answers `rate((EUR, USD))` and converts EUR into USD. - [ ] Setting a one-way rate over one direction of a two-way pair leaves no trace of the other direction. - [ ] Converting a direction that a one-way quotation does not price gives the new `ExchangeError` variant, not `Unquoted`. - [ ] `Market` round-trips through serde, and a table mixing one-way and two-way entries round-trips. - [ ] `Market` displays as `USD/EUR 1.0850/1.0855`. - [ ] `set_rate_both_ways` no longer exists. - [ ] `mise run fmtcheck`, `mise run ci`, and `mise run clippy` pass. **Out of scope:** - Triangulation (#47), dated rates (#48), and the provider trait (#49). - Recording that a crossed rate was derived rather than quoted. Provenance belongs to the dated-rate and provider work; half a provenance system built here would be in the wrong place. - Rewriting the hand-written serde visitors. #34 wants them replaced by derives, and this work necessarily adds to them — leave that swap to #34 rather than doing half of it here. - Folding `ExchangeRate` into `Market`. It was considered and rejected: a one-way quotation must stay expressible, and a single required-both-sides type would make every reverse conversion succeed at a price nobody offered. **Two naming notes for whoever picks this up:** `Quotation` is a near-neighbour of the noun #16 was closed to reserve. It earns its place because it names something `Rates` cannot — an entry that may price one direction or two — where the old `Quotes` was only ever a second word for rates. This is not a reversal of #16. `Crossed` (a market whose low is above its high) and `cross_with` (combining two rates through a shared currency) are unrelated senses of the same word. Both are standard finance terms, so both stay, but the doc comments should keep them apart rather than let a reader assume they are related.
rosa closed this issue 2026-08-20 17:41:11 +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#50
No description provided.