outcometick 1.6.2 → 1.6.4

package/README.md

@@ -5,7 +5,7 @@
   scripts/publish-sdk-repos.mjs and overwritten wholesale on each publish.
   An edit made here survives until the next publish and then disappears.
 
-  Generated from monorepo revision 5c26d7ed75e2172fff108af183089aa1460652ba.
+  Generated from monorepo revision c44df8d3662f109757247e01752e966858db6a05.
 -->
 
 # outcometick
@@ -18,7 +18,7 @@ Predict.fun crypto Up/Down markets.
 npm i -g outcometick
 
 ot check .                                           # validate, free, no data
-ot run . --data ./polymarket-data-samples --date …   # replay locally
+ot run . --data ./polymarket-data-samples            # replay locally
 ot submit . --assets btc,eth --from … --to …         # send it to the queue
 ot status <run_id>                                   # where it got to
 ot fetch  <run_id>                                   # download the report
@@ -63,7 +63,7 @@ ship in this package rather than being reimplemented client-side.
 It is the same engine, the same report and the same archive format the queue
 uses, against a local copy of the archive:
 
-    git clone https://github.com/Ligengxin96/polymarket-data-samples
+    curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz
 
 It is **not** the sandbox. Locally your strategy runs as you, with your
 privileges, on your machine — which is fine, because it is your code. On our

package/api/lib/backtest-contract.mjs

@@ -15,7 +15,7 @@ import { FIRST_COMPLETE_DAY } from './coverage-window.mjs';
 export const SCHEMA_VERSION = 1;
 
 /** SDK version reported by the docs page and stamped into every report. */
-export const SDK_VERSION = '1.6.2';
+export const SDK_VERSION = '1.6.4';
 
 /**
  * The tag of the sandbox images, and the ONLY place it is written down.
@@ -60,7 +60,7 @@ export const SDK_VERSION = '1.6.2';
  * forwarded a fourth descriptor, so fd 3 was closed inside the container and no
  * containerised run had ever returned anything.
  */
-export const SANDBOX_IMAGE_TAG = '1.14.0';
+export const SANDBOX_IMAGE_TAG = '1.15.0';
 
 // ---------------------------------------------------------------------------
 // Languages
@@ -154,12 +154,53 @@ export const DATASETS = Object.freeze({
   twap30s: 'TWAP over a 30-second lookback.',
   twap60s: 'TWAP over a 60-second lookback.',
   book: 'Order-book snapshots and deltas.',
+  bbo: 'Unthrottled top of book. Prices only, no sizes — it removes ladder levels the venue has since moved past, and never adds any.',
   trades: 'Every trade print on the venue.',
   markets: 'Per-market metadata, strike and settlement outcome.',
 });
 
 export const KNOWN_DATASETS = Object.freeze(Object.keys(DATASETS));
 
