cleolob 0.3.0__py3-none-any.whl

cleolob-0.3.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: cleolob
+Version: 0.3.0
+Summary: Reproducible limit-order-book execution research laboratory
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: gymnasium>=0.29
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: rl
+Requires-Dist: stable-baselines3>=2.3; extra == "rl"
+Requires-Dist: tensorboard>=2.16; extra == "rl"
+Provides-Extra: plots
+Requires-Dist: plotly>=5.20; extra == "plots"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: uvicorn>=0.29; extra == "web"
+Requires-Dist: plotly>=5.20; extra == "web"
+Requires-Dist: streamlit>=1.35; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: wheel>=0.44; extra == "dev"
+Dynamic: license-file

cleolob-0.3.0.dist-info/RECORD

@@ -0,0 +1,46 @@
+cleolob-0.3.0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+lob/__init__.py,sha256=kLQagXFAWt_wHpvFmjPQ1DU6RotTdxr5tiuBQBx6oyg,1005
+lob/__main__.py,sha256=SUwyY45wT1IsqUILKZWA9lZqyEY6VugRVAK3nthPOhI,1370
+lob/accounting.py,sha256=kv-egaontwnAkSqYpDAP8wCA3yh8nQYIPmzCc3c52xQ,5330
+lob/artifacts.py,sha256=oojAC8rSH5Z2GHfiJtEtXvHgn7prUxL9LQEiH2vwrRU,3768
+lob/benchmarks.py,sha256=ShkboOVH4anhnr7Ao0fyAKQPqEeePM-BukBoQKk2K_k,2060
+lob/calibration.py,sha256=TGg6WsrYU00KPJm-TEs0CezEvK5nT6pPo5uEGVOLE5U,26223
+lob/cli.py,sha256=M-zD3bWysj0TahR5CpeQARWy2wg63N8kOhrF_sCJm70,14630
+lob/config.py,sha256=THgL_OqWx0jDYnc3ZPppc-uqOvXK4CBQFAq3ddVKQw0,18702
+lob/controls.py,sha256=rn3L0nx01-Z4byTNnUdnl1uxk2drmy5OedRFr0RrNr4,35752
+lob/core_study.py,sha256=YkuZae3M2QDaB0RSVrzbCea9Bq5xItkF6AlAnKo24Pg,36700
+lob/data_download.py,sha256=D8boSbkTlW-7ljOqGCb4AVDo4x3jOR6XHaSYIta6Fj0,10678
+lob/engine.py,sha256=uWw8FyGPuPeu87y7ppqno9cRM0CVbN6WCg_us8BpQ0s,35433
+lob/execution.py,sha256=YKKXdlX6yxI8lpn5dTPd-O_cvE2Brfa87UOqOfJYiHs,22168
+lob/generalization.py,sha256=LJNWm515KZmlQSiPtWBanV86dnCYsCG3ilucBuX63EY,31958
+lob/mbo.py,sha256=2nzd0T7wUYmY5e_S3TBlhN2v0K2p6EfsVfWP6jdxO-o,27271
+lob/performance.py,sha256=0BSQFMTVgUYXI7Fat2ciJdU8gASkFMpr2BKjbxhHD0E,12602
+lob/policy_study.py,sha256=mbje4a5jZgb-PuJtAXNSMH9bFW_8zyO70TSeFWBY-c8,29100
+lob/portfolio.py,sha256=P6iMtHmdZd6xT6FHSTuC_KclvbXEkA8VCO_t0w8Dc10,40068
+lob/risk.py,sha256=QxB7FZskS6P9ADrcINj9ArmYFTK3uJQXDvyTZD84wFA,7463
+lob/rl_env.py,sha256=IsNTmmf6ekzAET7VwF9pY7OA7bfFmpq_KRiH1s2gYaQ,15721
+lob/robustness.py,sha256=7k0B_Oqe6d3SQ3WVKknn6JoXFc1YRNpAvhev8FMoOmw,20238
+lob/runner.py,sha256=TD_x7AVaDrF2nflzv4kAqkZHQVqynN4AxXYe9i16xNM,17669
+lob/scenarios.py,sha256=-Mm6gJeXV-cthutFUfKtpzIWgSDJT1WAG1InNV605h4,2312
+lob/settlement.py,sha256=LwBEyA0wAkL2FGxv18oKwqxSZWF0uJuOLiWsmevCd0w,3599
+lob/smoke.py,sha256=sENs0c_a6bJl1c9_fcJSW-oQIAxdNwaEz5czttxGlOI,4481
+lob/stats.py,sha256=mUStYp8-Sb8bsIGpKdVYSykJAqeqFTdskvd8RFxjwMQ,7683
+lob/zi_calibration.py,sha256=Kw5r0YmpNVFWQdB5RBW9zQjVYkudegjarDvnT89tdV0,33689
+lob/experiments/__init__.py,sha256=vWJxKzvE-54LIa_vaH5DYfW6Id23UkUpx3CULpcpuHA,272
+lob/experiments/design.py,sha256=aADmUjHwM8vZOHsapGUAPNqOOolW4IT_4qVaZxRUBAM,3214
+lob/experiments/registry.py,sha256=bMYneBYORjghzsscIrEUoAlU2jLkblUKRvH78A5dTIA,6616
+lob/experiments/report.py,sha256=9AelEsR7k--b6N4_6_Eg2OTxf2BbcbVn0nJYXzD5Nq8,4521
+lob/experiments/runner.py,sha256=7SknjGIRlNwx9WLBZ6i3CdP_I2bDs9lG1GptwihokDA,9340
+lob/replay/__init__.py,sha256=FEA8Szv_HYvlfc1HDLvnA0Bq-JBWrv-5R7DHUQ9RRqY,788
+lob/replay/assessment.py,sha256=bhODjCbPOGVx4_JNCHlCDg954QXrqLQaBLcld8Mkv3c,18083
+lob/replay/book.py,sha256=3_VNpi19qPstp6Oy4vrNibIF_ioRMjNouw_ry7bwp7k,10559
+lob/replay/engine.py,sha256=rypSH86J_78Xc677D37xOBmwIOYG57-Efu5w1PpXGHw,5072
+lob/replay/io.py,sha256=IqfuZg2JAMV8xAr6Wqgynoaut1d94vMdwwaWmXaHzXY,6023
+lob/replay/l2.py,sha256=-Khmq3AlgWrngUYMm7ghfFo5pC2vLLhuEeLwkXTB9dI,15261
+lob/replay/schema.py,sha256=rHp-J3tf1RMMq8eUQ8uWBNKrfmhf_sQzDajbsFq4HWI,8851
+lob/replay/validation.py,sha256=NLrDPtbE6_zieO7sdLUWcmEOLTpy8canJv7mDUus2tY,4951
+cleolob-0.3.0.dist-info/METADATA,sha256=qrvlzLotmNQxTy8rLpg58rlz-nYs5aUvf6CTS2iZUYo,908
+cleolob-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cleolob-0.3.0.dist-info/entry_points.txt,sha256=ckRiGiIehwCpTTOt9OuAjm2aZCEePIDJioFoYo2GX8s,38
+cleolob-0.3.0.dist-info/top_level.txt,sha256=03AhYCqqQXsQbWcycTfD6w5A6fZUmw510oEdHKjr0AY,4
+cleolob-0.3.0.dist-info/RECORD,,

