themeparks-backfill: --since/--until, incremental reruns, final days only; changeRows() exposes opening

[cubehouse]

What this fixes

A customer-style run of themeparks-backfill 8.3.1 found three problems in the command and one in the history helpers. Each was reproduced against the live API before it was fixed. The Python SDK ships the same fixes (ThemeParks/ThemeParks_Python#33), and the two behave the same except where noted below.

1. No date range. --since was Unknown option, so you always got everything your key reaches. New flags: --since YYYY-MM-DD and --until YYYY-MM-DD. Both days are inclusive, each must be a real calendar day (2025-02-30, 2025-1-1 and 20250101 are rejected), and --since after --until is refused before any request is made.
2. Reruns never updated. Once a park was complete, running it again printed already complete and exited 0 without fetching anything, so a nightly cron looked healthy but never updated. Now a finished file continues from the day after its last one. An interrupted run still resumes at its page boundary.
3. The last days were partial, and stayed partial. Runs ended on retrievableThrough, usually today. Today's row is the day so far, and the API docs say recording runs 2 to 3 days behind live data, so the last few days of every file were written while they could still change. Now:
   • a run ends at the new span().finalThrough (the earlier of recordedTo and retrievableThrough) and says when it held days back;
   • the next run adds those days once they are final;
   • each day is fetched once, as the archive recorded it, so the file only ever gets appended to.
4. history.changeRows() threw away opening, the state in force at the start of the range. It is now exposed without breaking anything: the result is the same async generator yielding the same { entityId, row } entries, and it also carries opening, keyed by entity id, readable after iterating or after await changes.load(), for one request. (history.changes() returns the raw envelope and always had it.)
5. waitTime: checked, no mismatch here. The README and the generated types both say number, matching the spec. A test now pins the README table to that.

Also fixed along the way (each has a test and a committed mutant)

• An interrupted run appended days twice. The state was written only at the end of a run or on an error the command caught, so Ctrl-C, SIGTERM or a kill during a multi-page download or a nightly extension left an older state, and the rerun appended the same days again. The state is now written atomically (temp file, then rename) before the first request and after every page, with the data file's size; a rerun first prints discarding the last N bytes of X: written after the last checkpoint, and fetched again now and cuts the file back to it. An extension is marked unfinished before it asks for anything. SIGTERM exits 143 (Ctrl-C 130). days() now awaits onPage, so the checkpoint is on disk before the next request.
• Two runs on one output at once are refused with a lock beside the state file ("another themeparks-backfill is writing this park"); a lock left by a process that is gone is taken over.
• A finished state file with a different column layout was appended to: the whole archive a second time, under a second header, exit 0. It is now refused, like an unfinished one.
• If the data file had been deleted but its state file remained, the next run carried on part-way through. It now downloads the park again.
• A continued file whose next day is older than the key may read is refused rather than carried forward past a gap.

Compatibility

• To be released as 8.4.0. HistorySpan gains a required field, finalThrough, so code that builds one by hand needs to add it. HistoryChanges and HistoryOpening are exported types. onPage may now return a promise.
• State files move to version 2. start is the first day the file covers (after the key's window), since the start it was asked for, end the newest recorded day, and size the file's size at the checkpoint.
• Version 1 files from this SDK are upgraded, not refused. Nobody recorded which of their newest days were final, so the upgrade removes rows dated within 7 days of the old end (kept rows are copied byte for byte) and fetches those days again, and says so. A file wholly inside that window, as every anonymous run's is, is downloaded again.
• --since on a rerun: the one the file was asked to start from, or one inside the file, is accepted (a fixed or rolling cron line works); any other before the file's first day, or one that would leave a gap, is refused with what to do.
• A day through recordedTo is one the archive has recorded and is fetched once. The archive can re-record a past day after a feed repair; the README says how to fetch a range again.

The Python library's matching PR follows the same rules and messages.

Verification

• npm test: 300 passed. npm run lint, npm run typecheck, prettier --check ., npm run build and npm run test:package are clean.
• test/mutation/run.mjs: 45/45 killed.
• Interruption is tested by abandoning a run mid-page, as a kill would, and resuming it (NDJSON and CSV, first run and extension).
• Live, against Bellewaerde (one small park) and Space Mountain:
  • a keyed four-page run was stopped with SIGINT after its first page: exit 130, state at the page boundary, lock released; the rerun resumed there and the file came out byte for byte identical to an uninterrupted run (3,270 rows, no duplicated (entityId, date));
  • an 8.3.1 anonymous file was downloaded again and stopped at recordedTo; running it again reported up to date with no history request;
  • --since/--until wrote only those days; an earlier --since was refused with the file untouched; --since after --until exited 2 before any request;
  • changeRows().opening for Space Mountain on 2026-09-26 is OPERATING at midnight, as in the capture.

🤖 Generated with Claude Code