outcometick 1.6.1 → 1.6.3

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 56659396f7f20223103270472ffb16a5b0417bbd.
+  Generated from monorepo revision 600941b94e4cf95204fc8daf624a24a05f9c43c0.
 -->
 
 # 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.1';
+export const SDK_VERSION = '1.6.3';
 
 /**
  * The tag of the sandbox images, and the ONLY place it is written down.
@@ -60,7 +60,7 @@ export const SDK_VERSION = '1.6.1';
  * 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.11.0';
+export const SANDBOX_IMAGE_TAG = '1.14.0';
 
 // ---------------------------------------------------------------------------
 // Languages
@@ -469,7 +469,17 @@ export const LIMITS = Object.freeze({
   // strategy being slow, and charging their execution budget for our network
   // is backwards — a 30-day run spent all twenty minutes fetching and was
   // killed without replaying an event.
-  wallClockMs: 20 * 60 * 1000,
+  //
+  // SIZED PER RUN, not a constant — see wallClockMsFor below. A flat twenty
+  // minutes was a limit on the SMALLEST run that could not finish: replay costs
+  // ~24s per market-day (measured, warm cache, 289 markets and ~1.04M events in
+  // a polymarket BTC day), so twenty minutes covers about fifty of them while
+  // the page was selling a ninety-day chip. The customer paid, watched it work
+  // for twenty minutes, and got a refund and no report.
+  //
+  // These two are the inputs to that function and the only numbers to tune.
+  replayBaseMs: 3 * 60 * 1000,
+  replayPerMarketDayMs: 35 * 1000,
   // The FETCH budget, separate and bounded. Not unbounded, because there is one
   // worker and one slot: a stalled R2 read used to sit inside the fetch while
   // the heartbeat kept renewing the lease, so nobody could reclaim the run and
@@ -491,6 +501,59 @@ export const LIMITS = Object.freeze({
   archiveRetentionDays: 7,
 });
 
+/**
+ * The longest range one run may cover, in CALENDAR DAYS.
+ *
+ * The product limit. Checked against the days that actually exist in the
+ * archive — the range AFTER it is intersected — not against what was asked
+ * for: requesting more days than exist has always been fine and is billed for
+ * what was there, and moving the check earlier would hard-fail a page whose
+ * capacity figure is a few minutes stale.
+ *
+ * Enforced in the API and mirrored in the editor, so nobody can build a
+ * submission the queue will refuse.
+ *
+ * Raising it is a hardware decision, not a config one: there is one worker
+ * slot and a run holds it for its whole life.
+ */
+export const MAX_BACKTEST_DAYS = 90;
+
+/**
+ * The clamp on the REPLAY BUDGET's input — not a limit on what may be run.
+ *
+ * The budget below grows with market-days because that is what the machine
+ * spends time on, and market-days are days × assets × intervals: ninety days
+ * of one asset is 90, ninety days of seven assets over two intervals is 1,260.
+ * Without a clamp the second would be handed an eight-hour budget and would
+ * hold the only worker slot for a working day.
+ *
+ * So a run larger than this still RUNS — it simply is not given proportionally
+ * more time, and if it cannot finish it is refunded in full like any other
+ * overrun. That is the honest failure: bounded queue damage, money back.
+ */
+export const BUDGET_CLAMP_MARKET_DAYS = 180;
+
+/**
+ * How long a run's REPLAY may take, given its size.
+ *
+ * Derived rather than declared so the limit and the thing it limits cannot
+ * drift: `MAX_BACKTEST_DAYS` decides how long a range can be, this decides how long
+ * that size is allowed to take, and both come from the two constants in LIMITS.
+ *
+ * Sized on the WARM path (~24s/market-day measured) plus margin, because the
+ * fetch has its own budget — `fetchClockMs` — and a slow archive read is our
+ * pipe being slow, not the strategy. A run whose days are cold spends that
+ * time under the fetch clock and arrives here with the same work to do.
+ */
+export function wallClockMsFor(marketDays) {
+  const n = Number.isFinite(marketDays) && marketDays > 0 ? Math.ceil(marketDays) : 1;
+  return LIMITS.replayBaseMs
+    + LIMITS.replayPerMarketDayMs * Math.min(n, BUDGET_CLAMP_MARKET_DAYS);
+}
+
+/** The ceiling that follows from the numbers above. For copy and for docs. */
+export const MAX_WALL_CLOCK_MS = wallClockMsFor(BUDGET_CLAMP_MARKET_DAYS);
+
 // ---------------------------------------------------------------------------
 // Rejection codes
 // ---------------------------------------------------------------------------
