outcometick 1.5.2 → 1.6.2

package/runner/harness/python/otengine.py

@@ -21,6 +21,7 @@ is the only rounding this module uses.
 from __future__ import annotations
 
 import math
+
 from typing import Any, Callable, Iterable
 
 SIDES = ("UP", "DOWN")
@@ -229,7 +230,13 @@ def match_order(book: Book, order: dict) -> dict:
     ladder = book.ladders[side]["bids" if reducing else "asks"]
     quoted = ladder.best()
     fills, remaining, notional = ladder.take(size, order.get("limit"))
-    filled = size - remaining
+    # SUMMED FROM WHAT WAS TAKEN, not derived as `size - remaining`. Mirrors
+    # book.mjs: `remaining` is the requested size with each level subtracted
+    # from it, and at float precision 1e308 - 1000 is still 1e308 -- so a huge
+    # but finite order consumed the whole ladder while reporting filled 0. No
+    # position, no cash, no trade row, and an empty book for everything after
+    # it. Adding up the levels taken cannot drift from what was removed.
+    filled = sum(f["size"] for f in fills)
     return {
         "fills": fills,
         "filled": filled,
@@ -326,18 +333,74 @@ class Portfolio:
             return None
 
         leg = self._legs(market_id)[order["side"]]
-        size = float(order.get("size") or 0)
-        if not size > 0:
+
+        # ONE PLACE THAT DECIDES WHETHER AN ORDER IS USABLE.
+        # Mirrors portfolio.mjs line for line -- see the reasoning there. Every
+        # unusable order is COUNTED AND RETURNS None, never raised: ValueError
+        # or OverflowError here would turn "reject one order" into "fail the
+        # whole run", which is the same input producing two different outcomes
+        # in two engines that are supposed to be one engine.
+        def _finite(v):
+            # A NUMBER, not something float() is willing to turn into one.
+            # Mirrors portfolio.mjs: coercion is not validation, and the two
+            # languages coerce differently -- float("10") and Number("10") both
+            # give 10, but float([10]) raises where Number([10]) gives 10. One
+            # strategy, one input, two outcomes.
+            if isinstance(v, bool) or not isinstance(v, (int, float)):
+                return None
+            f = float(v)
+            return f if math.isfinite(f) else None
+
+        has_size = order.get("size") is not None
+        has_notional = order.get("notional") is not None
+        if has_size == has_notional:
             self.rejected += 1
             return None
 
+        limit = None
+        if order.get("limit") is not None:
+            limit = _finite(order.get("limit"))
+            if limit is None or limit < 0 or limit > 1:
+                self.rejected += 1
+                return None
+
+        if has_notional:
+            budget = _finite(order.get("notional"))
+            if budget is None or budget <= 0 or limit is None or limit <= 0:
+                self.rejected += 1
+                return None
+            # The QUOTIENT can overflow from two finite inputs: 1e308 / 0.01 is
+            # inf, and math.floor(inf) raises. Checked before the floor.
+            #
+            # floor(a / b), NOT a // b: Python's float floor-division is not
+            # the same function -- 80 // 0.64 is 124 where Math.floor(80 / 0.64)
+            # is 125, and 1 // 0.1 is 9.
+            q = budget / limit
+            if not math.isfinite(q):
+                self.rejected += 1
+                return None
+            size = float(math.floor(q))
+        else:
+            size = _finite(order.get("size"))
+        if size is None or not size > 0:
+            self.rejected += 1
+            return None
         if order.get("reduce_only"):
             size = min(size, leg.size)
             if not size > EPS:
                 self.rejected += 1
                 return None
 
-        res = match_order(book, {**order, "size": size})
+        # One effective order from here on -- AFTER the reduce_only clamp, so
+        # the row reports what was actually requested of the book rather than
+        # what the strategy asked for before clamping. The derived size has to
+        # reach the fill row as well as the match: it did not, and a
+        # notional-only order produced a row whose `requested` was NaN, which
+        # the parser dropped. The fill happened; only its record vanished.
+        # Mirrors portfolio.mjs.
+        order = {**order, "size": size, "limit": limit}
+
+        res = match_order(book, order)
         if res["filled"] <= 0:
             self.fills.append(self._fill_row(ts, market_id, order, res, tag, 0.0, 0.0))
             return res
@@ -470,15 +533,46 @@ class RunAbort(Exception):
 
 
 class BudgetMonitor:
-    def __init__(self, limit_micros: float = 400, sample_floor: int = 200,
-                 tolerance: float = 0.01) -> None:
+    """Per-event budget. The mirror of BudgetMonitor in engine/replay.mjs.
+
+    SUSTAINED cost, which is what the limit is for and what customers are told
+    it means. The mean, not the tail.
+
+    This judged the breach rate against a 1% tolerance, and it was measuring the
+    wrong machine: the budget brackets each hook with two wall-clock reads, on a
+    2-core box where the worker decompresses and feeds stdin the whole time, so
+    an event that gets descheduled is recorded as an event the strategy spent
+    4ms in. Measured inside the real image, the same strategy averages 7.8us on
+    an idle host and 20.9us under contention, with worst cases of 766us and
+    4090us. Nothing about the strategy changed.
+
+    The page's own sample was rejected in production at avg 72us, a fifth of its
+    400us budget, because 1.1% of its events had been interrupted -- and those
+    breaches were scattered (events 171, 2368, 3201), not front-loaded, so no
+    warm-up floor could have fixed it.
+
+    The mean predicts the thing this protects: the 20-minute wall clock is mean
+    times event count. A hook that never returns is caught by the run deadline,
+    which is where that belongs.
+
+    Windowed, not lifetime: one monitor covers the whole run, so a lifetime mean
+    lets a cheap prefix pay for an expensive phase.
+    """
+
+    def __init__(self, limit_micros: float = 400, sample_floor: int = 2000) -> None:
         self.limit_micros = limit_micros
         self.sample_floor = sample_floor
-        self.tolerance = tolerance
         self.count = 0
         self.breaches = 0
         self.max_micros = 0.0
         self.total_micros = 0.0
+        # The most recent sample_floor events, as a ring. One monitor covers the
+        # whole run, so a lifetime mean is diluted by everything that came
+        # before: 18,000 events at 8us then 2,000 at 2,000us averages 207us and
+        # passes, while the last two thousand are continuously 5x over budget.
+        self._window = [0.0] * sample_floor
+        self._window_sum = 0.0
+        self._window_at = 0
 
     def record(self, micros: float) -> None:
         self.count += 1
@@ -487,11 +581,20 @@ class BudgetMonitor:
             self.max_micros = micros
         if micros > self.limit_micros:
             self.breaches += 1
+        self._window_sum += micros - self._window[self._window_at]
+        self._window[self._window_at] = micros
+        self._window_at = (self._window_at + 1) % len(self._window)
+
+    @property
+    def window_micros(self) -> float:
+        """Mean of the most recent sample_floor events. Zero until it fills."""
+        if self.count < self.sample_floor:
+            return 0.0
+        return self._window_sum / len(self._window)
 
     @property
     def breached(self) -> bool:
-        return (self.count >= self.sample_floor
-                and self.breaches / self.count > self.tolerance)
+        return self.count >= self.sample_floor and self.window_micros > self.limit_micros
 
     def summary(self) -> dict:
         return {
@@ -499,6 +602,10 @@ class BudgetMonitor:
             "breaches": self.breaches,
             "breach_rate": (self.breaches / self.count) if self.count else 0,
             "avg_micros": (self.total_micros / self.count) if self.count else 0,
+            # The number the verdict is made on. Without it a rejection shows a
+            # lifetime average inside budget and reads as a lie.
+            "window_micros": self.window_micros,
+            "window_events": self.sample_floor,
             "max_micros": self.max_micros,
             "limit_micros": self.limit_micros,
         }

package/runner/harness/python/otfeed.py

@@ -0,0 +1,109 @@
+"""Point-in-time views over an out-of-band series — the Python half.
+
+The mirror of runner/engine/feed.mjs. ``ctx.ref(name)`` and ``ctx.ext(name)``
+call ``feed.view_at(ctx.now)`` here and ``feed.viewAt(ctx.now)`` there; neither
+existed until now, so a manifest declaring ``reference`` or ``series`` was
+accepted, queued, billed, and then crashed on the strategy's first
+``ctx.ref(...)`` claiming the feed had not been declared -- which it had.
+
+Two properties, the same two the JavaScript guarantees:
+
+1. NOTHING STAMPED AFTER ctx.now IS REACHABLE. The cursor never advances past
+   ``now``, so a later row is not something a strategy can ask for. It is not
+   filtered on the way out; it is not reachable. A reference feed is exactly
+   where look-ahead would otherwise leak, because we hold the whole series up
+   front.
+
+2. WHAT THE STRATEGY GETS IS A COPY. ``ctx.book()`` and ``ctx.history()`` were
+   both caught handing out live objects a strategy could rewrite; a rewritten
+   reference row would poison every later ``window()`` over it.
+
+``lag_ms`` models publication delay: a row is invisible until ts_ms + lag_ms.
+
+Any change here needs the same change in feed.mjs. runner/conformance compares
+the two engines row by row and will go red if they drift.
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+
+from otengine import Rec
+
+__all__ = ("PointInTimeFeed", "build_feeds")
+
+
+class _View:
+    """What a strategy holds. Read-only, and clamped to the moment it was made."""
+
+    __slots__ = ("_rows", "_n", "_horizon")
+
+    def __init__(self, rows, n, horizon):
+        self._rows = rows
+        self._n = n
+        self._horizon = horizon
+
+    @property
+    def last(self):
+        """The most recent row at or before now, or None."""
+        return Rec(self._rows[self._n - 1]) if self._n > 0 else None
+
+    def window(self, k):
+        """The last ``k`` visible rows, oldest first. Never more than exist."""
+        try:
+            want = int(k)
+        except (TypeError, ValueError):
+            want = 0
+        want = max(0, min(want, self._n))
+        return [Rec(r) for r in self._rows[self._n - want:self._n]]
+
+    def at(self, ts):
+        """The row in effect at ``ts``, clamped to now.
+
+        Asking for a later timestamp cannot reach a later row.
+        """
+        try:
+            asked = float(ts)
+        except (TypeError, ValueError):
+            asked = self._horizon
+        t = min(asked, self._horizon)
+        # bisect over the visible prefix only.
+        i = bisect_right([r["ts_ms"] for r in self._rows[:self._n]], t)
+        return Rec(self._rows[i - 1]) if i > 0 else None
+
+
+class PointInTimeFeed:
+    def __init__(self, rows, lag_ms=0):
+        self.rows = rows
+        try:
+            self.lag_ms = float(lag_ms) or 0.0
+        except (TypeError, ValueError):
+            self.lag_ms = 0.0
+        # Monotone cursor: replay only moves forward, so the feed is walked once
+        # across a market-day. A fresh feed is built per market, so this is not
+        # an assumption about what the strategy does.
+        self.cursor = 0
+
+    def _visible_count(self, now):
+        limit = now - self.lag_ms
+        rows = self.rows
+        while self.cursor < len(rows) and rows[self.cursor]["ts_ms"] <= limit:
+            self.cursor += 1
+        if self.cursor > 0 and rows[self.cursor - 1]["ts_ms"] > limit:
+            i = self.cursor
+            while i > 0 and rows[i - 1]["ts_ms"] > limit:
+                i -= 1
+            return i
+        return self.cursor
+
+    def view_at(self, now):
+        return _View(self.rows, self._visible_count(now), now - self.lag_ms)
+
+
+def build_feeds(declared, rows_by_name, lag_by_name=None):
+    """Feeds a run declared, keyed by the name the strategy will ask for."""
+    lag_by_name = lag_by_name or {}
+    return {
+        name: PointInTimeFeed(rows_by_name.get(name, []), lag_by_name.get(name, 0))
+        for name in (declared or [])
+    }

package/runner/harness/python/otreplay.py

@@ -14,11 +14,45 @@ the conformance vectors compare them row for row. In particular:
 
 from __future__ import annotations
 
+import os
+import select
 import time
 from typing import Any, Callable
 
 from otengine import Book, BudgetMonitor, Portfolio, Rec, RunAbort, make_rng
 
+
+def write_all(fd, data, write=os.write):
+    """Write every byte, or raise.
+
+    A bare `os.write` is a SHORT write waiting to happen, and the loss is
+    silent: it returns how many bytes it took and the caller that ignores the
+    number simply drops the rest. Under gVisor -- which is what runs in
+    production -- a write past the 64KB pipe buffer returns exactly 65536 and
+    the container exits 0, so nothing anywhere reports a problem.
+
+    That is not hypothetical. The result line carries one summary per market,
+    so it passes 64KB at roughly 500 markets; a market-day of polymarket is
+    ~386. Every Python run large enough to matter lost the tail of its result
+    line, the worker never saw a terminating newline, and `collect()` fell back
+    to a default whose markets_run is 0 -- reported to the customer as
+    "no market-days were replayed". Seventeen runs, no report, every one
+    refunded. Node was unaffected only because fs.writeSync loops internally.
+    """
+    view = memoryview(data)
+    while view:
+        try:
+            n = write(fd, view)
+        except BlockingIOError:
+            select.select([], [fd], [])
+            continue
+        if n <= 0:
+            # Not survivable and not silent: a result channel that accepts
+            # nothing means this run has no way to report anything at all.
+            raise OSError("short write to the result channel")
+        view = view[n:]
+
+
 HOOK_FOR = {"tick": "on_tick", "book": "on_book", "trade": "on_trade"}
 
 
@@ -93,6 +127,26 @@ class BookView:
 _INTERNALS: dict[int, dict] = {}
 
 
+# Mirrors LIMITS.logLineChars / LIMITS.logBytesPerRun in
+# api/lib/backtest-contract.mjs. Two engines disagreeing about how much a
+# strategy may log is the same strategy behaving differently in two languages,
+# which is the thing the conformance suite exists to prevent.
+LOG_LINE_CHARS = 512
+LOG_BYTES_PER_RUN = 2 * 1024 * 1024
+
+
+# A settlement recompute is a once-per-market claim, so these are generous.
+# `crosschecks` rides the same result line as everything else: unbounded, it is
+# an output channel with no budget. Mirrors replay.mjs.
+MAX_CROSSCHECKS_PER_MARKET = 16
+CROSSCHECK_CLAIMED_CHARS = 32
+
+
+def make_log_budget(bytes_: int = LOG_BYTES_PER_RUN, line_chars: int = LOG_LINE_CHARS) -> dict:
+    """A log allowance for one run, shared by every market in it."""
+    return {"bytes": bytes_, "line_chars": line_chars, "spent": 0}
+
+
 class Ctx:
     """The strategy's whole world.
 
@@ -102,9 +156,15 @@ class Ctx:
 
     __slots__ = ("p", "market_id", "__weakref__")
 
-    def __init__(self, params, portfolio, market_id, log_limit, references,
+    def __init__(self, params, portfolio, market_id, log_budget, references,
                  series, rng):
-        object.__setattr__(self, "p", params)
+        # Rec, not the bare dict the job JSON carries: the SDK documents
+        # `ctx.p.entry_z` and every Python example in the docs is written
+        # that way, so a plain dict makes all of them fail on the first
+        # hook with "'dict' object has no attribute ...", while the
+        # identical JavaScript runs. Same parity break Rec exists to stop;
+        # `p` was simply missed. Subscript access keeps working.
+        object.__setattr__(self, "p", Rec(params or {}))
         object.__setattr__(self, "market_id", market_id)
         _INTERNALS[id(self)] = {
             "now": 0,
@@ -112,7 +172,7 @@ class Ctx:
             "book": None,
             "history": [],
             "logs": [],
-            "log_limit": log_limit,
+            "log_budget": log_budget,
             "refs": references or {},
             "series": series or {},
             "rng": rng,
@@ -164,11 +224,23 @@ class Ctx:
         return s["pf"].position(self.market_id, s["book"])
 
     def log(self, msg: Any) -> None:
+        # Bytes for the WHOLE RUN, not lines per market -- the mirror of
+        # ctx.log in engine/replay.mjs. The old shape gave every market its own
+        # allowance of 10,000 unbounded lines, and polymarket has ~386 markets
+        # a day, so a run could pour the archive it had just paid for into a
+        # file the customer downloads.
         s = _INTERNALS[id(self)]
-        if len(s["logs"]) >= s["log_limit"]:
+        budget = s["log_budget"]
+        if budget["spent"] >= budget["bytes"]:
             s["log_truncated"] = True
             return
-        s["logs"].append(f'{s["now"]} {msg}')
+        line = f'{s["now"]} {msg}'[: budget["line_chars"]]
+        # BYTES, not characters -- logs.txt is UTF-8. The JS side counts the
+        # same way; a run logging Chinese would otherwise spend a third of what
+        # it actually writes. The line cap stays in characters (readability);
+        # the run cap is about how much data leaves with the customer.
+        budget["spent"] += len(line.encode("utf-8")) + 1
+        s["logs"].append(line)
 
     def random(self, seed: int | None = None):
         return _INTERNALS[id(self)]["rng"](seed)
@@ -232,9 +304,18 @@ class Ctx:
         """
         s = _INTERNALS[id(self)]
         official = (s["market"] or {}).get("outcome")
+        # BOUNDED, for the same reason ctx.log is, and mirrored in replay.mjs.
+        # `outcome` is whatever the strategy passed and this can be called on
+        # every event; the whole list is serialised onto the result line, sent
+        # and parsed before anything downstream can ignore it. The panel only
+        # shows an aggregate, and a settlement recompute is a once-per-market
+        # claim, so a cap costs nothing real.
+        if len(s["crosschecks"]) >= MAX_CROSSCHECKS_PER_MARKET:
+            return
+        claimed = outcome if isinstance(outcome, str) else str(outcome)
         s["crosschecks"].append({
             "market_id": self.market_id,
-            "claimed": outcome,
+            "claimed": claimed[:CROSSCHECK_CLAIMED_CHARS],
             "official": official,
             "match": official == outcome,
         })
@@ -242,7 +323,7 @@ class Ctx:
 
 def replay_market(*, market: dict, events: list, strategy, hooks: dict,
                   portfolio: Portfolio | None = None, fill_delay_ms: int = 0,
-                  log_limit: int = 10_000, budget: BudgetMonitor | None = None,
+                  log_budget: dict | None = None, budget: BudgetMonitor | None = None,
                   references=None, series=None, seed: int = 1,
                   fee_bps: float = 0) -> dict:
     market_id = market["market_id"]
@@ -257,7 +338,8 @@ def replay_market(*, market: dict, events: list, strategy, hooks: dict,
     pf = portfolio if portfolio is not None else Portfolio(fee_bps=fee_bps)
     book = Book(market_id)
     monitor = budget if budget is not None else BudgetMonitor()
-    ctx = Ctx(getattr(strategy, "p", {}) or {}, pf, market_id, log_limit,
+    ctx = Ctx(getattr(strategy, "p", {}) or {}, pf, market_id,
+              log_budget if log_budget is not None else make_log_budget(),
               references, series, make_rng(seed))
     state = _INTERNALS[id(ctx)]
     state["book"] = book

package/runner/harness/python/outcometick.py

@@ -9,6 +9,8 @@ with.
 
 from __future__ import annotations
 
+import math
+
 # Named explicitly so `from __future__ import annotations` does not leak
 # `annotations` into the package's public surface — this module is also
 # published to PyPI, where dir(outcometick) is what a user reads as the API.
@@ -40,13 +42,55 @@ class Order:
 
     __slots__ = ("side", "size", "limit", "hold_s", "reduce_only", "tif", "tag")
 
-    def __init__(self, side, size, limit=None, hold_s=None, reduce_only=False,
-                 tif="ioc", tag=None):
+    def __init__(self, side, size=None, limit=None, hold_s=None, reduce_only=False,
+                 tif="ioc", tag=None, notional=None):
         if side not in SIDES:
             raise ValueError(f'side must be "UP" or "DOWN", got {side!r}')
-        if not (isinstance(size, (int, float)) and size > 0):
+        # SIZING IN MONEY -- this is about the `notional` argument below.
+        # `size` is CONTRACTS (see OrderSizing in index.d.ts); it is not
+        # money, and reading this heading as if it were is the one wrong
+        # turn this comment can cause. Mirrors index.mjs exactly -- see
+        # the reasoning there.
+        # Position sizing is nearly always a budget, and the only honest
+        # divisor is your own limit: a contract costs whatever it fills at, so
+        # dividing by the current best price overspends the moment there is any
+        # slippage. `notional` therefore REQUIRES `limit`.
+        if notional is not None:
+            if size is not None:
+                raise ValueError(
+                    "give size or notional, not both -- they answer the same question two ways")
+            if not (isinstance(notional, (int, float)) and not isinstance(notional, bool)
+                    and math.isfinite(notional) and notional > 0):
+                raise ValueError(f"notional must be a positive number, got {notional!r}")
+            if limit is None:
+                raise ValueError(
+                    "notional needs a limit: without a price ceiling there is no way"
+                    " to turn a budget into a size")
+            px = float(limit)
+            if not (math.isfinite(px) and px > 0):
+                raise ValueError(f"notional needs a limit above 0, got {limit!r}")
+            # FLOOR, so the spend is at most the budget rather than around it.
+            # floor(a / b), NOT a // b — see otengine.py. Python's float
+            # floor-division disagrees with Math.floor(a / b) on decimal
+            # boundaries: 80 // 0.64 is 124, Math.floor(80 / 0.64) is 125.
+            derived = math.floor(notional / px)
+            if derived < 1:
+                raise ValueError(f"notional {notional} buys no contracts at limit {px}")
+            size = derived
+        # FINITE, and not a bool. Node's Order uses Number.isFinite here, so
+        # without this `Order(size=float("inf"))` constructs in Python and
+        # throws in JS -- the published SDK behaving differently in the two
+        # languages it ships for.
+        if not (isinstance(size, (int, float)) and not isinstance(size, bool)
+                and math.isfinite(size) and size > 0):
             raise ValueError(f"size must be a positive number, got {size!r}")
-        if limit is not None and not (0 <= float(limit) <= 1):
+        # A NUMBER, matching the engine and index.mjs. float('0.5') and
+        # Number('0.5') both give 0.5, but float([0.5]) raises where
+        # Number([0.5]) gives 0.5 -- the same published SDK behaving
+        # differently in the two languages it ships for.
+        if limit is not None and not (
+                isinstance(limit, (int, float)) and not isinstance(limit, bool)
+                and math.isfinite(limit) and 0 <= float(limit) <= 1):
             # A binary outcome token trades between 0 and 1. A limit outside
             # that is not a price, and silently clamping it would fill an order
             # the strategy never asked for.