outcometick 1.4.0

package/api/lib/backtest-manifest.mjs

@@ -0,0 +1,345 @@
+// Validating `outcometick.json` and the files that come with it.
+//
+// This is the validator the docs promise `ot check` runs: "if it passes locally
+// it will not be rejected on submit". That promise only survives if there is
+// exactly ONE implementation — so the CLI, the API and the runner all call
+// this, and none of them re-derive a rule of their own.
+//
+// Everything here is free and happens before a credit is held. A rejection
+// costs the submitter nothing, so the checks lean strict: a manifest that is
+// ambiguous is rejected rather than interpreted.
+
+import {
+  LANGUAGES, KNOWN_LANGUAGES, HOOKS, KNOWN_HOOKS, HOOK_NAMES, LIMITS, MODES,
+  KNOWN_MODES, SCHEMA_VERSION, BacktestRejection, parseReferenceFeed,
+} from './backtest-contract.mjs';
+import { normalizeDatasets, assertCoverage } from './backtest-datasets.mjs';
+
+/** The one file name that is not the submitter's to choose. */
+export const MANIFEST_NAME = 'outcometick.json';
+
+/**
+ * File names must be plain, relative and flat-ish. A submission is not unpacked
+ * — the files arrive as text with names attached — but the runner does write
+ * them to a scratch directory, and a name is the one field that reaches a
+ * filesystem call. `..`, absolute paths, backslashes and control characters are
+ * all rejected rather than sanitised: a name we had to repair is a name the
+ * submitter did not mean.
+ */
+const SAFE_NAME = /^[A-Za-z0-9_][A-Za-z0-9._/-]*$/;
+
+function assertSafeName(name, what = 'file') {
+  const n = String(name ?? '');
+  if (!n) throw new BacktestRejection('E_MANIFEST', `${what} name is empty`);
+  if (n.length > LIMITS.maxFileNameLength) {
+    throw new BacktestRejection('E_MANIFEST', `${what} name longer than ${LIMITS.maxFileNameLength} characters: ${n.slice(0, 32)}…`);
+  }
+  if (!SAFE_NAME.test(n) || n.includes('..') || n.includes('//')) {
+    throw new BacktestRejection('E_MANIFEST', `${what} name is not a plain relative path: ${JSON.stringify(n)}`);
+  }
+  return n;
+}
+
+/**
+ * Parse the manifest text.
+ *
+ * A manifest that is not JSON, or is JSON but not an object, is E_MANIFEST and
+ * not E_ENTRY — the distinction matters because the codes drive what the CLI
+ * tells someone to go and look at.
+ */
+export function parseManifest(text) {
+  let doc;
+  try {
+    doc = JSON.parse(String(text));
+  } catch (err) {
+    throw new BacktestRejection('E_MANIFEST', `${MANIFEST_NAME} is not valid JSON: ${err.message}`);
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new BacktestRejection('E_MANIFEST', `${MANIFEST_NAME} must be a JSON object`);
+  }
+  return doc;
+}
+
+/**
+ * Validate the manifest on its own, without the files.
+ *
+ * Returns a normalised manifest: every optional field present with its default,
+ * every list de-duplicated and in a stable order. Downstream code reads the
+ * normalised form only, so no consumer has to repeat "or the default".
+ */
+export function validateManifest(doc) {
+  if (doc.schema !== SCHEMA_VERSION) {
+    throw new BacktestRejection('E_MANIFEST',
+      `unsupported schema ${JSON.stringify(doc.schema)}; this runner speaks schema ${SCHEMA_VERSION}`);
+  }
+
+  const language = String(doc.language ?? '');
+  if (!KNOWN_LANGUAGES.includes(language)) {
+    throw new BacktestRejection('E_MANIFEST',
+      `unsupported language ${JSON.stringify(doc.language)}; supported: ${KNOWN_LANGUAGES.join(', ')}`);
+  }
+  const lang = LANGUAGES[language];
+
+  // entry is "file:ClassName" — resolved by exact name, no discovery.
+  const entryRaw = String(doc.entry ?? '');
+  const sep = entryRaw.lastIndexOf(':');
+  if (sep <= 0 || sep === entryRaw.length - 1) {
+    throw new BacktestRejection('E_ENTRY',
+      `entry must be "file:ClassName", got ${JSON.stringify(doc.entry)}`);
+  }
+  const entryFile = assertSafeName(entryRaw.slice(0, sep), 'entry file');
+  const entryClass = entryRaw.slice(sep + 1);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(entryClass)) {
+    throw new BacktestRejection('E_ENTRY', `entry class name is not an identifier: ${JSON.stringify(entryClass)}`);
+  }
+
+  // hooks
+  if (!Array.isArray(doc.hooks) || doc.hooks.length === 0) {
+    throw new BacktestRejection('E_MANIFEST', 'hooks must be a non-empty array');
+  }
+  const hooks = [];
+  for (const raw of doc.hooks) {
+    const h = String(raw ?? '');
+    if (!KNOWN_HOOKS.includes(h)) {
+      throw new BacktestRejection('E_MANIFEST',
+        `unknown hook ${JSON.stringify(h)}; known: ${KNOWN_HOOKS.join(', ')}`);
+    }
+    if (!hooks.includes(h)) hooks.push(h);
+  }
+  // At least one hook must be able to return an Order, or the run cannot
+  // produce a trade and the report would be an empty equity curve the
+  // submitter paid for.
+  if (!hooks.some((h) => HOOKS[h].emitsOrders)) {
+    throw new BacktestRejection('E_MANIFEST',
+      `no hook that can return an Order was declared; one of ${KNOWN_HOOKS.filter((h) => HOOKS[h].emitsOrders).join(', ')} is required`);
+  }
+
+  const datasets = normalizeDatasets(doc.datasets);
+
+  // A hook that needs a dataset it was not given would simply never fire, and
+  // a strategy that silently never trades looks like a bad strategy rather
+  // than a bad manifest. Say so instead.
+  for (const h of hooks) {
+    const need = HOOKS[h].requiresDataset;
+    if (!need) continue;
+    const satisfied = need === 'settlement'
+      ? datasets.some((d) => d === 'settlement' || d === 'prices' || d.startsWith('twap'))
+      : datasets.includes(need);
+    if (!satisfied) {
+      throw new BacktestRejection('E_MANIFEST',
+        `hook ${h} needs the ${need} dataset, which is not declared`);
+    }
+  }
+
+  // mode
+  const mode = doc.mode == null ? 'market' : String(doc.mode);
+  if (!KNOWN_MODES.includes(mode)) {
+    throw new BacktestRejection('E_MANIFEST',
+      `unknown mode ${JSON.stringify(doc.mode)}; known: ${KNOWN_MODES.join(', ')}`);
+  }
+
+  // deps — names only, from the per-language allowlist. Versions are ours.
+  const deps = [];
+  if (doc.deps != null) {
+    if (!Array.isArray(doc.deps)) throw new BacktestRejection('E_MANIFEST', 'deps must be an array');
+    for (const raw of doc.deps) {
+      const d = String(raw ?? '').trim();
+      if (/[@=<>~^ ]/.test(d)) {
+        throw new BacktestRejection('E_MANIFEST',
+          `deps take names only, not versions: ${JSON.stringify(d)}. The runner pins them.`);
+      }
+      if (!lang.deps.includes(d)) {
+        throw new BacktestRejection('E_IMPORT',
+          `${d} is not on the ${lang.label} allowlist; available: ${lang.deps.join(', ')}`);
+      }
+      if (!deps.includes(d)) deps.push(d);
+    }
+  }
+
+  // reference feeds
+  const reference = [];
+  if (doc.reference != null) {
+    if (!Array.isArray(doc.reference)) throw new BacktestRejection('E_MANIFEST', 'reference must be an array');
+    for (const raw of doc.reference) {
+      const feed = parseReferenceFeed(raw);
+      if (!feed) {
+        throw new BacktestRejection('E_MANIFEST',
+          `unknown reference feed ${JSON.stringify(raw)}. Ask us and we will add it — adding a feed is cheap.`);
+      }
+      if (!reference.includes(feed.canonical)) reference.push(feed.canonical);
+    }
+  }
+
+  // series — the submitter's own CSV/Parquet, aligned to event time
+  const series = [];
+  if (doc.series != null) {
+    if (!Array.isArray(doc.series)) throw new BacktestRejection('E_MANIFEST', 'series must be an array');
+    if (doc.series.length > LIMITS.maxSeriesCount) {
+      throw new BacktestRejection('E_LIMIT',
+        `at most ${LIMITS.maxSeriesCount} series, got ${doc.series.length}`);
+    }
+    for (const raw of doc.series) {
+      if (!raw || typeof raw !== 'object') throw new BacktestRejection('E_MANIFEST', 'each series must be an object');
+      const name = String(raw.name ?? '');
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new BacktestRejection('E_MANIFEST', `series name is not an identifier: ${JSON.stringify(raw.name)}`);
+      }
+      if (series.some((s) => s.name === name)) {
+        throw new BacktestRejection('E_MANIFEST', `duplicate series name ${JSON.stringify(name)}`);
+      }
+      const file = assertSafeName(raw.file, 'series file');
+      let lagMs = 0;
+      if (raw.lag_ms != null) {
+        lagMs = Number(raw.lag_ms);
+        if (!Number.isInteger(lagMs) || lagMs < 0) {
+          throw new BacktestRejection('E_MANIFEST', `series ${name}: lag_ms must be a non-negative integer`);
+        }
+      }
+      series.push({ name, file, lag_ms: lagMs });
+    }
+  }
+
+  // params — defaults only, reachable as ctx.p
+  const params = {};
+  if (doc.params != null) {
+    if (typeof doc.params !== 'object' || Array.isArray(doc.params)) {
+      throw new BacktestRejection('E_MANIFEST', 'params must be an object');
+    }
+    const keys = Object.keys(doc.params);
+    if (keys.length > LIMITS.maxParams) {
+      throw new BacktestRejection('E_LIMIT', `at most ${LIMITS.maxParams} params, got ${keys.length}`);
+    }
+    for (const k of keys) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {
+        throw new BacktestRejection('E_MANIFEST', `param name is not an identifier: ${JSON.stringify(k)}`);
+      }
+      const v = doc.params[k];
+      const ok = typeof v === 'number' ? Number.isFinite(v)
+        : (typeof v === 'string' || typeof v === 'boolean');
+      if (!ok) {
+        throw new BacktestRejection('E_MANIFEST',
+          `param ${k} must be a finite number, string or boolean — a sweep has to be able to vary it`);
+      }
+      params[k] = v;
+    }
+  }
+
+  return {
+    schema: SCHEMA_VERSION,
+    language,
+    languageId: lang.id,
+    entry: { file: entryFile, className: entryClass },
+    hooks,
+    datasets,
+    mode,
+    deps,
+    reference,
+    series,
+    params,
+  };
+}
+
+/**
+ * Validate the submitted files against the manifest and the hard limits.
+ *
+ * `files` is [{name, content}] as submitted — text only. The manifest itself
+ * counts toward both the file count and the size budget, because it is one of
+ * the things the submitter has to fit in.
+ */
+export function validateFiles(files, manifest) {
+  if (!Array.isArray(files) || files.length === 0) {
+    throw new BacktestRejection('E_MANIFEST', 'no files submitted');
+  }
+  if (files.length > LIMITS.maxFiles) {
+    throw new BacktestRejection('E_LIMIT',
+      `at most ${LIMITS.maxFiles} files, got ${files.length}. Archives and repository URLs are not accepted.`);
+  }
+
+  const seen = new Map();
+  let total = 0;
+  for (const f of files) {
+    const name = assertSafeName(f?.name);
+    if (seen.has(name)) throw new BacktestRejection('E_MANIFEST', `duplicate file ${name}`);
+    const content = f?.content;
+    if (typeof content !== 'string') {
+      throw new BacktestRejection('E_MANIFEST', `file ${name} must be submitted as text`);
+    }
+    // A NUL byte means this is not the text file it claims to be. We never
+    // unpack anything, so this is the whole of the "no archives" enforcement:
+    // a zip cannot survive the trip as a JSON string without one.
+    if (content.includes('\0')) {
+      throw new BacktestRejection('E_MANIFEST',
+        `file ${name} contains a NUL byte — submissions are text only, no archives`);
+    }
+    const bytes = Buffer.byteLength(content, 'utf8');
+    total += bytes;
+    seen.set(name, { name, bytes, content });
+  }
+
+  if (total > LIMITS.maxTotalSourceBytes) {
+    throw new BacktestRejection('E_LIMIT',
+      `total source is ${total} bytes, over the ${LIMITS.maxTotalSourceBytes} byte limit`);
+  }
+  if (!seen.has(MANIFEST_NAME)) {
+    throw new BacktestRejection('E_MANIFEST', `${MANIFEST_NAME} is required`);
+  }
+  if (!seen.has(manifest.entry.file)) {
+    throw new BacktestRejection('E_ENTRY',
+      `entry names ${manifest.entry.file}, which was not submitted`);
+  }
+  for (const s of manifest.series) {
+    if (!seen.has(s.file)) {
+      throw new BacktestRejection('E_MANIFEST',
+        `series ${s.name} names ${s.file}, which was not submitted`);
+    }
+  }
+
+  const lang = LANGUAGES[manifest.language];
+  for (const { name } of seen.values()) {
+    if (name === MANIFEST_NAME) continue;
+    if (manifest.series.some((s) => s.file === name)) continue; // data files, any extension
+    const ext = name.slice(name.lastIndexOf('.'));
+    if (!lang.sourceExtensions.includes(ext)) {
+      throw new BacktestRejection('E_MANIFEST',
+        `${name} is not a ${lang.label} source file; expected one of ${lang.sourceExtensions.join(', ')}`);
+    }
+  }
+
+  return { files: [...seen.values()], totalBytes: total };
+}
+
+/**
+ * The full pre-billing check: manifest, files, and the scope it will run over.
+ *
+ * Scope is checked here rather than at submission time because coverage is a
+ * property of the manifest's declared datasets crossed with the requested
+ * range, and both come from the submitter. Getting E_COVERAGE from `ot check`
+ * is the difference between fixing a manifest and buying a useless run.
+ *
+ * @param {{manifestText?:string, manifest?:object, files:Array, scope:object}} input
+ */
+export function checkSubmission({ manifestText, manifest: manifestDoc, files, scope }) {
+  const doc = manifestDoc ?? parseManifest(
+    manifestText ?? files?.find((f) => f?.name === MANIFEST_NAME)?.content,
+  );
+  const manifest = validateManifest(doc);
+  const checked = validateFiles(files, manifest);
+  if (scope) {
+    assertCoverage({
+      datasets: manifest.datasets,
+      venue: scope.venue,
+      from: scope.from,
+      to: scope.to,
+    });
+  }
+  return {
+    manifest,
+    files: checked.files,
+    totalBytes: checked.totalBytes,
+    // What the runner has to call, in this language's spelling. Resolved here
+    // so neither the runner nor the CLI re-implements the parity table.
+    hookNames: Object.fromEntries(manifest.hooks.map((h) => [h, HOOK_NAMES[manifest.languageId][h]])),
+    shardable: MODES[manifest.mode].shardable,
+    rateMultiplier: MODES[manifest.mode].rateMultiplier,
+  };
+}