+/**
+ * Declarable, but NOT part of the manifest the editor seeds or the prewarm warms.
+ *
+ * Two reasons, and NOT coverage — see DEGRADING_DATASETS: a range that predates
+ * the stream runs fine, so seeding it would not break anything.
+ *
+ * 1. REPORT CONTINUITY. bbo changes which ladder levels are fillable, so
+ *    turning it on by default changes the fills of every manifest already
+ *    written. Reports we have already delivered would stop reproducing, and
+ *    the customer did not ask for a different book.
+ * 2. BANDWIDTH. Archive fetch is the binding constraint (1.9-3.5 MB/s against a
+ *    20-minute wall clock), and the busiest series measure +13%~+29% on top of
+ *    a ~112MB market-day. That is charged to every run, including the ones
+ *    that would never look at it.
+ *
+ * The cost of opt-in is that an opted-in run pays a full decode instead of
+ * hitting the prewarm, because the prewarm warms the default shape. That is the
+ * honest trade: warming both shapes doubles a cache sized in tens of GB.
+ */
+export const OPT_IN_DATASETS = Object.freeze(['bbo']);
+
+/**
+ * Datasets that DEGRADE instead of rejecting when the archive lacks them.
+ *
+ * The general rule for a captured stream is the opposite — outside its window
+ * is E_COVERAGE, never a silent substitution — and that rule is right for
+ * anything a strategy READS. `bbo` is different in kind: a strategy never reads
+ * it. It refines the order book by deleting levels the venue has since moved
+ * past, so a day without it is not a wrong answer, it is the answer this
+ * product gave for its whole life before 2026-09-02.
+ *
+ * So a range that straddles the start of capture runs: the days that have it
+ * are refined, the days that do not behave exactly as they did before. What is
+ * NOT optional is saying so — `bbo_days` / `bbo_missing_days` in coverage and
+ * `bbo_applied` in the report, for the same reason `fill_delay_ms` is written
+ * out: two reports that used different books are otherwise identical, and
+ * whoever holds the archive has no way to tell which one they have.
+ */
+export const DEGRADING_DATASETS = Object.freeze(['bbo']);
+
 /**
  * A derived stream is computed from one we hold rather than captured. It is
  * always flagged as derived on every row, and may never be presented as the
@@ -194,6 +235,12 @@ export const CAPTURE_WINDOWS = Object.freeze({
     twap30s: Object.freeze({ from: '2026-08-07', to: null }),
     twap60s: Object.freeze({ from: '2026-08-07', to: null }),
     book: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
+    // MEASURED, not the deploy date: collection began 2026-09-02T00:42:18.154Z,
+    // so 09-02 is missing its first 42 minutes and every market that opened in
+    // them has no top of book at all. Registering 09-02 would accept a run over
+    // a day it can only half serve — silent degradation, which is the one thing
+    // a stream added mid-archive must not do. 09-03 is the first complete day.
+    bbo: Object.freeze({ from: '2026-09-03', to: null }),
     trades: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
     markets: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
   }),
@@ -575,6 +622,12 @@ export const REJECTION_CODES = Object.freeze({
   E_COVERAGE: 'A captured stream was requested outside the window it was captured in.',
   E_LIMIT: 'A submission limit was exceeded — file count, total source size or series size.',
   E_SCOPE: 'The requested venue, asset or date range is not something we can serve.',
+  // The only one `ot check` cannot produce: it means the run started and did not
+  // finish. Used in eleven places across the API, the CLI and the worker long before
+  // it was declared here — so the docs table, which renders these keys, never listed
+  // the one code a customer was most likely to be holding when they came to look it up.
+  E_RUNTIME: 'The run started but could not finish — the sandbox crashed, the feed to it was'
+    + ' cut short, or the replay ended early. Nothing was billed.',
 });
 
 export const KNOWN_REJECTION_CODES = Object.freeze(Object.keys(REJECTION_CODES));

package/api/lib/backtest-datasets.mjs

@@ -11,7 +11,8 @@
 import { classifyPath } from './data-taxonomy.mjs';
 import {
   CAPTURE_WINDOWS, DERIVED_DATASETS, KNOWN_DATASETS, BacktestRejection,
-  MARKET_INTERVALS, DEFAULT_INTERVALS, MAX_LATENCY_MS,
+  MARKET_INTERVALS, DEFAULT_INTERVALS, MAX_LATENCY_MS, OPT_IN_DATASETS,
+  DEGRADING_DATASETS,
 } from './backtest-contract.mjs';
 
 /**
@@ -28,9 +29,15 @@ const ARCHIVE_DATASETS = Object.freeze({
     twap30s: Object.freeze(['twap30s']),
     twap60s: Object.freeze(['twap60s']),
     book: Object.freeze(['book', 'price_change']),
+    bbo: Object.freeze(['best_bid_ask']),
     trades: Object.freeze(['last_trade_price']),
     markets: Object.freeze(['markets']),
   }),
+  // Predict.fun has no equivalent stream. Deliberately absent rather than
+  // mapped to something close: `archiveDatasetsFor` would silently fetch
+  // nothing, and a strategy would get an empty feed with no error. The
+  // rejection comes from CAPTURE_WINDOWS.predict having no `bbo` entry, which
+  // makes uncapturedRange return the whole range -> E_COVERAGE.
   predict: Object.freeze({
     prices: Object.freeze(['prices']),
     twap30s: Object.freeze(['twap30s']),
@@ -140,6 +147,11 @@ const nextDay = (d) => shiftDay(d, 1);
 export function assertCoverage({ datasets, venue, from, to }) {
   for (const ds of datasets ?? []) {
     if (ds === 'settlement') continue;
+    // A degrading dataset never blocks a run: where the archive has it the run
+    // is refined, where it does not the run behaves as it always did. The days
+    // it covers are reported rather than enforced — see bboCoverage below and
+    // DEGRADING_DATASETS for why this one is not like the others.
+    if (DEGRADING_DATASETS.includes(ds)) continue;
     if (DERIVED_DATASETS[ds]) {
       // A derived stream is a function of one we hold, so its availability is
       // the SOURCE stream's availability, not its own.
@@ -164,6 +176,76 @@ export function assertCoverage({ datasets, venue, from, to }) {
   }
 }
 
+/**
+ * Did this day actually read the archive dataset, judged by what it was decoded
+ * from rather than by what was asked for?
+ *
+ * `inputs` are "<path>:<sha256>" entries recorded by the decoder for every
+ * object it really opened. The sha is hex and paths do not contain a colon at
+ * the end, so the split is on the LAST one.
+ *
+ * WHY NOT THE REQUESTED DATASET LIST. A day inside the capture window whose
+ * object is simply missing from the catalog — our outage, not the customer's
+ * date range — still asks for `best_bid_ask`, decodes fine on the old book, and
+ * would be reported as covered. The report would then claim a refinement the
+ * replay never had.
+ */
+export function inputsInclude(inputs, archiveDataset) {
+  return inputKeys(inputs, archiveDataset).size > 0;
+}
+
+/**
+ * Which MARKET-DAYS an archive dataset was actually read for: `asset|interval`.
+ *
+ * The day alone is not the unit. A run reads each asset group separately and
+ * their inputs are merged, so "this date opened a best_bid_ask object" is true
+ * as soon as ONE asset did — a BTC+ETH run where only BTC has the object would
+ * replay ETH on the old book and report the whole date as covered. Same
+ * false-coverage class as inferring from the capture window, hidden one
+ * dimension further in.
+ *
+ * `asset|interval` rather than the full billing key because the caller already
+ * knows which day it is asking about; joined with the day it is exactly the
+ * `asset|day|interval` that countMarketDays bills on.
+ *
+ * A venue-wide object carries no asset (markets metadata does not), so it
+ * contributes nothing here — which is right: it is not a per-market-day fact.
+ */
+export function inputKeys(inputs, archiveDataset) {
+  const out = new Set();
+  for (const entry of inputs ?? []) {
+    const raw = String(entry);
+    // The sha is hex and an object key has no trailing colon, so split on the
+    // LAST one — a path that itself contains a colon must still classify.
+    const cut = raw.lastIndexOf(':');
+    const p = cut > 0 ? raw.slice(0, cut) : raw;
+    const c = classifyPath(p);
+    if (c.dataset !== archiveDataset) continue;
+    if (!c.asset) continue;
+    out.add(`${c.asset}|${c.interval ?? 'none'}`);
+  }
+  return out;
+}
+
+/**
+ * Split a run's days into the ones a degrading dataset covers and the ones it
+ * does not, so the report can state it rather than leave it to be inferred.
+ *
+ * Deliberately computed from CAPTURE_WINDOWS rather than from which files the
+ * worker happened to find: a day inside the window with a missing object is a
+ * gap in OUR archive and belongs in the same coverage entry as any other
+ * missing object, while a day before the window is not a gap at all — nothing
+ * was ever captured. Conflating them would report our outages as the customer's
+ * date range being too early.
+ *
+ * @returns {{covered: string[], missing: string[]}}
+ */
+export function degradingCoverage(venue, dataset, days) {
+  const covered = [], missing = [];
+  for (const d of days ?? []) (isCaptured(venue, dataset, d) ? covered : missing).push(d);
+  return { covered, missing };
+}
+
 /**
  * The archive dataset names a run must fetch for a given manifest.
  *
@@ -191,6 +273,34 @@ export function archiveDatasetsFor({ datasets, venue, from, to }) {
   return [...out].sort();
 }
 
+/**
+ * The archive datasets to read FOR ONE DAY.
+ *
+ * Identical to archiveDatasetsFor for everything that is not degrading. The
+ * difference is the whole point: a degrading dataset is dropped on a day its
+ * capture window does not cover, so the files are never fetched, never decoded
+ * and never applied.
+ *
+ * WITHOUT THIS the range-level list is used for every day, and a run spanning
+ * the start of capture reads a PARTIAL day's file and applies it — while
+ * `bboCoverage` reports that same day as missing, because it asks
+ * CAPTURE_WINDOWS. The report would then state that a day ran on the old
+ * behaviour while it actually ran on a half-covered book. 2026-09-02 is exactly
+ * that day: capture began at 00:42:18Z, so markets opening before then get no
+ * refinement and markets after do — a density change inside one day, which is
+ * the thing the book cadence is carefully arranged never to produce.
+ *
+ * The range is still passed through rather than collapsed to the day, because
+ * `settlement` expands against the whole range and narrowing that here would
+ * change which streams a day fetches for reasons unrelated to this.
+ */
+export function archiveDatasetsForDay({ datasets, venue, day, from, to }) {
+  const usable = (datasets ?? []).filter(
+    (d) => !DEGRADING_DATASETS.includes(d) || isCaptured(venue, d, day),
+  );
+  return archiveDatasetsFor({ datasets: usable, venue, from, to });
+}
+
 /**
  * The settlement files a day's markets need, beyond what the strategy asked for.
  *
@@ -345,5 +455,28 @@ export function normalizeDatasets(list) {
  */
 const SETTLEMENT_STREAMS = new Set(['prices', 'twap30s', 'twap60s']);
 export const PREWARM_DATASETS = Object.freeze(
-  KNOWN_DATASETS.filter((d) => !SETTLEMENT_STREAMS.has(d)),
+  KNOWN_DATASETS.filter((d) => !SETTLEMENT_STREAMS.has(d) && !OPT_IN_DATASETS.includes(d)),
 );
