outcometick 1.6.2 → 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 5c26d7ed75e2172fff108af183089aa1460652ba.
+  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.2';
+export const SDK_VERSION = '1.6.3';
 
 /**
  * The tag of the sandbox images, and the ONLY place it is written down.
@@ -575,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));

package/cli/commands/run.mjs

@@ -27,6 +27,7 @@ import {
 import { loadSeries } from '../../runner/series-data.mjs';
 import { buildReport } from '../../runner/engine/report.mjs';
 import { buildArchive } from '../../runner/archive.mjs';
+import { createLineWriter } from '../../runner/stdin-writer.mjs';
 import { loadLocalDay, localDays, looksLikeArchive } from '../local-data.mjs';
 import { readSubmission, validate } from '../ot.mjs';
 
@@ -72,29 +73,50 @@ function runHarness({
       }
     });
     child.on('error', reject);
-    child.on('close', (code) => resolve({ code, stderr, lines, forged }));
+    child.on('close', (code) => {
+      // A short feed that still exited 0 is the dangerous case: the harness
+      // replayed whatever reached it, reported cleanly, and the report looks
+      // complete. It must not be resolved as a successful run. When the harness
+      // died first the pipe breaks as a CONSEQUENCE, and its own exit code and
+      // stderr say more than the EPIPE does — so let that path through
+      // unchanged and let the caller report the real failure.
+      if (streamError && code === EXIT.ok) { reject(streamError); return; }
+      resolve({ code, stderr, lines, forged });
+    });
 
-    child.stdin.on('error', () => {});
-    child.stdin.write(`${JSON.stringify({ ...job, outputKey })}\n`);
-    for (const m of markets) {
-      // Series rows are INTERLEAVED into the same stream in event time, exactly
-      // as the worker sends them — and `lags` travels with them, or a signal
-      // that declared a publication delay would be visible the instant its row
-      // was stamped rather than when it could have existed.
-      const lines = m.events.map((ev) => JSON.stringify(ev));
-      const merged = seriesNames.length
-        ? mergeReferenceRows(lines, seriesRows, m.market, 'ext', seriesLags)
-        : lines;
-      child.stdin.write(`${JSON.stringify({
-        market: m.market,
-        stream: m.stream,
-        n: merged.length,
-        ...(seriesNames.length ? { series: seriesNames } : {}),
-        ...(Object.keys(seriesLags).length ? { lags: seriesLags } : {}),
-      })}\n`);
-      for (const line of merged) child.stdin.write(`${line}\n`);
-    }
-    child.stdin.end();
+    // THE SAME writer the queue uses (runner/stdin-writer.mjs). This loop used
+    // to ignore what write() returned and swallow every stdin error, so once
+    // the pipe's buffer filled the rows simply stopped arriving: a 289-market
+    // day came back as a 2-market report, exit 0, no warning. `ot run` and the
+    // worker have drifted eight times; sharing the writer is how this one stops
+    // being a ninth.
+    let streamError = null;
+    const write = createLineWriter(child.stdin);
+    (async () => {
+      await write(JSON.stringify({ ...job, outputKey }));
+      for (const m of markets) {
+        // Series rows are INTERLEAVED into the same stream in event time,
+        // exactly as the worker sends them — and `lags` travels with them, or a
+        // signal that declared a publication delay would be visible the instant
+        // its row was stamped rather than when it could have existed.
+        const lines = m.events.map((ev) => JSON.stringify(ev));
+        const merged = seriesNames.length
+          ? mergeReferenceRows(lines, seriesRows, m.market, 'ext', seriesLags)
+          : lines;
+        await write(JSON.stringify({
+          market: m.market,
+          stream: m.stream,
+          n: merged.length,
+          ...(seriesNames.length ? { series: seriesNames } : {}),
+          ...(Object.keys(seriesLags).length ? { lags: seriesLags } : {}),
+        }));
+        for (const line of merged) await write(line);
+      }
+      child.stdin.end();
+    })().catch((err) => {
+      streamError = err;
+      child.stdin.destroy();
+    });
   });
 }
 
@@ -127,11 +149,13 @@ function demux(lines) {
 export async function cmdRun({ dir, flags }) {
   const dataRoot = flags.data;
   if (!dataRoot) {
-    throw new Error('--data is required: point it at a cloned sample archive\n'
-      + '  git clone https://github.com/Ligengxin96/polymarket-data-samples');
+    throw new Error('--data is required: point it at an unpacked sample archive\n'
+      + '  curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz');
   }
   if (!await looksLikeArchive(dataRoot)) {
-    throw new Error(`${path.resolve(dataRoot)} does not look like an archive — no recognisable data files under it`);
+    throw new Error(`${path.resolve(dataRoot)} does not look like an archive — no recognisable data files under it\n`
+      + '  the sample archive is a release download, not the git repository:\n'
+      + '  curl -L https://github.com/Ligengxin96/polymarket-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz');
   }
 
   const files = await readSubmission(dir);
@@ -341,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/ot.mjs

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

package/package.json

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

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