Add a `Portfolio` contract to lawsynth-quant: an ordered, single-currency book of `Lot`s that aggregates exact cost basis, mark-to-market value, gross notional, and unrealized P&L. Every total reuses `Money`'s overflow-checked integer algebra, so figures are exact — no rounding, no binary floating point, no silent wrapping. Marks are supplied by a caller per-instrument resolver, so the portfolio never sources or infers a price; an unpriced instrument is rejected rather than defaulted to zero. Foreign-currency lots and mark currency mismatches are rejected, never silently converted. Adds a deterministic versioned byte encoding (`LSQF1`) with a length-prefixed lot sequence and a strict decoder that rejects unknown versions, truncation, over-large lot counts, currency drift, and trailing bytes. Promotes the "multi-instrument portfolio aggregation" item that the Lot slice deferred; realized P&L, lot-matched fill accounting, FX, financing, and fees remain out of scope. Updates the quant-foundation spec + changelog and adds a new `MissingMark` error variant. 5 new tests (18 total pass); clippy -D warnings and rustfmt clean.
Quant foundation boundary
Status: QR0 implementation slice 1. This specification covers the exact money,
observation-identity, single-position valuation, exact mark-to-market
profit-and-loss, and single-currency multi-instrument portfolio-aggregation
primitives compiled in lawsynth-quant. Trading calendars, corporate actions,
market-data tables, realized-P&L and lot-matched fill accounting, leakage checks,
fixture licensing, and complete experiment manifests remain unimplemented and
MUST NOT be claimed from this initial slice.
Money
Currency is a versioned closed set for the initial end-of-day research
boundary: USD, EUR, TRY, GBP, CHF, and JPY. Unknown codes are rejected rather
than guessed. Each currency defines its ISO-style minor-unit exponent: JPY uses
zero and the others use two.
Money stores a signed i128 count of minor units plus one Currency. It never
uses binary floating point. Addition and subtraction MUST reject currency
mismatches and arithmetic overflow. Negation, absolute value, and exact integer
scaling (for example a quantity of units) preserve the currency and MUST likewise
reject overflow rather than wrapping, including the single i128::MIN boundary.
Scaling is by an integer factor only: it introduces no rounding and no fractional
minor units. Callers are responsible for supplying a separate, sourced FX
conversion policy; the crate does not silently convert.
Canonical money bytes are:
"LSQM1" | 3-byte currency code | signed i128 minor units (big endian)
Readers reject unknown versions, unsupported currencies, and any trailing or missing bytes.
Observation identity
UtcTimestamp is a signed Unix millisecond count. It represents an already
resolved UTC instant: local wall time, daylight-saving rules, exchange sessions,
and observation cutoffs are deliberately not inferred.
ObservationKey combines a validated portable instrument identifier, one UTC
timestamp, and a sequence number. The sequence makes multiple events at one
millisecond explicit. Ordering is lexicographic by instrument, timestamp, then
sequence.
Canonical observation bytes are:
"LSQO1" | u16 instrument-byte length (big endian) | instrument UTF-8
| signed i64 Unix milliseconds (big endian) | u32 sequence (big endian)
Instrument identifiers use the existing lawsynth-core::Identifier grammar and
are limited to 65,535 bytes by this encoding. Decoders reject malformed UTF-8,
invalid identifiers, length mismatches, unknown versions, and trailing bytes.
Position
Direction is the net sign of a holding: long, short, or flat. Position
combines a validated portable instrument identifier with a signed i64 unit
count. It never uses binary floating point.
Valuation reuses the exact Money integer algebra rather than defining a second
one. At a per-unit Money price:
market_valueis exactlyprice * quantity(overflow-checked scaling).notionalis its absolute magnitude, ignoring sign.establish_cash_flowis its negation: going long is a cash outflow, going short is an inflow.
combine nets two holdings of the same instrument by adding signed quantities;
it rejects a differing instrument and rejects quantity overflow. reverse
returns the offsetting position that flattens this one, rejecting the single
i64::MIN boundary rather than wrapping. No FX conversion, price sourcing, or
rounding is introduced; multi-instrument portfolio aggregation is out of scope.
Canonical position bytes are:
"LSQP1" | u16 instrument-byte length (big endian) | instrument UTF-8
| signed i64 quantity (big endian)
Decoders reject malformed UTF-8, invalid identifiers, length mismatches, unknown versions, and trailing bytes.
Lot and mark-to-market P&L
A Lot is one executed Position paired with a per-unit Money entry price: the
smallest unit of profit-and-loss accounting. Both its cost basis and its mark
profit reuse the exact Money integer algebra rather than defining a second one,
so P&L introduces no rounding, no binary floating point, and no silent wrapping.
At a per-unit Money mark price:
entry_valueis the signed cost basis, exactlyentry_price * quantity.market_valueis the signed current value, exactlymark * quantity.unrealized_pnlis exactlyquantity * (mark - entry_price). The per-unit price move is taken with overflow-checked subtraction, so a currency mismatch between the mark and the entry price is rejected rather than converted. The signed quantity makes the result correct in both directions: a long profits when the mark rises, a short profits when it falls.
Realized P&L, average-cost or lot-matched accumulation across multiple fills, FX
conversion, financing, and fees are out of scope for this slice; multi-instrument
aggregation is provided by Portfolio below.
Canonical lot bytes are:
"LSQL1" | 24-byte entry-price money segment ("LSQM1"...) | position bytes ("LSQP1"...)
The fixed-width entry price precedes the variable-length position so the decoder can split the two without a separate length prefix. Decoders reject unknown versions, truncated input, and any malformed money or position segment.
Portfolio aggregation
A Portfolio is an ordered book of Lots that all report in one currency: the
first multi-instrument aggregation in this foundation. Every total reuses the
exact Money integer algebra rather than defining a second one, so a portfolio
figure introduces no rounding, no binary floating point, and no silent wrapping.
Construction fixes the single reporting currency. with_lot returns a new
portfolio with the lot appended (order preserved), and from_lots builds one
from an ordered sequence. A lot whose entry price is not in the portfolio
currency is rejected rather than silently converted; there is no FX in this
slice.
Mark-to-market lookups are supplied by the caller as a per-instrument resolver, so the portfolio never sources or infers a price. An instrument the resolver cannot price is rejected rather than defaulted to zero. Against those marks:
cost_basisis the exact sum of every lot's entry value; an empty portfolio is exactly zero in its currency.market_valueis the exact sum of every lot'smark * quantity.gross_notionalis the exact sum of every lot's absolute exposure, so long and short magnitudes add rather than cancel.unrealized_pnlis the exact sum of every lot'squantity * (mark - entry). A currency mismatch between a mark and its lot is rejected, and any summation or scaling overflow surfaces as an error rather than wrapping.
Canonical portfolio bytes are:
"LSQF1" | 3-byte currency code | u32 lot count (big endian)
| repeated { u32 lot-byte length (big endian) | lot bytes ("LSQL1"...) }
Each lot carries a length prefix so the variable-length lots are self-delimiting. Decoders reject unknown versions, unsupported currencies, a truncated header, truncated length prefixes or lot segments, a lot count larger than the payload, a lot whose currency differs from the portfolio, and any trailing bytes. Marks are transient inputs and are not part of the encoded state. Realized P&L, lot-matched fill accounting, FX conversion, financing, and fees remain out of scope.
Determinism and non-goals
Encoding is independent of locale, machine endianness, wall clock, and hash-map
order. stable_fingerprint is the existing deterministic FNV-1a identifier for
fixtures and in-process comparisons; it is not a cryptographic checksum and
MUST NOT replace SHA-256 in governed experiment artifacts.
This slice does not define prices, returns, asset identifiers, trading days, day-count conventions, FX rates, rounding policy, realized-P&L or lot-matched fill accounting, or live market connectivity. Portfolio aggregation is limited to single-currency valuation totals over the lots a caller supplies.