Skip to content

Replace ledger state machine with OCaml implementation - #3

Closed
gpu004 wants to merge 11 commits into
codex/rewrite-ledger-state-machinefrom
codex/ocaml-ledger-rewrite
Closed

Replace ledger state machine with OCaml implementation#3
gpu004 wants to merge 11 commits into
codex/rewrite-ledger-state-machinefrom
codex/ocaml-ledger-rewrite

Conversation

@gpu004

@gpu004 gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner

Stacked on #2.

Adds the OCaml ledger state machine and its interface, property and unit tests, workflow changes, documentation, and paired Zig/OCaml benchmark material. It also carries the README cleanup that is unrelated to the copied TigerBeetle source.

The final tree is unchanged from the original PR before this split.

Note

Replace Zig ledger state machine with a full OCaml reimplementation

  • Adds a complete OCaml reimplementation of TigerBeetle's ledger state machine in ocam/src/state_machine.ml, covering account/transfer creation, pending/post/void/expiry, linked-chain atomicity, queries, and account balance history.
  • Exposes the public API via ocam/src/state_machine.mli as the tigerbeetle_ocaml.state_machine dune library, including a U128 module for 128-bit arithmetic with overflow/underflow signaling.
  • Adds deterministic unit tests in ocam/test/state_machine_test.ml and QCheck property tests in ocam/test/state_machine_property_test.ml covering balance conservation, idempotency, atomicity, and expiry.
  • Adds a benchmark in ocam/bench/state_machine_bench.ml and a comparison script that runs both the OCaml and pinned Zig state machines and prints throughput and allocation metrics side-by-side.
  • Updates CI workflows to use the ocam/ directory and wrap dune commands with opam exec --.

Macroscope summarized f2869b0.

@coderabbitai

coderabbitai Bot commented Jul 13, 2026

Copy link
Copy Markdown

Warning

Review limit reached

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

Next review available in: 59 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: 119075f7-03e3-4f52-af7d-7a8c5380742c

📥 Commits

Reviewing files that changed from the base of the PR and between 769d2ba and f2869b0.

📒 Files selected for processing (26)
  • .github/workflows/tb_ocaml_ci.yml
  • .github/workflows/tb_ocaml_coverage.yml
  • .gitignore
  • AGENTS.md
  • BENCHMARK_COMPARISON.md
  • README.md
  • bench/test_options.zig
  • bench/vsr_options.zig
  • doc/README.md
  • doc/architecture.md
  • ocam/.ocamlformat
  • ocam/OCAML_REWRITE.md
  • ocam/bench/dune
  • ocam/bench/run_state_machine_comparison.sh
  • ocam/bench/state_machine_bench.ml
  • ocam/dune-project
  • ocam/src/dune
  • ocam/src/state_machine.ml
  • ocam/src/state_machine.mli
  • ocam/test/dune
  • ocam/test/state_machine_property_test.ml
  • ocam/test/state_machine_test.ml
  • ocam/tigerbeetle_ocaml.opam
  • tigerbeetle_state_machine_bench.zig
  • zoom-out.html
  • zoom-out.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/ocaml-ledger-rewrite

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.

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

cursor review

@cursor

cursor Bot commented Jul 13, 2026

Copy link
Copy Markdown

Skipping Bugbot: Bugbot is disabled for this repository. Visit the Bugbot dashboard to update your settings.

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

cursor review

@cursor

cursor Bot commented Jul 13, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

cursor review

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

@macroscope-app review

@macroscopeapp

macroscopeapp Bot commented Jul 13, 2026

Copy link
Copy Markdown

Manual reviews triggered for commit f2869b0:

All prior checks · these links stay valid even if you push more commits.

@macroscopeapp

macroscopeapp Bot commented Jul 13, 2026

Copy link
Copy Markdown

Review started! Results will be posted as check runs when complete.

Comment thread tigerbeetle_state_machine_bench.zig Outdated
Comment thread ocam/src/state_machine.ml
Comment thread ocam/src/state_machine.ml
Comment thread ocam/src/state_machine.ml
@macroscopeapp

macroscopeapp Bot commented Jul 13, 2026

Copy link
Copy Markdown

Approvability

Verdict: Needs human review

