cTrader/docs/export-runner-quirks.md

# export-runner.sh — quirk audit & hardening decisions

`scripts/export-runner.sh` is the Linux-host port of the original Unraid data-export
driver. Before going live it was put through a multi-lens adversarial audit (5 review
lenses over the script **and** the `MS_SimpleExport` cBot, each finding independently
verified). 49 findings survived verification, deduplicating to ~18 distinct quirks.

This document records what was fixed, what was a deliberate behaviour choice, and what
is intentionally left alone — so the rationale is not lost.

## Behaviour decisions (the load-bearing ones)

| Topic | Decision | Why |
|---|---|---|
| **Transient failure** | Retry ×3, then **hard-abort** the whole run | A login stall / crash / timeout must never be silently treated as "empty month". Aborting loudly means a gap is noticed, not buried. |
| **Resume** | **Gap-aware**: walk every month from the symbol's first data month to now; scrape only **missing** months + the **trailing edge** (latest existing + current). | Fixes the silent middle-gap (old `ls\|sort\|tail-1` resume never backfilled) **and** stops overwriting known-good middle files. |
| **Empty month** | Don't write empty files. A clean `No historical data` is classified **empty → skip**. | For continuously-active instruments a true in-range empty month effectively never occurs; the empty path is purely defensive and must not trip the hard-abort. |
| **Current month** | Clamp the end date to **yesterday** | cTrader rejects a backtest whose end date is in the future (proven), so the whole current month was being dropped. Clamping captures the partial month now; next month's edge re-scrape completes it. |

## Classification — the core of the hardening

`run_one` reads the console log stream (with a per-run `timeout`) and classifies the
outcome, instead of trusting a single stdout sentinel:

- `DATA_FOUND` / `EXPORT_SUCCESS` → **success** (rc 0)
- `No historical data for the specified period` → **clean-empty** (rc 3, skipped)
- the backtest reaches its `}` summary but exported nothing → **clean-empty** (rc 3, skipped).
  This catches a cTrader-side **data hole** (a month with no data *inside* a symbol's
  range, e.g. Copper 2017-04), which emits a degenerate empty result block
  (`{ "Equity":, … }`) instead of the clean "No historical data" message — surfaced by
  the first real production run.
- bot `ERROR:` (an OnStop exception, e.g. a write failure) → **failure** (rc 2)
- no `}` terminator at all — timeout, crash, dead stream → **transient failure** (rc 2,
  retried then aborted). A genuine transient failure never reaches the clean `}` summary,
  which is what separates it from a data hole.

A produced ZIP is validated (`testzip` + non-empty entry) **before** the `mv`, so a
truncated artifact from a cut-off run is caught instead of being promoted to a final file.

## Quirks fixed (no behaviour choice needed)

| Quirk | Fix |
|---|---|
| No per-run timeout → a hung console blocks the whole export forever | `timeout` around the log drain; a hang is a transient failure |
| `--rm` + `docker logs -f` race could lose markers on a fast-exiting container | dropped `--rm`; container kept until logs drained, then removed; trap reaps any in-flight container on Ctrl-C (no orphans) |
| `*ERROR*` matched as an unanchored substring | matched against the bot's `ERROR:` form / the explicit verdict markers |
| Resume parser `cut -f2/-f3` corrupts year/month for symbols containing `_` | parsed with a bash regex anchored on the symbol |
| Resume `sort\|tail` is lexical | month walk is purely numeric (`year*12 + month-1` index) |
| Empty / corrupt ZIP promoted to a final file | `validate_export` (PK + CRC + non-empty entry) gates the `mv` |
| Monthly start-probe only tested days 01–10 | discovery probes the **full** month; yearly probe uses December (catches same-year-later starts) |
| Completion banner always printed "success" | banner reports saved / empty counts |

## Intentionally NOT changed — frozen by the existing corpus

The binary record layout (`M1Record` = 48 B: raw `double` OHLC, `float` spread, `int`
volume; `TickRecord` = 24 B) is **frozen by the ~4380 existing `.m1`/`.tick` files** the
bot already produced. Any layout change makes new files incompatible with the corpus, so
the following audit findings are **WONTFIX** unless the whole dataset is re-exported:

- `TickVolume` stored as `int` (would need `long`) — harmless in practice: an M1 bar's
  tick count never approaches `int` range.
- `Spread` as raw `float` price units, and no `Digits` field — a downstream reader must
  know the contract out-of-band. (Also: `Symbol.Spread` is usually 0 in M1 bar replay, so
  that column is largely meaningless for M1 mode — a data-source limitation, not fixable
  without tick data.)
- ZIP entry named after `Symbol.Name` while the file is named after the requested symbol —
  cosmetic: the file is renamed by the driver and the reader opens the single entry by
  position, not name.

If the format is ever migrated, that is a separate project that also re-exports the corpus.

## Verification

The hardened script was validated end-to-end against a scratch directory (the real NFS
data dir untouched):

- **Gap-fill / edge / clamp / trusted-middle**: seeded `2026_03` + `2026_05` (gap at `04`);
  the run filled `04`, re-scraped the `05` edge, captured the current month `06` clamped to
  yesterday, and left the trusted middle `03` byte-identical.
- **Clean-empty safety**: `run_one` on an empty future window returns rc 3 (skip), never the
  rc 2 that would abort the run.