package/api/lib/coverage-window.mjs

@@ -0,0 +1,42 @@
+// Where the dataset starts, for two different audiences.
+//
+// The archive genuinely holds 2026-06-06 onward, and the API says so: a
+// customer querying what exists must be told what exists. But collection began
+// PART-WAY THROUGH 06-06, so that day and 06-07 are partial — and a marketing
+// line that says "since 06-06" invites a buyer to check, find two thin days and
+// conclude the coverage claims cannot be trusted. The two dates answer
+// different questions, so both are published rather than one being bent:
+//
+//   firstDay          what the archive contains        (API contract)
+//   firstCompleteDay  the first full UTC day           (what we advertise)
+//
+// Same convention as the public sample repos, which have always started their
+// range at the first complete day.
+
+/** First complete UTC day per venue. Collection started mid-day before these. */
+export const FIRST_COMPLETE_DAY = Object.freeze({
+  polymarket: '2026-06-08', // 06-06 and 06-07 are partial
+  predict: '2026-06-13',    // 06-12 is ~66% of the day
+});
+
+/** The product as a whole starts when its earliest venue is complete. */
+export const PRODUCT_FIRST_COMPLETE_DAY = FIRST_COMPLETE_DAY.polymarket;
+
+/**
+ * The advertised window over a sorted list of archived days.
+ *
+ * Counts from the first complete day, never from the first day held — quoting
+ * "69 days since 06-06" and "since 06-08" in the same breath is the kind of
+ * inconsistency a buyer notices before anything else.
+ *
+ * @param {string[]} days sorted ascending
+ */
+export function completeWindow(days, firstComplete = PRODUCT_FIRST_COMPLETE_DAY) {
+  const full = (days ?? []).filter((d) => d >= firstComplete);
+  return {
+    firstCompleteDay: full[0] ?? null,
+    // Length of the list, not a date subtraction: a gap in the archive must
+    // reduce this, and calendar arithmetic would paper over it.
+    completeDays: full.length,
+  };
+}