+
+/**
+ * EVERY dataset shape worth warming: the default one, plus the default one with
+ * each opt-in dataset added.
+ *
+ * A decoded day is cached per SHAPE, so warming only the default leaves every
+ * opted-in run paying the full decode — the timer stays green, the cache grows,
+ * and the one customer who asked for more waits longest. That is the failure
+ * this file already documents for the default shape; an opt-in dataset just
+ * moves it one step along.
+ *
+ * The cost is bounded and mostly imaginary: on a day the opt-in dataset is not
+ * captured, `archiveDatasetsForDay` drops it, both shapes normalise to the same
+ * archive files, and the second warm is a cache HIT rather than a second copy.
+ * Only days that actually carry it are stored twice.
+ *
+ * Derived, so a dataset added to the product is warmed without anyone
+ * remembering to come here.
+ */
+export const PREWARM_SHAPES = Object.freeze([
+  PREWARM_DATASETS,
+  ...OPT_IN_DATASETS.map((d) => Object.freeze([...PREWARM_DATASETS, d])),
+]);

package/api/lib/data-taxonomy.mjs

@@ -19,6 +19,7 @@ export const DATASETS = {
   twap30s: 'TWAP 30s settlement stream — settled 5-minute markets before they moved to the 60s lookback; still archived daily',
   twap60s: 'TWAP 60s settlement stream — settles both 5-minute and 15-minute markets',
   book: 'Full-depth order-book snapshots',
+  best_bid_ask: 'Top of book, unthrottled — the same best bid/ask price_change carries, at every update rather than the capture cadence; prices only, no sizes, so depth still needs book or price_change',
   price_change: 'Order-book deltas with best bid/ask',
   last_trade_price: 'Every trade print',
   markets: 'Per-market metadata, strike and settlement outcome',
@@ -59,13 +60,35 @@ export function classifyPath(filePath) {
       return { venue, dataset: 'klines', asset: assetOf(segs[3]), interval: num(segs[4]), ext };
     }
     if (ds === 'orderbook') {
-      // BTC-5M / BTC-15M / MARKET-<id>
-      const m = /^([A-Za-z]+)-(\d+[mMhHdD]|DAILY)$/.exec(segs[3] ?? '');
+      // BTC-5M / BTC-15M / BTC-HOURLY / BTC-DAILY / BTC-OTHER / MARKET-<id>
+      //
+      // Predict names its hourly and daily series by word rather than by
+      // duration. Both are mapped onto the vocabulary every other dataset
+      // already uses, because the alternative cost customers real data twice
+      // over:
+      //
+      //   HOURLY matched neither branch of the earlier pattern, so the whole
+      //   series classified to interval:null. `interval=1h` returned an empty
+      //   list — no error, just nothing — while the files sat in the archive,
+      //   and /v1/meta never named the value at all, so a customer building an
+      //   enumeration from it could not learn the data existed.
+      //
+      //   DAILY did match, but produced `daily`: a value no duration parser
+      //   accepts, that sorts after 1mo because sortIntervals cannot read it,
+      //   and that shares one array with the klines' own `1d` while meaning
+      //   the same span.
+      //
+      // The list stays a whitelist. Widening the second group to \w+ would
+      // turn BTC-OTHER into interval:'other' — inventing a period for the
+      // series that exists precisely because its period is unknown.
+      const BY_WORD = { HOURLY: '1h', DAILY: '1d' };
+      const m = /^([A-Za-z]+)-(\d+[mMhHdD]|HOURLY|DAILY)$/.exec(segs[3] ?? '');
+      const period = m?.[2];
       return {
         venue,
         dataset: 'orderbook',
         asset: assetOf(m?.[1] ?? segs[3]),
-        interval: m ? m[2].toLowerCase() : null,
+        interval: period ? (BY_WORD[period.toUpperCase()] ?? period.toLowerCase()) : null,
         ext,
       };
     }

package/cli/commands/run.mjs

@@ -21,12 +21,13 @@ import { fileURLToPath } from 'node:url';
 import { LANGUAGES, HOOK_NAMES, LIMITS } from '../../api/lib/backtest-contract.mjs';
 import { CHANNEL, EXIT, parseTrade, parseFill, parseResult, parseOutputLine } from '../../runner/harness/protocol.mjs';
 import {
-  countMarketDays, countStreams, buildCoverage, mergeReferenceRows, makeBookThrottle,
+  countMarketDays, countStreams, buildCoverage, bboCoverage, mergeReferenceRows, makeBookThrottle,
   sortMarketsForReplay,
 } from '../../runner/events.mjs';
 import { loadSeries } from '../../runner/series-data.mjs';
 import { buildReport } from '../../runner/engine/report.mjs';
 import { buildArchive } from '../../runner/archive.mjs';
+import { createLineWriter } from '../../runner/stdin-writer.mjs';
 import { loadLocalDay, localDays, looksLikeArchive } from '../local-data.mjs';
 import { readSubmission, validate } from '../ot.mjs';
 
@@ -72,29 +73,50 @@ function runHarness({
       }
     });
     child.on('error', reject);