cleolob-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cleolob-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cleo = lob.cli:main

cleolob-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

cleolob-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lob

lob/__init__.py

@@ -0,0 +1,17 @@
+"""LOB Execution Lab — event-driven limit order book simulation and optimal execution."""
+from .engine import ExchangeSimulator, Order, OrderBook, OrderStatus, OrderType, Side, SimConfig, TimeInForce, Trade
+from .accounting import FeeConfig, Ledger
+from .risk import ExecutionRisk, RiskConfig
+from .execution import (AlmgrenChrissAgent, ExecutionAgent, ExecutionReport, POVAgent,
+                        ScheduleAgent, TWAPAgent, VWAPAgent, build_report,
+                        estimate_volume_profile)
+from .rl_env import LOBExecutionEnv
+from .scenarios import SCENARIOS, scenario_params
+
+__all__ = [
+    "ExchangeSimulator", "Order", "OrderBook", "OrderType", "Side", "SimConfig", "Trade",
+    "OrderStatus", "TimeInForce", "FeeConfig", "Ledger", "RiskConfig", "ExecutionRisk",
+    "ExecutionAgent", "ScheduleAgent", "TWAPAgent", "VWAPAgent", "AlmgrenChrissAgent",
+    "POVAgent", "ExecutionReport", "build_report", "estimate_volume_profile",
+    "LOBExecutionEnv", "SCENARIOS", "scenario_params",
+]

