outcometick 1.4.0

package/cli/commands/fetch.mjs

@@ -0,0 +1,43 @@
+// `ot fetch <run_id>` — download a finished run's archive.
+//
+// Referenced by `ot status`, which is why it exists: the same rule as `ot
+// status` itself — do not print a command that is not real.
+//
+// The archive URL is presigned for 15 minutes and is a bearer token for someone
+// else's strategy results, so this asks the API for a fresh one each time
+// rather than caching anything.
+
+import { writeFile } from 'node:fs/promises';
+import { readKey, getBinary, DEFAULT_API } from '../api-client.mjs';
+
+export async function cmdFetch({ dir, flags }) {
+  const runId = dir;
+  if (!runId || runId === '.') throw new Error('usage: ot fetch <run_id> [--out <file>]');
+  const key = readKey();
+  const api = flags.api ?? DEFAULT_API;
+
+  const { status, json, text, body } = await getBinary(
+    api, `/v1/backtest/run/${encodeURIComponent(runId)}/archive`, key,
+  );
+
+  if (status === 404) {
+    process.stderr.write(`\n  no run ${runId} under this key\n\n`);
+    return 1;
+  }
+  if (status === 409) {
+    // The run exists but has produced nothing yet — a different thing from a
+    // missing run, and the status is the useful part.
+    process.stderr.write(`\n  no archive yet — run is ${json?.status ?? 'not finished'}\n`
+      + `  ot status ${runId}\n\n`);
+    return 1;
+  }
+  if (status !== 200 || !body) {
+    process.stderr.write(`\n  ${status}: ${json?.error ?? text.slice(0, 300)}\n\n`);
+    return 1;
+  }
+
+  const out = flags.out ?? `${runId}.zip`;
+  await writeFile(out, body);
+  process.stdout.write(`\n  ${out} (${(body.length / 1024).toFixed(0)} KB)\n\n`);
+  return 0;
+}

package/cli/commands/run.mjs

