outcometick 1.6.3 → 1.6.5

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 600941b94e4cf95204fc8daf624a24a05f9c43c0.
+  Generated from monorepo revision 13e95ca5b2d1f465cb53799e610a08476f1db274.
 -->
 
 # outcometick

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.3';
+export const SDK_VERSION = '1.6.5';
 
 /**
  * The tag of the sandbox images, and the ONLY place it is written down.
@@ -60,7 +60,7 @@ export const SDK_VERSION = '1.6.3';
  * 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.16.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 }),
   }),
@@ -247,6 +294,24 @@ const BOOK_CAPTURE = Object.freeze({
   ]),
 });
 
+/**
+ * The days the book cadence changed, oldest first.
+ *
+ * Exported for the prewarm, which has to warm one shape PER CADENCE TIER: the
+ * cadence is chosen from a run's date RANGE, so a range that stops short of a
+ * change and one that crosses it are two different cache entries for the same
+ * day. Warming a single range therefore covers exactly one tier and silently
+ * misses the others — which is what happened between 2026-08-25 and
+ * 2026-09-07, when the prewarm warmed the whole sellable span (500ms) while
+ * every run over recent days wanted 20ms.
+ *
+ * Derived from the table above rather than restated, so a new cadence entry
+ * grows the warm set without anyone remembering to come here.
+ */
+export function bookCadenceChangeDays(venue) {
+  return (BOOK_CAPTURE[venue] ?? []).map((e) => e.from);
+}
+
 /**
  * The cadence ONE ASSET replays at within a run: the COARSEST its date range
  * contains. Ask per asset; there is no run-wide answer by design.

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,15 +19,46 @@ 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',
+  last_trade_price: 'Trade prints, unthrottled',
   markets: 'Per-market metadata, strike and settlement outcome',
   tick_size_change: 'Tick-size changes',
   orderbook: 'Order-book snapshots (Predict.fun)',
-  klines: 'OHLCV candles derived from the settlement feed',
+  klines: 'OHLC candles derived from the settlement feed, with a tick count — no trade volume; the settlement feed is a price feed',
   other: 'Uncategorised',
 };
 
+/**
+ * The same descriptions in Chinese.
+ *
+ * HERE, not in the page that renders them. Two of these lines state the
+ * SETTLEMENT BASIS — which TWAP stream settles which market — and CLAUDE.md
+ * pins that fact to four places that must move together. A Chinese copy living
+ * in a component would be a fifth, and it would drift the way every other
+ * hand-copy in this repo has: the basis already moved once (5-minute markets
+ * settled on the 30s stream until 2026-08-07, on the 60s stream after), and an
+ * AI assistant quoted a stale copy of our coverage back to a customer.
+ *
+ * Sitting beside DATASETS means changing one entry puts the other on screen in
+ * the same diff. data-taxonomy.test.mjs asserts the key sets match, so a new
+ * dataset cannot land with only one language.
+ */
+export const DATASETS_ZH = {
+  prices: '结算价流，逐 tick（Chainlink 瞬时流）',
+  twap30s: 'TWAP 30 秒结算流——5 分钟市场改用 60 秒回看之前的结算线，至今仍逐日归档',
+  twap60s: 'TWAP 60 秒结算流——5 分钟与 15 分钟市场都判定在它上面',
+  book: '全深度盘口快照',
+  best_bid_ask: '盘口顶部，未抽稀——与 price_change 携带的是同一个最优买卖价，但每次更新都出一行，而不是按采集节奏；只有价格没有挂单量，深度仍需 book 或 price_change',
+  price_change: '盘口增量，带最优买卖价',
+  last_trade_price: '成交流，未抽稀',
+  markets: '每个市场的元数据、strike 与结算结果',
+  tick_size_change: '最小变动价位的变更',
+  orderbook: '盘口快照（Predict.fun）',
+  klines: '由结算价流推导的 OHLC K 线，带 tick 计数——没有成交量，结算流是价格流不是成交流',
+  other: '未归类',
+};
+
 const num = (s) => (s == null ? null : s);
 
 /**
@@ -59,13 +90,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,7 +21,7 @@ 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';
@@ -220,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,
@@ -236,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({
@@ -440,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

@@ -4,7 +4,7 @@
 // R2. Both go through runner/events.mjs for the row -> event mapping, because
 // the docs make a promise about exactly this pair:
 //
-//     The identical files, same checksums, same coverage report. A backtest
+//     The identical files, byte for byte, with the same checksums. A backtest
 //     here and a backtest on your own machine after subscribing read the same
 //     bytes — that is the point of offering it.
 //
@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outcometick",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "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);
   }
 
   /**