outcometick 1.6.3 → 1.6.5

package/runner/engine/portfolio.mjs

@@ -12,8 +12,24 @@
 
 import { matchOrder, isSide } from './book.mjs';
 
-/** Settlement value of one contract, given the official outcome. */
-export const contractValue = (side, outcome) => (outcome === side ? 1 : 0);
+/**
+ * A market that settled 50:50. Predict.fun resolves end_price == start_price
+ * this way: both outcome tokens pay half a dollar.
+ */
+export const OUTCOME_TIE = 'TIE';
+
+/** Every official outcome a market can settle on. */
+export const OUTCOMES = Object.freeze(['UP', 'DOWN', OUTCOME_TIE]);
+
+/**
+ * Settlement value of one contract, given the official outcome.
+ *
+ * MUST MATCH otengine.py `contract_value`, and `scripts/audit-report.py`.
+ */
+export const contractValue = (side, outcome) => {
+  if (outcome === OUTCOME_TIE) return 0.5;
+  return outcome === side ? 1 : 0;
+};
 
 const EPS = 1e-9;
 

package/runner/engine/replay.mjs

@@ -571,14 +571,35 @@ export function replayMarket({
     control.setNow(ev.ts_ms);
 
     if (ev.kind === 'book') {
-      if (ev.snapshot) book.snapshot(ev.ts_ms, ev.levels);
+      // BEFORE the snapshot test, because a bound carries snapshot:false and
+      // would otherwise be applied as a delta with no ladder, no price and no
+      // size — which Book.delta rejects by throwing, taking the whole run with
+      // it.
+      if (ev.bbo) book.bbo(ev.ts_ms, ev.side, ev.bid, ev.ask);
+      else if (ev.snapshot) book.snapshot(ev.ts_ms, ev.levels);
       else book.delta(ev.ts_ms, ev.side, ev.ladder, ev.px, ev.size);
     }
     drainUntil(ev.ts_ms);
 
     if (ev.kind === 'tick') control.pushTick(ev);
 
-    const hook = HOOK_FOR[ev.kind];
+    // A BOUND REFINES THE BOOK SILENTLY. Three reasons it must not reach a hook,
+    // and the first one alone is enough:
+    //
+    //  - The event has no `levels`, `ladder`, `px` or `size`. Handing it to
+    //    on_book gives a documented SDK input a shape no documentation
+    //    describes, and a strategy reading ev.levels gets undefined.
+    //  - This stream is UNTHROTTLED — 1.3M rows in a day of BTC-5m against a
+    //    price_change stream thinned to 20-500ms. Firing a hook on each would
+    //    multiply hook invocations several-fold inside a 20-minute wall clock,
+    //    and a run that times out is refunded in full at our cost.
+    //  - Nothing is lost by staying quiet: ctx.book() is live, so the next real
+    //    event already sees the refined ladder. Pruning only ever REMOVES
+    //    liquidity, so not waking a strategy cannot cost it an opportunity that
+    //    existed — which is the direction this engine resolves ambiguity in.
+    //
+    // MUST MATCH otreplay.py. Both engines or neither.
+    const hook = ev.bbo ? null : HOOK_FOR[ev.kind];
     if (hook && hooks[hook]) emit(call(hook, ev), ev.ts_ms);
 
     if (monitor.breached) {

package/runner/engine/report.mjs

@@ -8,6 +8,8 @@
 // Nothing in this module can see the strategy. It reads the trade and fill logs
 // the engine produced, so a report cannot be tuned by the thing it is judging.
 
+import { contractValue } from './portfolio.mjs';
+
 /** Entry-price buckets for the calibration panel. */
 export const CALIBRATION_BUCKETS = Object.freeze([
   [0.0, 0.1], [0.1, 0.2], [0.2, 0.3], [0.3, 0.4], [0.4, 0.5],
@@ -181,10 +183,11 @@ export function metrics(trades, { feesPaid = 0, days = 1 } = {}) {
 /**
  * Mean realised edge per contract, in dollars.
  *
- * A binary token bought at p is worth 1 if its side settles and 0 otherwise, so
- * the edge on one contract is (outcome - p). Only settled trades carry an
- * outcome; a trade closed early is edge against the market, not against the
- * truth, and is excluded rather than scored as if it had settled.
+ * A binary token bought at p is worth 1 if its side settles and 0 otherwise
+ * (0.5 on a TIE — `contractValue`), so the edge on one contract is
+ * (outcome - p). Only settled trades carry an outcome; a trade closed early is
+ * edge against the market, not against the truth, and is excluded rather than
+ * scored as if it had settled.
  */
 export function edgePerContract(trades) {
   const settled = trades.filter((t) => t.how === 'settled' && t.entry_px != null && t.outcome);
@@ -192,8 +195,7 @@ export function edgePerContract(trades) {
   let contracts = 0;
   let edge = 0;
   for (const t of settled) {
-    const won = t.outcome === t.side ? 1 : 0;
-    edge += (won - t.entry_px) * t.size;
+    edge += (contractValue(t.side, t.outcome) - t.entry_px) * t.size;
     contracts += t.size;
   }
   return contracts > 0 ? edge / contracts : 0;
@@ -207,8 +209,7 @@ export function brier(trades) {
   const settled = trades.filter((t) => t.how === 'settled' && t.entry_px != null && t.outcome);
   if (!settled.length) return null;
   return mean(settled.map((t) => {
-    const won = t.outcome === t.side ? 1 : 0;
-    return (t.entry_px - won) ** 2;
+    return (t.entry_px - contractValue(t.side, t.outcome)) ** 2;
   }));
 }
 
@@ -268,7 +269,7 @@ export function calibration(trades) {
     const inBucket = settled.filter((t) => t.entry_px >= lo && t.entry_px < hi);
     if (!inBucket.length) return null;
     const implied = mean(inBucket.map((t) => t.entry_px));
-    const realized = mean(inBucket.map((t) => (t.outcome === t.side ? 1 : 0)));
+    const realized = mean(inBucket.map((t) => contractValue(t.side, t.outcome)));
     return {
       bucket: `${lo.toFixed(2)}-${hi.toFixed(2)}`,
       lo,
@@ -298,8 +299,8 @@ export function baselines(marketSummaries, { size = 1 } = {}) {
   const out = { always_up: 0, always_down: 0, always_favourite: 0 };
   for (const m of marketSummaries) {
     if (!m.outcome || m.up_px == null || m.down_px == null) continue;
-    out.always_up += ((m.outcome === 'UP' ? 1 : 0) - m.up_px) * size;
-    out.always_down += ((m.outcome === 'DOWN' ? 1 : 0) - m.down_px) * size;
+    out.always_up += (contractValue('UP', m.outcome) - m.up_px) * size;
+    out.always_down += (contractValue('DOWN', m.outcome) - m.down_px) * size;
     // The favourite is the side the market thinks is MORE likely, and on a
     // binary market the price IS the implied probability — so it is the DEARER
     // side, not the cheaper one. This was inverted: the panel labelled "always
@@ -307,7 +308,7 @@ export function baselines(marketSummaries, { size = 1 } = {}) {
     // handed customers a backwards comparison to judge their strategy against.
     const favSide = m.up_px >= m.down_px ? 'UP' : 'DOWN';
     const favPx = Math.max(m.up_px, m.down_px);
-    out.always_favourite += ((m.outcome === favSide ? 1 : 0) - favPx) * size;
+    out.always_favourite += (contractValue(favSide, m.outcome) - favPx) * size;
   }
   return {
     always_up: r2(out.always_up),

package/runner/events.mjs

@@ -6,14 +6,15 @@
 //
 // The lesson this is applying is the one runner/conformance already enforces
 // for the two engines: two implementations of the same rules drift, and the
-// drift is silent. "The identical files, same checksums, same coverage report"
+// drift is silent. "The identical files, byte for byte, with the same checksums"
 // is a published promise about `ot run` versus a queued run — it cannot be true
 // if local and remote decode the archive differently.
 
 import { classifyPath } from '../api/lib/data-taxonomy.mjs';
-import { resolveSettlementStream } from '../api/lib/backtest-datasets.mjs';
+import { resolveSettlementStream, degradingCoverage, inputKeys } from '../api/lib/backtest-datasets.mjs';
 import { bookThrottleMs } from '../api/lib/backtest-contract.mjs';
 import { Book } from './engine/book.mjs';
+import { OUTCOME_TIE, OUTCOMES } from './engine/portfolio.mjs';
 
 /**
  * Coerce a field to a number, or null.
@@ -146,16 +147,33 @@ function predictRecord(row) {
   const closeMs = num(row.end_sec) == null ? null : num(row.end_sec) * 1000;
   const start = num(row.start_price);
   const end = num(row.end_price);
-  // RESOLVED is the venue's own word for "this is final". An OPEN market has no
-  // outcome even if both prices are present — they are live quotes then, not a
-  // settlement, and treating them as one would hand a strategy the answer.
-  // Same rule, and the same reason: only a RESOLVED market with two readable
-  // prices has an outcome. A tie is not a guess either — the venue settles it
-  // one way and we do not know which, so the market-day is dropped.
-  const outcome = String(row.status).toUpperCase() === 'RESOLVED'
-    && start != null && end != null && end !== start
-    ? (end > start ? 'UP' : 'DOWN')
-    : null;
+  // `end_price` is the settlement marker, NOT `status`.
+  //
+  // This used to require status === 'RESOLVED', on the theory that an OPEN
+  // market's prices are live quotes rather than a settlement. Both halves were
+  // wrong. `end_price` is written only by the settlement backfill, which is
+  // driven by `end_price IS NULL` and drops a market from its re-read queue the
+  // moment it lands — so `status` is whatever the venue last said while we were
+  // still polling, and it freezes there. There is no row in the whole table
+  // with status RESOLVED and no end_price, so the implication runs one way
+  // only: end_price present ⇒ settled.
+  //
+  // MEASURED 2026-09-08, all assets: 1245 markets, every one of them with an
+  // end_price, but only 1104 said RESOLVED. The check discarded 39/873 of the
+  // 5-minute markets (4.5%) and 21/291 of the 15-minute ones (7.2%) — reported
+  // to the customer as "outcome could not be read" while the outcome was right
+  // there, and billed for, because a market-day charges whole.
+  //
+  // A TIE IS ITS OWN OUTCOME. Predict.fun settles end_price == start_price
+  // 50:50 — every UP and every DOWN contract pays $0.50 (`contractValue`).
+  // It used to be dropped because the engines only knew UP/DOWN, which cost the
+  // customer 0.53–1.20% of the 5-minute markets they paid for, reported as
+  // "outcome could not be read". Never "fix" a tie by picking a side: half of
+  // them would be scored backwards.
+  let outcome = null;
+  if (start != null && end != null) {
+    outcome = end > start ? 'UP' : end < start ? 'DOWN' : OUTCOME_TIE;
+  }
   return {
     market_id: String(row.market_id ?? row.condition_id ?? ''),
     slug: row.category_slug ?? null,
@@ -465,6 +483,58 @@ export function eventsFromRow(filePath, row, markets, bySlug = null, throttle =
     }]];
   }
 
+  if (meta.dataset === 'best_bid_ask') {
+    // TOP OF BOOK AS A BOUND, not as a quote.
+    //
+    // This stream carries prices and no sizes, so it can never say what IS on
+    // the ladder — only what is NOT: "nothing better than this exists right
+    // now". The engine uses it to delete levels the venue has moved past and
+    // never to add one, because a level invented without a size is exactly the
+    // fabricated liquidity this product has had to fix five times.
+    //
+    // Emitted as kind:'book' deliberately: on_book already fires for the book,
+    // a strategy reads the refined ladder rather than this row, and no new hook
+    // or SDK surface appears. `bbo` marks it as a bound so the engine does not
+    // mistake it for a delta with a missing size.
+    const side = sideOfToken(market, row.asset_id ?? payload.asset_id);
+    if (!side) return [];
+    const bid = num(payload.best_bid);
+    const ask = num(payload.best_ask);
+    // MEASURED, over 900,000 rows across BTC-5m, SOL-15m and DOGE-5m on
+    // 2026-09-04: zero crossed, zero equal, zero outside [0,1], zero
+    // unparseable. So none of these guards fire on today's archive — they are
+    // here because the failure they prevent is silent and total. A garbage
+    // bound is a MAXIMAL deletion instruction: one unreadable row would empty a
+    // ladder, the market would stop filling, and the run would come back with
+    // an honest-looking report of a strategy that could not trade.
+    //
+    // Fail-safe rather than fail-closed, and that is the one place this differs
+    // from the rest of this file: dropping a bbo row costs nothing but the
+    // refinement, leaving the book exactly as it was before 2026-09-02. There
+    // is no wrong answer to propagate, so the market is not dropped.
+    if (bid == null || ask == null) return [];
+    if (bid < 0 || bid > 1 || ask < 0 || ask > 1) return [];
+    if (bid > ask) return [];
+    // 0 and 1 need NO special case, which is why the rule is phrased as a
+    // bound. `best_bid = "0"` is how the venue writes "no bid", and deleting
+    // every bid strictly better than 0 deletes all of them — correct. Its
+    // complement is `best_ask = "1"` on the other token of the same market,
+    // because UP + DOWN = 1: measured as an exact pairing, 3228 `bid=0 ask=0.01`
+    // against 3228 `bid=0.99 ask=1`, every count matching. An earlier version of
+    // this rule treated [0.001, 0.999] as the valid domain and would have
+    // thrown away precisely those rows — the ones carrying the MOST definite
+    // information about the book.
+    return [[id, {
+      kind: 'book',
+      ts_ms: ts,
+      snapshot: false,
+      bbo: true,
+      side,
+      bid,
+      ask,
+    }]];
+  }
+
   if (meta.dataset === 'price_change') {
     // A delta carries a batch, each entry naming its own token and ladder side.
     const changes = Array.isArray(payload.price_changes) ? payload.price_changes : [];
@@ -530,7 +600,7 @@ export function buildSlugIndex(markets) {
  * The coverage block, in ONE shape.
  *
  * The docs promise a local run and a queued run produce "the identical files,
- * same checksums, same coverage report". They already shared the decoder and
+ * byte for byte, with the same checksums". They already shared the decoder and
  * the feed list; the coverage object was still built twice, so `ot run` emitted
  * five keys where the queue emitted ten, and anyone diffing the two saw a
  * schema difference rather than an answer. A field a local run genuinely cannot
@@ -546,6 +616,21 @@ export function buildCoverage({
   streams = {},
   droppedRows = 0,
   unreconciledRows = 0,
+  /**
+   * Did the manifest declare `bbo`, and on which of the run's days did the
+   * archive actually have it?
+   *
+   * Always emitted, even when nothing declared it, because these three keys are
+   * the only place a reader can tell which book a report was computed against.
+   * `bbo` refines the ladder by deleting levels the venue has moved past, and a
+   * run over 2026-06-10 and a run over 2026-09-04 both succeed while using two
+   * different books. Same reason `fill_delay_ms` is written out: without it,
+   * whoever holds the archive cannot tell which of the two they have.
+   */
+  bboDeclared = false,
+  bboDays = [],
+  bboMissingDays = [],
+  bboPartialDays = [],
   local = false,
   source = null,
 }) {
@@ -568,11 +653,81 @@ export function buildCoverage({
     // Rows the harness produced that do not describe a market the caller
     // supplied. Published rather than swallowed.
     unreconciled_rows: unreconciledRows,
+    // Which book this report was computed against. `bbo_missing_days` is not an
+    // error and is not a gap in the archive for the days before 2026-09-02 —
+    // nothing was ever captured then. It is the list of days that ran exactly
+    // as this product ran for its whole life before that stream existed.
+    bbo_declared: bboDeclared,
+    bbo_days: bboDays,
+    bbo_missing_days: bboMissingDays,
+    // Dates where SOME market-days got the refinement and some did not, each
+    // naming the `asset|interval` that did not. A date is never in more than
+    // one of these three, and the three together are every date scanned.
+    bbo_partial_days: bboPartialDays,
     // Local-only, and last: a queued run has no source directory to name.
     ...(local ? { local: true, source } : {}),
   };
 }
 
+/**
+ * Which of a run's days the unthrottled top-of-book stream actually covered.
+ *
+ * SHARED, for the reason every predicate in this file is shared: `ot run` and
+ * the queue have drifted apart nine times, always by each computing a rule the
+ * other also computes. This one decides what a report SAYS about itself, so a
+ * second copy would let the local run and the queue describe the same archive
+ * differently.
+ *
+ * Days come from the markets actually scanned rather than from the requested
+ * range, so the answer describes the run that happened.
+ *
+ * `bbo_missing_days` is not an error and not a gap in our archive: before
+ * 2026-09-02 nothing was captured, so those days ran exactly as this product
+ * ran for its whole life before the stream existed. Reported anyway, because
+ * two runs that used different books are otherwise indistinguishable — the same
+ * reason `fill_delay_ms` is written out.
+ */
+export { inputKeys };
+
+export function bboCoverage({ venue, datasets, markets, applied = null }) {
+  if (!(datasets ?? []).includes('bbo')) {
+    return { bboDeclared: false, bboDays: [], bboMissingDays: [], bboPartialDays: [] };
+  }
+  // MEASURED OR NOTHING. There used to be a fallback that inferred coverage
+  // from CAPTURE_WINDOWS when no measurement was passed, and that is fail-OPEN
+  // for precisely the bug this function exists to prevent: a caller added later
+  // — or a refactor that drops an argument — would silently go back to claiming
+  // a refinement the replay never had. The window says what SHOULD have been
+  // possible; only the decode knows what happened.
+  if (!applied) {
+    throw new Error('bboCoverage: `applied` is required when the manifest declares bbo '
+      + '— coverage must be measured from what was decoded, never inferred from the capture window');
+  }
+
+  // THE UNIT IS THE MARKET-DAY, the same `asset|day|interval` the run is billed
+  // on. Collapsing to the date makes one asset speak for every asset.
+  const byDay = new Map();
+  for (const m of markets ?? []) {
+    const day = m?.day;
+    if (!day) continue;
+    if (!byDay.has(day)) byDay.set(day, new Set());
+    byDay.get(day).add(`${m.market?.asset ?? 'unknown'}|${m.market?.interval ?? 'none'}`);
+  }
+
+  const full = [], none = [], partial = [];
+  for (const day of [...byDay.keys()].sort()) {
+    const scanned = [...byDay.get(day)];
+    const got = applied.get(day) ?? new Set();
+    const without = scanned.filter((k) => !got.has(k)).sort();
+    if (without.length === 0) full.push(day);
+    else if (without.length === scanned.length) none.push(day);
+    // NAMED, not counted. "Some of 2026-09-04 ran on the old book" is not
+    // actionable; "ETH|5m did" is. Same reason uncapturedRange returns the gap.
+    else partial.push({ day, without });
+  }
+  return { bboDeclared: true, bboDays: full, bboMissingDays: none, bboPartialDays: partial };
+}
+
 /**
  * The billing unit: one asset on one UTC day.
  *
@@ -697,7 +852,7 @@ export function marketUnusable(market, inWindow) {
   // nothing to merge — replayed it out of the cache anyway.
   if (!market.asset) return 'market has no asset';
   if (market.stream == null) return 'settlement stream could not be resolved';
-  if (market.outcome !== 'UP' && market.outcome !== 'DOWN') {
+  if (!OUTCOMES.includes(market.outcome)) {
     return 'outcome could not be read';
   }
   if (!inWindow || inWindow.length === 0) return 'no events inside the market window';
@@ -781,7 +936,15 @@ export function finaliseMarket(events, market) {
   let downPx = null;
   for (const ev of inWindow) {
     if (ev.kind !== 'book') continue;
-    if (ev.snapshot) book.snapshot(ev.ts_ms, ev.levels);
+    // THE SAME THREE BRANCHES AS replay.mjs, IN THE SAME ORDER. A bound was
+    // missing here while the engine applied it, so the strategy traded against
+    // a pruned ladder and the report compared it to an unpruned one: a bound
+    // landing between the UP and DOWN snapshots left up_px at the stale 0.44
+    // while ctx.book() already said 0.45. The baseline is what every headline
+    // number is measured against, so a book it never traded on is worse than a
+    // missing baseline.
+    if (ev.bbo) book.bbo(ev.ts_ms, ev.side, ev.bid, ev.ask);
+    else if (ev.snapshot) book.snapshot(ev.ts_ms, ev.levels);
     else if (ev.side && ev.ladder) book.delta(ev.ts_ms, ev.side, ev.ladder, ev.px, ev.size);
     // BOTH SIDES FROM ONE BOOK STATE, captured together.
     //

package/runner/harness/node/sdk/index.d.ts

@@ -12,6 +12,13 @@
 
 export type Side = 'UP' | 'DOWN';
 
+/**
+ * How a market settled. `'TIE'` is a 50:50 settlement — Predict.fun resolves
+ * an end price equal to the start price this way, and every UP and DOWN
+ * contract pays $0.50.
+ */
+export type Outcome = Side | 'TIE';
+
 export declare const SIDES: readonly ['UP', 'DOWN'];
 
 /** One level of resting depth: [price, size]. */
@@ -129,7 +136,7 @@ export interface Ctx<P = Record<string, unknown>> {
    * one. Recorded for the cross-check panel, never enforced — a mismatch is
    * information, not a failed run.
    */
-  assert_outcome(market: unknown, outcome: Side): void;
+  assert_outcome(market: unknown, outcome: Outcome): void;
 }
 
 /**
@@ -207,7 +214,7 @@ export declare class Order {
  *     onTick(ctx: Ctx, tick: Tick): Order | null
  *     onBook(ctx: Ctx, book: BookView): Order | null
  *     onTrade(ctx: Ctx, trade: Tick): Order | null
- *     onSettle(ctx: Ctx, market: Market, outcome: Side): void
+ *     onSettle(ctx: Ctx, market: Market, outcome: Outcome): void
  */
 export declare class Strategy<P = Record<string, unknown>> {
   /** Params from the manifest, injected by the runner before the first hook. */

package/runner/harness/protocol.mjs

@@ -6,6 +6,7 @@
 // untrusted output — the container is the boundary, not the harness.
 //
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { OUTCOMES } from '../engine/portfolio.mjs';
 
 // This is also the reason the REPORT is not computed inside. Metrics,
 // calibration, latency and slippage are all derived outside, in one shared
@@ -159,7 +160,7 @@ export function parseTrade(raw) {
     opened_ms: finite(raw.opened_ms) ? raw.opened_ms : null,
     closed_ms: finite(raw.closed_ms) ? raw.closed_ms : null,
     how: typeof raw.how === 'string' ? raw.how : 'exit',
-    outcome: raw.outcome === 'UP' || raw.outcome === 'DOWN' ? raw.outcome : undefined,
+    outcome: OUTCOMES.includes(raw.outcome) ? raw.outcome : undefined,
   };
 }
 
@@ -232,7 +233,7 @@ export function parseResult(raw) {
       market_id: typeof m.market_id === 'string' ? m.market_id : null,
       asset: typeof m.asset === 'string' ? m.asset : null,
       interval: typeof m.interval === 'string' ? m.interval : null,
-      outcome: m.outcome === 'UP' || m.outcome === 'DOWN' ? m.outcome : null,
+      outcome: OUTCOMES.includes(m.outcome) ? m.outcome : null,
       up_px: finite(m.up_px) ? m.up_px : null,
       down_px: finite(m.down_px) ? m.down_px : null,
       stream: typeof m.stream === 'string' ? m.stream : null,

package/runner/harness/python/otengine.py

@@ -85,27 +85,33 @@ class Ladder:
 
     def __init__(self, direction: int) -> None:
         self.direction = direction
-        self.levels: list[list[int | float]] = []  # [ticks, size], best first
+        # [ticks, size, ts], best first. `ts` is when this level was last
+        # stated by the archive; `prune` needs it to tell a level the venue has
+        # moved past from one stamped the same millisecond as the bound that
+        # would delete it. Kept as a third slot rather than a parallel map so
+        # both engines carry it the same way.
+        self.levels: list[list[int | float]] = []
 
     def _worse(self, a: int, b: int) -> int:
         return (a - b) if self.direction > 0 else (b - a)
 
-    def reset(self, levels: Iterable[Any]) -> None:
+    def reset(self, levels: Iterable[Any], ts: int = 0) -> None:
         rows = []
         for entry in levels or ():
             px, size = entry[0], float(entry[1])
             if size > 0:
-                rows.append([to_ticks(float(px)), size])
+                rows.append([to_ticks(float(px)), size, ts])
         rows.sort(key=lambda r: r[0] * (1 if self.direction > 0 else -1))
         self.levels = rows
 
-    def apply(self, px: float, size: float) -> None:
+    def apply(self, px: float, size: float, ts: int = 0) -> None:
         ticks = to_ticks(float(px))
         n = float(size)
         for i, level in enumerate(self.levels):
             if level[0] == ticks:
                 if n > 0:
                     level[1] = n
+                    level[2] = ts
                 else:
                     self.levels.pop(i)
                 return
@@ -114,7 +120,54 @@ class Ladder:
         j = len(self.levels)
         while j > 0 and self._worse(self.levels[j - 1][0], ticks) > 0:
             j -= 1
-        self.levels.insert(j, [ticks, n])
+        self.levels.insert(j, [ticks, n, ts])
+
+    def prune(self, bound: float | None, ts: int) -> int:
+        """Delete every level STRICTLY BETTER than `bound` that is older than `ts`.
+
+        The whole of what the unthrottled top-of-book stream may do. It carries
+        prices and no sizes, so it can state what is NOT on the ladder and never
+        what is; adding a level from it would be liquidity invented without a
+        size.
+
+        Why it matters: `take()` eats from the best end while the delta stream
+        maintaining this ladder is thinned to the venue's capture cadence, so the
+        stalest levels are exactly the ones an order hits first — and stale in
+        one direction only, since a price already taken still looks available.
+
+        OLDER THAN, not "at or older than": a delta and a bound stamped the same
+        millisecond contradict each other and the archive does not say which came
+        first, so requiring the level to be strictly older makes the result the
+        same whichever way a tie was sorted.
+
+        MUST MATCH Ladder.prune in runner/engine/book.mjs exactly.
+        """
+        # A NUMBER, not something that parses as one. float('0.45') is 0.45
+        # while JavaScript's Number.isFinite('0.45') is false, so accepting
+        # strings here would make the same event prune in Python and not in
+        # Node. bool is excluded because it is an int in Python and True would
+        # otherwise read as the bound 1.
+        if not isinstance(bound, (int, float)) or isinstance(bound, bool):
+            return 0
+        b = float(bound)
+        if b != b or b in (float("inf"), float("-inf")):
+            return 0
+        # Inside [0, 1], for the reason spelled out in Ladder.prune in
+        # runner/engine/book.mjs: a bound is a maximal deletion instruction, and
+        # an outcome token cannot quote outside that range.
+        if b < 0.0 or b > 1.0:
+            return 0
+        cap = to_ticks(b)
+        kept = []
+        removed = 0
+        for level in self.levels:
+            if self._worse(level[0], cap) < 0 and level[2] < ts:
+                removed += 1
+                continue
+            kept.append(level)
+        if removed:
+            self.levels = kept
+        return removed
 
     def best(self) -> float | None:
         return from_ticks(self.levels[0][0]) if self.levels else None
@@ -122,14 +175,14 @@ class Ladder:
     def depth(self, bound: float | None = None) -> float:
         cap = None if bound is None else to_ticks(float(bound))
         total = 0.0
-        for ticks, size in self.levels:
+        for ticks, size, _ts in self.levels:
             if cap is not None and self._worse(ticks, cap) > 0:
                 break
             total += size
         return total
 
     def view(self, n: int = 10) -> list[list[float]]:
-        return [[from_ticks(t), s] for t, s in self.levels[:n]]
+        return [[from_ticks(t), s] for t, s, _ts in self.levels[:n]]
 
     def take(self, size: float, bound: float | None):
         cap = None if bound is None else to_ticks(float(bound))
@@ -169,8 +222,8 @@ class Book:
             spec = (levels or {}).get(side)
             if not spec:
                 continue
-            self.ladders[side]["asks"].reset(spec.get("asks"))
-            self.ladders[side]["bids"].reset(spec.get("bids"))
+            self.ladders[side]["asks"].reset(spec.get("asks"), ts)
+            self.ladders[side]["bids"].reset(spec.get("bids"), ts)
 
     def delta(self, ts: int, side: str, kind: str, px: float, size: float) -> None:
         self.ts = ts
@@ -178,7 +231,26 @@ class Book:
             raise ValueError(f"unknown side {side}")
         if kind not in ("asks", "bids"):
             raise ValueError(f"unknown ladder {kind}")
-        self.ladders[side][kind].apply(px, size)
+        self.ladders[side][kind].apply(px, size, ts)
+
+    def bbo(self, ts: int, side: str, bid: float | None, ask: float | None) -> int:
+        """Apply an unthrottled top-of-book bound. DELETES ONLY.
+
+        `bid` and `ask` are prices with no size behind them, so they can shrink
+        the book and never grow it.
+
+        0 and 1 need no special case. `bid = 0` is how the venue writes "no bid",
+        and deleting every bid strictly better than 0 deletes all of them. Its
+        complement is `ask = 1` on the other token of the same market, since
+        UP + DOWN = 1 — measured as an exact pairing in the archive.
+
+        MUST MATCH Book.bbo in runner/engine/book.mjs exactly.
+        """
+        self.ts = ts
+        if side not in SIDES:
+            raise ValueError(f"unknown side {side}")
+        lad = self.ladders[side]
+        return lad["asks"].prune(ask, ts) + lad["bids"].prune(bid, ts)
 
     def best(self, side: str) -> float | None:
         """The price to BUY that outcome at — the best ask."""
@@ -249,7 +321,14 @@ def match_order(book: Book, order: dict) -> dict:
     }
 
 
-def contract_value(side: str, outcome: str) -> int:
+OUTCOME_TIE = "TIE"
+
+
+def contract_value(side: str, outcome: str) -> float:
+    # A tie settles 50:50: both outcome tokens pay half a dollar. MUST MATCH
+    # portfolio.mjs `contractValue`.
+    if outcome == OUTCOME_TIE:
+        return 0.5
     return 1 if outcome == side else 0
 
 

package/runner/harness/python/otreplay.py

@@ -429,7 +429,13 @@ def replay_market(*, market: dict, events: list, strategy, hooks: dict,
         state["now"] = ts
 
         if ev.get("kind") == "book":
-            if ev.get("snapshot"):
+            # BEFORE the snapshot test, because a bound carries snapshot:false
+            # and would otherwise be applied as a delta with no ladder, no price
+            # and no size — which Book.delta rejects by raising, taking the whole
+            # run with it. MUST MATCH the same ordering in runner/engine/replay.mjs.
+            if ev.get("bbo"):
+                book.bbo(ts, ev.get("side"), ev.get("bid"), ev.get("ask"))
+            elif ev.get("snapshot"):
                 book.snapshot(ts, ev.get("levels") or {})
             else:
                 book.delta(ts, ev.get("side"), ev.get("ladder"), ev.get("px"), ev.get("size"))
@@ -441,7 +447,11 @@ def replay_market(*, market: dict, events: list, strategy, hooks: dict,
             # comment in replay.mjs.
             state["history"].append(Rec(ev))
 
-        hook = HOOK_FOR.get(ev.get("kind"))
+        # A bound refines the book silently and never reaches a hook — the event
+        # has no levels/ladder/px/size, the stream is unthrottled, and ctx.book()
+        # is live so the next real event already sees the refined ladder. Full
+        # reasoning in replay.mjs; both engines or neither.
+        hook = None if ev.get("bbo") else HOOK_FOR.get(ev.get("kind"))
         if hook and hooks.get(hook):
             emit(call(hook, ev_rec), ts)