@@ -0,0 +1,269 @@
+// `ot run` — replay locally, against a cloned sample archive.
+//
+// The same engine, the same harnesses, the same report and the same archive
+// writer the queue uses. That is the whole point of the command: the docs
+// promise "a backtest here and a backtest on your own machine after subscribing
+// read the same bytes", and the only way that holds is by not having a second
+// implementation of any of it.
+//
+// What differs from the worker: the data comes off disk instead of R2, and
+// there is no container. `ot run` says so plainly rather than implying the
+// isolation is the same — locally the strategy runs with the user's own
+// privileges, which is fine, because it is their code on their machine.
+
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { LANGUAGES, HOOK_NAMES, LIMITS } from '../../api/lib/backtest-contract.mjs';
+import { CHANNEL, EXIT, parseTrade, parseFill, parseResult, parseOutputLine } from '../../runner/harness/protocol.mjs';
+import { buildReport, metrics, LATENCY_STEPS } from '../../runner/engine/report.mjs';
+import { buildArchive } from '../../runner/archive.mjs';
+import { loadLocalDay, localDays, looksLikeArchive } from '../local-data.mjs';
+import { readSubmission, validate } from '../ot.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const RUNNER = path.join(HERE, '..', '..', 'runner');
+
+/** Run one pass of the local harness over the given markets. */
+function runHarness({ languageId, jobDir, job, markets, outputKey }) {
+  const cmd = languageId === 'python' ? (process.env.OT_PYTHON || 'python3') : process.execPath;
+  const argv = languageId === 'python'
+    ? [path.join(RUNNER, 'harness/python/harness.py'), jobDir]
+    : [path.join(RUNNER, 'harness/node/harness.mjs'), jobDir];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, argv, { stdio: ['pipe', 'inherit', 'pipe', 'pipe'] });
+    const lines = [];
+    let tail = '';
+    let stderr = '';
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.stdio[3].on('data', (d) => {
+      tail += d;
+      const parts = tail.split('\n');
+      tail = parts.pop();
+      for (const line of parts) {
+        if (!line) continue;
+        const parsed = parseOutputLine(outputKey, line);
+        if (parsed) lines.push(parsed);
+      }
+    });
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code, stderr, lines }));
+
+    child.stdin.on('error', () => {});
+    child.stdin.write(`${JSON.stringify({ ...job, outputKey })}\n`);
+    for (const m of markets) {
+      child.stdin.write(`${JSON.stringify({ market: m.market, stream: m.stream, n: m.events.length })}\n`);
+      for (const ev of m.events) child.stdin.write(`${JSON.stringify(ev)}\n`);
+    }
+    child.stdin.end();
+  });
+}
+
+function demux(lines) {
+  const trades = [];
+  const fills = [];
+  const logs = [];
+  let result = parseResult({});
+  for (const { channel, payload } of lines) {
+    if (channel === CHANNEL.log) { logs.push(payload); continue; }
+    if (channel === CHANNEL.result) {
+      try { result = parseResult(JSON.parse(payload)); } catch { /* keep the empty one */ }
+      continue;
+    }
+    let raw;
+    try { raw = JSON.parse(payload); } catch { continue; }
+    const row = channel === CHANNEL.trade ? parseTrade(raw) : parseFill(raw);
+    if (!row) continue;
+    (channel === CHANNEL.trade ? trades : fills).push(row);
+  }
+  return { trades, fills, logs: logs.join('\n'), result };
+}
+
+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');
+  }
+  if (!await looksLikeArchive(dataRoot)) {
+    throw new Error(`${path.resolve(dataRoot)} does not look like an archive — no recognisable data files under it`);
+  }
+
+  const files = await readSubmission(dir);
+  const checked = await validate(files);
+  const { manifest } = checked;
+  const languageId = manifest.languageId;
+
+  const available = await localDays(dataRoot);
+  if (available.length === 0) throw new Error(`no dated files under ${path.resolve(dataRoot)}`);
+  const days = flags.date ? [flags.date] : available;
+  const unknown = days.filter((d) => !available.includes(d));
+  if (unknown.length) {
+    throw new Error(`${unknown.join(', ')} not in ${path.resolve(dataRoot)} — it holds ${available[0]}..${available[available.length - 1]}`);
+  }
+
+  const venue = flags.venue ?? 'polymarket';
+  const assets = (flags.assets ?? '').split(',').map((a) => a.trim().toUpperCase()).filter(Boolean);
+
+  const markets = [];
+  for (const day of days) {
+    const loaded = await loadLocalDay({
+      root: dataRoot, day, venue,
+      assets: assets.length ? assets : ['BTC', 'ETH', 'SOL', 'XRP'],
+      datasets: manifest.datasets,
+    });
+    if (loaded.markets.length === 0) {
+      process.stderr.write(`  ${day}: ${loaded.reason}\n`);
+      continue;
+    }
+    markets.push(...loaded.markets);
+  }
+  if (markets.length === 0) throw new Error('no market-days could be read from that archive');
+
+  const jobDir = await mkdtemp(path.join(tmpdir(), 'ot-run-'));
+  try {
+    const src = path.join(jobDir, 'src');
+    await mkdir(src, { recursive: true });
+    for (const f of checked.files) {
+      const dest = path.resolve(src, f.name);
+      await mkdir(path.dirname(dest), { recursive: true });
+      await writeFile(dest, f.content);
+    }
+    // The SDK has to be resolvable exactly as it is in the image, or the
+    // documented `import … from "outcometick"` fails locally and works remotely.
+    if (languageId === 'nodejs') {
+      const { cp } = await import('node:fs/promises');
+      await cp(path.join(RUNNER, 'harness/node/sdk'),
+        path.join(jobDir, 'node_modules', 'outcometick'), { recursive: true });
+    }
+
+    const baseJob = {
+      entry: manifest.entry,
+      hooks: Object.fromEntries(manifest.hooks.map((h) => [h, HOOK_NAMES[languageId][h]])),
+      arities: { on_market_open: 3, on_tick: 3, on_book: 3, on_trade: 3, on_settle: 4 },
+      params: manifest.params,
+      mode: manifest.mode,
+      seed: Number(flags.seed ?? 1),
+      feeBps: Number(flags['fee-bps'] ?? 0),
+      limits: LIMITS,
+    };
+    if (languageId === 'python') {
+      process.env.PYTHONPATH = [path.join(RUNNER, 'harness/python'), process.env.PYTHONPATH]
+        .filter(Boolean).join(path.delimiter);
+    }
+
+    if (!flags.json) {
+      process.stdout.write(`\n  ${markets.length} market-days · ${manifest.language} · local replay\n`);
+    }
+
+    const passes = [];
+    for (const step of LATENCY_STEPS) {
+      const outputKey = randomBytes(32).toString('hex');
+      const res = await runHarness({
+        languageId, jobDir, outputKey, markets,
+        job: { ...baseJob, fillDelayMs: step.ms },
+      });
+      const out = demux(res.lines);
+      if (step.ms === 0) {
+        if (res.code === EXIT.rejected || res.code === EXIT.budget) {
+          const r = out.result.rejection ?? { code: 'E_RUNTIME', detail: res.stderr.slice(0, 2000) };
+          const err = new Error(r.detail);
+          err.code = r.code;
+          err.detail = r.detail;
+          throw err;
+        }
+        if (res.code !== EXIT.ok) throw new Error(res.stderr.slice(0, 2000) || `harness exited ${res.code}`);
+      }
+      passes.push({ delayMs: step.ms, ...out, ok: res.code === EXIT.ok });
+      // A strategy that never traded has no latency curve to draw.
+      if (step.ms === 0 && out.trades.length === 0) break;
+    }
+
+    const base = passes[0];
+    const marketMeta = new Map(markets.map((m) => [m.market.market_id, {
+      market_id: m.market.market_id,
+      asset: m.market.asset,
+      interval: m.market.interval,
+      outcome: m.market.outcome,
+      up_px: m.up_px,
+      down_px: m.down_px,
+      stream: m.stream,
+    }]));
+
+    const report = buildReport({
+      runId: `local_${days[0]}`,
+      submittedAt: 0,
+      manifest,
+      scope: {
+        venue,
+        assets: assets.length ? assets : [...new Set(markets.map((m) => m.market.asset).filter(Boolean))],
+        from: days[0],
+        to: days[days.length - 1],
+        marketDays: markets.length,
+        archivedDayCount: days.length,
+      },
+      scanned: { markets: base.result.marketsRun, market_days: markets.length, events: base.result.eventsSeen },
+      trades: base.trades,
+      fills: base.fills,
+      marketSummaries: [...marketMeta.values()],
+      marketMeta,
+      feesPaid: base.result.feesPaid,
+      latency: passes.filter((p) => p.ok).map((p) => ({
+        delayMs: p.delayMs, netPnl: metrics(p.trades).net_pnl ?? 0,
+      })),
+      sweep: null,
+      crosschecks: base.result.crosschecks,
+      seed: Number(flags.seed ?? 1),
+      coverage: {
+        local: true,
+        source: path.resolve(dataRoot),
+        market_days_scanned: markets.length,
+        streams: [...marketMeta.values()].reduce((acc, m) => {
+          const k = m.stream ?? 'unknown';
+          acc[k] = (acc[k] ?? 0) + 1;
+          return acc;
+        }, {}),
+      },
+      budget: base.result.budget,
+    });
+
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(report)}\n`);
+    } else {
+      const m = report.metrics;
+      const money = (v) => (v == null ? '—' : `${v < 0 ? '-' : '+'}$${Math.abs(v).toLocaleString()}`);
+      process.stdout.write(`\n  net pnl        ${money(m.net_pnl)}\n`);
+      process.stdout.write(`  trades         ${m.trades}\n`);
+      process.stdout.write(`  win rate       ${m.win_rate == null ? '—' : `${(m.win_rate * 100).toFixed(1)}%`}\n`);
+      process.stdout.write(`  brier          ${m.brier_score ?? '—'}\n`);
+      process.stdout.write(`  edge/contract  ${m.edge_per_contract == null ? '—' : `${(m.edge_per_contract * 100).toFixed(1)}¢`}\n`);
+      process.stdout.write(`  fees           ${money(m.fees)}\n`);
+      if (report.slippage.pnl_lost_to_slippage != null) {
+        process.stdout.write(`  lost to slip   ${money(report.slippage.pnl_lost_to_slippage)}\n`);
+      }
+      process.stdout.write('\n  This is a LOCAL replay: no container, your own privileges, sample data.\n');
+    }
+
+    const outFile = flags.out ?? `${path.basename(path.resolve(dir))}-local.zip`;
+    const zip = await buildArchive({
+      runId: report.run_id,
+      report,
+      trades: base.trades,
+      fills: base.fills,
+      logs: base.logs,
+      source: checked.files,
+    });
+    await writeFile(outFile, zip);
+    if (!flags.json) process.stdout.write(`  archive        ${outFile} (${(zip.length / 1024).toFixed(0)} KB)\n\n`);
+    return 0;
+  } finally {
+    await rm(jobDir, { recursive: true, force: true });
+  }
+}
+
+export { LANGUAGES };

package/cli/commands/status.mjs

@@ -0,0 +1,102 @@
+// `ot status <run_id>` — where a submitted run got to.
+//
+// This command exists because `ot submit` prints it. A tool that tells you to
+// run something that does not exist is worse than one that tells you nothing.
+//
+// It reads; it never bills, cancels or retries. The archive it points at is
+// fetched through the API rather than a stored URL: archive links are 15-minute
+// bearer tokens for someone's strategy results, so the right thing to hold onto
+// is the run id, not the link.
+
+import { readKey, get } from '../api-client.mjs';
+
+const STATUS_LINE = {
+  staging: 'staging — the submission is still being stored',
+  queued: 'queued — waiting for a worker',
+  running: 'running',
+  done: 'done',
+  failed: 'failed',
+  rejected: 'rejected',
+  expired: 'expired — the archive is past its retention window',
+};
+
+// Statuses in which the ledger has settled, so spent-vs-returned is a fact
+// rather than a guess. Anything not listed still holds the credits.
+const SETTLED = new Set(['done', 'failed', 'rejected', 'expired']);
+
+function ms(v) {
+  return v == null ? '—' : new Date(v).toISOString().replace('T', ' ').slice(0, 19);
+}
+
+export async function cmdStatus({ dir, flags }) {
+  // The run id is positional, which `parseArgs` hands back as `dir`.
+  const runId = dir;
+  if (!runId || runId === '.') throw new Error('usage: ot status <run_id>');
+  const key = readKey();
+  const api = flags.api ?? 'https://outcometick.com';
+
+  const { status, json, text } = await get(api, `/v1/backtest/run/${encodeURIComponent(runId)}`, key);
+  if (status === 404) {
+    process.stderr.write(`\n  no run ${runId} under this key\n\n`);
+    return 1;
+  }
+  if (status === 401) {
+    process.stderr.write('\n  OT_BACKTEST_KEY was not accepted.\n\n');
+    return 1;
+  }
+  if (status !== 200 || !json) {
+    process.stderr.write(`\n  ${status}: ${json?.error ?? text.slice(0, 300)}\n\n`);
+    return 1;
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(json)}\n`);
+    return 0;
+  }
+
+  process.stdout.write(`\n  ${json.run_id}\n`);
+  process.stdout.write(`  status      ${STATUS_LINE[json.status] ?? json.status}\n`);
+  process.stdout.write(`  scope       ${json.venue} · ${(json.assets ?? []).join(' ')} · ${json.from}..${json.to}\n`);
+  process.stdout.write(`  market-days ${json.market_days}\n`);
+  process.stdout.write(`  submitted   ${ms(json.created_ms)}\n`);
+  if (json.finished_ms) process.stdout.write(`  finished    ${ms(json.finished_ms)}\n`);
+
+  if (json.rejection) {
+    process.stdout.write(`\n  ${json.rejection.code}\n  ${json.rejection.detail}\n`);
+  }
+
+  // Held vs spent, said plainly: a partial run bills for the market-days it
+  // actually read, and the difference goes back. Printing only one of the two
+  // numbers is how a refund looks like an overcharge.
+  //
+  // But "returned" may only be said once the run has actually finished. While
+  // it is still staging or queued nothing has been spent and nothing has been
+  // returned either — the credits are HELD. Deriving the refund from
+  // held - spent in that state prints "0 spent (100 returned)" at a moment when
+  // the customer's balance is still 100 short, which is the opposite of
+  // reassuring.
+  if (SETTLED.has(json.status) && json.credits_spent != null) {
+    const held = json.credits_held ?? 0;
+    const returned = held - json.credits_spent;
+    process.stdout.write(`  credits     ${json.credits_spent} spent`);
+    process.stdout.write(returned > 0 ? ` (${returned} returned)\n` : '\n');
+  } else if (json.credits_held != null) {
+    process.stdout.write(`  credits     ${json.credits_held} held\n`);
+  }
+
+  const m = json.report?.metrics;
+  if (m) {
+    const money = (v) => (v == null ? '—' : `${v < 0 ? '-' : '+'}$${Math.abs(v).toLocaleString()}`);
+    process.stdout.write(`\n  net pnl     ${money(m.net_pnl)}\n`);
+    process.stdout.write(`  trades      ${m.trades}\n`);
+    if (m.win_rate != null) process.stdout.write(`  win rate    ${(m.win_rate * 100).toFixed(1)}%\n`);
+  }
+
+  if (json.archive_available) {
+    const kb = json.archive_bytes == null ? '' : ` (${(json.archive_bytes / 1024).toFixed(0)} KB)`;
+    process.stdout.write(`\n  archive${kb}\n`);
+    process.stdout.write(`  ot fetch ${json.run_id}\n`);
+  }
+  process.stdout.write('\n');
+  return 0;
+}

