From 42e0854b1988d4d056d3597a92b343f8a046f8e3 Mon Sep 17 00:00:00 2001 From: PureSaber Date: Mon, 12 Oct 2026 00:51:40 +0800 Subject: [PATCH 1/2] Add exact shared-capital continuous research and settlement scheduling --- README.md | 3 + docs/SHARED_CAPITAL.md | 80 ++++ pyproject.toml | 2 +- requirements.lock | 2 +- src/quant_execution/continuous.py | 621 ++++++++++++++++++++++++++++++ tests/test_continuous.py | 226 +++++++++++ 6 files changed, 932 insertions(+), 2 deletions(-) create mode 100644 docs/SHARED_CAPITAL.md create mode 100644 src/quant_execution/continuous.py create mode 100644 tests/test_continuous.py diff --git a/README.md b/README.md index e24f08c..d313e23 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # quant-execution +The additive [shared-capital research account](docs/SHARED_CAPITAL.md) supports +continuous sleeve allocation, explicit settlement/FX, margin states and checkpoints. + 研究可信度升级:接口、使用示例、验收及限制见 [11–20 使用说明](docs/CONTINUOUS_REPLAY.md)。 Hong Kong daily cash-equity research is available through diff --git a/docs/SHARED_CAPITAL.md b/docs/SHARED_CAPITAL.md new file mode 100644 index 0000000..a8fc757 --- /dev/null +++ b/docs/SHARED_CAPITAL.md @@ -0,0 +1,80 @@ +# Shared capital continuous research + +`quant_execution.continuous.SharedCapitalAccount` is an additive, offline API. +It owns one authoritative `ExactAccountLedger`. Sleeve attribution books receive +disjoint cash allocations whose sum is the total account's opening cash. Fills, +fees, FX conversions and outside flows post to both the total ledger and the +owning attribution book; transfers post only to the two attribution books with +offsetting clearing entries. Attribution books never create additional NAV or +buying power. Per-currency cash, instrument quantities, NAV and every balanced +transaction are reconciled after every accepted event. + +Construct the account using QDK `InstrumentSpec` objects, `owners` mapping each +instrument to exactly one sleeve, `allocations` mapping sleeves to currency cash, +`base_currency`, UTC `opened_at`, and explicit `fx_rates` to base. Only cash +equities/ETFs (long only) and linear futures are supported. Futures require explicit +`initial_margin_rate` and `maintenance_margin_rate`, each positive and at most one. +One instrument cannot be netted across sleeves. No broker, market impact, order +matching, automatic liquidation, inverse derivative, option, tax or corporate +action inference is provided. The caller declares actual research fills and fees. + +Every event has `event_id`, UTC `at`, UTC `available_at <= at`, nonnegative integer +`sequence` and `kind`. Unknown fields are rejected. Money/price/quantity values +are exact decimal strings (or integers), with at most eight decimal places. + +| kind | Additional fields | +| --- | --- | +| mark | instrument_id, price | +| fx_mark | currency, rate (base currency units per currency unit) | +| fill | sleeve, instrument_id, signed quantity, price, nonnegative fee, settles_at; optional order_id | +| settle | none; releases holds matured at this instant | +| transfer | source sleeve, target sleeve, currency, positive amount | +| external_cash | sleeve, currency, signed nonzero amount | +| fx_convert | sleeve, source_currency, target_currency, positive source_amount, target_amount | +| charge | sleeve, instrument_id, nonnegative amount in settlement currency | +| variation_margin | sleeve, instrument_id, price, signed amount (checked by QExec against futures PnL) | + +```python +account.apply({ + "event_id": "buy-1", "kind": "fill", "sleeve": "trend", + "instrument_id": "ETF-A", "quantity": "5", "price": "100", "fee": "1", + "at": "2026-01-02T10:00:00Z", "available_at": "2026-01-02T10:00:00Z", + "sequence": 3, "settles_at": "2026-01-05T10:00:00Z", +}) +``` + +`replay(events)` sorts a batch by `(at, sequence)`. `apply` requires strict order +across chunks. Exact same-ID retries are no-ops; conflicting IDs or tied keys +fail. Each event is atomic, including failed ledger postings. A failed batch +leaves its previously accepted events, so use checkpoint restore for a clean retry. +`checkpoint()` binds the accepted journal and the full opening configuration +(instrument terms, owners, allocations, currency, time, FX). `restore` on a fresh +account verifies that identity before applying any event; failed restore is atomic. + +Purchased cash units cannot be sold before settlement. Sale proceeds count in NAV +but cannot be spent, converted or transferred until their declared settlement. +Buys and fees debit cash immediately. Due holds release before each event and are +listed in history; no holiday calendar is silently inferred. Reinvestment uses +the resulting settled balances. Futures positive unrealized PnL is unavailable +until variation settlement; negative unrealized PnL reduces collateral immediately. +No cross-currency collateral credit is allowed; use explicit funded FX conversion. +The difference between actual conversion amounts and marked FX changes economic +PnL, never external flows. Internal transfers are PnL-neutral. + +`initial_margin_shortfall` uses initial margin and blocks increased risk. +`margin_call` uses maintenance margin. Marks, charges and variation settlement are +economic facts: losses are retained and calls exposed. Explicit risk reductions, +positive deposits and internal transfers may partly cure a deficit if no affected +budget deficit worsens; there is no automatic trade or account recovery. + +History records external-flow-adjusted event returns; cumulative return is their +product. A nonpositive prior NAV makes the subsequent return unavailable. Economic +PnL remains final NAV minus initial NAV minus contemporaneously FX-valued external +flows. Cash/units reconcile exactly; summed base NAV may differ by at most one +1e-8 rounding quantum per sleeve. Tests use separate Decimal scalar expectations +for cash, FX, futures and PnL, plus shared-cash competition and chunk identity. + +The portfolio `continuous-study` CLI supplies a frozen notional-to-lot policy, +next-observation declared executions, immutable revision pairs and the common +measurement declaration. Existing QExec APIs and schema versions are unchanged. +Rollback is a revert of this additive module and its consumers; preserve outputs. diff --git a/pyproject.toml b/pyproject.toml index b63d5dc..9086aa8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,7 +12,7 @@ requires-python = ">=3.10" dependencies = [ "pyarrow>=14.0", "jsonschema>=4.20", - "quant-data-kit @ git+https://github.com/PureSaber/quant-data-kit.git@f49f1cc306a4a27a2734e21c89ec5b68f7d7384d", + "quant-data-kit @ git+https://github.com/PureSaber/quant-data-kit.git@f85128307dd0e3407d24350282fe7b679b591309", ] [project.optional-dependencies] diff --git a/requirements.lock b/requirements.lock index 7ec269a..e39e3f3 100644 --- a/requirements.lock +++ b/requirements.lock @@ -69,7 +69,7 @@ pytz==2026.3.post1 # via pandas pyyaml==6.0.3 # via quant-data-kit -quant-data-kit @ git+https://github.com/PureSaber/quant-data-kit.git@f49f1cc306a4a27a2734e21c89ec5b68f7d7384d +quant-data-kit @ git+https://github.com/PureSaber/quant-data-kit.git@f85128307dd0e3407d24350282fe7b679b591309 # via quant-execution (pyproject.toml) referencing==0.37.0 # via diff --git a/src/quant_execution/continuous.py b/src/quant_execution/continuous.py new file mode 100644 index 0000000..086fa70 --- /dev/null +++ b/src/quant_execution/continuous.py @@ -0,0 +1,621 @@ +"""Finite, offline shared-capital research on the existing exact QExec ledger. + +One economic account, with disjoint attribution books whose opening allocations +sum to its cash. Attribution books are never additional buying power. Instruments +have a fixed sleeve owner; there are no cross-sleeve position/margin offsets. +""" + +from __future__ import annotations + +import hashlib +import json +from copy import deepcopy +from dataclasses import replace +from decimal import Decimal, localcontext + +from quant_data_kit import AssetClass, FixedPoint, MarkPriceEvent +from quant_data_kit.artifacts import canonical_json +from quant_data_kit.domain_v2 import dataclass_payload +from quant_data_kit.temporal_v2 import ensure_utc_datetime, parse_timestamp_exact + +from .contracts import Fee, Fill, Funding, LedgerEventType, Settlement, Side +from .ledger import ExactAccountLedger +from .schemas import execution_payload + +ZERO = Decimal(0) +EVENT_FIELDS = { + "mark": {"instrument_id", "price"}, + "fx_mark": {"currency", "rate"}, + "settle": set(), + "transfer": {"source", "target", "currency", "amount"}, + "external_cash": {"sleeve", "currency", "amount"}, + "fx_convert": { + "sleeve", + "source_currency", + "target_currency", + "source_amount", + "target_amount", + }, + "fill": {"sleeve", "instrument_id", "quantity", "price", "fee", "settles_at"}, + "charge": {"sleeve", "instrument_id", "amount"}, + "variation_margin": {"sleeve", "instrument_id", "price", "amount"}, +} +UNSUPPORTED = [ + "live_execution", + "market_validity", + "short_cash_assets", + "options", + "inverse_derivatives", + "cross_sleeve_netting", + "automatic_liquidation", + "inferred_corporate_actions", + "broker_specific_margin", + "historical_state_queries", +] + + +def number(value): + if isinstance(value, bool) or not isinstance(value, (str, int, Decimal)): + raise TypeError("exact decimal string or integer required") + result = Decimal(value) + if not result.is_finite(): + raise ValueError("finite amount required") + return result + + +def fp(value): + return FixedPoint.from_decimal(number(value), 8) + + +def utc(value): + return ensure_utc_datetime(parse_timestamp_exact(value, field="at"), field="at") + + +def digest(value): + return hashlib.sha256(canonical_json(value)).hexdigest() + + +class _CashLedger(ExactAccountLedger): + """Closed research cash journal; no changes to existing public ledger methods.""" + + def cash_journal(self, identity, changes, at, category): + changes = {currency: fp(amount).to_decimal() for currency, amount in changes.items()} + counterpart = { + "external": "equity:external_flows", + "transfer": "clearing:sleeve_transfer", + "fx": "clearing:fx_conversion", + }[category] + postings = tuple( + posting + for currency, amount in sorted(changes.items()) + for posting in ( + self._posting("assets:cash", currency, number(amount)), + self._posting(counterpart, currency, -number(amount)), + ) + ) + tx = self._make_transaction( + event_type=LedgerEventType.FX_CONVERSION, + reference_id=identity, + idempotency_key=identity, + event_time=at, + postings=postings, + ) + self._post(tx) + self._event_time = at + + +class SharedCapitalAccount: + """Apply declared executions, never synthesize fills from returns. + + All amounts are fixed to eight decimal places; excess precision is rejected. + Sale proceeds and purchased units remain reserved until their explicit UTC + settlement instant. At every event, matured holds are released first. Fees are + paid on execution. Futures use explicit linear notional margin rates, with + negative unrealized PnL reserved and positive PnL unavailable until settlement. + """ + + sends_live_orders = False + + def __init__(self, *, specs, owners, allocations, base_currency, opened_at, fx_rates=None): + self.opened_at = utc(opened_at) + self.base_currency = base_currency + self.specs = {} + for spec in specs: + if spec.instrument_id in self.specs: + raise ValueError("duplicate instrument") + if spec.asset_class not in {AssetClass.EQUITY, AssetClass.ETF, AssetClass.FUTURE}: + raise ValueError("only long cash equities/ETFs and linear futures supported") + if spec.inverse or spec.quote_currency not in {None, spec.settlement_currency}: + raise ValueError("inverse or quanto instruments unsupported") + if max(spec.available_at, spec.effective_from) > self.opened_at: + raise ValueError("instrument unavailable at account opening") + if spec.asset_class is AssetClass.FUTURE: + initial = number(spec.metadata.get("initial_margin_rate", "-1")) + maintenance = number(spec.metadata.get("maintenance_margin_rate", "-1")) + if not 0 < maintenance <= initial <= 1: + raise ValueError("explicit positive maintenance/initial margin rates required") + if "initial_margin_per_contract" in spec.metadata: + raise ValueError("only notional-rate futures margin supported") + else: + spec = replace(spec, metadata={**spec.metadata, "research_delivery": "true"}) + self.specs[spec.instrument_id] = spec + if not self.specs or set(owners) != set(self.specs) or not allocations: + raise ValueError("nonempty instruments, exact owners and allocations required") + self.owners = dict(owners) + self.allocations = deepcopy(allocations) + if any(not isinstance(s, str) or not s.strip() or s == "total" for s in allocations): + raise ValueError("nonempty sleeve IDs required") + if not set(owners.values()) <= set(allocations): + raise ValueError("unknown instrument sleeve") + currencies = {base_currency} | {s.settlement_currency for s in self.specs.values()} + currencies |= {c for cash in allocations.values() for c in cash} + self.currencies = sorted(currencies) + rates = {c: number(v) for c, v in (fx_rates or {}).items()} + if rates.get(base_currency, Decimal(1)) != 1: + raise ValueError("base FX must equal one") + rates[base_currency] = Decimal(1) + if set(rates) != currencies or any(v <= 0 for v in rates.values()): + raise ValueError("explicit opening FX for every currency required") + self.rates = rates + self.configuration_sha256 = digest( + { + "instruments": [dataclass_payload(s) for _, s in sorted(self.specs.items())], + "owners": self.owners, + "allocations": self.allocations, + "base_currency": base_currency, + "opened_at": self.opened_at.isoformat(), + "fx_rates": {c: str(v) for c, v in rates.items()}, + } + ) + kwargs = { + "base_currency": base_currency, + "instruments": self.specs, + "opened_at": self.opened_at, + "fx_to_base": {c: fp(v) for c, v in rates.items()}, + } + totals = {c: ZERO for c in currencies} + self.sleeves = {} + for sleeve, cash in sorted(allocations.items()): + values = {c: number(cash.get(c, "0")) for c in currencies} + if any(v < 0 for v in values.values()): + raise ValueError("negative opening allocation") + for c, v in values.items(): + totals[c] += v + self.sleeves[sleeve] = _CashLedger( + account_id="attribution:" + sleeve, + initial_cash={c: fp(v) for c, v in values.items()}, + **kwargs, + ) + self.ledger = _CashLedger( + account_id="shared-research", + initial_cash={c: fp(v) for c, v in totals.items()}, + **kwargs, + ) + self.pending, self.history, self.events = [], [], [] + self.seen, self.marks = {}, {} + self.last_key = (self.opened_at, -1) + self.initial_nav = self.ledger.snapshot().nav.to_decimal() + if self.initial_nav <= 0: + raise ValueError("positive opening NAV required") + self.external_flows = ZERO + self.wealth = Decimal(1) + self.return_defined = True + + def _quantity(self, sleeve, instrument): + return ( + self.sleeves[sleeve] + .snapshot(self.last_key[0]) + .positions.get(instrument, fp(0)) + .to_decimal() + ) + + def _books(self, sleeve): + return (self.ledger, self.sleeves[sleeve]) + + def liquidity(self, sleeve=None, *, maintenance=False): + book = self.ledger if sleeve is None else self.sleeves[sleeve] + snap = book.snapshot(self.last_key[0]) + free = {c: book.cash_balance(c) for c in self.currencies} + for item in self.pending: + if sleeve is None or item["sleeve"] == sleeve: + free[item["currency"]] -= item["cash"] + for instrument, quantity in snap.positions.items(): + spec = self.specs[instrument] + if spec.asset_class is AssetClass.FUTURE and quantity.units: + price = self.marks[instrument] + notional = abs( + quantity.to_decimal() * price * spec.contract_multiplier.to_decimal() + ) + # FixedPoint rounding happens only in the underlying ledger; liquidity + # keeps the exact conservative reserve, never rounds buying power up. + free[spec.settlement_currency] -= notional * number( + spec.metadata[ + "maintenance_margin_rate" if maintenance else "initial_margin_rate" + ] + ) + pnl = ( + snap.unrealized_pnl[instrument].to_decimal() + / self.rates[spec.settlement_currency] + ) + free[spec.settlement_currency] += min(ZERO, pnl) + return free + + def _mark(self, instrument, price, at, identity): + if instrument not in self.specs or number(price) <= 0: + raise ValueError("known instrument and positive mark required") + spec = self.specs[instrument] + if number(price) % spec.price_tick.to_decimal(): + raise ValueError("mark not tick aligned") + for book in (self.ledger, *self.sleeves.values()): + book.mark( + MarkPriceEvent( + event_id=identity, + instrument_id=instrument, + price=fp(price), + event_time=at, + received_at=at, + available_at=at, + source="declared-research", + trading_day=at.date(), + session_id=at.date().isoformat(), + sequence=0, + ) + ) + self.marks[instrument] = number(price) + + def _dispatch(self, e, at): + kind, identity = e["kind"], e["event_id"] + sleeve = e.get("sleeve") + flow, risk_reducing = ZERO, False + if kind == "mark": + self._mark(e["instrument_id"], e["price"], at, identity) + elif kind == "fx_mark": + currency, rate = e["currency"], number(e["rate"]) + if currency not in self.currencies or rate <= 0: + raise ValueError("known currency and positive FX required") + for book in (self.ledger, *self.sleeves.values()): + book.set_fx_rate(currency, fp(rate), event_time=at) + self.rates[currency] = rate + elif kind == "settle": + pass # Maturity release is explicit in the event history. + elif kind == "transfer": + source, target, c = e["source"], e["target"], e["currency"] + amount = number(e["amount"]) + if source == target or amount <= 0 or amount > self.liquidity(source)[c]: + raise ValueError("invalid or unfunded internal transfer") + self.sleeves[source].cash_journal(identity, {c: -amount}, at, "transfer") + self.sleeves[target].cash_journal(identity, {c: amount}, at, "transfer") + elif kind == "external_cash": + c, amount = e["currency"], number(e["amount"]) + if c not in self.currencies or amount == 0: + raise ValueError("known currency and nonzero flow required") + for book in self._books(sleeve): + book.cash_journal(identity, {c: amount}, at, "external") + flow = amount * self.rates[c] + elif kind == "fx_convert": + source, target = e["source_currency"], e["target_currency"] + sold, bought = number(e["source_amount"]), number(e["target_amount"]) + if source == target or source not in self.currencies or target not in self.currencies: + raise ValueError("distinct known FX currencies required") + if sold <= 0 or bought <= 0 or sold > self.liquidity(sleeve)[source]: + raise ValueError("positive funded FX amounts required") + for book in self._books(sleeve): + book.cash_journal(identity, {source: -sold, target: bought}, at, "fx") + elif kind in {"fill", "charge", "variation_margin"}: + instrument = e["instrument_id"] + if self.owners[instrument] != sleeve: + raise ValueError("instrument belongs to another sleeve") + spec = self.specs[instrument] + if (spec.effective_to is not None and at >= spec.effective_to) or ( + spec.superseded_at is not None and at >= spec.superseded_at + ): + raise ValueError("instrument terms expired or superseded") + c = spec.settlement_currency + if kind == "fill": + quantity, price, fee = number(e["quantity"]), number(e["price"]), number(e["fee"]) + settles = utc(e["settles_at"]) + if settles < at or fee < 0 or quantity == 0 or price <= 0: + raise ValueError("invalid fill, fee or settlement time") + if ( + quantity % spec.quantity_step.to_decimal() + or price % spec.price_tick.to_decimal() + ): + raise ValueError("fill not step/tick aligned") + old = self._quantity(sleeve, instrument) + final = old + quantity + if spec.asset_class is not AssetClass.FUTURE: + held = sum( + (p["units"] for p in self.pending if p["instrument"] == instrument), ZERO + ) + if final < 0 or (quantity < 0 and -quantity > old - held): + raise ValueError("short cash inventory or sale of unsettled units") + if ( + quantity > 0 + and quantity * price * spec.contract_multiplier.to_decimal() + fee + > self.liquidity(sleeve)[c] + ): + raise ValueError("insufficient settled cash or margin") + risk_reducing = abs(final) < abs(old) and old * final >= 0 + self._mark(instrument, price, at, identity + ":execution-mark") + for book in self._books(sleeve): + book.apply( + Fill( + fill_id=identity, + order_id=e.get("order_id", identity), + account_id=book.account_id, + strategy_id=sleeve, + instrument_id=instrument, + side=Side.BUY if quantity > 0 else Side.SELL, + quantity=fp(abs(quantity)), + price=fp(price), + event_time=at, + ) + ) + book.apply( + Fee( + fee_id=identity + ":fee", + fill_id=identity, + account_id=book.account_id, + amount=fp(fee), + currency=c, + event_time=at, + fee_type="explicit_research_fee", + ) + ) + if spec.asset_class is not AssetClass.FUTURE and settles > at: + self.pending.append( + { + "event_id": identity, + "sleeve": sleeve, + "currency": c, + "instrument": instrument, + "at": settles, + "units": max(ZERO, quantity), + "cash": max(ZERO, -quantity) + * price + * spec.contract_multiplier.to_decimal(), + } + ) + elif kind == "charge": + amount = number(e["amount"]) + if amount < 0: + raise ValueError("nonnegative charge required") + for book in self._books(sleeve): + book.apply( + Funding( + funding_id=identity, + instrument_id=instrument, + account_id=book.account_id, + amount=fp(-amount), + currency=c, + event_time=at, + ) + ) + else: + if spec.asset_class is not AssetClass.FUTURE: + raise ValueError("variation margin requires future") + self._mark(instrument, e["price"], at, identity + ":settlement-mark") + for book in self._books(sleeve): + book.apply( + Settlement( + settlement_id=identity, + account_id=book.account_id, + instrument_id=instrument, + amount=fp(e["amount"]), + currency=c, + event_time=at, + settlement_type="daily_mark", + settlement_price=fp(e["price"]), + ) + ) + else: + raise ValueError("unsupported event kind") + return flow, risk_reducing + + def apply(self, event): + """Atomic event admission; rejected attempts never alter the account.""" + with localcontext() as context: + context.prec = 64 + return self._apply(event) + + def _apply(self, event): + e = json.loads(canonical_json(event)) + kind = e.get("kind") + required = {"event_id", "at", "sequence", "available_at", "kind"} | EVENT_FIELDS.get( + kind, set() + ) + optional = {"order_id"} if kind == "fill" else set() + if kind not in EVENT_FIELDS or not required <= set(e) or set(e) - required - optional: + raise ValueError("unsupported event kind or fields") + identity, fingerprint = e["event_id"], digest(e) + if not isinstance(identity, str) or not identity.strip(): + raise ValueError("nonempty event ID required") + if identity in self.seen: + if self.seen[identity] != fingerprint: + raise ValueError("event ID reused with changed content") + return + at = utc(e["at"]) + sequence = e["sequence"] + if type(sequence) is not int or sequence < 0 or (at, sequence) <= self.last_key: + raise ValueError("strictly increasing UTC/sequence required across chunks") + if "available_at" not in e or utc(e["available_at"]) > at: + raise ValueError("explicit availability no later than event required") + states = [book.capture_state() for book in (self.ledger, *self.sleeves.values())] + previous = deepcopy((self.pending, self.marks, self.rates, self.last_key)) + before = self.ledger.snapshot(self.last_key[0]).nav.to_decimal() + try: + self.last_key = (at, sequence) + released = [p["event_id"] for p in self.pending if p["at"] <= at] + self.pending = [p for p in self.pending if p["at"] > at] + old_free = {s: self.liquidity(s) for s in (None, *self.sleeves)} + flow, reducing = self._dispatch(e, at) + new_free = {s: self.liquidity(s) for s in old_free} + # Marks, actual charges and settlement are economic facts, not orders: + # preserve their losses and expose the resulting call without liquidation. + if e["kind"] in {"fill", "transfer", "fx_convert", "external_cash"}: + for s, free in new_free.items(): + for c, amount in free.items(): + if amount < 0 and not ( + ( + reducing + or e["kind"] == "transfer" + or (e["kind"] == "external_cash" and flow > 0) + ) + and amount >= min(ZERO, old_free[s][c]) + ): + raise ValueError("insufficient settled cash or margin") + reconciliation = self.reconcile() + after = self.ledger.snapshot(at).nav.to_decimal() + except Exception: + for book, state in zip((self.ledger, *self.sleeves.values()), states): + book.restore_state(state) + self.pending, self.marks, self.rates, self.last_key = previous + raise + event_return = (after - flow) / before - 1 if before > 0 else None + self.external_flows += flow + if event_return is None: + self.return_defined = False + elif self.return_defined: + self.wealth *= 1 + event_return + self.history.append( + { + "event_id": identity, + "at": at.isoformat(), + "sequence": sequence, + "nav": str(after), + "external_flow": str(flow), + "net_return": None if event_return is None else str(event_return), + "released_settlements": released, + "free_cash": { + "total" if s is None else s: {c: str(v) for c, v in f.items()} + for s, f in new_free.items() + }, + "initial_margin_shortfall": any( + v < 0 for f in new_free.values() for v in f.values() + ), + "margin_call": any( + v < 0 for s in new_free for v in self.liquidity(s, maintenance=True).values() + ), + "reconciliation": reconciliation, + } + ) + self.events.append(e) + self.seen[identity] = fingerprint + + def replay(self, events): + ordered = sorted(events, key=lambda e: (utc(e["at"]), e["sequence"])) + for event in ordered: + self.apply(event) + return self.report() + + def reconcile(self): + at = self.last_key[0] + total = self.ledger.snapshot(at) + sleeves = [book.snapshot(at) for book in self.sleeves.values()] + cash_residual = { + c: self.ledger.cash_balance(c) + - sum((book.cash_balance(c) for book in self.sleeves.values()), ZERO) + for c in self.currencies + } + position_residual = { + i: total.positions.get(i, fp(0)).to_decimal() + - sum((s.positions.get(i, fp(0)).to_decimal() for s in sleeves), ZERO) + for i in self.specs + } + nav_residual = total.nav.to_decimal() - sum((s.nav.to_decimal() for s in sleeves), ZERO) + # Per-book base valuation rounds to 1e-8. Allow at most one quantum per + # attribution book, while native-currency cash and units remain exact. + if ( + any(cash_residual.values()) + or any(position_residual.values()) + or abs(nav_residual) > Decimal("1e-8") * len(sleeves) + ): + raise AssertionError("shared-capital attribution failed") + for book in (self.ledger, *self.sleeves.values()): + for tx in book.transactions: + totals = {} + for p in tx.postings: + totals[p.currency] = totals.get(p.currency, ZERO) + p.amount.to_decimal() + if any(totals.values()): + raise AssertionError("unbalanced ledger transaction") + return { + "cash_residual": {c: str(v) for c, v in cash_residual.items()}, + "position_residual": {i: str(v) for i, v in position_residual.items()}, + "nav_residual": str(nav_residual), + "ledger_balanced": True, + } + + def report(self): + at = self.last_key[0] + final = self.ledger.snapshot(at) + return { + "schema": "quant.shared-capital/v1", + "evidence_kind": "declared_research_execution", + "sample_kind": "unclassified", + "configuration_sha256": self.configuration_sha256, + "sends_live_orders": False, + "final_account": execution_payload(final), + "sleeves": { + s: execution_payload(book.snapshot(at)) for s, book in self.sleeves.items() + }, + "ledger": [execution_payload(tx) for tx in self.ledger.transactions], + "attribution_ledgers": { + s: [execution_payload(tx) for tx in book.transactions] + for s, book in self.sleeves.items() + }, + "history": deepcopy(self.history), + "events": deepcopy(self.events), + "pending": [ + {**p, "at": p["at"].isoformat(), "cash": str(p["cash"]), "units": str(p["units"])} + for p in self.pending + ], + "initial_nav": str(self.initial_nav), + "external_flows": str(self.external_flows), + "net_pnl": str(final.nav.to_decimal() - self.initial_nav - self.external_flows), + "cumulative_return": str(self.wealth - 1) if self.return_defined else None, + "reconciliation": self.reconcile(), + "unsupported_scopes": UNSUPPORTED, + } + + def checkpoint(self): + """Portable replay checkpoint; hash-bound journal, not mutable private state.""" + payload = { + "schema": "quant.capital-checkpoint/v1", + "events": deepcopy(self.events), + "configuration_sha256": self.configuration_sha256, + } + return {**payload, "sha256": digest(payload)} + + def restore(self, checkpoint): + if self.events: + raise ValueError("restore requires a fresh identically configured account") + payload = {k: v for k, v in checkpoint.items() if k != "sha256"} + if ( + payload.get("schema") != "quant.capital-checkpoint/v1" + or digest(payload) != checkpoint["sha256"] + ): + raise ValueError("checkpoint integrity failed") + if payload["configuration_sha256"] != self.configuration_sha256: + raise ValueError("checkpoint configuration differs") + states = [book.capture_state() for book in (self.ledger, *self.sleeves.values())] + fields = ( + "pending", + "history", + "events", + "seen", + "marks", + "rates", + "last_key", + "external_flows", + "wealth", + "return_defined", + ) + previous = {name: deepcopy(getattr(self, name)) for name in fields} + try: + self.replay(payload["events"]) + except Exception: + for book, state in zip((self.ledger, *self.sleeves.values()), states): + book.restore_state(state) + for name, value in previous.items(): + setattr(self, name, value) + raise diff --git a/tests/test_continuous.py b/tests/test_continuous.py new file mode 100644 index 0000000..4f21600 --- /dev/null +++ b/tests/test_continuous.py @@ -0,0 +1,226 @@ +from copy import deepcopy +from datetime import timedelta +from decimal import Decimal + +import pytest +from conftest import T0, spec +from quant_data_kit import AssetClass, MarginMode + +from quant_execution.continuous import SharedCapitalAccount + + +def account(allocations=None): + specs = [ + spec(i, asset_class=AssetClass.ETF, product_type="cash_etf", settlement_currency=c) + for i, c in [("A", "USD"), ("B", "USD"), ("E", "EUR")] + ] + specs.append( + spec( + "F", + asset_class=AssetClass.FUTURE, + product_type="linear_future", + settlement_currency="USD", + margin_mode=MarginMode.CROSS, + metadata={"initial_margin_rate": "0.2", "maintenance_margin_rate": "0.1"}, + ) + ) + return SharedCapitalAccount( + specs=specs, + owners={"A": "alpha", "B": "beta", "E": "beta", "F": "beta"}, + allocations=allocations or {"alpha": {"USD": "600"}, "beta": {"USD": "400"}}, + base_currency="USD", + opened_at=T0.isoformat(), + fx_rates={"EUR": "1.2"}, + ) + + +def event(n, kind, **kwargs): + at = (T0 + timedelta(seconds=n)).isoformat() + return dict(event_id=f"e{n}", at=at, available_at=at, sequence=n, kind=kind, **kwargs) + + +def fill(n, sleeve="alpha", instrument="A", quantity="5", price="100", fee="1", delay=0): + return event( + n, + "fill", + sleeve=sleeve, + instrument_id=instrument, + quantity=quantity, + price=price, + fee=fee, + settles_at=(T0 + timedelta(seconds=n + delay)).isoformat(), + ) + + +def test_shared_capital_competes_and_transfers_are_neutral(): + a = account() + a.apply(fill(1)) # 600 - 500 - 1 = 99, not 1000 of independent buying power. + original = a.report() + with pytest.raises(ValueError, match="insufficient"): + a.apply(fill(2, "beta", "B")) + assert a.report() == original + a.apply(event(3, "transfer", source="alpha", target="beta", currency="USD", amount="99")) + assert a.ledger.cash_balance("USD") == Decimal(499) + with pytest.raises(ValueError, match="insufficient"): + a.apply(fill(4, "beta", "B")) # 501 cannot be funded by combined remaining 499. + a.apply(fill(5, "beta", "B", quantity="4")) + report = a.report() + assert Decimal(report["net_pnl"]) == -2 + assert a.ledger.cash_balance("USD") == 98 + assert report["reconciliation"]["cash_residual"]["USD"] == "0E-8" + + +def test_settlement_hold_units_and_cash_prevent_reinvestment_until_maturity(): + a = account() + a.apply(fill(1, delay=3)) + with pytest.raises(ValueError, match="unsettled units"): + a.apply(fill(2, quantity="-5", price="110")) + a.apply(fill(4, quantity="-5", price="110", delay=4)) + # Cash is 648, but only 98 settled. Pending proceeds cannot fund another sleeve. + assert a.ledger.cash_balance("USD") == 1048 + with pytest.raises(ValueError, match="unfunded"): + a.apply(event(5, "transfer", source="alpha", target="beta", currency="USD", amount="100")) + a.apply(event(8, "settle")) + a.apply(event(9, "transfer", source="alpha", target="beta", currency="USD", amount="600")) + a.apply(fill(10, "beta", "B", quantity="9")) + assert Decimal(a.report()["net_pnl"]) == 47 + + +def test_fx_futures_and_independent_decimal_conservation(): + a = account() + events = [ + fill(1), + event(2, "mark", instrument_id="A", price="110"), + event( + 3, + "fx_convert", + sleeve="beta", + source_currency="USD", + target_currency="EUR", + source_amount="120", + target_amount="100", + ), + fill(4, "beta", "E", quantity="2", price="20", fee="1"), + event(5, "fx_mark", currency="EUR", rate="1.3"), + fill(6, "beta", "F", quantity="2", price="100", fee="2"), + event(7, "mark", instrument_id="F", price="105"), + event(8, "variation_margin", sleeve="beta", instrument_id="F", price="105", amount="10"), + event(9, "external_cash", sleeve="alpha", currency="USD", amount="50"), + event(10, "charge", sleeve="beta", instrument_id="F", amount="3"), + ] + result = a.replay(events) + # Independent scalar cash bookkeeping: USD=1000-501-120-2+10+50-3=434, + # EUR=100-40-1=59, spot A=550; E=40 EUR; futures reset after +10 settlement. + expected = Decimal(434) + Decimal(59 + 40) * Decimal("1.3") + 550 + assert a.ledger.cash_balance("USD") == 434 + assert a.ledger.cash_balance("EUR") == 59 + assert Decimal(result["final_account"]["nav"]["units"]) / 10**8 == expected + assert Decimal(result["net_pnl"]) == expected - 1000 - 50 == Decimal("62.7") + for tx in result["ledger"]: + for currency in ("USD", "EUR"): + assert ( + sum(p["amount"]["units"] for p in tx["postings"] if p["currency"] == currency) == 0 + ) + resumed = account() + resumed.replay(events[:5]) + checkpoint = resumed.checkpoint() + restored = account() + restored.restore(checkpoint) + assert restored.replay(events[5:]) == result + assert account().replay(list(reversed(events))) == result + + +def test_margin_call_keeps_loss_blocks_increase_allows_reduction_and_deposit(): + a = account() + a.apply(fill(1, "beta", "F", quantity="10", fee="0")) + a.apply(event(2, "mark", instrument_id="F", price="60")) + assert a.report()["history"][-1]["margin_call"] + assert Decimal(a.report()["net_pnl"]) == -400 + before = a.report() + with pytest.raises(ValueError, match="insufficient"): + a.apply(fill(3, "beta", "F", quantity="1", price="60", fee="0")) + assert a.report() == before + a.apply(fill(4, "beta", "F", quantity="-5", price="60", fee="0")) + a.apply(event(5, "external_cash", sleeve="beta", currency="USD", amount="100")) + assert not a.report()["history"][-1]["margin_call"] + + +def test_idempotency_ordering_availability_and_checkpoint_identity(): + a = account() + e = fill(1) + a.apply(e) + before = a.report() + a.apply(e) + assert a.report() == before + with pytest.raises(ValueError, match="changed content"): + a.apply({**e, "fee": "2"}) + with pytest.raises(ValueError, match="strictly increasing"): + a.apply({**e, "event_id": "different"}) + with pytest.raises(ValueError, match="availability"): + a.apply({**fill(2), "available_at": (T0 + timedelta(seconds=3)).isoformat()}) + checkpoint = deepcopy(a.checkpoint()) + checkpoint["events"][0]["price"] = "99" + with pytest.raises(ValueError, match="integrity"): + account().restore(checkpoint) + with pytest.raises(ValueError, match="configuration"): + account({"alpha": {"USD": "601"}, "beta": {"USD": "399"}}).restore(a.checkpoint()) + with pytest.raises(ValueError, match="another sleeve"): + a.apply(fill(3, "beta", "A", quantity="1")) + + +def test_initial_shortfall_is_not_maintenance_call_and_partial_transfer_helps(): + a = account({"alpha": {"USD": "750"}, "beta": {"USD": "250"}}) + a.apply(fill(1, "beta", "F", quantity="10", fee="0")) + a.apply(event(2, "mark", instrument_id="F", price="90")) + assert a.report()["history"][-1]["initial_margin_shortfall"] + assert not a.report()["history"][-1]["margin_call"] + assert a.liquidity("beta")["USD"] == -30 + a.apply(event(3, "transfer", source="alpha", target="beta", currency="USD", amount="10")) + assert a.liquidity("beta")["USD"] == -20 + assert a.ledger.cash_balance("USD") == 1000 + assert Decimal(a.report()["net_pnl"]) == -100 + + +def test_closed_events_exact_cash_precision_and_atomic_restore(): + from quant_data_kit.exceptions import ValidationError + + from quant_execution.continuous import digest + + a = account() + for invalid in [ + {**event(1, "settle"), "ignored": "bad"}, + event(1, "external_cash", sleeve="alpha", currency="USD", amount="0.000000001"), + ]: + original = a.report() + with pytest.raises((ValueError, ValidationError)): + a.apply(invalid) + assert a.report() == original + checkpoint = a.checkpoint() + checkpoint["events"] = [fill(1), fill(2, quantity="100")] + checkpoint["sha256"] = digest({k: v for k, v in checkpoint.items() if k != "sha256"}) + original = a.report() + with pytest.raises(ValueError): + a.restore(checkpoint) + assert a.report() == original + + +@pytest.mark.parametrize( + "changes", + [ + {"quantity": "0"}, + {"quantity": "0.5"}, + {"price": "0"}, + {"price": "1.001"}, + {"fee": "-1"}, + {"price": True}, + {"quantity": "NaN"}, + {"settles_at": T0.isoformat()}, + {"sequence": True}, + ], +) +def test_bad_fill_is_atomic(changes): + a = account() + original = a.report() + with pytest.raises((ValueError, TypeError)): + a.apply({**fill(1), **changes}) + assert a.report() == original From 49ef53d2c502ad6faad6818f853dadd1f8b8b182 Mon Sep 17 00:00:00 2001 From: PureSaber Date: Mon, 12 Oct 2026 01:00:35 +0800 Subject: [PATCH 2/2] Reserve futures losses in native currency before FX rounding --- src/quant_execution/continuous.py | 14 ++++++++++---- tests/test_continuous.py | 25 +++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/src/quant_execution/continuous.py b/src/quant_execution/continuous.py index 086fa70..1bf875d 100644 --- a/src/quant_execution/continuous.py +++ b/src/quant_execution/continuous.py @@ -78,6 +78,15 @@ def digest(value): class _CashLedger(ExactAccountLedger): """Closed research cash journal; no changes to existing public ledger methods.""" + def native_future_pnl(self, instrument, mark): + # Collateral is reserved in its native currency. Never divide a rounded + # base-currency reporting PnL by FX: that can erase a small native loss. + quantity = self._positions.get(instrument, ZERO) + spec = self.instruments[instrument] + return quantity * mark * spec.contract_multiplier.to_decimal() - self._position_cost( + instrument, derivative=True + ) + def cash_journal(self, identity, changes, at, category): changes = {currency: fp(amount).to_decimal() for currency, amount in changes.items()} counterpart = { @@ -233,10 +242,7 @@ def liquidity(self, sleeve=None, *, maintenance=False): "maintenance_margin_rate" if maintenance else "initial_margin_rate" ] ) - pnl = ( - snap.unrealized_pnl[instrument].to_decimal() - / self.rates[spec.settlement_currency] - ) + pnl = book.native_future_pnl(instrument, price) free[spec.settlement_currency] += min(ZERO, pnl) return free diff --git a/tests/test_continuous.py b/tests/test_continuous.py index 4f21600..c3cf271 100644 --- a/tests/test_continuous.py +++ b/tests/test_continuous.py @@ -204,6 +204,31 @@ def test_closed_events_exact_cash_precision_and_atomic_restore(): assert a.report() == original +def test_native_futures_loss_is_reserved_before_fx_reporting_rounding(): + instrument = spec( + "F", + asset_class=AssetClass.FUTURE, + product_type="linear_future", + settlement_currency="EUR", + price_tick="0.00000001", + margin_mode=MarginMode.CROSS, + metadata={"initial_margin_rate": "0.2", "maintenance_margin_rate": "0.1"}, + ) + a = SharedCapitalAccount( + specs=[instrument], + owners={"F": "beta"}, + allocations={"beta": {"EUR": "100"}}, + base_currency="USD", + opened_at=T0.isoformat(), + fx_rates={"EUR": "0.1"}, + ) + a.apply(fill(1, "beta", "F", quantity="1", price="100", fee="0")) + a.apply(event(2, "mark", instrument_id="F", price="99.99999999")) + # Native loss is 1e-8 EUR, even though its 1e-9 USD report rounds to zero. + expected = Decimal(100) - Decimal("99.99999999") * Decimal("0.2") - Decimal("0.00000001") + assert a.liquidity("beta")["EUR"] == expected == Decimal("79.999999992") + + @pytest.mark.parametrize( "changes", [