feat(research): materialize aggregate trade flow

[proerror77]

Change contract

Materialize authenticated aggregate-trade count, volume, notional, and signed flow into each PIT LOB row so the declared trade modality is actually consumable by Spot and USD-M HFT research.

Issue relationship

Refs #779

Out of scope

ResearchSnapshot V2 fee, funding/OI, and realized latency evidence binding; those remain in the next stacked rollout unit.

Dependencies and merge order

Depends on #781. Merge #781 first, then retarget this PR to main.

Focused validation

• Linux target test compilation passed.
• Existing strict modality rejection remains.
• Fixture proves one authenticated aggregate trade appears as count 1, base volume 2, quote volume 201, and signed imbalance 1.

Rollout and rollback

No runtime mutation. Rollback is the single commit; current production collectors and uploaders are untouched.

Scope exception

None.

Summary by CodeRabbit

• New Features
  • PIT materialization now incorporates aggregate trade data alongside limit order book snapshots.
  • Added base volume, trade count, quote volume, and signed-flow imbalance metrics for each book-sample interval.
  • Generated records now identify both order book and trade-tick data modalities.
• Improvements
  • Trade data is filtered by symbol and aggregated consistently within sampling intervals.
  • Source revisions are explicitly tracked when generating materialized records.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7c582bef-2126-402b-9184-7543f3d49f5e

📥 Commits

Reviewing files that changed from the base of the PR and between a15880c and aa0aa8d.

📒 Files selected for processing (2)

• agent-worktree.yml
• rust_hft/tools/collector/src/bin/lob-pit-materializer.rs

---

📝 Walkthrough

Walkthrough

The worktree contract now targets LOB PIT trade features. PIT materialization filters aggregate trades by symbol and interval, computes trade features, emits both LOB and TradeTick modalities, and validates the output.

Changes

PIT trade-feature materialization

Layer / File(s)	Summary
Update the worktree contract agent-worktree.yml	The worktree declaration now uses the lob-pit-trade-features owner, path, branch, base SHA, dependency, and permitted files.
Add aggregate-trade features to PIT rows rust_hft/tools/collector/src/bin/lob-pit-materializer.rs	Materialization receives aggregate trades and market-specific source revisions. It filters trades by symbol and interval, computes trade count, base volume, quote volume, and signed-flow imbalance, and declares Lob and TradeTick modalities. Fixtures and assertions validate the new values.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Materializer
  participant AggregateTrades
  participant PITRows
  Materializer->>AggregateTrades: Filter by symbol and sample interval
  AggregateTrades-->>Materializer: Return trade aggregates
  Materializer->>PITRows: Emit LOB and TradeTick features

Loading

Possibly related issues

• proerror77/monday/773: Concerns PIT materialization that binds LOB data with aggregate-trade modalities.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: materializing aggregate trade flow for research.
Description check	✅ Passed	The description covers the change contract, issue relationship, scope, dependencies, validation, rollback, and scope exception.
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.

✨ 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/lob-pit-trade-features

---

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

[proerror77]

@codex review exact head 73e4ae4

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 73e4ae425a

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

[proerror77]

@codex review exact head 547d4f0

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 547d4f0cc4

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

[proerror77]

@codex review exact head aa0aa8d

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: aa0aa8d899

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