package/cli/commands/submit.mjs

@@ -0,0 +1,77 @@
+// `ot submit` — send a validated submission to the queue.
+//
+// Validates locally FIRST, with the same validator the queue runs, so the
+// common failures cost a round trip rather than a queued run. The server
+// validates again regardless: a client that decided its own submission was fine
+// is not a security model, and the CLI is a convenience, not an authority.
+//
+// The same goes for the price. `ot submit` prints what the server quoted; it
+// never computes one. A number this file derived would be a second pricing
+// implementation, and the first time it disagreed the customer would be told
+// one thing and charged another.
+
+import { readSubmission, validate } from '../ot.mjs';
+import { readKey, post, DEFAULT_API } from '../api-client.mjs';
+
+export async function cmdSubmit({ dir, flags }) {
+  const api = flags.api ?? DEFAULT_API;
+  const key = readKey();
+
+  const assets = (flags.assets ?? '').split(',').map((a) => a.trim()).filter(Boolean);
+  if (assets.length === 0) throw new Error('--assets is required, e.g. --assets btc,eth');
+  if (!flags.from && !flags.range) throw new Error('--from and --to are required, or --range "30 days"');
+
+  const files = await readSubmission(dir);
+  const scope = {
+    venue: flags.venue ?? 'polymarket',
+    assets,
+    ...(flags.range ? { range: flags.range } : { from: flags.from, to: flags.to }),
+  };
+
+  // Locally first. The rejection codes are identical either way, so a customer
+  // who fixes what `ot check` said will not be told something different here.
+  await validate(files);
+
+  const body = { ...scope, files, ...(flags.email ? { email: flags.email } : {}) };
+  const { status, json, text } = await post(api, '/v1/backtest/submit', body, key);
+
+  if (status === 202 && json?.run_id) {
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(json)}\n`);
+      return 0;
+    }
+    const q = json.quote ?? {};
+    process.stdout.write(`\n  queued — ${json.run_id}\n`);
+    process.stdout.write(`  scope       ${q.venue} · ${(q.assets ?? []).join(' ')} · ${q.from}..${q.to}\n`);
+    process.stdout.write(`  market-days ${q.marketDays}\n`);
+    if (q.missingDays > 0) {
+      // Said out loud: a smaller number than the range asked for, unexplained,
+      // reads as a bug in our favour.
+      process.stdout.write(`  not in the archive: ${q.missingDays} day(s) — not billed\n`);
+    }
+    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`);
+    return 0;
+  }
+
+  if (status === 402) {
+    process.stderr.write(`\n  not enough credits: have ${json?.balance}, this run needs ${json?.required}\n\n`);
+    return 1;
+  }
+  if (status === 401) {
+    process.stderr.write('\n  OT_BACKTEST_KEY was not accepted.\n\n');
+    return 1;
+  }
+  if (status === 422 && json?.code) {
+    // The server rejected something the local validator passed. That should not
+    // happen — the promise is that they are the same validator — so say so
+    // rather than printing it as an ordinary error.
+    process.stderr.write(`\n  ${json.code}\n  ${json.detail}\n\n`
+      + '  This passed `ot check` locally. That is a bug on our side —\n'
+      + '  please report it with the manifest.\n\n');
+    return 1;
+  }
+  process.stderr.write(`\n  ${status}: ${json?.error ?? text.slice(0, 300)}\n\n`);
+  return 1;
+}