@@ -512,6 +575,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));
@@ -563,6 +632,12 @@ export function contractDocument() {
     referenceSymbols: [...REFERENCE_SYMBOLS],
     modes: MODES,
     limits: LIMITS,
+    // THE CEILINGS A CLIENT HAS TO KNOW BEFORE IT BUILDS A REQUEST. They are
+    // not in LIMITS because LIMITS describes the sandbox — what one strategy
+    // gets — and these describe what one RUN may ask for. A client that cannot
+    // read them discovers them as a 422 on the paid path.
+    maxBacktestDays: MAX_BACKTEST_DAYS,
+    maxMarketDays: BUDGET_CLAMP_MARKET_DAYS,
     rejectionCodes: REJECTION_CODES,
   };
 }

package/api/lib/data-taxonomy.mjs

@@ -11,7 +11,7 @@
 import { venueOfPath } from './venue-path.mjs';
 
 /** Asset symbols we collect, longest-first so BNBUSDT matches before BNB. */
-const ASSETS = ['BTC', 'ETH', 'SOL', 'XRP', 'DOGE', 'BNB', 'HYPE', 'ZEC'];
+export const ASSETS = ['BTC', 'ETH', 'SOL', 'XRP', 'DOGE', 'BNB', 'HYPE', 'ZEC'];
 
 /** Datasets, as a customer would name them. */
 export const DATASETS = {

package/cli/commands/run.mjs

@@ -22,10 +22,12 @@ import { LANGUAGES, HOOK_NAMES, LIMITS } from '../../api/lib/backtest-contract.m
 import { CHANNEL, EXIT, parseTrade, parseFill, parseResult, parseOutputLine } from '../../runner/harness/protocol.mjs';
 import {
   countMarketDays, countStreams, buildCoverage, 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';
 
@@ -71,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();
+    });
   });
 }
 
@@ -126,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);
@@ -242,6 +267,15 @@ export async function cmdRun({ dir, flags }) {
     markets.push(...loaded.markets);
   }
   if (markets.length === 0) throw new Error('no market-days could be read from that archive');
+  // SESSION IS ONE STREAM ACROSS THE RANGE, so it is ordered once over every
+  // day — the same thing fetchMarketDays does for the queue. Ordering it a day
+  // at a time leaves the stream day-major, which is chronological only by
+  // accident and stops being so as soon as two assets are in scope. Session
+  // shares one Portfolio across every market, so this is part of the ANSWER,
+  // not of the log.
+  if ((manifest.mode ?? 'market') === 'session') {
+    sortMarketsForReplay(markets, { mode: 'session' });
+  }
   // ONE ASSET ON ONE UTC DAY — the unit the queue bills in. `markets` is one
   // entry per market, and a day of BTC 15-minute markets is ninety-six of them,
   // so counting entries reported a run as being a hundred times bigger than the
@@ -331,6 +365,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,

package/cli/commands/submit.mjs

@@ -79,7 +79,16 @@ export async function cmdSubmit({ dir, flags }) {
     }
     process.stdout.write(`  cost        ${json.credits_held} cr\n`);
     process.stdout.write(`  source      sha256 ${String(json.source_sha256).slice(0, 16)}…\n\n`);
