research: build snapshots from verified market artifacts

[proerror77]

Change contract

Build one deterministic ResearchSnapshot from externally anchored VerifiedBinanceMarketTape and VerifiedPolymarketEvidenceSet handles, deriving and validating the canonical artifact audit internally before any research projection or label binding.

Out of scope

• Artifact acquisition or download
• Snapshot CLI flag wiring
• External audit JSON or digest inputs
• Multi-hour Polymarket aggregation
• Evaluator execution, deployment, and live trading

Dependency or merge order

Base: main after #140 and #141. Merge this adapter before the focused verified-artifact CLI and cloud E2E layer. No stacked base PR remains.

Focused validation

• Unresolved factor observations are generated without labels, then bound only by exact event and UP/DOWN token identity to official outcomes.
• Contract availability and four source-freshness flags fail closed before label binding.
• Official true and false outcomes remain distinct and preserve the official availability timestamp.
• Unknown event/token, early settlement, wrong winning token, and unavailable/stale-only observations fail closed.
• PM-book cadence now fails during builder option validation when it is coarser than the quote-age gate; the existing coverage counterexample test enforces the same full-depth invariant.
• Canonical artifact audit is built internally; Polymarket projection receives its governed maximum source delay.
• PM book provenance records only verified-artifact projection rows; hot/archive counters remain zero.
• Typed Polymarket verifier/set invariants already prove exact five-minute contracts; the adapter does not duplicate that trust-boundary validation.
• Scope is 6 files and 746 changed lines, below the 750-line guardrail; git diff --check is clean and no new rustfmt::skip was added.
• Final policy hash independently recomputed from 36 source files: sha256:c7ccfd3bd8fc0ab7cd1444768cfe8b53b95baefc8973b47f34d5156b31d234c0.
• No local Cargo/rustfmt was used; GitHub Linux CI is authoritative.

Rollout / rollback impact

Research-only opt-in API. Existing database snapshot compilation and live execution remain unchanged. Rollback is a single PR revert before the dependent CLI layer.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

The PR adds a verified-artifact ResearchSnapshot builder that validates Binance and Polymarket evidence, binds official outcomes, constructs manifest metadata, and exposes the builder publicly. It also adds settlement-binding tests and updates research mission policy identifiers.

Verified snapshot pipeline

Layer / File(s)	Summary
Verified artifact snapshot builder rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs, rust_hft/prediction-markets/crates/ploy-research/src/lib.rs, rust_hft/prediction-markets/crates/ploy-research/src/factors.rs, rust_hft/prediction-markets/config/research_missions/*	Verified Binance and Polymarket artifacts are validated and projected into factor observations, book snapshots, settlement outcomes, and a populated research manifest; the builder is re-exported and mission policy identifiers are updated.
Settlement binding and migration validation rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs, rust_hft/prediction-markets/tasks/todo.md	Official outcome lookup is available without feature or test gating, with tests covering exact settlement binding, freshness filtering, clock availability, and token consistency; the snapshot CLI and E2E migration task is recorded.

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

Sequence Diagram(s)

sequenceDiagram
  participant VerifiedBinanceMarketTape
  participant VerifiedPolymarketEvidenceSet
  participant build_research_snapshot_from_verified_artifacts
  participant ResearchSnapshotManifest
  participant ResearchSnapshot
  VerifiedBinanceMarketTape->>build_research_snapshot_from_verified_artifacts: provide verified Binance tape
  VerifiedPolymarketEvidenceSet->>build_research_snapshot_from_verified_artifacts: provide verified Polymarket evidence
  build_research_snapshot_from_verified_artifacts->>ResearchSnapshotManifest: validate artifacts and construct audit metadata
  build_research_snapshot_from_verified_artifacts->>ResearchSnapshot: build updates, outcomes, factors, and book snapshots
  ResearchSnapshotManifest-->>ResearchSnapshot: attach manifest and row counts

Loading

Possibly related PRs

• proerror77/monday#136: Introduces the verified Polymarket evidence consumed by the new snapshot builder.
• proerror77/monday#137: Introduces verified Binance projection types used by snapshot construction.
• proerror77/monday#139: Adds the shared verified-artifact audit construction used by the snapshot builder.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 is concise and accurately summarizes the main change: building snapshots from verified market artifacts.
Description check	✅ Passed	The description covers the main template sections and change details; only the optional Scope exception section is omitted.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/polymarket-verified-snapshot-adapter

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs`:
- Around line 539-548: In the EventDiscovered update construction, set
resolved_up_won to None so pre-settlement replay cannot expose the official
outcome. Preserve label attachment through bind_and_filter_verified_observations
after settlement.available_at.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6dd64a93-df8a-45cc-b363-c0e6d97b107d

📥 Commits

Reviewing files that changed from the base of the PR and between cbb37c5 and 810341b.

⛔ Files ignored due to path filters (1)

• rust_hft/prediction-markets/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (6)

• rust_hft/prediction-markets/crates/ploy-research/Cargo.toml
• rust_hft/prediction-markets/crates/ploy-research/prediction-policy-dependencies.linux.sha256
• rust_hft/prediction-markets/crates/ploy-research/prediction-policy-dependencies.linux.txt
• rust_hft/prediction-markets/crates/ploy-research/src/lib.rs
• rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs
• rust_hft/prediction-markets/tasks/todo.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 810341b1cb

ℹ️ 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]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs`:
- Around line 193-198: Update the option validation containing the positive
cadence checks to also require options.pm_book_sample_secs not exceed
options.max_quote_age_secs. Preserve the existing validation error behavior and
reject invalid manifests during builder validation before snapshot creation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 12dcbf6b-a569-4702-bf6f-e29062b258b2

📥 Commits

Reviewing files that changed from the base of the PR and between 810341b and ff109f4.

📒 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/factors.rs
• rust_hft/prediction-markets/crates/ploy-research/src/lib.rs
• rust_hft/prediction-markets/crates/ploy-research/src/research_snapshot.rs
• rust_hft/prediction-markets/tasks/todo.md

🚧 Files skipped from review as they are similar to previous changes (1)

• rust_hft/prediction-markets/crates/ploy-research/src/lib.rs