Skip to content

fix(prediction): bind settlement splits to time cohorts - #143

Merged
proerror77 merged 10 commits into
mainfrom
codex/polymarket-event-settlement-contract
Jul 19, 2026
Merged

proerror77 merged 10 commits into
mainfrom
codex/polymarket-event-settlement-contract

Conversation

@proerror77

@proerror77 proerror77 commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Change contract

Bind the governed BTC/SOL five-minute settlement trainer and LoopRun settlement verdict to one mission-pinned wall-clock boundary so complete event lifetimes, rather than only decision rows or event IDs, are separated across train and validation.

Out of scope

  • Token-side UP/DOWN repricing, fill, slippage, and markout evaluators
  • Separating the legacy full-sample promotion report and execution matrices; this PR protects the governed LoopRun verdict, not dry-run promotion readiness
  • Full-update-tick collection or changes to the stable one-second L2 collector
  • Governed 15-minute or one-hour mission/data expansion
  • ECS, runtime execution, Paper/Shadow, or live-trading changes
  • Architecture/checklist/TODO documentation, split into stacked PR docs(prediction): define event cohort architecture #144

Dependency or merge order

The code contract is based directly on main and is independently reversible. Documentation PR #144 is stacked on this branch because it describes the new schema and cohort behavior. Merge #143 first, retarget #144 to main, rerun its current-head checks, then merge #144.

Focused validation

  • Scope guardrail: 9 files and 747 non-generated changed lines against main.
  • rustfmt --edition 2021 --check on touched Rust source files
  • jq -e on both mission templates
  • git diff --check
  • Checked-in .example.json missions deliberately retain an invalid zero cohort sentinel and placeholder snapshot ID; a targeted test proves full mission validation rejects them until an operator selects real immutable inputs.
  • Wrapper counterexample exercises the real RustProcessEvaluator::command(request) path and proves the mission boundary reaches the precompiled evaluator argv.
  • Governed baseline and candidate evaluation fail closed when the boundary is missing, invalid, outside the snapshot range, lacks an event horizon, or presents a non-300-second window under the governed five-minute policy.
  • Settlement walk-forward counterexamples purge an episode crossing the mission boundary and prove later rolling windows cannot train on post-boundary episodes; generic factor/token paths retain their existing split behavior.
  • Burn trainer counterexamples reject: a training event ending at the boundary; combined nanosecond/millisecond/second truncation across the boundary; validation event starting before the boundary; dataset boundary drift from the mission; mixed-horizon rows; and a registry-rehashed v2 manifest without the required boundary.
  • Existing late-official-label and event-ID overlap tests remain in force.
  • Linux Rust tests and clippy run in GitHub CI; no local Cargo build/test was used.

Rollout / rollback impact

Research-only. Prediction mission schema moves from v1 to v2 and requires time_cohort_boundary_ms; binary model manifest schema moves from v2 to v3 and seals that mission boundary into the dataset contract/hash and model manifest. Existing mission v1/model v2 artifacts fail closed and require a new mission/retraining; no boundary is inferred. The checked-in examples remain intentionally non-runnable until their zero boundary and REPLACE_WITH... snapshot placeholder are replaced in a reviewed immutable mission revision. The prediction policy snapshot ID changes because the governed evaluator now consumes the boundary. Roll back by reverting this PR; no data, collector, ECS, execution, or live state is mutated.

Architecture note

One symbol × horizon remains one research task, one event root remains one episode with two independent token LOBs, and settlement probability remains separate from future token execution heads. The current settlement baseline continues to use the retained one-second L2 snapshots.

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@proerror77, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 18 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 924991f8-daa7-440c-a917-b72cb968ecca

📥 Commits

Reviewing files that changed from the base of the PR and between 7221a6e and fb5e326.

📒 Files selected for processing (6)
  • rust_hft/prediction-markets/config/research_missions/polymarket-btc-5m.example.json
  • rust_hft/prediction-markets/config/research_missions/polymarket-sol-5m.example.json
  • rust_hft/prediction-markets/crates/ploy-research/src/bin/monday-prediction-evaluator.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/lib.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/model/supervised/mod.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/prediction_loop.rs
📝 Walkthrough

Walkthrough

The PR upgrades prediction missions to v2 with a required time cohort boundary, forwards that boundary through evaluator processes, applies cohort-aware walk-forward purging, and seals the boundary into binary dataset manifests and partition validation.

Changes

Prediction time-boundary governance

