Nothing in the crate names a moment in time #55

Closed
opened 2026-08-21 23:14:00 +00:00 by rosa · 2 comments
Owner

Problem

The crate names no point in time. #48 needs to file each quotation under the
moment it was made, and there is no type for that moment. No dependency
supplies one either: jiff, chrono, and time are all below 1.0, so putting
any of them in the public API binds this crate's breaking releases to theirs.

Proposal

A Timestamp in the exchange module: a point in UTC, ordered, read and
written as RFC 3339. Conversion to and from jiff, chrono, and time sits
behind an optional feature each.

Settled in triage. docs/adr/0004-a-timestamp-is-the-crates-own-type.md
records why the crate writes the type rather than taking one, and CONTEXT.md
defines the term.

Out of scope

History and dated lookup, which are #48. Calendar arithmetic, durations,
timezone conversion, and formatting options — a caller who needs those has a
date library already.

## Problem The crate names no point in time. #48 needs to file each quotation under the moment it was made, and there is no type for that moment. No dependency supplies one either: `jiff`, `chrono`, and `time` are all below 1.0, so putting any of them in the public API binds this crate's breaking releases to theirs. ## Proposal A `Timestamp` in the `exchange` module: a point in UTC, ordered, read and written as RFC 3339. Conversion to and from `jiff`, `chrono`, and `time` sits behind an optional feature each. Settled in triage. `docs/adr/0004-a-timestamp-is-the-crates-own-type.md` records why the crate writes the type rather than taking one, and `CONTEXT.md` defines the term. ## Out of scope `History` and dated lookup, which are #48. Calendar arithmetic, durations, timezone conversion, and formatting options — a caller who needs those has a date library already.
Author
Owner

Agent Brief

Category: enhancement
Summary: Add Timestamp, a UTC point in time read and written as RFC 3339,
in the exchange module.

Current behavior:

Nothing in the crate names a point in time. Quotation holds a pair and its
prices with no notion of when it was made, and the Quotation deserializer
documents that it skips any field it does not know, naming the time the price
was observed as an example. No dependency supplies a date type, and none should
— jiff (0.2), chrono (0.4), and time (0.3) are all below 1.0.

Desired behavior:

lucre::exchange::Timestamp names one moment in UTC. It orders, compares,
prints, and reads RFC 3339, and does nothing else. Callers who need calendar
arithmetic, durations, timezone conversion, or formatting options use the date
library they already have and convert.

Reading accepts a full RFC 3339 string with any offset and normalizes it to
UTC, because feeds publish in local time. Writing always ends in Z.

Four inputs are refused rather than repaired:

  • A bare date, such as 2026-08-14. A day holds many moments, and choosing one
    is the caller's policy.
  • More than nine fractional digits, since truncating loses what the document
    stated.
  • A leap second, :60, so ordering stays total.
  • A year outside 1 through 9999.

The year bound is what makes Display and serialization total: RFC 3339 output
is always four digits, so no accessor returns a Result. This is the trade ADR
0002 made for prices, applied here.

Key interfaces:

  • Timestamp — Copy, Clone, Debug, Eq, Ord, Hash. Ordering is by
    the moment, so a BTreeMap keyed by it ranges correctly. Debug should
    print the moment, following the precedent set by #27 for Pair.
  • Construction from parts, and from a count of seconds and nanoseconds since
    the Unix epoch, each returning a Result with one error type in the shape
    the crate's other errors take (thiserror plus miette::Diagnostic, a
    variant per rejection above, each carrying what it read — see #13 and #19).
  • FromStr and Display, matching how Pair and Currency read and print
    text. Display writes RFC 3339 ending in Z.
  • Serialize and Deserialize behind the serde feature, in the crate's
    single serde module, writing the same text Display does.
  • Three new optional dependencies, each behind a feature of the same name:
    jiff, chrono, time. Each gives From/TryFrom both ways against that
    crate's UTC instant type. These were approved in triage; do not add any
    other dependency.

Acceptance criteria:

  • Timestamp parses 2026-08-14T16:00:00Z, 2026-08-14T18:00:00+02:00,
    and 2026-08-14T16:00:00.123456789Z, and the first two compare equal.
  • Display and Serialize write the same RFC 3339 text, always ending in
    Z, and a value round-trips through both.
  • Parsing refuses a bare date, a tenth fractional digit, a leap second, and
    a year of 0 or 10000, each with its own error variant naming what it read.
  • Sorting timestamps orders them by moment, and a BTreeMap keyed by
    Timestamp returns the expected entries from a ..= range.
  • Each of the jiff, chrono, and time features converts both ways
    without losing a nanosecond, and the crate builds with each on alone.
  • 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 and the three new
    features.