lob/__main__.py

@@ -0,0 +1,29 @@
+"""Smoke test: 10 simulated seconds of background flow, then a liquidity shock."""
+from __future__ import annotations
+
+from .engine import ExchangeSimulator, Order, OrderType, Side, SimConfig
+
+if __name__ == "__main__":
+    sim = ExchangeSimulator(SimConfig())
+    for _ in range(300):
+        sim.step(0.1)
+    ts = sim.cfg.tick_size
+    bids, asks = sim.book.depth(5)
+    print(f"[t={sim.t:.0f}s] trades={len(sim.book.trades)}  mid={sim.book.mid() * ts:.2f}  "
+          f"spread={sim.book.spread()} tick(s)")
+    print("  bids:", [(round(p * ts, 2), v) for p, v in bids])
+    print("  asks:", [(round(p * ts, 2), v) for p, v in asks])
+
+    # Liquidity shock: 3,000-share market sell, then watch resilience refill the bid side.
+    mid_before = sim.book.mid()
+    trades = sim.book.process(Order(10**9, Side.SELL, 3000, OrderType.MARKET, "DEMO", sim.t),
+                              sim.t)
+    vwap = sum(t.price * t.qty for t in trades) / sum(t.qty for t in trades)
+    print(f"\n[shock] sold {sum(t.qty for t in trades):,} @ vwap {vwap * ts:.4f} "
+          f"(mid was {mid_before * ts:.4f} -> slippage "
+          f"{(mid_before - vwap) / mid_before * 1e4:.1f} bps)")
+    for k in range(1, 4):
+        sim.step(2.0)
+        bids, _ = sim.book.depth(3)
+        print(f"[t=+{2 * k}s] best bids after refill:",
+              [(round(p * ts, 2), v) for p, v in bids])

lob/accounting.py

