outcometick 1.6.1 → 1.6.2

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 5c26d7ed75e2172fff108af183089aa1460652ba.
 -->
 
 # 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.1';
+export const SDK_VERSION = '1.6.2';
 
 /**
  * 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
 // ---------------------------------------------------------------------------
@@ -563,6 +626,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,6 +22,7 @@ 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';
@@ -242,6 +243,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

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

@@ -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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outcometick",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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