Out of scope:

  • History and dated lookup. That is #48, which builds on this.
  • Any change to Quotation, Exchange, or Pair. Quotation gains no
    timestamp field; the history keys on one instead.
  • Calendar arithmetic, durations, timezone conversion, formatting options, and
    parsing any format other than RFC 3339.
  • Timestamp at the crate root. Triage settled that it lives in the exchange
    module, because that is the only thing that uses it and the crate is not
    offering a general datetime.
## Agent Brief **Category:** enhancement **Summary:** Add `Timestamp`, a UTC point in time read and written as RFC 3339, in the `exchange` module. **Current behavior:** Nothing in the crate names a point in time. `Quotation` holds a pair and its prices with no notion of when it was made, and the `Quotation` deserializer documents that it skips any field it does not know, naming the time the price was observed as an example. No dependency supplies a date type, and none should — `jiff` (0.2), `chrono` (0.4), and `time` (0.3) are all below 1.0. **Desired behavior:** `lucre::exchange::Timestamp` names one moment in UTC. It orders, compares, prints, and reads RFC 3339, and does nothing else. Callers who need calendar arithmetic, durations, timezone conversion, or formatting options use the date library they already have and convert. Reading accepts a full RFC 3339 string with any offset and normalizes it to UTC, because feeds publish in local time. Writing always ends in `Z`. Four inputs are refused rather than repaired: - A bare date, such as `2026-08-14`. A day holds many moments, and choosing one is the caller's policy. - More than nine fractional digits, since truncating loses what the document stated. - A leap second, `:60`, so ordering stays total. - A year outside 1 through 9999. The year bound is what makes `Display` and serialization total: RFC 3339 output is always four digits, so no accessor returns a `Result`. This is the trade ADR 0002 made for prices, applied here. **Key interfaces:** - `Timestamp` — `Copy`, `Clone`, `Debug`, `Eq`, `Ord`, `Hash`. Ordering is by the moment, so a `BTreeMap` keyed by it ranges correctly. `Debug` should print the moment, following the precedent set by #27 for `Pair`. - Construction from parts, and from a count of seconds and nanoseconds since the Unix epoch, each returning a `Result` with one error type in the shape the crate's other errors take (`thiserror` plus `miette::Diagnostic`, a variant per rejection above, each carrying what it read — see #13 and #19). - `FromStr` and `Display`, matching how `Pair` and `Currency` read and print text. `Display` writes RFC 3339 ending in `Z`. - `Serialize` and `Deserialize` behind the `serde` feature, in the crate's single serde module, writing the same text `Display` does. - Three new optional dependencies, each behind a feature of the same name: `jiff`, `chrono`, `time`. Each gives `From`/`TryFrom` both ways against that crate's UTC instant type. These were approved in triage; do not add any other dependency. **Acceptance criteria:** - [ ] `Timestamp` parses `2026-08-14T16:00:00Z`, `2026-08-14T18:00:00+02:00`, and `2026-08-14T16:00:00.123456789Z`, and the first two compare equal. - [ ] `Display` and `Serialize` write the same RFC 3339 text, always ending in `Z`, and a value round-trips through both. - [ ] Parsing refuses a bare date, a tenth fractional digit, a leap second, and a year of 0 or 10000, each with its own error variant naming what it read. - [ ] Sorting timestamps orders them by moment, and a `BTreeMap` keyed by `Timestamp` returns the expected entries from a `..=` range. - [ ] Each of the `jiff`, `chrono`, and `time` features converts both ways without losing a nanosecond, and the crate builds with each on alone. - [ ] `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 and the three new features. **Out of scope:** - `History` and dated lookup. That is #48, which builds on this. - Any change to `Quotation`, `Exchange`, or `Pair`. `Quotation` gains no timestamp field; the history keys on one instead. - Calendar arithmetic, durations, timezone conversion, formatting options, and parsing any format other than RFC 3339. - `Timestamp` at the crate root. Triage settled that it lives in the `exchange` module, because that is the only thing that uses it and the crate is not offering a general datetime.
Author
Owner

Changed my mind, I'm just going to use the time crate.

Changed my mind, I'm just going to use the `time` crate.
rosa closed this issue 2026-08-22 13:54:05 +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#55
No description provided.