-    child.on('close', (code) => resolve({ code, stderr, lines, forged }));
+    child.on('close', (code) => {
+      // A short feed that still exited 0 is the dangerous case: the harness
+      // replayed whatever reached it, reported cleanly, and the report looks
+      // complete. It must not be resolved as a successful run. When the harness
+      // died first the pipe breaks as a CONSEQUENCE, and its own exit code and
+      // stderr say more than the EPIPE does — so let that path through
+      // unchanged and let the caller report the real failure.
+      if (streamError && code === EXIT.ok) { reject(streamError); return; }
+      resolve({ code, stderr, lines, forged });
+    });
 
-    child.stdin.on('error', () => {});
-    child.stdin.write(`${JSON.stringify({ ...job, outputKey })}\n`);
-    for (const m of markets) {
-      // Series rows are INTERLEAVED into the same stream in event time, exactly
-      // as the worker sends them — and `lags` travels with them, or a signal
-      // that declared a publication delay would be visible the instant its row
-      // was stamped rather than when it could have existed.
-      const lines = m.events.map((ev) => JSON.stringify(ev));
-      const merged = seriesNames.length
-        ? mergeReferenceRows(lines, seriesRows, m.market, 'ext', seriesLags)
-        : lines;
-      child.stdin.write(`${JSON.stringify({
-        market: m.market,
-        stream: m.stream,
-        n: merged.length,
-        ...(seriesNames.length ? { series: seriesNames } : {}),
-        ...(Object.keys(seriesLags).length ? { lags: seriesLags } : {}),
-      })}\n`);
-      for (const line of merged) child.stdin.write(`${line}\n`);
-    }
-    child.stdin.end();
+    // THE SAME writer the queue uses (runner/stdin-writer.mjs). This loop used
+    // to ignore what write() returned and swallow every stdin error, so once
+    // the pipe's buffer filled the rows simply stopped arriving: a 289-market
+    // day came back as a 2-market report, exit 0, no warning. `ot run` and the
+    // worker have drifted eight times; sharing the writer is how this one stops
+    // being a ninth.
+    let streamError = null;
+    const write = createLineWriter(child.stdin);
+    (async () => {
+      await write(JSON.stringify({ ...job, outputKey }));
+      for (const m of markets) {
+        // Series rows are INTERLEAVED into the same stream in event time,
+        // exactly as the worker sends them — and `lags` travels with them, or a
+        // signal that declared a publication delay would be visible the instant
+        // its row was stamped rather than when it could have existed.
+        const lines = m.events.map((ev) => JSON.stringify(ev));
+        const merged = seriesNames.length
+          ? mergeReferenceRows(lines, seriesRows, m.market, 'ext', seriesLags)
+          : lines;
+        await write(JSON.stringify({
+          market: m.market,
+          stream: m.stream,
+          n: merged.length,
+          ...(seriesNames.length ? { series: seriesNames } : {}),
+          ...(Object.keys(seriesLags).length ? { lags: seriesLags } : {}),
+        }));
+        for (const line of merged) await write(line);
+      }
+      child.stdin.end();
+    })().catch((err) => {
+      streamError = err;
+      child.stdin.destroy();
+    });
   });
 }
 