@@ -0,0 +1,115 @@
+"""Owner-specific cash, inventory, fees and average-cost PnL accounting.
+
+Prices accepted by the ledger are currency. Trade prices remain integer ticks.
+Fees are recognised when a fill occurs; maker rebates may be negative. Initial
+inventory is endowed at its stated cost basis, never recorded as trading profit.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+from typing import Any, Mapping
+
+from .engine import Side, Trade
+
+
+@dataclass(frozen=True)
+class FeeConfig:
+    maker_bps: float = 0.0
+    taker_bps: float = 0.0
+    per_share: float = 0.0
+
+    def __post_init__(self) -> None:
+        for name, value in asdict(self).items():
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+                raise ValueError(f"{name} must be finite")
+        if self.per_share < 0 or self.taker_bps < 0:
+            raise ValueError("per_share and taker_bps must be nonnegative")
+
+    def charge(self, price: float, qty: int, *, maker: bool = False) -> float:
+        if not math.isfinite(price) or price < 0 or isinstance(qty, bool) or not isinstance(qty, int) or qty < 0:
+            raise ValueError("fee price and integer quantity must be finite and nonnegative")
+        return price * qty * (self.maker_bps if maker else self.taker_bps) / 1e4 + qty * self.per_share
+
+
+def fee_config(value: FeeConfig | Mapping[str, Any] | None) -> FeeConfig:
+    return value if isinstance(value, FeeConfig) else FeeConfig(**dict(value or {}))
+
+
+@dataclass(frozen=True)
+class AccountSnapshot:
+    cash: float
+    inventory: int
+    average_cost: float
+    gross_realized_pnl: float
+    unrealized_pnl: float
+    total_fees: float
+    realized_pnl: float
+    equity: float
+    total_pnl: float
+
+
+class Ledger:
+    """A single owner's signed position using moving-average cost basis."""
+
+    def __init__(self, *, inventory: int = 0, average_cost: float = 0.0,
+                 cash: float = 0.0, fees: FeeConfig | Mapping[str, Any] | None = None) -> None:
+        if isinstance(inventory, bool) or not isinstance(inventory, int):
+            raise ValueError("inventory must be an integer")
+        if not math.isfinite(average_cost) or average_cost < 0 or not math.isfinite(cash):
+            raise ValueError("initial cash and cost basis must be finite; basis must be nonnegative")
+        if inventory and average_cost <= 0:
+            raise ValueError("nonzero initial inventory requires a positive cost basis")
+        self.inventory = inventory
+        self.average_cost = float(average_cost) if inventory else 0.0
+        self.cash = float(cash)
+        self.initial_equity = self.cash + inventory * self.average_cost
+        self.fees = fee_config(fees)
+        self.total_fees = 0.0
+        self.gross_realized_pnl = 0.0
+        self.filled_qty = 0
+
+    def apply_fill(self, side: Side, price: float, qty: int, *, maker: bool = False) -> float:
+        if not isinstance(side, Side) or isinstance(qty, bool) or not isinstance(qty, int) or qty <= 0:
+            raise ValueError("fill side and positive integer quantity required")
+        if not math.isfinite(price) or price <= 0:
+            raise ValueError("fill price must be positive and finite")
+        signed_qty = side.value * qty
+        old = self.inventory
+        updated = old + signed_qty
+        if old == 0 or old * signed_qty > 0:
+            self.average_cost = (abs(old) * self.average_cost + qty * price) / abs(updated)
+        else:
+            closing = min(abs(old), qty)
+            self.gross_realized_pnl += closing * (price - self.average_cost) * (1 if old > 0 else -1)
+            if updated == 0:
+                self.average_cost = 0.0
+            elif old * updated < 0:
+                self.average_cost = price
+        fee = self.fees.charge(price, qty, maker=maker)
+        self.inventory = updated
+        self.cash -= signed_qty * price + fee
+        self.total_fees += fee
+        self.filled_qty += qty
+        return fee
+
+    def apply_trade(self, trade: Trade, owner: str, tick_size: float) -> float:
+        if tick_size <= 0 or not math.isfinite(tick_size):
+            raise ValueError("tick_size must be positive and finite")
+        taker, maker = trade.taker_owner == owner, trade.maker_owner == owner
+        if taker == maker:
+            raise ValueError("trade must identify owner on exactly one side")
+        side = trade.taker_side if taker else trade.taker_side.opposite
+        return self.apply_fill(side, trade.price * tick_size, trade.qty, maker=maker)
+
+    def snapshot(self, mark: float) -> AccountSnapshot:
+        if not math.isfinite(mark) or mark < 0:
+            raise ValueError("mark must be finite and nonnegative")
+        unrealized = self.inventory * (mark - self.average_cost)
+        equity = self.cash + self.inventory * mark
+        pnl = self.gross_realized_pnl + unrealized - self.total_fees
+        if not math.isclose(equity - self.initial_equity, pnl, abs_tol=1e-7, rel_tol=1e-10):
+            raise ArithmeticError("cash/inventory PnL identity failed")
+        return AccountSnapshot(self.cash, self.inventory, self.average_cost,
+                               self.gross_realized_pnl, unrealized, self.total_fees,
+                               self.gross_realized_pnl - self.total_fees, equity, pnl)

lob/artifacts.py