package/cli/local-data.mjs

@@ -0,0 +1,177 @@
+// Reading a cloned sample archive off disk, for `ot run`.
+//
+// The counterpart to runner/fetch-data.mjs, which reads the same archive out of
+// R2. Both go through runner/events.mjs for the row -> event mapping, because
+// the docs make a promise about exactly this pair:
+//
+//     The identical files, same checksums, same coverage report. A backtest
+//     here and a backtest on your own machine after subscribing read the same
+//     bytes — that is the point of offering it.
+//
+// Two decoders would make that false the first time they disagreed, and the
+// disagreement would be silent.
+
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { createGunzip } from 'node:zlib';
+import path from 'node:path';
+
+import { classifyPath } from '../api/lib/data-taxonomy.mjs';
+import { archiveDatasetsFor, fileMatchesRun } from '../api/lib/backtest-datasets.mjs';
+import { indexMarkets, eventsFromRow, finaliseMarket, parseRow } from '../runner/events.mjs';
+
+/**
+ * Every file under a directory, as archive-relative paths.
+ *
+ * Symlinks are skipped rather than followed, in both directions: a symlinked
+ * directory is not descended into and a symlinked file is not read. `--data`
+ * points at a directory the user cloned from the internet, and git happily
+ * carries symlinks — so without this, a repo dressed up as sample data could
+ * name `~/.ssh/id_rsa` as a prices file and have `ot run` read it. Very little
+ * of an arbitrary file survives being parsed as archive rows, which makes this
+ * a poor exfiltration channel rather than a safe one; there is no reason to
+ * leave it open when the fix is to not follow the link.
+ *
+ * Regular files and real directories are all a genuine archive contains.
+ */
+async function walk(root, prefix = '', depth = 0) {
+  const out = [];
+  // A real archive is nested about six deep. The bound is what stops a
+  // symlink-free cycle or a pathologically deep tree from spinning here.
+  if (depth > 12) return out;
+  let entries;
+  try {
+    entries = await readdir(path.join(root, prefix), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isSymbolicLink()) continue;
+    if (e.isDirectory()) out.push(...await walk(root, rel, depth + 1));
+    else if (e.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+/** Stream one local archive file, gunzipping if needed, yielding parsed rows. */
+async function* readRows(root, rel) {
+  const full = path.join(root, rel);
+  const raw = createReadStream(full);
+  const stream = rel.endsWith('.gz') ? raw.pipe(createGunzip()) : raw;
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  const isCsv = rel.includes('.csv');
+  let header = null;
+  for await (const line of rl) {
+    const s = line.trim();
+    if (!s) continue;
+    if (isCsv && header === null) { header = s.split(','); continue; }
+    const row = parseRow(s, { isCsv, header });
+    if (row) yield row;
+  }
+}
+
+/**
+ * Which UTC day a sample archive path belongs to.
+ *
+ * The sample repos name files with the day in them, the same as the archive.
+ * A file we cannot date is skipped rather than guessed at — a mis-dated file
+ * would put one day's events into another day's market.
+ */
+export function dayOfPath(rel) {
+  const m = /(\d{4}-\d{2}-\d{2})/.exec(rel);
+  return m ? m[1] : null;
+}
+
+/**
+ * Load one day out of a local archive.
+ *
+ * Returns the same shape fetchMarketDays does, so `ot run` and the worker feed
+ * the harness identically.
+ */
+export async function loadLocalDay({ root, day, venue, assets, datasets }) {
+  const archiveDatasets = archiveDatasetsFor({ datasets, venue, from: day, to: day });
+  const all = await walk(root);
+  const wanted = all.filter((rel) => dayOfPath(rel) === day
+    && fileMatchesRun(rel, { venue, assets, archiveDatasets }));
+
+  if (wanted.length === 0) {
+    return { markets: [], reason: `no files for ${day} under ${root}` };
+  }
+
+  // Markets first: everything else is keyed by market, and the settlement
+  // stream resolution needs this.
+  const marketRows = [];
+  for (const rel of wanted.filter((r) => classifyPath(r).dataset === 'markets')) {
+    for await (const row of readRows(root, rel)) marketRows.push(row);
+  }
+  const markets = indexMarkets(marketRows);
+  if (markets.size === 0) {
+    return { markets: [], reason: `no market metadata for ${day}` };
+  }
+
+  const byMarket = new Map();
+  for (const rel of wanted) {
+    if (classifyPath(rel).dataset === 'markets') continue;
+    for await (const row of readRows(root, rel)) {
+      for (const [id, ev] of eventsFromRow(rel, row, markets)) {
+        if (!markets.has(id)) continue;
+        let list = byMarket.get(id);
+        if (!list) { list = []; byMarket.set(id, list); }
+        list.push(ev);
+      }
+    }
+  }
+
+  const out = [];
+  for (const [marketId, events] of byMarket) {
+    const market = markets.get(marketId);
+    // Fail-closed, exactly as the worker does: a market whose settlement stream
+    // we cannot read is dropped, not guessed at.
+    if (!market || market.stream == null) continue;
+    const { events: inWindow, up_px, down_px } = finaliseMarket(events, market);
+    if (inWindow.length === 0) continue;
+    out.push({
+      market: {
+        market_id: market.market_id,
+        asset: market.asset,
+        interval: market.interval,
+        strike: market.strike,
+        outcome: market.outcome,
+        open_ts_ms: market.open_ts_ms,
+        close_ts_ms: market.close_ts_ms,
+      },
+      events: inWindow,
+      stream: market.stream,
+      day,
+      up_px,
+      down_px,
+    });
+  }
+  return { markets: out, reason: null };
+}
+
+/** Days a local archive appears to hold, sorted. */
+export async function localDays(root) {
+  const all = await walk(root);
+  const days = new Set();
+  for (const rel of all) {
+    const d = dayOfPath(rel);
+    if (d) days.add(d);
+  }
+  return [...days].sort();
+}
+
+/** Does this look like a cloned sample archive at all? */
+export async function looksLikeArchive(root) {
+  try {
+    const s = await stat(root);
+    if (!s.isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  const all = await walk(root);
+  return all.some((rel) => classifyPath(rel).dataset !== 'other');
+}