An exchange cannot say what a pair was priced at last month #48

Closed
opened 2026-08-18 00:39:06 +00:00 by rosa · 2 comments
Owner

Problem

Exchange stores one quotation per pair and no time. An invoice dated last
month has to be restated at the price in effect then, and the table cannot
answer that. Feeds carry the moment of the quotation, so the information exists
and is dropped: the Quotation deserializer already skips an as_of field.

Proposal

A History beside Exchange, holding every quotation a table has held, each
filed under the Timestamp it was made at. Reading a history at a moment gives
a plain Exchange.

Depends on #55, which adds Timestamp.

Settled in triage

  • History sits beside Exchange rather than replacing it, so the plain table
    stays as simple as it is now. It also means #47's triangulation lands once,
    on Exchange, and a history inherits it.
  • Entries are keyed by moment, not by day. Turning an invoice date into a
    moment is the caller's policy.
  • Quotation gains no field. A timestamp on it would change equality,
    ordering, and the wire format for callers who have no use for one, and would
    undo the compatibility ADR 0002 kept.
  • A lookup returns the newest quotation at or before the asked moment, and
    nothing at all before the earliest.
  • Both directions of a pair share one entry per moment, as they do in
    Exchange.
  • A history reads and writes a flat list of entries, which is the shape feeds
    ship. This is what finally reads the as_of field.
  • A history does not convert amounts. Reading it at a moment gives an
    Exchange, which does.

CONTEXT.md defines History and Timestamp.

Out of scope