package/api/lib/data-taxonomy.mjs

@@ -0,0 +1,175 @@
+// Turn an archive path into the dimensions a customer actually thinks in:
+// venue, dataset, asset, interval. The archive's own layout grew organically
+// (three settlement streams, two venues, derived klines) and is not something a
+// buyer should have to learn.
+//
+// Pure and total: every mirrored path must classify, because the API lists
+// whatever the catalog holds. Anything unrecognised comes back with
+// dataset:'other' and null dimensions rather than being dropped — a file that
+// silently disappears from listings is worse than one that is awkward to filter.
+
+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'];
+
+/** Datasets, as a customer would name them. */
+export const DATASETS = {
+  prices: 'Settlement feed, tick by tick (instantaneous Chainlink stream)',
+  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',
+  price_change: 'Order-book deltas with best bid/ask',
+  last_trade_price: 'Every trade print',
+  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',
+  other: 'Uncategorised',
+};
+
+const num = (s) => (s == null ? null : s);
+
+/**
+ * @returns {{venue:'polymarket'|'predict', dataset:string, asset:string|null,
+ *            interval:string|null, ext:string}}
+ */
+export function classifyPath(filePath) {
+  const p = String(filePath);
+  const segs = p.split('/');
+  const name = segs[segs.length - 1] ?? '';
+  const venue = venueOfPath(p);
+  const ext = name.endsWith('.csv.gz') ? 'csv.gz' : name.endsWith('.jsonl.gz') ? 'jsonl.gz' : '';
+
+  const assetOf = (s) => {
+    if (!s) return null;
+    const up = s.toUpperCase();
+    return ASSETS.find((a) => up.startsWith(a)) ?? null;
+  };
+
+  // derived/klines/<source>/<ASSET>/<interval>/<file>
+  if (segs[0] === 'derived' && segs[1] === 'klines') {
+    return { venue, dataset: 'klines', asset: assetOf(segs[3]), interval: num(segs[4]), ext };
+  }
+
+  // data/predict-fun/<dataset>/...
+  if (segs[1] === 'predict-fun') {
+    const ds = segs[2];
+    if (ds === 'klines') {
+      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] ?? '');
+      return {
+        venue,
+        dataset: 'orderbook',
+        asset: assetOf(m?.[1] ?? segs[3]),
+        interval: m ? m[2].toLowerCase() : null,
+        ext,
+      };
+    }
+    if (ds === 'prices') return { venue, dataset: 'prices', asset: assetOf(segs[3]), interval: null, ext };
+    if (ds === 'markets') return { venue, dataset: 'markets', asset: null, interval: null, ext };
+    return { venue, dataset: 'other', asset: null, interval: null, ext };
+  }
+
+  // data/chainlink[-twap-30s|-60s]/daily/prices/<ASSETUSD>/<file>
+  if (segs[1]?.startsWith('chainlink')) {
+    const dataset = segs[1] === 'chainlink-twap-30s' ? 'twap30s'
+      : segs[1] === 'chainlink-twap-60s' ? 'twap60s'
+        : 'prices';
+    return { venue, dataset, asset: assetOf(segs[4]), interval: null, ext };
+  }
+
+  // data/polymarket/daily/<dataset>/<ASSET-interval>/<file>
+  if (segs[1] === 'polymarket') {
+    const dataset = DATASETS[segs[3]] ? segs[3] : 'other';
+    const m = /^([A-Za-z]+)-(\d+[mMhHdD])$/.exec(segs[4] ?? '');
+    return {
+      venue,
+      dataset,
+      asset: assetOf(m?.[1] ?? segs[4]),
+      interval: m ? m[2].toLowerCase() : null,
+      ext,
+    };
+  }
+
+  return { venue, dataset: 'other', asset: null, interval: null, ext };
+}
+
+/**
+ * The token that names "this dimension does not apply to the file".
+ *
+ * `interval` is only meaningful for datasets that are sliced by market period
+ * (book, price_change, klines, …); the settlement streams (prices, twap30s,
+ * twap60s) are continuous and classify to interval:null. Without a way to name
+ * that, `interval=5m` drops them — the SQL `WHERE interval='5m'` vs NULL trap,
+ * where "not applicable" reads as "does not match". A customer wanting "5m
+ * market data plus every period-less dataset" then cannot express it at all.
+ *
+ * Spelling it as a value rather than widening `interval=5m` implicitly keeps
+ * the filter-never-widens rule: only a query that asks for it gets it, so
+ * someone pulling just 5m klines is not handed the settlement streams too.
+ * No real dimension value is 'none' (intervals are 1s…1mo, assets are BTC…ZEC),
+ * so the token cannot collide with data.
+ */
+export const NO_VALUE = 'none';
+
+/**
+ * Does a classified file match a structured query? Absent filters match
+ * everything; every supplied filter must match (AND), and each may be a
+ * comma-separated list (OR within it). Within that list, NO_VALUE matches a
+ * file whose dimension is null — `interval=5m,none`.
+ */
+export function matchesQuery(meta, q) {
+  const hit = (want, got) => {
+    if (!want) return true;
+    const alts = String(want).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
+    if (alts.length === 0) return true;
+    if (got == null) return alts.includes(NO_VALUE);
+    return alts.includes(String(got).toLowerCase());
+  };
+  return hit(q.venue, meta.venue)
+    && hit(q.dataset, meta.dataset)
+    && hit(q.asset, meta.asset)
+    && hit(q.interval, meta.interval);
+}
+
+/**
+ * Distinct dimension values across a set of classified files (for /v1/meta).
+ *
+ * `nullable` names the dimensions some file leaves empty, so a caller can find
+ * NO_VALUE without reading the docs — undiscoverable is how the interval=5m
+ * complaint started. It is deliberately NOT folded into `assets`/`intervals`:
+ * those have always held real symbols and real durations, and a client that
+ * builds an enum from them, parses them as durations, or loops over every
+ * interval to fetch data would break on a token — or quietly start pulling the
+ * period-less files it never asked for.
+ */
+export function summarise(metas) {
+  const s = { venues: new Set(), datasets: new Set(), assets: new Set(), intervals: new Set() };
+  let assetless = false;
+  let intervalless = false;
+  for (const m of metas) {
+    s.venues.add(m.venue);
+    s.datasets.add(m.dataset);
+    if (m.asset) s.assets.add(m.asset); else assetless = true;
+    if (m.interval) s.intervals.add(m.interval); else intervalless = true;
+  }
+  const sortIntervals = (a, b) => {
+    const unit = { m: 1, h: 60, d: 1440, w: 10080, mo: 43200 };
+    const parse = (x) => {
+      const mm = /^(\d+)(mo|[mhdw])$/.exec(x);
+      return mm ? Number(mm[1]) * (unit[mm[2]] ?? 1) : Number.MAX_SAFE_INTEGER;
+    };
+    return parse(a) - parse(b);
+  };
+  return {
+    venues: [...s.venues].sort(),
+    datasets: [...s.datasets].sort(),
+    assets: [...s.assets].sort(),
+    intervals: [...s.intervals].sort(sortIntervals),
+    nullable: [assetless ? 'asset' : null, intervalless ? 'interval' : null].filter(Boolean),
+  };
+}