@@ -127,11 +149,13 @@ function demux(lines) {
 export async function cmdRun({ dir, flags }) {
   const dataRoot = flags.data;
   if (!dataRoot) {
-    throw new Error('--data is required: point it at a cloned sample archive\n'
-      + '  git clone https://github.com/Ligengxin96/polymarket-data-samples');
+    throw new Error('--data is required: point it at an unpacked sample archive\n'
+      + '  curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz');
   }
   if (!await looksLikeArchive(dataRoot)) {
-    throw new Error(`${path.resolve(dataRoot)} does not look like an archive — no recognisable data files under it`);
+    throw new Error(`${path.resolve(dataRoot)} does not look like an archive — no recognisable data files under it\n`
+      + '  the sample archive is a release download, not the git repository:\n'
+      + '  curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz');
   }
 
   const files = await readSubmission(dir);
@@ -196,6 +220,7 @@ export async function cmdRun({ dir, flags }) {
   // been covered while agreeing about everything else. That is the harder
   // discrepancy to notice, because the report looks complete.
   const missing = [];
+  const bboApplied = new Map();  // day -> Set('<ASSET>|<interval>')
   for (const day of days) {
     const loaded = await loadLocalDay({
       root: dataRoot, day, venue,
@@ -212,6 +237,13 @@ export async function cmdRun({ dir, flags }) {
         to: days[days.length - 1],
       }),
     });
+    // Measured from EVENTS, keyed by market-day — the same fact the queue
+    // records, produced by the same decoder. See fetchDay's bboKeys.
+    if (loaded.bboKeys?.length) {
+      const acc = bboApplied.get(day) ?? new Set();
+      for (const k of loaded.bboKeys) acc.add(k);
+      bboApplied.set(day, acc);
+    }
     if (loaded.markets.length === 0) {
       process.stderr.write(`  ${day}: ${loaded.reason}\n`);
       missing.push({
@@ -341,6 +373,27 @@ export async function cmdRun({ dir, flags }) {
     }
 
     const base = passes[0];
+    // A SHORT REPLAY MUST FAIL EVEN WHEN NOTHING REPORTED AN ERROR.
+    //
+    // The backpressure bug produced exactly that shape: every write "succeeded",
+    // the harness exited 0, and 2 of 289 markets came back as a clean, complete
+    // looking report. Fixing the writer closes the cause we found; counting what
+    // came back is what catches the next one, whatever it turns out to be.
+    //
+    // `markets_run` is incremented by the harness only after a market is fully
+    // replayed, so on a clean exit it equals what was fed. A rejected or
+    // over-budget run never reaches here — those exit non-zero and are raised
+    // above with the sandbox's own reason, which says more than this count.
+    if (base.result.marketsRun < markets.length) {
+      const err = new Error(
+        `only ${base.result.marketsRun} of ${markets.length} market(s) were replayed —`
+        + ' the report would be incomplete, so none was written.'
+        + ' This usually means the feed to the runner was cut short.',
+      );
+      err.code = 'E_RUNTIME';
+      err.detail = err.message;
+      throw err;
+    }
     const marketMeta = new Map(markets.map((m) => [m.market.market_id, {
       market_id: m.market.market_id,
       asset: m.market.asset,
@@ -395,6 +448,7 @@ export async function cmdRun({ dir, flags }) {
         referenceDeclared: [],
         streams: countStreams([...marketMeta.values()]),
         droppedRows: base.malformed ?? 0,
+        ...bboCoverage({ venue, datasets: manifest.datasets, markets, applied: bboApplied }),
         local: true,
         source: path.resolve(dataRoot),
       }),

package/cli/local-data.mjs

@@ -20,7 +20,7 @@ import path from 'node:path';
 
 import { classifyPath } from '../api/lib/data-taxonomy.mjs';
 import {
-  archiveDatasetsFor, fileMatchesRun, normalizeIntervals, settlementPathsFor, orderedFeed,
+  archiveDatasetsForDay, fileMatchesRun, normalizeIntervals, settlementPathsFor, orderedFeed,
 } from '../api/lib/backtest-datasets.mjs';
 import {
   indexMarkets, eventsFromRow, finaliseMarket, parseRow, buildSlugIndex, marketUnusable,
@@ -115,7 +115,10 @@ export function dayOfPath(rel) {
  * the harness identically.
  */
 export async function loadLocalDay({ root, day, venue, assets, datasets, intervals, throttle = null }) {
-  const archiveDatasets = archiveDatasetsFor({ datasets, venue, from: day, to: day });
+  // Day-scoped, and degrading datasets gated by their capture window — the
+  // same call the queue makes, because `ot run` and the worker have drifted
+  // apart nine times and every one of them was a rule computed twice.
+  const archiveDatasets = archiveDatasetsForDay({ datasets, venue, day, from: day, to: day });
   // Same normalisation, same default, same two filters as the queue. `ot run`
   // promises the identical files and checksums; an interval narrowing applied
   // on one side only would break that on the very first 15m market.
@@ -160,11 +163,18 @@ export async function loadLocalDay({ root, day, venue, assets, datasets, interva
     all.filter((rel) => dayOfPath(rel) === day), { venue, assets, already: wanted })]);
 
   const byMarket = new Map();
+  const bboSeen = new Set();  // '<ASSET>|<interval>' that produced a usable bound
   for (const rel of feed) {
     if (classifyPath(rel).dataset === 'markets') continue;
     for await (const row of readRows(root, rel)) {
       for (const [id, ev] of eventsFromRow(rel, row, markets, bySlug, throttle)) {
         if (!markets.has(id)) continue;
+        // Same fact, same source as the queue: an EVENT, not a file. See
+        // fetchDay's bboKeys.
+        if (ev.bbo) {
+          const mk = markets.get(id);
+          if (mk?.asset) bboSeen.add(`${String(mk.asset).toUpperCase()}|${mk.interval ?? 'none'}`);
+        }
         let list = byMarket.get(id);
         if (!list) { list = []; byMarket.set(id, list); }
         list.push(ev);
@@ -217,6 +227,11 @@ export async function loadLocalDay({ root, day, venue, assets, datasets, interva
     // one promise `ot run` makes: the identical files from the identical
     // archive.
     markets: sortMarketsForReplay(out),
+    // Every file this day was actually read from, the same field the queue
+    // records — coverage states which days really read the top-of-book stream,
+    // and it has to answer that the same way on both sides.
+    inputs: feed,
+    bboKeys: [...bboSeen].sort(),
     unusable,
     reason: out.length === 0 && unusable.length
       ? `${unusable.length} market(s) unusable: ${unusable[0].why}`

package/cli/ot.mjs

@@ -2,7 +2,7 @@
 // `ot` — the command line the SDK docs tell customers to use.
 //
 //   ot check .                                          validate, free, no data
-//   ot run . --data ./polymarket-data-samples --date …  replay locally
+//   ot run . --data ./polymarket-data-samples           replay locally
 //   ot submit . --assets btc,eth --from … --to …        send it to the queue
 //
 // The one thing this file must get right is that `ot check` runs the SAME
@@ -57,7 +57,7 @@ const USAGE = `ot ${SDK_VERSION} — outcometick strategy tools
       --api <url>     API base (default https://outcometick.com)
 
   Free sample data:
-      git clone https://github.com/Ligengxin96/polymarket-data-samples
+      curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz
 `;
 
 /** Parse argv into {command, dir, flags}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outcometick",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Strategy SDK and CLI for outcometick prediction-market backtests",
   "type": "module",
   "license": "MIT",

package/runner/engine/book.mjs

@@ -57,15 +57,21 @@ class Ladder {
   #order(a, b) { return this.dir > 0 ? a - b : b - a; }
 
   /** Replace the whole ladder (a snapshot). */
-  reset(levels) {
+  reset(levels, ts = 0) {
     this.levels = (levels ?? [])
-      .map(([px, size]) => ({ ticks: toTicks(px), size: Number(size) }))
+      .map(([px, size]) => ({ ticks: toTicks(px), size: Number(size), ts }))
       .filter((l) => l.size > 0 && Number.isFinite(l.ticks))
       .sort((a, b) => this.#order(a.ticks, b.ticks));
   }
 
-  /** Apply one delta. A size of zero removes the level. */
-  apply(px, size) {
+  /**
+   * Apply one delta. A size of zero removes the level.
+   *
+   * `ts` is carried on the level itself so `prune` can tell a level the venue
+   * has moved past from one that arrived in the same millisecond as the bound
+   * about to delete it. See prune.
+   */
+  apply(px, size, ts = 0) {
     const ticks = toTicks(px);
     const n = Number(size);
     const i = this.levels.findIndex((l) => l.ticks === ticks);
@@ -73,10 +79,63 @@ class Ladder {
       if (i >= 0) this.levels.splice(i, 1);
       return;
     }
-    if (i >= 0) { this.levels[i].size = n; return; }
+    if (i >= 0) { this.levels[i].size = n; this.levels[i].ts = ts; return; }
     let j = this.levels.length;
     while (j > 0 && this.#order(this.levels[j - 1].ticks, ticks) > 0) j -= 1;
-    this.levels.splice(j, 0, { ticks, size: n });
+    this.levels.splice(j, 0, { ticks, size: n, ts });
+  }
+
+  /**
+   * Delete every level STRICTLY BETTER than `bound` that is older than `ts`.
+   *
+   * This is the whole of what the unthrottled top-of-book stream is allowed to
+   * do. That stream carries prices and no sizes, so it can state what is NOT on
+   * the ladder — "nothing better than this exists right now" — and can never
+   * state what is. Adding a level from it would be liquidity invented without a
+   * size, which is the class of bug this engine has had to fix five times.
+   *
+   * WHY IT MATTERS AT ALL: `take()` eats from the best end, and the delta stream
+   * that maintains this ladder is thinned to the venue's capture cadence (500ms
+   * for most assets). So the levels that are stalest are exactly the ones an
+   * order hits first, and they are stale in one direction only — a price that
+   * has since been taken still looks available. That is a systematic bias in the
+   * strategy's favour, which is the opposite of this file's stated bias.
+   *
+   * OLDER THAN, not "at or older than", and that is the point of carrying `ts`
+   * per level. A delta and a bound stamped the same millisecond contradict each
+   * other and the archive does not say which came first; leaving it to arrival
+   * order would make the result depend on how the reader happened to sort a tie.
+   * Requiring the level to be strictly older makes the outcome the same either
+   * way.
+   *
+   * Levels are best-first, so everything better than the bound is a prefix —
+   * but the age test is not prefix-aligned, so the prefix is filtered rather
+   * than sliced.
+   */
+  prune(bound, ts) {
+    // Not just finite: inside [0, 1]. An outcome token pays 0 or 1, so a bound
+    // outside that is a row we cannot read, and a bound is a MAXIMAL deletion
+    // instruction — acting on a misread one empties the ladder and the market
+    // silently stops filling. The decoder already refuses these; this is the
+    // second door, and it is what makes the engines, the Python engine and
+    // scripts/audit-report.py agree on the same rule rather than three
+    // slightly different ones.
+    // A NUMBER, not something that parses as one. `Number.isFinite('0.45')` is
+    // false because it does not coerce, while Python's `float('0.45')` is 0.45
+    // — so accepting strings on one side would make the same event prune in one
+    // engine and not the other. Both refuse anything that is not already a
+    // number, which is what the decoder emits.
+    if (typeof bound !== 'number' || !Number.isFinite(bound)) return 0;
+    if (bound < 0 || bound > 1) return 0;
+    const cap = toTicks(bound);
+    let removed = 0;
+    const kept = [];
+    for (const l of this.levels) {
+      if (this.#order(l.ticks, cap) < 0 && l.ts < ts) { removed += 1; continue; }
+      kept.push(l);
+    }
+    if (removed) this.levels = kept;
+    return removed;
   }
 
   /** Best resting price, or null when empty. */
@@ -138,8 +197,8 @@ export class Book {
     for (const side of SIDES) {
       const l = levels?.[side];
       if (!l) continue;
-      this.ladders[side].asks.reset(l.asks);
-      this.ladders[side].bids.reset(l.bids);
+      this.ladders[side].asks.reset(l.asks, ts);
+      this.ladders[side].bids.reset(l.bids, ts);
     }
   }
 
@@ -147,7 +206,29 @@ export class Book {
     this.ts = ts;
     if (!isSide(side)) throw new Error(`unknown side ${side}`);
     if (kind !== 'asks' && kind !== 'bids') throw new Error(`unknown ladder ${kind}`);
-    this.ladders[side][kind].apply(px, size);
+    this.ladders[side][kind].apply(px, size, ts);
+  }
+
+  /**
+   * Apply an unthrottled top-of-book bound: the venue says nothing better than
+   * this rests on either ladder right now.
+   *
+   * 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, which is
+   * exactly what it means. 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, count for count.
+   *
+   * @returns {number} levels removed, for the caller that reports it
+   */
+  bbo(ts, side, bid, ask) {
+    this.ts = ts;
+    if (!isSide(side)) throw new Error(`unknown side ${side}`);
+    const l = this.ladders[side];
+    return l.asks.prune(ask, ts) + l.bids.prune(bid, ts);
   }
 
   /**

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/events.mjs

@@ -11,7 +11,7 @@
 // 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';
 
@@ -465,6 +465,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 : [];
@@ -546,6 +598,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 +635,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.
  *
@@ -781,7 +918,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/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."""

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)
 

package/runner/stdin-writer.mjs

@@ -0,0 +1,69 @@
+/**
+ * Backpressure-aware line writer for a child process's stdin.
+ *
+ * Both the queued worker and `ot run` push an entire archive down one pipe —
+ * tens of millions of newline-framed rows for a large run. Ignoring what
+ * `write()` returns does not merely buffer: past the pipe's high-water mark the
+ * rows stop reaching the harness, and because a strategy that exits early
+ * closes the pipe under us, the failure arrives as an error on a stream nobody
+ * is listening to. The result is a run that replays the first fraction of its
+ * markets, exits 0, and produces a report that looks complete.
+ *
+ * That is not hypothetical: `ot run` did exactly this. It wrote 6.04M rows in a
+ * synchronous loop with `stdin.on('error', () => {})`, and a 289-market day
+ * came back as a 2-market report with no warning at all.
+ *
+ * Two details here are paid for in incidents and must not be simplified away:
+ *
+ *   1. ONE error listener for the whole stream, not one per line. A `once`
+ *      added per write and never removed is millions of live listeners, and the
+ *      writer dies of its own bookkeeping partway through a run.
+ *   2. An error has to settle a PENDING DRAIN. If the pipe breaks while we are
+ *      parked waiting for one, the drain never arrives, the promise never
+ *      settles, and the consumer waits for input that is not coming — burning
+ *      the whole wall clock instead of failing in the second it broke.
+ */
+
+/**
+ * @param {import('node:stream').Writable} stream
+ * @returns {(line: string) => Promise<void>} resolves once the line is accepted
+ */
+export function createLineWriter(stream) {
+  let writeError = null;
+  let wakeDrain = null;
+
+  stream.on('error', (err) => {
+    writeError = err;
+    const wake = wakeDrain;
+    wakeDrain = null;
+    if (wake) wake();
+  });
+
+  return (line) => new Promise((resolve, reject) => {
+    if (writeError) { reject(writeError); return; }
+    // Sequential by contract, and it says so rather than corrupting quietly.
+    // `wakeDrain` is a single slot: a second concurrent call would overwrite
+    // the first one's continuation, so that write would never settle and its
+    // line could interleave into the middle of another. Both callers await
+    // every line, and the framing (a market header, then that market's rows)
+    // only means anything in order — so this is a programming error, not a
+    // case to support.
+    if (wakeDrain) {
+      reject(new Error('createLineWriter: concurrent write; lines must be awaited one at a time'));
+      return;
+    }
+    // Respect backpressure: ignoring the return of write() is the whole bug.
+    if (stream.write(`${line}\n`)) { resolve(); return; }
+    wakeDrain = () => {
+      stream.removeListener('drain', onDrain);
+      if (writeError) reject(writeError);
+      else resolve();
+    };
+    function onDrain() {
+      const wake = wakeDrain;
+      wakeDrain = null;
+      if (wake) wake();
+    }
+    stream.once('drain', onDrain);
+  });
+}