@@ -0,0 +1,82 @@
+"""Compact, portable research evidence; no absolute machine paths in metadata."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .config import canonical_json
+from .experiments.registry import PROJECT_ROOT, runtime_metadata, sha256_file, source_manifest, write_json
+
+
+def portable_provenance() -> dict[str, Any]:
+    runtime = runtime_metadata()
+    runtime.pop("executable", None)
+    runtime["cpu"] = platform.processor() or os.environ.get("PROCESSOR_IDENTIFIER", "unknown")
+    runtime["logical_cpu_count"] = os.cpu_count()
+    if os.name == "nt":
+        try:
+            import winreg
+            with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE,
+                                r"HARDWARE\DESCRIPTION\System\CentralProcessor\0") as key:
+                runtime["cpu"] = winreg.QueryValueEx(key, "ProcessorNameString")[0].strip()
+        except OSError:
+            pass
+    commit, dirty = None, None
+    try:
+        commit = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], cwd=PROJECT_ROOT, text=True,
+            stderr=subprocess.DEVNULL, timeout=5).strip()
+        dirty = bool(subprocess.check_output(
+            ["git", "status", "--porcelain"], cwd=PROJECT_ROOT, text=True,
+            stderr=subprocess.DEVNULL, timeout=5).strip())
+    except (OSError, subprocess.SubprocessError):
+        pass
+    source = source_manifest()
+    return {"git_commit": commit, "git_dirty": dirty, "runtime": runtime,
+            "source_files": source,
+            "source_sha256": hashlib.sha256(canonical_json(source).encode()).hexdigest()}
+
+
+def seal_artifacts(root: str | Path) -> dict:
+    root = Path(root).resolve(strict=True)
+    files = {}
+    for path in sorted(root.rglob("*")):
+        if path.is_symlink():
+            raise ValueError("artifact symlinks are not supported")
+        if path.is_file() and path != root / "checksums.json":
+            files[path.relative_to(root).as_posix()] = sha256_file(path)
+    if not files:
+        raise ValueError("cannot seal an empty artifact")
+    result = {"format": "cleolob-compact-v1", "algorithm": "sha256", "files": files}
+    write_json(root / "checksums.json", result)
+    return result
+
+
+def verify_artifacts(root: str | Path) -> dict:
+    root = Path(root).resolve(strict=True)
+    manifest = json.loads((root / "checksums.json").read_text(encoding="utf-8"))
+    if (manifest.get("format") != "cleolob-compact-v1" or manifest.get("algorithm") != "sha256"
+            or not isinstance(manifest.get("files"), dict) or not manifest["files"]):
+        raise ValueError("unsupported or empty artifact manifest")
+    issues = []
+    actual = {p.relative_to(root).as_posix() for p in root.rglob("*")
+              if p.is_file() and p != root / "checksums.json"}
+    if actual != set(manifest["files"]):
+        issues.append("artifact file set changed")
+    for name, digest in manifest["files"].items():
+        target = root / name
+        # Require canonical portable relative names, even when reading on Windows.
+        if (not name or "\\" in name or ":" in name or name.startswith("/")
+                or any(part in {"", ".", ".."} for part in name.split("/"))
+                or not target.resolve().is_relative_to(root)
+                or target.is_symlink() or any(p.is_symlink() for p in target.parents if p != root)):
+            issues.append(f"unsafe artifact: {name}")
+        elif not target.is_file() or sha256_file(target) != digest:
+            issues.append(f"checksum mismatch: {name}")
+    return {"valid": not issues, "issues": issues, "files": len(manifest["files"]),
+            "meaning": "byte integrity only; not independent scientific validation"}

lob/benchmarks.py

@@ -0,0 +1,42 @@
+"""Measured local throughput; correctness checks bracket each timed workload."""
+from __future__ import annotations
+
+import platform
+import statistics
+import time
+import tracemalloc
+from typing import Any
+
+from .engine import Order, OrderBook, OrderType, Side
+
+
+def benchmark_matching(pairs: int = 2000, repeats: int = 3) -> dict[str, Any]:
+    if not 1 <= pairs <= 100_000 or not 1 <= repeats <= 10:
+        raise ValueError("pairs must be 1..100000 and repeats 1..10")
+    rates = []
+    for _ in range(repeats):
+        book = OrderBook()
+        started = time.perf_counter()
+        for index in range(pairs):
+            now = float(index)
+            book.process(Order(2 * index + 1, Side.SELL, 10, OrderType.LIMIT, "maker", now, price=10001), now)
+            book.process(Order(2 * index + 2, Side.BUY, 10, OrderType.MARKET, "taker", now), now)
+        elapsed = time.perf_counter() - started
+        if len(book.trades) != pairs or book.orders:
+            raise AssertionError("matching benchmark failed fill/book reconciliation")
+        book.assert_invariants()
+        rates.append(2 * pairs / elapsed)
+    # Memory instrumentation changes timing; measure it in a separate untimed pass.
+    tracemalloc.start()
+    book = OrderBook()
+    for index in range(pairs):
+        book.process(Order(index + 1, Side.BUY, 10, OrderType.LIMIT, "maker", 0.0, price=10000), 0.0)
+    _, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    book.assert_invariants()
+    return {"workload": "alternating one resting limit and one fully matching market order",
+            "orders_per_repeat": 2 * pairs, "fills_per_repeat": pairs, "repeats": repeats,
+            "orders_per_second_median": statistics.median(rates), "orders_per_second_samples": rates,
+            "resting_orders_memory_count": pairs, "python_tracemalloc_peak_bytes": peak,
+            "python": platform.python_version(), "platform": platform.platform(),
+            "note": "Local Python microbenchmark, not full market throughput; no latency/agent/replay workload included."}