package/api/lib/venue-path.mjs

@@ -0,0 +1,16 @@
+// Which venue an archive path belongs to.
+//
+// Split out of scope.mjs so that the parts of the codebase that only need to
+// CLASSIFY a path do not have to import the file that decides who may DOWNLOAD
+// one. data-taxonomy.mjs needs this function, and data-taxonomy.mjs is reachable
+// from the published `outcometick` package — which would otherwise have dragged
+// the whole entitlement gate into a public repo along with it.
+//
+// scope.mjs still re-exports this so its own export surface is unchanged; the
+// copy of scope.mjs that chainlink-data keeps in sync is unaffected.
+
+/** The venue a given archive path belongs to. */
+export function venueOfPath(filePath) {
+  return String(filePath).toLowerCase().split('/').includes('predict-fun')
+    ? 'predict' : 'polymarket';
+}

package/bin/ot.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Thin shim so `ot` is a stable entry point regardless of the layout.
+import { main } from '../cli/ot.mjs';
+main(process.argv.slice(2)).then((code) => process.exit(code));

package/cli/api-client.mjs

@@ -0,0 +1,71 @@
+// The HTTP side of the CLI, in one place.
+//
+// Shared so that the key is read the same way everywhere: from the environment,
+// never from a flag. A flag lands in shell history and in the process list, and
+// this key spends money.
+
+export const DEFAULT_API = 'https://outcometick.com';
+
+/** The key, from the environment. */
+export function readKey() {
+  const key = process.env.OT_BACKTEST_KEY;
+  if (!key) {
+    throw new Error('OT_BACKTEST_KEY is not set.\n'
+      + '  It is the key you were emailed when you bought credits.\n'
+      + '  export OT_BACKTEST_KEY="bt_…"');
+  }
+  return key;
+}
+
+async function request(api, path, { method = 'GET', body, key, redirect } = {}) {
+  let res;
+  try {
+    res = await fetch(`${api}${path}`, {
+      method,
+      ...(redirect ? { redirect } : {}),
+      headers: {
+        ...(body ? { 'content-type': 'application/json' } : {}),
+        ...(key ? { authorization: `Bearer ${key}` } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (err) {
+    throw new Error(`could not reach ${api}: ${err.message}`);
+  }
+  return res;
+}
+
+/** GET returning parsed JSON, without throwing on a non-2xx. */
+export async function get(api, path, key) {
+  const res = await request(api, path, { key });
+  const text = await res.text();
+  let json;
+  try { json = JSON.parse(text); } catch { json = null; }
+  return { status: res.status, json, text };
+}
+
+/** POST returning parsed JSON, without throwing on a non-2xx. */
+export async function post(api, path, body, key) {
+  const res = await request(api, path, { method: 'POST', body, key });
+  const text = await res.text();
+  let json;
+  try { json = JSON.parse(text); } catch { json = null; }
+  return { status: res.status, json, text };
+}
+
+/**
+ * GET a binary body, following the archive endpoint's redirect to R2.
+ *
+ * The redirect target is presigned and short-lived, so it is followed
+ * immediately rather than handed back to the caller to use later.
+ */
+export async function getBinary(api, path, key) {
+  const res = await request(api, path, { key });
+  if (!res.ok) {
+    const text = await res.text();
+    let json;
+    try { json = JSON.parse(text); } catch { json = null; }
+    return { status: res.status, json, text, body: null };
+  }
+  return { status: res.status, json: null, text: '', body: Buffer.from(await res.arrayBuffer()) };
+}