[EmergentMonk]

Historical preservation release

Adds eight racing-history exhibits to the existing three-year MELBCUPSIM archive (11 total years, 1861–2025).

Complete finishing orders: 1988 Empire Rose (22 runners); 2005 Makybe Diva (24 runners).

Sourced podium showcases: 1861 Archer (17 historical starters), 1930 Phar Lap (15), 1983 Kiwi (24), 1987 Kensei (21), 1989 Tawrrific (23), 1990 Kingston Rule (24). Only the verified first three are depicted; other competitors are deliberately not fictionalised.

Implementation: dynamic archive selection, visible FULL/TOP 3 markers, historical field-size provenance in exported receipts, engine rejection of what-if simulations based on incomplete fields, and regression tests. Existing 2023–25 models untouched.

Research honesty: 1988 complete ordering comes from a published 22-place secondary table; VRC independently corroborates first/second but full source reconciliation remains an open archival task. See README for all evidence links and limitations. The 3200m oval is still a schematic animated exhibit, not original race telemetry or period track geometry.

No gambling mechanics, dependencies or external runtime services.

Summary by Sourcery

Extend the simulator's historical Melbourne Cup archive back to 1861 while preserving provenance and preventing unsupported simulations of incomplete historical fields.

New Features:

• Expand the Melbourne Cup historical archive with eight exhibits spanning 1861–2005, including complete finishing orders for 1988 and 2005 and verified podium showcases for six additional years.
• Populate archive selection dynamically and clearly distinguish full-field records from top-three historical exhibits in the interface.

Bug Fixes:

• Prevent what-if simulations from being created for historical records with incomplete fields, avoiding fictional full-field interpretations.

Enhancements:

• Include field coverage, historical field size, and source provenance in exported race receipts.
• Clarify archival limitations, synthetic animation, and historical track-geometry caveats in the user-facing documentation.

Documentation:

• Document the expanded archive, evidence sources, coverage guarantees, and known source limitations.
• Update the archival roadmap and invariants to define partial-field behavior and provenance requirements.

Tests:

• Add regression coverage for complete 1988 and 2005 archives, deterministic replay, and rejection of what-if simulations for podium-only records.

[sourcery-ai]

Sorry @EmergentMonk, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 2 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-01T05:32:37.232664Z	5029901	PR opened
🔒 Security Review	✅ Completed 2026-11-01T05:32:49.218606Z	5029901	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sourcery-ai]

Reviewer's Guide

The PR extends the deterministic historical archive from three years to 11 spanning 1861–2025, models partial historical evidence honestly as TOP 3 exhibits, adds complete 1988 and 2005 orders, and wires coverage-aware selection, UI messaging, receipt provenance, engine safeguards, documentation, and regression tests without changing the legacy 2023–25 simulation models.

Sequence diagram for partial-field replay protection

sequenceDiagram
    actor User
    participant UI as Replay UI
    participant Engine as Race engine
    participant Archive as ARCHIVE
    User->>UI: Select podium archive year
    UI->>Archive: getArchive(year)
    Archive-->>UI: coverage podium and fieldSize
    UI->>UI: Disable what-if option
    User->>Engine: buildRace(mode, year)
    Engine->>Archive: getArchive(year)
    Archive-->>Engine: podium archive
    alt mode is whatif
        Engine-->>User: RangeError: What-if requires a complete recorded field
    else mode is replay
        Engine-->>UI: Fixed top-three replay with synthetic motion
    end

Loading

Entity relationship diagram for historical archive provenance

erDiagram
    ARCHIVE_RECORD {
        number year PK
        string coverage
        number fieldSize
        number recordedRunners
        string source
        string secondarySource
    }
    REPLAY_RECEIPT {
        number year
        string coverage
        number fieldSize
        number recordedRunners
        boolean syntheticMotion
    }
    ARCHIVE_RECORD ||--o{ REPLAY_RECEIPT : produces

Loading

Flow diagram for dynamic archive selection and replay display

flowchart TD
    Start[Load application] --> Populate[Populate archive selector from ARCHIVE]
    Populate --> Select[Select year]
    Select --> Coverage{Archive coverage}
    Coverage -->|full| Full[Show FULL marker and recorded runners]
    Coverage -->|podium| Top3[Show TOP 3 marker and historical field size]
    Full --> Mode[Configure replay or what-if]
    Top3 --> Replay[Force replay mode]
    Mode --> Run[Build deterministic race]
    Replay --> Run
    Run --> Receipt[Export coverage and field-size provenance]

Loading

File-Level Changes

Change	Details	Files
Expanded the archive with eight historically sourced exhibits while preserving the existing 2023–2025 records and documenting provenance and limitations.	Added six TOP 3 exhibits with explicit historical field sizes and two FULL finishing-order exhibits for 1988 and 2005. Documented evidence links, the 1988 secondary-source caveat, synthetic animation, and schematic track limitations. Recorded archive scope and future primary-source reconciliation work in project invariants and roadmap.	README.md docs/INVARIANTS.md docs/ROADMAP.md src/data.mjs
Implemented archive-driven UI selection and clear coverage labeling for full-field versus podium-only exhibits.	Populated the year selector dynamically from archive data and labeled entries FULL or TOP 3. Displayed field-size provenance and warnings that undisclosed runners are not depicted. Disabled what-if mode for partial archives and updated mode, HUD, canvas, and result messaging accordingly.	index.html src/main.mjs
Enforced historical coverage constraints in the simulation engine and exposed provenance in exported receipts.	Rejected what-if requests for podium-only archives at engine level, in addition to the UI restriction. Added coverage, recorded-runner count, historical field size, and secondary-source metadata to receipts.	src/engine.mjs
Added regression coverage for full-field preservation, partial-field semantics, determinism, and what-if rejection.	Verified 1988 and 2005 field sizes, leading finishers, complete place sequences, timeline length, and deterministic rebuilds. Verified all six TOP 3 archives retain their declared field sizes, depict only three finishers, and reject what-if simulations.	tests/engine.test.mjs

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.