Triangulation (#47), the provider trait (#49), and two-sided quotes (#50).

## Problem `Exchange` stores one quotation per pair and no time. An invoice dated last month has to be restated at the price in effect then, and the table cannot answer that. Feeds carry the moment of the quotation, so the information exists and is dropped: the `Quotation` deserializer already skips an `as_of` field. ## Proposal A `History` beside `Exchange`, holding every quotation a table has held, each filed under the `Timestamp` it was made at. Reading a history at a moment gives a plain `Exchange`. Depends on #55, which adds `Timestamp`. ## Settled in triage - `History` sits beside `Exchange` rather than replacing it, so the plain table stays as simple as it is now. It also means #47's triangulation lands once, on `Exchange`, and a history inherits it. - Entries are keyed by moment, not by day. Turning an invoice date into a moment is the caller's policy. - `Quotation` gains no field. A timestamp on it would change equality, ordering, and the wire format for callers who have no use for one, and would undo the compatibility ADR 0002 kept. - A lookup returns the newest quotation at or before the asked moment, and nothing at all before the earliest. - Both directions of a pair share one entry per moment, as they do in `Exchange`. - A history reads and writes a flat list of entries, which is the shape feeds ship. This is what finally reads the `as_of` field. - A history does not convert amounts. Reading it at a moment gives an `Exchange`, which does. `CONTEXT.md` defines **History** and **Timestamp**. ## Out of scope Triangulation (#47), the provider trait (#49), and two-sided quotes (#50).
Author
Owner

Agent Brief

Category: enhancement
Summary: Add History, a table of every quotation a pair has held over
time, which reads at a moment as a plain Exchange.

Blocked on #55, which adds Timestamp. Do not start until that lands.

Current behavior:

Exchange holds one quotation per currency pair, keyed by the two currencies
sorted, so either direction names the same entry. Nothing records when a
quotation was made. A caller restating a month-old invoice has to keep a
separate table per date themselves. The Quotation deserializer documents that
it skips fields it does not know, naming a time field as the example, so a feed
document's as_of is read and discarded.

Desired behavior:

lucre::exchange::History holds many quotations per pair, each filed under the
Timestamp it was made at. Its lookups take a moment and answer with what was
in effect then: the newest quotation at or before that moment, and nothing at
all for a moment before the pair's earliest. A moment with no quotation for
that pair is not an error, just an absence — a weekend reads Friday's price.

Reading a history at a moment gives an owned Exchange holding, for each pair,
the quotation in effect then. Pairs with nothing yet quoted are absent from it.

Key interfaces:

  • History — same derives Exchange carries. Entries key on the pair's two
    currencies sorted, together with the moment, so a quotation over EUR/USD
    displaces one over USD/EUR at the same moment.
  • Setting a quotation at a moment hands back whatever that pair held at that
    exact moment, as Exchange's setter does. Setting never fails.
  • A method taking a moment and returning an owned Exchange.
  • Lookups by pair and moment, mirroring the two Exchange has: one giving the
    quotation as stored, one giving the price for the asked direction as a
    one-way quotation. Both return Option.
  • Removal and emptying, and the measurement and iteration Exchange gained in
    #6 and #9. Iteration order should be pair order, then moment.
  • Extend, FromIterator, and From<[_; N]> over (Timestamp, Quotation)
    tuples, matching what #6 gave Exchange over anything Into<Quotation>.
  • Serialize and Deserialize behind the serde feature, in the crate's
    single serde module. The wire shape is a flat list of entries, each naming
    the moment alongside the pair and its price or prices: {"as_of": "...", "base": "USD", "quote": "EUR", "rate": "0.9"}. A list, not a map, because a
    pair appears many times. Reuse the private reader that already reads a
    quotation's fields rather than writing a second one.
  • The Quotation deserializer's doc calls the field it skips "the time of the
    quote". CONTEXT.md reserves quote for the currency alone, so reword it to
    say the moment the price was made. Whether Quotation still skips the field
    is unchanged — it does.

Acceptance criteria:

  • A history holding one pair at two moments answers each with its own
    quotation, and answers a moment between them with the earlier one.
  • A moment before a pair's earliest quotation answers None, for both
    lookups.
  • Setting a quotation at a moment the pair already holds hands back the
    displaced quotation; setting at a new moment hands back None.
  • A quotation over EUR/USD and one over USD/EUR at the same moment are
    one entry, and the second displaces the first.
  • Reading at a moment gives an Exchange that converts, iterates, and
    serializes exactly as one built by hand from the same quotations.
  • A history round-trips through JSON, and reading a feed document that
    names as_of on every entry produces the expected history.
  • Exchange is unchanged, and Quotation gains no field and no method.
  • mise run ci passes. Clippy and the tests run twice, with no features
    and with all of them.
  • docs/agents/codebase-map.md lists the new module.

Out of scope:

  • Any conversion method on History. Callers read it at a moment and convert
    through the Exchange that comes back.
  • Triangulation (#47), the provider trait (#49), two-sided quotes (#50).
  • Changing Exchange's wire format, which stays a map keyed by pair.
  • Any interpolation between two quotations, or any rule that carries a price
    forward with an expiry.
## Agent Brief **Category:** enhancement **Summary:** Add `History`, a table of every quotation a pair has held over time, which reads at a moment as a plain `Exchange`. **Blocked on #55**, which adds `Timestamp`. Do not start until that lands. **Current behavior:** `Exchange` holds one quotation per currency pair, keyed by the two currencies sorted, so either direction names the same entry. Nothing records when a quotation was made. A caller restating a month-old invoice has to keep a separate table per date themselves. The `Quotation` deserializer documents that it skips fields it does not know, naming a time field as the example, so a feed document's `as_of` is read and discarded. **Desired behavior:** `lucre::exchange::History` holds many quotations per pair, each filed under the `Timestamp` it was made at. Its lookups take a moment and answer with what was in effect then: the newest quotation at or before that moment, and nothing at all for a moment before the pair's earliest. A moment with no quotation for that pair is not an error, just an absence — a weekend reads Friday's price. Reading a history at a moment gives an owned `Exchange` holding, for each pair, the quotation in effect then. Pairs with nothing yet quoted are absent from it. **Key interfaces:** - `History` — same derives `Exchange` carries. Entries key on the pair's two currencies sorted, together with the moment, so a quotation over `EUR/USD` displaces one over `USD/EUR` at the same moment. - Setting a quotation at a moment hands back whatever that pair held at that exact moment, as `Exchange`'s setter does. Setting never fails. - A method taking a moment and returning an owned `Exchange`. - Lookups by pair and moment, mirroring the two `Exchange` has: one giving the quotation as stored, one giving the price for the asked direction as a one-way quotation. Both return `Option`. - Removal and emptying, and the measurement and iteration `Exchange` gained in #6 and #9. Iteration order should be pair order, then moment. - `Extend`, `FromIterator`, and `From<[_; N]>` over `(Timestamp, Quotation)` tuples, matching what #6 gave `Exchange` over anything `Into<Quotation>`. - `Serialize` and `Deserialize` behind the `serde` feature, in the crate's single serde module. The wire shape is a flat list of entries, each naming the moment alongside the pair and its price or prices: `{"as_of": "...", "base": "USD", "quote": "EUR", "rate": "0.9"}`. A list, not a map, because a pair appears many times. Reuse the private reader that already reads a quotation's fields rather than writing a second one. - The `Quotation` deserializer's doc calls the field it skips "the time of the quote". `CONTEXT.md` reserves *quote* for the currency alone, so reword it to say the moment the price was made. Whether `Quotation` still skips the field is unchanged — it does. **Acceptance criteria:** - [ ] A history holding one pair at two moments answers each with its own quotation, and answers a moment between them with the earlier one. - [ ] A moment before a pair's earliest quotation answers `None`, for both lookups. - [ ] Setting a quotation at a moment the pair already holds hands back the displaced quotation; setting at a new moment hands back `None`. - [ ] A quotation over `EUR/USD` and one over `USD/EUR` at the same moment are one entry, and the second displaces the first. - [ ] Reading at a moment gives an `Exchange` that converts, iterates, and serializes exactly as one built by hand from the same quotations. - [ ] A history round-trips through JSON, and reading a feed document that names `as_of` on every entry produces the expected history. - [ ] `Exchange` is unchanged, and `Quotation` gains no field and no method. - [ ] `mise run ci` passes. Clippy and the tests run twice, with no features and with all of them. - [ ] `docs/agents/codebase-map.md` lists the new module. **Out of scope:** - Any conversion method on `History`. Callers read it at a moment and convert through the `Exchange` that comes back. - Triangulation (#47), the provider trait (#49), two-sided quotes (#50). - Changing `Exchange`'s wire format, which stays a map keyed by pair. - Any interpolation between two quotations, or any rule that carries a price forward with an expiry.
rosa changed title from A rate table cannot say what the rate was on a given date to An exchange cannot say what a pair was priced at last month 2026-08-21 23:17:32 +00:00
Author
Owner

I changed my mind about #55, I will just use the time crate as part of the public API.

I changed my mind about #55, I will just use the `time` crate as part of the public API.
rosa closed this issue 2026-08-22 14:40:02 +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#48
No description provided.