-    process.stdout.write(`  ot status ${json.run_id}   (or wait for the email)\n\n`);
+    // DO NOT PROMISE THE EMAIL WHEN NONE WAS ASKED FOR. `--email` is what
+    // fills deliver_to, and without it the delivery poller correctly skips the
+    // run — so the old unconditional "(or wait for the email)" told every CLI
+    // submitter to wait for something that was never going to arrive. The flag
+    // was implemented and undocumented, which is the same failure from the
+    // other side: nobody could use the thing this line advertised.
+    process.stdout.write(flags.email
+      ? `  ot status ${json.run_id}   (or wait for the email)\n\n`
+      : `  ot status ${json.run_id}\n`
+        + '  (no --email, so nothing will be sent — note that id down)\n\n');
     return 0;
   }
 

package/cli/local-data.mjs

@@ -24,6 +24,7 @@ import {
 } from '../api/lib/backtest-datasets.mjs';
 import {
   indexMarkets, eventsFromRow, finaliseMarket, parseRow, buildSlugIndex, marketUnusable,
+  sortMarketsForReplay,
   makeBookThrottle,
 } from '../runner/events.mjs';
 
@@ -211,7 +212,11 @@ export async function loadLocalDay({ root, day, venue, assets, datasets, interva
     });
   }
   return {
-    markets: out,
+    // THE SAME ORDER THE QUEUE FEEDS — see sortMarketsForReplay. A local replay
+    // that emitted its logs in a different order than the queue would break the
+    // one promise `ot run` makes: the identical files from the identical
+    // archive.
+    markets: sortMarketsForReplay(out),
     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
@@ -41,6 +41,10 @@ const USAGE = `ot ${SDK_VERSION} — outcometick strategy tools
 
   ot submit <dir> --assets btc,eth --from <day> --to <day> [--venue polymarket]
       Send it to the queue. Needs OT_BACKTEST_KEY.
+      --email <address>   have the finished report emailed to you. Without it
+                          the run is only reachable from 'ot status', which
+                          means remembering the id — and a queued run outlives
+                          the terminal you started it from.
 
   ot status <run_id>
       Where a submitted run got to, and what it cost. Needs OT_BACKTEST_KEY.
@@ -53,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.1",
+  "version": "1.6.3",
   "description": "Strategy SDK and CLI for outcometick prediction-market backtests",
   "type": "module",
   "license": "MIT",

package/runner/engine/report.mjs

@@ -36,6 +36,64 @@ const r4 = (x) => (Number.isFinite(x) ? Number(x.toFixed(4)) : null);
  */
 const collateralOf = (t) => (t.entry_px ?? 0) * (t.size ?? 0);
 
+/**
+ * The most money this strategy had at risk AT ONE TIME.
+ *
+ * THE NUMBER THAT ANSWERS "how much do I need to run this", and the one this
+ * report was missing. Summing every entry answers a different question: the
+ * sample strategy opened 1,676 positions over fifteen days and never held more
+ * than one, so its entries total $72,175 while it never needed more than $80.
+ * Dividing a loss by the sum therefore reported −4.35% for a strategy that had
+ * burned through its stake thirty-nine times over.
+ *
+ * Computed by sweeping the open/close events, so overlapping positions add up
+ * and sequential ones do not. Trades with no timestamps are skipped rather
+ * than assumed concurrent — an unknown that inflates the peak would make the
+ * strategy look safer to fund than it is.
+ */
+function peakCapital(trades) {
+  const events = [];
+  for (const t of trades) {
+    if (t.opened_ms == null || t.closed_ms == null) continue;
+    const amt = collateralOf(t);
+    if (!(amt > 0)) continue;
+    events.push([t.opened_ms, amt]);
+    events.push([t.closed_ms, -amt]);
+  }
+  // Closes before opens at the same instant: a position that ends exactly when
+  // the next begins did not need both stakes at once.
+  events.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let cur = 0;
+  let peak = 0;
+  for (const [, delta] of events) {
+    cur += delta;
+    if (cur > peak) peak = cur;
+  }
+  return peak;
+}
+
+/** Share of the run's span with a position open. Money idle is money wasted. */
+function holdingRatio(trades) {
+  const withTimes = trades.filter((t) => t.opened_ms != null && t.closed_ms != null);
+  if (withTimes.length === 0) return null;
+  const first = Math.min(...withTimes.map((t) => t.opened_ms));
+  const last = Math.max(...withTimes.map((t) => t.closed_ms));
+  const span = last - first;
+  if (!(span > 0)) return null;
+  // Union of the intervals, not their sum: two overlapping positions are one
+  // stretch of being in the market, and summing them can exceed the span.
+  const spans = withTimes
+    .map((t) => [t.opened_ms, t.closed_ms])
+    .sort((a, b) => a[0] - b[0]);
+  let held = 0;
+  let [s, e] = spans[0];
+  for (const [a, b] of spans.slice(1)) {
+    if (a > e) { held += e - s; [s, e] = [a, b]; } else if (b > e) e = b;
+  }
+  held += e - s;
+  return held / span;
+}
+
 /**
  * Headline metrics — the twelve cells at the top of the report.
  */
@@ -52,6 +110,8 @@ export function metrics(trades, { feesPaid = 0, days = 1 } = {}) {
   const wins = pnls.filter((p) => p > 0);
   const losses = pnls.filter((p) => p < 0);
   const collateral = sum(closed.map(collateralOf));
+  const peak = peakCapital(closed);
+  const hold = holdingRatio(closed);
 
   const equity = equityCurve(closed);
   const dd = maxDrawdown(equity.map((p) => p.equity));
@@ -91,7 +151,20 @@ export function metrics(trades, { feesPaid = 0, days = 1 } = {}) {
     // is only an entry rate for strategies that enter once — this one is an
     // entry rate for all of them, and equals `trades` in the common case.
     markets_traded: new Set(closed.map((t) => t.market_id)).size,
+    // Net P&L over the SUM of every entry — "for each dollar traded, how much
+    // was made". Renamed on the page to say that, because "return on capital"
+    // reads as an account return and is not one: the same stake recycled a
+    // thousand times makes this number a thousand times smaller than what
+    // happened to the money.
     return_on_collateral: collateral > 0 ? r4(netPnl / collateral) : null,
+    // THE ACCOUNT NUMBER. Net P&L over the most that was ever at risk at once,
+    // which is what someone funding this strategy actually has to put up.
+    peak_capital: r2(peak),
+    return_on_peak: peak > 0 ? r4(netPnl / peak) : null,
+    // How much of the run had a position open. The sample strategy is in the
+    // market 13% of the time, which is the other half of why the two return
+    // figures differ by three orders of magnitude.
+    holding_ratio: hold == null ? null : r4(hold),
     // Cents of edge per contract: what the outcome was worth minus what was
     // paid, averaged. This is the number that says whether there was an edge
     // at all, as opposed to a lucky run of variance.

package/runner/events.mjs

@@ -619,8 +619,83 @@ export function countStreams(items) {
  * stream, or settled off an outcome we could not read, is invisible and makes
  * the report wrong.
  */
+/**
+ * Put one day's markets in the order they will be replayed.
+ *
+ * ASSET, THEN OPENING TIME, THEN ID — and shared, because `ot run` and the
+ * queue both feed markets to a strategy and a difference here is a difference
+ * in what a reader sees from the same archive.
+ *
+ * The decoder produces market_id order, which is a hash and therefore
+ * unrelated to time. Nothing about a RESULT depends on it — state is reset at
+ * every on_market_open, which is what lets these be sharded — but `ctx.log`
+ * from every market lands in one stream, and a human reads that stream as a
+ * timeline. In hash order its timestamps jump hours in both directions for no
+ * visible reason.
+ *
+ * Asset before time so each market-day stays a CONTIGUOUS block:
+ * `marketDayPrefix` counts a market-day done when its last market is done, and
+ * interleaving two assets pushes both of their last markets to the end of the
+ * run — a progress bar that sits still and then jumps, which is the "looks
+ * stuck" this channel exists to remove.
+ *
+ * The id breaks ties because many strikes open at the same instant, and an
+ * unstable order would make two runs of the same strategy over the same days
+ * emit their logs differently.
+ */
+export function sortMarketsForReplay(markets, { mode = 'market' } = {}) {
+  const byId = (a, b) => {
+    const ai = String(a.market?.market_id ?? '');
+    const bi = String(b.market?.market_id ?? '');
+    return ai < bi ? -1 : (ai > bi ? 1 : 0);
+  };
+  const byTime = (a, b) => (a.market?.open_ts_ms ?? 0) - (b.market?.open_ts_ms ?? 0);
+
+  // SESSION MODE IS ONE STREAM, so it is ordered by time and by nothing else.
+  //
+  // Session shares one instance and one Portfolio across every market in the
+  // range — the docs call it "one ordered stream across the range" — which
+  // makes the feed order part of the RESULT, not just of the log. Its equity
+  // curve, its position and its P&L accumulate in whatever order markets
+  // arrive. Feeding it asset-major would build that curve by walking all of
+  // BTC and then going back in time to walk all of ETH: not a sequence that
+  // ever happened, and not a number anyone can act on.
+  //
+  // Before this function existed, session got market_id order — a hash. The
+  // "ordered stream" in the docs was ordered by nothing at all.
+  if (mode === 'session') return markets.sort((a, b) => byTime(a, b) || byId(a, b));
+
+  // Market mode: each market is independent (state resets at every
+  // on_market_open), so the order changes no result — only what a human reads.
+  // Asset-major keeps each market-day a CONTIGUOUS block, which is what
+  // marketDayPrefix needs: it counts a market-day done when its LAST market is
+  // done, and interleaving assets pushes every asset's last market to the end
+  // of the run — a progress bar that sits still and then jumps.
+  return markets.sort((a, b) => {
+    const aa = a.market?.asset ?? '';
+    const ba = b.market?.asset ?? '';
+    if (aa !== ba) return aa < ba ? -1 : 1;
+    return byTime(a, b) || byId(a, b);
+  });
+}
+
 export function marketUnusable(market, inWindow) {
   if (!market) return 'no market metadata';
+  // WHICH ASSET IS THIS? Every layer above needs the answer and none of them
+  // can work it out later: the billing key is `asset|day|interval`, the book
+  // cadence is chosen per asset, and — since the decoded day became per-asset —
+  // a market with no asset belongs to no cache entry in particular. Predict
+  // publishes ONE venue-wide markets file, and the per-asset row filter is
+  // `if (m.asset && …)`, so a row missing its category lands in every asset's
+  // read at once, each carrying a different slice of its events under the same
+  // name. Keeping any one of those replays a market with half its data and
+  // nothing to say so.
+  //
+  // Decided HERE because this is the one function both the queue and `ot run`
+  // ask. The first version of this rule lived in the queue's merge step, which
+  // meant the local runner kept the market, and a single-asset run — which has
+  // 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') {
     return 'outcome could not be read';

package/runner/harness/node/harness.mjs

@@ -526,7 +526,34 @@ async function main() {
           + ' ctx.log output was dropped. ctx.log is for reading, not for'
           + ' exporting; see the SDK docs for the limit.\n');
       }
-      for (const line of out.logs) logsOut.write(`${entry.market.market_id} ${line}\n`);
+      // OPENING TIME FIRST, then a short id.
+      //
+      // The prefix used to be the full 64-character condition hash, which
+      // identifies a market to the venue and to nobody reading a log: there is
+      // no way to tell from it which market this was, or when. The opening
+      // time is the thing a person actually navigates by — it is what the
+      // venue puts in the slug — and eight characters of the hash still
+      // separate the several strikes that open at the same instant.
+      //
+      // MUST MATCH THE PYTHON HARNESS. Two log formats from one archive is the
+      // kind of divergence the conformance suite exists to catch.
+      // A market with no opening time keeps the id alone rather than gaining a
+      // leading space — every consumer of this file splits on whitespace, and
+      // a blank first field shifts all of them by one.
+      const shortId = String(entry.market.market_id ?? '').slice(0, 10);
+      // READABLE, because ctx.log already puts the EVENT time on every line as
+      // epoch millis. Two bare 13-digit numbers side by side are two numbers
+      // nobody can tell apart — and the one this prefix exists for is the one
+      // that would be mistaken for the other.
+      //
+      // UTC, to the minute: the market schedule is published in UTC and a
+      // market-day is a UTC day, so a local rendering would file a row under a
+      // different date than the archive does.
+      const openedAt = entry.market.open_ts_ms == null
+        ? null
+        : new Date(entry.market.open_ts_ms).toISOString().slice(0, 16).replace('T', ' ');
+      const prefix = openedAt == null ? shortId : `${openedAt} ${shortId}`;
+      for (const line of out.logs) logsOut.write(`${prefix} ${line}\n`);
       for (const c of out.crosschecks) result.crosschecks.push(c);
 
       // Tracked as the stream went past rather than scanned afterwards: there

package/runner/harness/node/sdk/index.mjs

@@ -42,7 +42,10 @@ export class Order {
     if (!SIDES.includes(side)) {
       throw new Error(`side must be "UP" or "DOWN", got ${JSON.stringify(side)}`);
     }
-    // SIZE IN MONEY, converted here rather than in the engine.
+    // SIZING IN MONEY — this is about the `notional` field, converted here
+    // rather than in the engine. `size` is CONTRACTS (see OrderSizing in
+    // index.d.ts); it is not money, and reading this heading as if it were
+    // is the one wrong turn this comment can cause.
     //
     // Position sizing is nearly always a budget, not a contract count, and the
     // conversion has exactly one honest divisor: your own limit. A contract

package/runner/harness/python/harness.py

@@ -18,6 +18,7 @@ import hmac
 import importlib.util
 import json
 import os
+import datetime as _datetime
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -447,7 +448,19 @@ def main() -> int:
                  " run's ctx.log output was dropped. ctx.log is for reading,"
                  " not for exporting; see the SDK docs for the limit.")
         for line in out["logs"]:
-            logs_fh.write(f'{entry["market"]["market_id"]} {line}\n')
+            # 开盘时间在前，短 id 在后 —— 见 node harness 里的同一处注释。
+            # 两个 harness 的日志格式必须一致。
+            _open = entry["market"].get("open_ts_ms")
+            _sid = str(entry["market"].get("market_id") or "")[:10]
+            # 格式化成可读的 UTC —— ctx.log 已经在每行放了事件时间（毫秒数），
+            # 两个 13 位裸数字挨在一起没人分得清。见 node harness 的注释。
+            # 没有开盘时间时只留 id，不要留一个前导空格。
+            if _open is None:
+                _prefix = _sid
+            else:
+                _dt = _datetime.datetime.fromtimestamp(_open / 1000, _datetime.timezone.utc)
+                _prefix = f"{_dt.strftime('%Y-%m-%d %H:%M')} {_sid}"
+            logs_fh.write(f'{_prefix} {line}\n')
         result["crosschecks"].extend(out["crosschecks"])
 
         # Tracked as the stream went past; there is no array left to scan.

package/runner/harness/python/outcometick.py

@@ -46,7 +46,11 @@ class Order:
                  tif="ioc", tag=None, notional=None):
         if side not in SIDES:
             raise ValueError(f'side must be "UP" or "DOWN", got {side!r}')
-        # SIZE IN MONEY. Mirrors index.mjs exactly -- see the reasoning there.
+        # SIZING IN MONEY -- this is about the `notional` argument below.
+        # `size` is CONTRACTS (see OrderSizing in index.d.ts); it is not
+        # money, and reading this heading as if it were is the one wrong
+        # turn this comment can cause. Mirrors index.mjs exactly -- see
+        # the reasoning there.
         # Position sizing is nearly always a budget, and the only honest
         # divisor is your own limit: a contract costs whatever it fills at, so
         # dividing by the current best price overspends the moment there is any

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);
+  });
+}