CEX HFT: define latency measurement and evidence guideline

[proerror77]

Change contract

Publish one canonical, code-audited contract for CEX HFT timestamp semantics, comparable latency benchmarks, execution spans, evidence levels, and outcome validation.

Closes #394. Parent PRD: #350.

Out of scope

• Runtime behavior changes
• Live trading enablement
• Exchange deployment or latency claims
• Fixed venue SLOs without measured evidence

Dependency / merge order

None. This documentation baseline should merge before follow-up runtime issues #395-#399 are promoted.

Focused validation

• git diff --check 9d7b2cca23b05588ed5608afc9926ad29cecd5b4...HEAD
• README link resolves to the guideline
• Code anchors re-read at audit SHA 9d7b2cca23b05588ed5608afc9926ad29cecd5b4
• Standards review: 0 findings
• Spec review: 0 findings

Review size

2 changed files, 196 non-generated lines; below the 25-file / 750-line split threshold.

Rollout / rollback impact

Documentation only. Rollout has no runtime effect; rollback is reverting this PR. Live remains disabled.

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guideline for measuring and interpreting CEX HFT latency.
  • Documented timestamp standards, benchmark requirements, execution evidence, outcome validation, and review criteria.
  • Added the latency measurement guideline to the canonical documentation links.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 43 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 Plus

Run ID: 874766ae-911a-432c-88c1-8d7a76cafc0d

📥 Commits

Reviewing files that changed from the base of the PR and between 423f22d and a1302de.

📒 Files selected for processing (1)

• rust_hft/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md

📝 Walkthrough

Walkthrough

Adds a canonical CEX HFT latency measurement guideline covering timestamp semantics, benchmark protocols, execution evidence, outcome validation, audit findings, and review gates, and links it from the documentation index.

Changes

CEX HFT latency measurement guideline

Layer / File(s)	Summary
Timestamp and public-feed measurement contracts rust_hft/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md	Defines canonical venue and local timestamps, clock rules, comparison boundaries, public-feed formulas, and metric limitations.
Benchmark and execution evidence requirements rust_hft/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md	Specifies benchmark metadata, clock error bounds, sample sufficiency, distinct execution spans, evidence levels, and outcome validation.
Audit snapshot and review checklist rust_hft/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md, rust_hft/docs/README.md	Documents audited instrumentation gaps, review gates, and a canonical documentation link.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related issues

• #395: The guideline separates venue and local timestamp semantics, matching the issue’s objective of type-safe separation between exchange and receive-time values.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the PR’s main change: defining the CEX HFT latency measurement and evidence guideline.
Description check	✅ Passed	The description covers the change contract, out-of-scope work, dependency order, validation, rollout, and size notes.
Linked Issues check	✅ Passed	The guideline appears to satisfy #394 by defining canonical timestamps, benchmark rules, evidence levels, and outcome validation.
Out of Scope Changes check	✅ Passed	The diff is documentation-only and stays within the stated scope, with no unrelated runtime or deployment changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cex-latency-guideline

---

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: 3

🤖 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/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md`:
- Around line 3-6: Update the guideline introduction to replace the unexplained
“Monday” reference with the canonical project or system name used by the
repository; if “Monday” is intentionally a defined entity, add a concise
definition before its first use.
- Around line 111-113: Update the intent-to-NIC latency guidance to define how
intent_ts and kernel_tx_ts are mapped into a common clock domain, including the
conversion error bound. If no valid paired-clock conversion is available,
require reporting intent-to-write_return and kernel transmit spans separately
rather than subtracting timestamps from different domains.
- Around line 160-181: Update every code anchor path in the “Code anchors”
section to prefix repository-relative paths with rust_hft/, including
market-core, data-pipelines, apps, tools, and infra-services references. Keep
symbol names unchanged and ensure all links resolve unambiguously from the
document’s current repository context.

🪄 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 Plus

Run ID: 00a75582-e0fe-4787-91a9-c3c7812aeb25

📥 Commits

Reviewing files that changed from the base of the PR and between 9d7b2cc and 423f22d.

📒 Files selected for processing (2)

• rust_hft/docs/README.md
• rust_hft/docs/architecture/CEX_HFT_LATENCY_MEASUREMENT_GUIDELINE.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 423f22d1ed

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