outcometick 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ligengxin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+<!--
+  GENERATED — do not edit this repository directly.
+
+  Every file here is built from the outcometick monorepo by
+  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 532aa834e8f0f07b21958b0d3c30e7332fbbc34e.
+-->
+
+# outcometick
+
+The TypeScript / JavaScript strategy SDK and the `ot` command line for
+[outcometick.com](https://outcometick.com) — tick-level data for Polymarket and
+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 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
+```
+
+## Writing a strategy
+
+Fully typed — `ot` ships `.d.ts` declarations, so a strategy that type-checks
+is one the queue will accept.
+
+```ts
+import { Strategy, Order, type Ctx, type Tick } from "outcometick";
+
+export default class MeanReversion extends Strategy<{ entry_z: number; size: number }> {
+  private entered = false;
+
+  onMarketOpen() { this.entered = false; }
+
+  onTick(ctx: Ctx<{ entry_z: number; size: number }>, tick: Tick): Order | null {
+    const z = ctx.zscore(tick.value, { window: 180 });
+    if (this.entered || Math.abs(z) < ctx.p.entry_z) return null;
+    const side = z > 0 ? "DOWN" : "UP";
+    const limit = ctx.book().best(side);
+    if (limit === null) return null;
+    this.entered = true;
+    return new Order({ side, size: ctx.p.size, limit });
+  }
+}
+```
+
+Plain JavaScript works too — the runtime is ESM with no build step.
+
+## The point of `ot check`
+
+It runs the **same validator the queue runs** — the same module, not a copy. If
+it passes locally it will not be rejected on submit. That is only true because
+there is one implementation, which is why the validator and the static analysers
+ship in this package rather than being reimplemented client-side.
+
+## What `ot run` is and is not
+
+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
+
+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
+machines it runs in a container with no network, no writable filesystem and a
+hard CPU and wall-clock budget.
+
+## Testing
+
+```
+npm install && npm test
+```
+
+Requires `python3` on PATH: one of the two static analysers is written in
+Python, and the CLI drives it the same way the API does.
+
+---
+
+Writing your strategy in Python instead? The SDK for it is
+[`pip install outcometick`](https://pypi.org/project/outcometick/). `ot` runs
+those too — it is the one CLI for both languages.
+
+Full reference: https://outcometick.com/docs/sdk

package/api/lib/backtest-contract.mjs

@@ -0,0 +1,318 @@
+// The backtest contract: what a submission may declare, and what the runner
+// promises to honour. This module is the single source of truth for both ends
+// — the API validates against it, the runner builds its sandbox from it, and
+// /v1/backtest/contract serves it to the SDK and the docs page.
+//
+// Everything here is a closed set on purpose. An unknown language, dataset,
+// hook or reference feed is a rejection, never a pass-through: the whole
+// premise is a sealed, deterministic replay, and "we did not recognise it so we
+// ignored it" is how a strategy silently gets fed something other than what it
+// asked for.
+
+import { FIRST_COMPLETE_DAY } from './coverage-window.mjs';
+
+/** Manifest schema version. Field meanings never change within a version. */
+export const SCHEMA_VERSION = 1;
+
+/** SDK version reported by the docs page and stamped into every report. */
+export const SDK_VERSION = '1.4.0';
+
+// ---------------------------------------------------------------------------
+// Languages
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtimes we execute, pinned exactly. A range is not accepted: two runs of the
+ * same source on different patch releases can differ in float formatting or
+ * dict ordering, and the product claims byte-identical reports.
+ *
+ * `compiled` languages are deliberately absent for now. Compiling untrusted
+ * source IS untrusted execution (build.rs, proc macros, go generate), needs a
+ * vendored offline module cache, and its own resource envelope — a different
+ * security problem from importing a module, not a bigger version of the same
+ * one. Adding one means adding an entry here plus a runner plugin; nothing in
+ * the API or the schema has to move.
+ */
+export const LANGUAGES = Object.freeze({
+  'python@3.14': Object.freeze({
+    id: 'python',
+    label: 'python',
+    runtime: 'python 3.14 · numpy, pandas, polars, scipy',
+    entrySignature: 'on_tick(ctx, tick) -> Order | None',
+    // Names only. Versions are ours and there is no install step inside the
+    // sandbox — the image already holds them.
+    deps: Object.freeze(['numpy', 'pandas', 'polars', 'scipy']),
+    sourceExtensions: Object.freeze(['.py', '.json']),
+  }),
+  'nodejs@24': Object.freeze({
+    id: 'nodejs',
+    label: 'node.js',
+    runtime: 'node 24 · danfo, mathjs, decimal.js',
+    entrySignature: 'onTick(ctx, tick) => Order | null',
+    deps: Object.freeze(['danfojs-node', 'mathjs', 'decimal.js']),
+    sourceExtensions: Object.freeze(['.mjs', '.js', '.json']),
+  }),
+});
+
+export const KNOWN_LANGUAGES = Object.freeze(Object.keys(LANGUAGES));
+
+/** Hook names differ per language; the semantics do not. */
+export const HOOK_NAMES = Object.freeze({
+  python: Object.freeze({
+    on_market_open: 'on_market_open',
+    on_tick: 'on_tick',
+    on_book: 'on_book',
+    on_trade: 'on_trade',
+    on_settle: 'on_settle',
+  }),
+  nodejs: Object.freeze({
+    on_market_open: 'onMarketOpen',
+    on_tick: 'onTick',
+    on_book: 'onBook',
+    on_trade: 'onTrade',
+    on_settle: 'onSettle',
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * The five events the runner drives. `emits` says whether returning an Order
+ * from that hook is meaningful — returning one from a lifecycle hook is a
+ * signature error, not a silently dropped order.
+ */
+export const HOOKS = Object.freeze({
+  on_market_open: Object.freeze({ arity: 3, emitsOrders: false, requiresDataset: null }),
+  on_tick: Object.freeze({ arity: 3, emitsOrders: true, requiresDataset: 'settlement' }),
+  on_book: Object.freeze({ arity: 3, emitsOrders: true, requiresDataset: 'book' }),
+  on_trade: Object.freeze({ arity: 3, emitsOrders: true, requiresDataset: 'trades' }),
+  on_settle: Object.freeze({ arity: 4, emitsOrders: false, requiresDataset: null }),
+});
+
+export const KNOWN_HOOKS = Object.freeze(Object.keys(HOOKS));
+
+// ---------------------------------------------------------------------------
+// Datasets
+// ---------------------------------------------------------------------------
+
+/**
+ * Dataset names as the SDK sees them. These are NOT the archive's internal
+ * dataset names — `book` covers two different venue-specific trees, and
+ * `settlement` is not a stored stream at all but a per-market resolution. The
+ * mapping lives in backtest-datasets.mjs so this file stays a contract.
+ */
+export const DATASETS = Object.freeze({
+  settlement: 'Resolves per market to the stream that market actually settled on.',
+  prices: 'The 1 Hz Chainlink report stream.',
+  twap30s: 'TWAP over a 30-second lookback.',
+  twap60s: 'TWAP over a 60-second lookback.',
+  book: 'Order-book snapshots and deltas.',
+  trades: 'Every trade print on the venue.',
+  markets: 'Per-market metadata, strike and settlement outcome.',
+});
+
+export const KNOWN_DATASETS = Object.freeze(Object.keys(DATASETS));
+
+/**
+ * A derived stream is computed from one we hold rather than captured. It is
+ * always flagged as derived on every row, and may never be presented as the
+ * captured stream — the honesty of the archive is the product.
+ */
+export const DERIVED_DATASETS = Object.freeze({
+  'twap60s:derived': Object.freeze({
+    from: 'prices',
+    produces: 'twap60s',
+    lookbackSeconds: 60,
+  }),
+  'twap30s:derived': Object.freeze({
+    from: 'prices',
+    produces: 'twap30s',
+    lookbackSeconds: 30,
+  }),
+});
+
+/**
+ * When each captured stream actually starts, per venue.
+ *
+ * Requesting a captured stream outside its window is E_COVERAGE — never a
+ * silent substitution, and never an approximation. A customer who asked for
+ * twap60s and got 1 Hz reports back would draw a conclusion about a settlement
+ * rule that did not exist yet.
+ *
+ * `null` end means "still being captured".
+ */
+export const CAPTURE_WINDOWS = Object.freeze({
+  polymarket: Object.freeze({
+    prices: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
+    twap30s: Object.freeze({ from: '2026-08-07', to: null }),
+    twap60s: Object.freeze({ from: '2026-08-07', to: null }),
+    book: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
+    trades: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
+    markets: Object.freeze({ from: FIRST_COMPLETE_DAY.polymarket, to: null }),
+  }),
+  predict: Object.freeze({
+    prices: Object.freeze({ from: FIRST_COMPLETE_DAY.predict, to: null }),
+    twap30s: Object.freeze({ from: '2026-08-07', to: null }),
+    twap60s: Object.freeze({ from: '2026-08-07', to: null }),
+    book: Object.freeze({ from: FIRST_COMPLETE_DAY.predict, to: null }),
+    trades: Object.freeze({ from: FIRST_COMPLETE_DAY.predict, to: null }),
+    markets: Object.freeze({ from: FIRST_COMPLETE_DAY.predict, to: null }),
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Reference feeds (external data, resolved before the run)
+// ---------------------------------------------------------------------------
+
+/**
+ * Outside data never arrives as a call from strategy code — the sandbox has no
+ * network, and a live fetch would make the same source produce different
+ * reports on different days. Feeds are resolved into a dataset ahead of the run
+ * and replayed on the same clock as everything else.
+ *
+ * Binance klines are pre-downloaded from data.binance.vision, which publishes
+ * one zip per symbol per day; see scripts/fetch-binance-reference.mjs.
+ */
+export const REFERENCE_FEEDS = Object.freeze({
+  'binance:{symbol}:spot:1s': Object.freeze({ kind: 'klines', market: 'spot', interval: '1s' }),
+  'binance:{symbol}:spot:100ms': Object.freeze({ kind: 'klines', market: 'spot', interval: '100ms', assets: Object.freeze(['BTC', 'ETH']) }),
+  'binance:{symbol}:perp:1s': Object.freeze({ kind: 'klines', market: 'perp', interval: '1s' }),
+  'binance:{symbol}:funding': Object.freeze({ kind: 'funding', market: 'perp', interval: null }),
+});
+
+/** Symbols we carry a reference feed for. */
+export const REFERENCE_SYMBOLS = Object.freeze(['btcusdt', 'ethusdt', 'solusdt', 'xrpusdt']);
+
+/** `binance:btcusdt:spot:1s` -> {feed, symbol} or null if it is not a feed we carry. */
+export function parseReferenceFeed(name) {
+  const s = String(name ?? '').trim().toLowerCase();
+  const parts = s.split(':');
+  if (parts[0] !== 'binance' || parts.length < 3) return null;
+  const symbol = parts[1];
+  if (!REFERENCE_SYMBOLS.includes(symbol)) return null;
+  const pattern = ['binance', '{symbol}', ...parts.slice(2)].join(':');
+  const feed = REFERENCE_FEEDS[pattern];
+  if (!feed) return null;
+  if (feed.assets && !feed.assets.includes(symbol.replace(/usdt$/, '').toUpperCase())) return null;
+  return { canonical: s, pattern, symbol, ...feed };
+}
+
+// ---------------------------------------------------------------------------
+// Run modes
+// ---------------------------------------------------------------------------
+
+/**
+ * `market` shards by market-day across workers, which is what makes a
+ * market-day cheap. `session` feeds one instance every market in the range as a
+ * single ordered stream — it cannot be sharded, so it runs slower and bills at
+ * a multiple.
+ */
+export const MODES = Object.freeze({
+  market: Object.freeze({ shardable: true, rateMultiplier: 1 }),
+  session: Object.freeze({ shardable: false, rateMultiplier: 3 }),
+});
+
+export const KNOWN_MODES = Object.freeze(Object.keys(MODES));
+
+// ---------------------------------------------------------------------------
+// Limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Hard limits, enforced by the API on submission and by the sandbox at run
+ * time. The API copy of a limit is a fast rejection, not the security boundary
+ * — the sandbox enforces every one of these again.
+ */
+export const LIMITS = Object.freeze({
+  maxFiles: 6,
+  maxTotalSourceBytes: 256 * 1024,
+  maxFileNameLength: 96,
+  maxSeriesBytes: 32 * 1024 * 1024,
+  maxSeriesCount: 4,
+  perEventBudgetMicros: 400,
+  memoryBytes: 8 * 1024 * 1024 * 1024,
+  vcpu: 4,
+  wallClockMs: 20 * 60 * 1000,
+  logLinesPerMarketDay: 10_000,
+  maxParams: 64,
+  maxSweepCells: 256,
+  archiveRetentionDays: 90,
+});
+
+// ---------------------------------------------------------------------------
+// Rejection codes
+// ---------------------------------------------------------------------------
+
+/**
+ * Every rejection a submission can earn before anything is billed. `ot check`
+ * runs the same validator and returns the same codes — the docs promise that a
+ * local pass is not rejected on submit, so these must stay in one place.
+ */
+export const REJECTION_CODES = Object.freeze({
+  E_MANIFEST: 'Missing or malformed outcometick.json, or a schema version we do not know.',
+  E_ENTRY: 'entry does not resolve to a class in the named file, or the class does not implement the SDK base.',
+  E_HOOK_SIG: 'A declared hook has the wrong arity or returns a type that is not Order or nothing.',
+  E_IMPORT: 'An import outside the allowlist, transitive ones included. The offending chain is printed.',
+  E_FORBIDDEN: 'Threads, subprocess, eval, dynamic import, reflection or a native extension found at import time.',
+  E_NONDETERMINISM: 'Unseeded randomness or a wall-clock read. Use ctx.random and ctx.now.',
+  E_STATE: 'Instance state is not serialisable, so the market-day cannot be moved between workers.',
+  E_BUDGET: 'Per-event budget exceeded on the smoke run. Nothing was billed.',
+  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.',
+});
+
+export const KNOWN_REJECTION_CODES = Object.freeze(Object.keys(REJECTION_CODES));
+
+/**
+ * A rejection carries its code so the CLI, the API and the page all speak the
+ * same language. Thrown rather than returned wherever validation is deep enough
+ * that threading a result out would obscure the check.
+ */
+export class BacktestRejection extends Error {
+  constructor(code, detail, extra = {}) {
+    if (!REJECTION_CODES[code]) throw new Error(`unknown rejection code ${code}`);
+    super(detail || REJECTION_CODES[code]);
+    this.name = 'BacktestRejection';
+    this.code = code;
+    this.detail = detail || REJECTION_CODES[code];
+    Object.assign(this, extra);
+  }
+
+  toJSON() {
+    const { code, detail, ...rest } = this;
+    return { code: this.code, detail: this.detail, ...stripNoise(rest) };
+  }
+}
+
+function stripNoise(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) {
+    if (k === 'name' || k === 'message' || k === 'stack') continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/** The whole contract, in the shape /v1/backtest/contract serves it. */
+export function contractDocument() {
+  return {
+    schema: SCHEMA_VERSION,
+    sdkVersion: SDK_VERSION,
+    languages: Object.fromEntries(Object.entries(LANGUAGES).map(([k, v]) => [k, {
+      label: v.label, runtime: v.runtime, entrySignature: v.entrySignature, deps: [...v.deps],
+    }])),
+    hooks: HOOKS,
+    hookNames: HOOK_NAMES,
+    datasets: DATASETS,
+    derivedDatasets: DERIVED_DATASETS,
+    captureWindows: CAPTURE_WINDOWS,
+    referenceFeeds: REFERENCE_FEEDS,
+    referenceSymbols: [...REFERENCE_SYMBOLS],
+    modes: MODES,
+    limits: LIMITS,
+    rejectionCodes: REJECTION_CODES,
+  };
+}

package/api/lib/backtest-datasets.mjs

@@ -0,0 +1,225 @@
+// Translating between what a strategy asks for and what the archive holds.
+//
+// The SDK's dataset names are a product surface: `book`, `trades`, `settlement`.
+// The archive's are a storage detail: `price_change`, `orderbook`,
+// `last_trade_price`, `chainlink-twap-60s`. Keeping the two apart is what lets
+// the archive be reorganised without breaking a manifest a customer wrote three
+// months ago.
+//
+// The interesting one is `settlement`, which is not a stored stream at all.
+
+import { classifyPath } from './data-taxonomy.mjs';
+import {
+  CAPTURE_WINDOWS, DERIVED_DATASETS, KNOWN_DATASETS, BacktestRejection,
+} from './backtest-contract.mjs';
+
+/**
+ * SDK dataset name -> the archive dataset names that satisfy it, per venue.
+ *
+ * `book` and `trades` are one concept each to a strategy but two different
+ * trees per venue: Polymarket publishes full snapshots plus deltas, Predict.fun
+ * publishes a single `orderbook` tree. A strategy that declares `book` gets
+ * whatever that venue actually has, which is the point of naming it `book`.
+ */
+const ARCHIVE_DATASETS = Object.freeze({
+  polymarket: Object.freeze({
+    prices: Object.freeze(['prices']),
+    twap30s: Object.freeze(['twap30s']),
+    twap60s: Object.freeze(['twap60s']),
+    book: Object.freeze(['book', 'price_change']),
+    trades: Object.freeze(['last_trade_price']),
+    markets: Object.freeze(['markets']),
+  }),
+  predict: Object.freeze({
+    prices: Object.freeze(['prices']),
+    twap30s: Object.freeze(['twap30s']),
+    twap60s: Object.freeze(['twap60s']),
+    book: Object.freeze(['orderbook']),
+    trades: Object.freeze(['last_trade_price']),
+    markets: Object.freeze(['markets']),
+  }),
+});
+
+/**
+ * `markets` is always fed, whether or not a strategy declares it.
+ *
+ * Not a convenience: on_market_open carries the strike and on_settle carries
+ * the official outcome, both of which live in the markets tree, and the
+ * settlement-stream resolution below reads twapLookbackSeconds from the same
+ * place. A run without it could not identify which stream a market settled on,
+ * which is the one thing this product exists to get right.
+ */
+export const ALWAYS_FED = Object.freeze(['markets']);
+
+/**
+ * Which captured stream a single market settled on.
+ *
+ * Read from the market's OWN config, never inferred from its date. The venues
+ * moved 5-minute markets onto a 30-second TWAP and then onto 60, while
+ * 15-minute markets went straight to 60 — so any date-based rule is wrong for
+ * whole classes of market inside the transition, and wrong quietly. The market
+ * record states its own lookback; that is the answer.
+ *
+ * Fail-closed on anything unrecognised. A market whose config we cannot read is
+ * not guessed at: the caller gets null and must reject the market-day rather
+ * than feed a strategy a stream the market did not settle on.
+ *
+ * @param {object} market a row from the markets dataset
+ * @returns {'prices'|'twap30s'|'twap60s'|null}
+ */
+export function resolveSettlementStream(market) {
+  const cfg = market?.raw?.cryptoMarketConfig ?? market?.cryptoMarketConfig ?? null;
+  // No config object at all is a record we could not read, NOT evidence of the
+  // pre-TWAP regime. An earlier version returned 'prices' here and that was
+  // fail-OPEN in the worst possible place: every market whose metadata we
+  // failed to parse would have been fed the 1 Hz stream and silently reported
+  // as if that were what it settled on. A dropped market-day is visible in
+  // coverage and costs the customer nothing; a wrong settlement stream is
+  // invisible and makes the whole report a lie.
+  if (!cfg || typeof cfg !== 'object') return null;
+  if (!Object.prototype.hasOwnProperty.call(cfg, 'twapLookbackSeconds')) return null;
+
+  const lookback = cfg.twapLookbackSeconds;
+  // An explicit null or 0 IS a positive statement: this market settled on the
+  // instantaneous stream. That is different from the field being absent.
+  if (lookback === null || lookback === 0) return 'prices';
+  if (lookback === 30) return 'twap30s';
+  if (lookback === 60) return 'twap60s';
+  return null;
+}
+
+/**
+ * Is a captured stream available for this venue on this day?
+ *
+ * Both ends are inclusive and `to: null` means "still capturing".
+ */
+export function isCaptured(venue, dataset, day) {
+  const w = CAPTURE_WINDOWS[venue]?.[dataset];
+  if (!w) return false;
+  if (day < w.from) return false;
+  if (w.to && day > w.to) return false;
+  return true;
+}
+
+/**
+ * Every day in [from, to] on which a captured stream is unavailable.
+ *
+ * Returned rather than counted so E_COVERAGE can name the range that failed —
+ * "twap60s is not captured before 2026-08-07" is actionable, "coverage error"
+ * is not.
+ */
+export function uncapturedRange(venue, dataset, from, to) {
+  const w = CAPTURE_WINDOWS[venue]?.[dataset];
+  if (!w) return { from, to };
+  const badFrom = from < w.from ? from : null;
+  const badTo = badFrom ? (to < w.from ? to : prevDay(w.from)) : null;
+  if (badFrom) return { from: badFrom, to: badTo };
+  if (w.to && to > w.to) return { from: nextDay(w.to), to };
+  return null;
+}
+
+function shiftDay(day, delta) {
+  const d = new Date(`${day}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + delta);
+  return d.toISOString().slice(0, 10);
+}
+const prevDay = (d) => shiftDay(d, -1);
+const nextDay = (d) => shiftDay(d, 1);
+
+/**
+ * Check a manifest's declared datasets against a venue and date range.
+ *
+ * `settlement` is exempt: it resolves per market to whatever that market
+ * settled on, so it is available wherever the archive is — that is the entire
+ * reason to prefer it, and why the docs recommend it.
+ *
+ * Throws BacktestRejection(E_COVERAGE) on the first stream that is not
+ * available for the whole range, naming the gap.
+ */
+export function assertCoverage({ datasets, venue, from, to }) {
+  for (const ds of datasets ?? []) {
+    if (ds === 'settlement') continue;
+    if (DERIVED_DATASETS[ds]) {
+      // A derived stream is a function of one we hold, so its availability is
+      // the SOURCE stream's availability, not its own.
+      const src = DERIVED_DATASETS[ds].from;
+      const gap = uncapturedRange(venue, src, from, to);
+      if (gap) {
+        throw new BacktestRejection('E_COVERAGE',
+          `${ds} is derived from ${src}, which is not captured for ${gap.from}..${gap.to ?? gap.from} on ${venue}`,
+          { dataset: ds, derivedFrom: src, venue, gap });
+      }
+      continue;
+    }
+    const gap = uncapturedRange(venue, ds, from, to);
+    if (gap) {
+      const w = CAPTURE_WINDOWS[venue]?.[ds];
+      throw new BacktestRejection('E_COVERAGE',
+        `${ds} is not captured for ${gap.from}..${gap.to ?? gap.from} on ${venue}`
+        + (w ? ` (captured from ${w.from}${w.to ? ` to ${w.to}` : ''})` : '')
+        + '. Use settlement, or a :derived stream if you specifically want today\'s rules on older dates.',
+        { dataset: ds, venue, gap, capturedFrom: w?.from ?? null, capturedTo: w?.to ?? null });
+    }
+  }
+}
+
+/**
+ * The archive dataset names a run must fetch for a given manifest.
+ *
+ * `settlement` expands to every stream that could be authoritative for some
+ * market in the range: the resolution is per market and is not known until the
+ * markets metadata has been read, so the worker fetches the union and the
+ * engine picks per market. Streams outside their capture window are dropped
+ * rather than requested — no market in that window can have settled on them.
+ */
+export function archiveDatasetsFor({ datasets, venue, from, to }) {
+  const wanted = new Set();
+  for (const ds of [...(datasets ?? []), ...ALWAYS_FED]) {
+    if (ds === 'settlement') {
+      for (const s of ['prices', 'twap30s', 'twap60s']) {
+        if (!uncapturedRange(venue, s, from, to) || isCaptured(venue, s, to)) wanted.add(s);
+      }
+      continue;
+    }
+    const base = DERIVED_DATASETS[ds]?.from ?? ds;
+    wanted.add(base);
+  }
+  const out = new Set();
+  const map = ARCHIVE_DATASETS[venue] ?? {};
+  for (const w of wanted) for (const a of map[w] ?? []) out.add(a);
+  return [...out].sort();
+}
+
+/**
+ * Does an archived file belong to this run's scope?
+ *
+ * Runs on top of the entitlement gate, never instead of it: this decides what a
+ * paid-for run is FED, while scope.mjs decides what a customer may DOWNLOAD.
+ * A backtest reads files the submitter has not bought, which is the product —
+ * so this filter must never be mistaken for an authorisation check.
+ */
+export function fileMatchesRun(filePath, { venue, assets, archiveDatasets }) {
+  const meta = classifyPath(filePath);
+  if (meta.venue !== venue) return false;
+  if (!archiveDatasets.includes(meta.dataset)) return false;
+  // Venue-wide datasets (markets) carry no asset and are always in scope.
+  if (meta.asset && assets?.length && !assets.includes(meta.asset)) return false;
+  return true;
+}
+
+/** Validate a declared dataset list, returning it normalised. */
+export function normalizeDatasets(list) {
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new BacktestRejection('E_MANIFEST', 'datasets must be a non-empty array');
+  }
+  const out = [];
+  for (const raw of list) {
+    const ds = String(raw ?? '').trim();
+    if (!KNOWN_DATASETS.includes(ds) && !DERIVED_DATASETS[ds]) {
+      throw new BacktestRejection('E_MANIFEST',
+        `unknown dataset ${JSON.stringify(ds)}; known: ${[...KNOWN_DATASETS, ...Object.keys(DERIVED_DATASETS)].join(', ')}`);
+    }
+    if (!out.includes(ds)) out.push(ds);
+  }
+  return out;
+}