Unable to check for correctness in f2869b0. This PR introduces a complete new OCaml ledger state machine implementation (~1000+ lines of core logic), which constitutes a significant new feature requiring human review. Additionally, there are unresolved HIGH severity findings regarding balancing transfer sentinel handling and timeout overflow checking that should be addressed.

You can customize Macroscope's approvability policy. Learn more.

@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review
@codex review
cursor review
@macroscope-app review
@deepsourcebot review

@coderabbitai

coderabbitai Bot commented Jul 13, 2026

Copy link
Copy Markdown

@tusharhqq I'll go ahead and review the PR now. Note that I can only act on the @coderabbitai mention — the other tags (@codex, cursor, @macroscope-app, @deepsourcebot) are for separate tools/bots and aren't something I can trigger or respond to.

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

@macroscopeapp

macroscopeapp Bot commented Jul 13, 2026

Copy link
Copy Markdown

Review started! Results will be posted as check runs when complete.

@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: b10615d2d2

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

Comment thread ocam/src/state_machine.ml Outdated
Comment thread ocam/src/state_machine.ml
Comment thread ocam/bench/run_state_machine_comparison.sh Outdated
@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review
@codex review
cursor review
@macroscope-app review
@deepsourcebot review

@coderabbitai

coderabbitai Bot commented Jul 13, 2026

Copy link
Copy Markdown

@tusharhqq I'll trigger another review for you. As mentioned before, I can only respond to @coderabbitai mentions — the other tools (@codex, cursor, @macroscope-app, @deepsourcebot) are separate integrations that I have no control over, so you'll need to check with those tools/bots directly if you want their review as well.

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

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

@macroscopeapp

macroscopeapp Bot commented Jul 13, 2026

Copy link
Copy Markdown

Review started! Results will be posted as check runs when complete.

@chatgpt-codex-connector

Copy link
Copy Markdown

To use Codex here, create a Codex account and connect to github.

@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: f2869b0b28

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

Comment thread ocam/src/state_machine.ml
| None ->
replace_state state trial;
results
| Some failure ->

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve transient failures across linked rollbacks

When a linked transfer chain fails, the state mutations from trial must roll back, but transient failures still consume the failing transfer ID; the pinned TigerBeetle tests cover this with exceeds_debits/exceeds_credits inside linked chains and expect a later retry to return id_already_failed. This branch discards the cloned failed_transfers table along with the balances, so a transfer ID that hit Transfer_debit_account_not_found, Transfer_exceeds_debits, etc. inside a failed linked chain can be reused successfully.

Useful? React with 👍 / 👎.

Comment thread ocam/src/state_machine.ml
Comment on lines +851 to +853
then Account_linked_event_chain_open
else Account_linked_event_failed)
})

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Validate open linked suffixes before masking results

For a trailing open linked chain, this branch never executes the requests, so an earlier real failure in that open suffix is hidden as *_linked_event_failed. The pinned corpus has an open chain where a middle account fails with exists_with_different_flags and only the final event reports linked_event_chain_open; with the current shortcut, clients lose the actual validation result and any required transient-failure bookkeeping for transfer chains.

Useful? React with 👍 / 👎.

Comment thread ocam/src/state_machine.ml
| Error `Out_of_range -> error Account_imported_timestamp_out_of_range
| Error `Regressed -> error Account_imported_timestamp_must_not_regress
| Ok timestamp ->
let account = { request with timestamp } in

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Strip event-only flags before storing records

This stores request.flags unchanged, so accounts created with linked or imported keep those event-only bits in lookups and future idempotency comparisons. TigerBeetle clears LNK/IMP on stored records (for example, linked/imported account lookups in the pinned tests show no such flags), so retrying the same account without those request-only flags can incorrectly return Account_exists_with_different_flags; transfers have the same issue at their storage site.

Useful? React with 👍 / 👎.

@gpu004 gpu004 closed this Jul 13, 2026
@gpu004

gpu004 commented Jul 13, 2026

Copy link
Copy Markdown
Owner Author

Superseded by #4, which is now merged. PR #4 retains the maintained implementation and incorporates the useful unique benchmark work from this PR; the invalid native fixture/runner was intentionally not carried forward because it did not match the pinned TigerBeetle commit sequence.

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.

1 participant