Layer / File(s) Summary
Mission contract and evaluator wiring
rust_hft/prediction-markets/crates/ploy-research/src/prediction_loop.rs, rust_hft/prediction-markets/config/research_missions/*, rust_hft/prediction-markets/crates/ploy-research/src/bin/monday-prediction-research.rs
Mission schema v2 adds and validates time_cohort_boundary_ms; example missions include the field, and subprocess commands forward it to the evaluator.
Cohort-aware settlement evaluation
rust_hft/prediction-markets/crates/ploy-research/src/factors_v2.rs, rust_hft/prediction-markets/crates/ploy-research/src/bin/monday-prediction-evaluator.rs, rust_hft/prediction-markets/crates/ploy-research/src/lib.rs
Settlement evaluation constructs validated time cohorts and excludes crossing or post-boundary events from walk-forward slices, with corresponding tests and report metadata.
Manifest-sealed binary dataset boundary
rust_hft/prediction-markets/crates/ploy-research/src/model/supervised/burn_binary.rs, rust_hft/prediction-markets/crates/ploy-research/src/model/supervised/mod.rs
Binary dataset schema v3 stores the shared boundary, materializes event timestamps, enforces strict train/validation placement, and rejects manifests without the boundary.
Governance documentation and operating checklist
docs/architecture/PREDICTION_MARKETS.md, rust_hft/prediction-markets/docs/ALPHA_FACTOR_SEARCH_CICD.md, rust_hft/prediction-markets/docs/CRYPTO_LOB_ML_DEPLOY_CHECKLIST.md, rust_hft/prediction-markets/tasks/todo.md
Documentation describes mission identity, boundary sealing, supported horizons, fail-closed examples, and remaining token-market research tasks.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Mission
  participant ResearchLauncher
  participant Evaluator
  participant WalkForward
  Mission->>ResearchLauncher: provide time_cohort_boundary_ms
  ResearchLauncher->>Evaluator: pass boundary CLI argument
  Evaluator->>Evaluator: validate boundary and event window
  Evaluator->>WalkForward: provide SettlementProbabilityTimeCohort
  WalkForward-->>Evaluator: return purged settlement slices
Loading

Possibly related PRs

  • proerror77/monday#41: Introduced the governed Burn binary lane and its fail-closed dataset contract, which this change extends with a sealed time boundary.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 48.72% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title matches the main change: binding settlement behavior to a mission time cohort boundary.
Description check ✅ Passed The description covers the required contract, out-of-scope, merge order, validation, rollout, and scope notes, with only minor heading mismatches.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/polymarket-event-settlement-contract

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

#[test]
fn evaluator_process_is_the_precompiled_monday_binary() {
fn evaluator_command_forwards_the_mission_cohort_boundary() {
let root = std::env::temp_dir().join(format!(
@proerror77
proerror77 marked this pull request as ready for review July 19, 2026 01:58

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7221a6e664

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
rust_hft/prediction-markets/crates/ploy-research/src/factors_v2.rs (1)

7378-7441: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Cohort-aware purge logic is correct; consider extracting the shared event-end lookup.

Verified against settlement_time_cohort_purges_crossing_and_post_boundary_training_events: crossing/post-boundary events are correctly excluded from both train and test, and both filters fail closed on any missing/overflowing timestamp arithmetic. The test_rows and train_rows filters each re-derive event_ends.get(row.event_id.as_str()).and_then(Option::as_ref), duplicating the lookup already done in the ends_in closure a few lines above — a small helper (e.g. event_end_of(row)) would remove the repetition without changing behavior.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rust_hft/prediction-markets/crates/ploy-research/src/factors_v2.rs` around
lines 7378 - 7441, Extract the repeated event-end lookup in
event_disjoint_walk_forward_slices into a shared helper such as
event_end_of(row), returning the referenced event end from event_ends. Reuse
this helper in ends_in and both train_rows/test_rows cohort filters, preserving
the current fail-closed handling and behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@rust_hft/prediction-markets/crates/ploy-research/src/factors_v2.rs`:
- Around line 7378-7441: Extract the repeated event-end lookup in
event_disjoint_walk_forward_slices into a shared helper such as
event_end_of(row), returning the referenced event end from event_ends. Reuse
this helper in ends_in and both train_rows/test_rows cohort filters, preserving
the current fail-closed handling and behavior.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e81d7c5d-0224-4cae-ae42-a786f4a4da56

📥 Commits

Reviewing files that changed from the base of the PR and between 05199d5 and 7221a6e.

📒 Files selected for processing (13)
  • docs/architecture/PREDICTION_MARKETS.md
  • rust_hft/prediction-markets/config/research_missions/polymarket-btc-5m.example.json
  • rust_hft/prediction-markets/config/research_missions/polymarket-sol-5m.example.json
  • rust_hft/prediction-markets/crates/ploy-research/src/bin/monday-prediction-evaluator.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/bin/monday-prediction-research.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/factors_v2.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/lib.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/model/supervised/burn_binary.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/model/supervised/mod.rs
  • rust_hft/prediction-markets/crates/ploy-research/src/prediction_loop.rs
  • rust_hft/prediction-markets/docs/ALPHA_FACTOR_SEARCH_CICD.md
  • rust_hft/prediction-markets/docs/CRYPTO_LOB_ML_DEPLOY_CHECKLIST.md
  • rust_hft/prediction-markets/tasks/todo.md

@proerror77

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@proerror77

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@proerror77

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@proerror77
proerror77 merged commit ecbc49a into main Jul 19, 2026
25 of 26 checks passed
@proerror77
proerror77 deleted the codex/polymarket-event-settlement-contract branch July 19, 2026 02:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants