Journal-based linked chains, timestamp indexes, U128/result codes, module split, CI and repo hygiene

[devin-ai-integration]

Summary

Implements the review items 4–17 from the repo improvement pass (perf, code quality, CI, hygiene). Items 1–3 (Zig differential harness, 128-byte wire codecs, C-ABI adapter) are not in this PR; Result_code is the first step toward them.

Core (ocam/src)

state_machine.ml is split into U128, Types, Result_code, Timeline, Ledger, State_machine. The public State_machine interface is unchanged apart from additions (module U128, module Result_code; record types are re-exported as type account = Types.account = {...}).

• Linked chains no longer clone the whole state. Ledger.transact records undo closures for each mutation while a chain runs; a failed/open chain replays them in reverse. Rollback cost is proportional to the chain, not the ledger.

  val Ledger.transact : t -> (unit -> 'a) -> 'a * (unit -> unit)   (* result, rollback *)

• Indexed queries. Timeline is an append-only array of strictly increasing (timestamp, value) pairs with binary-searched inclusive range reads (to_seq_in_range ~minimum ~maximum ~reversed). Ledger.t keeps accounts_by_timestamp, transfers_by_timestamp, per-account account_transfers / account_history, and a pending_by_expiry map, so query_accounts / query_transfers / get_account_transfers / get_account_balances / expire_pending_transfers no longer scan+sort every stored object. Commit-order timestamps are now a documented precondition (Timeline.append raises on non-increasing timestamps).
• U128 completed: mul, div_rem, shifts, of_string(_opt), to_hex_string, int/int64 conversions; to_string is now always decimal; add/sub/mul return Error on overflow/underflow instead of wrapping.
• Result_code: numeric account_to_code / transfer_to_code / *_of_code matching the pinned state_machine.zig enum values (created_code = 0xffff_ffff). Where the OCaml variant is coarser than upstream, *_codes returns the set of upstream codes and *_to_code returns None.
• Dropped the unused base dependency; the core is Stdlib-only.

Tests / bench

• New u128_test, result_code_test, timeline_test (unit + QCheck), plus test_failed_chain_leaves_no_index_entries asserting rollback restores tables, indexes, history, expiry, and commit timestamp.
• Benchmark now has six workloads: posted, pending+post/void, linked, failing-linked (rollback), indexed queries, expiry.

CI / hygiene / docs

• CI: setup-ocaml@v3 with dune-cache, opam lint, dune build @fmt; coverage workflow enforces a 75% minimum (measured: 79.3%).
• CI was red on trunk since the OxCaml migration because the unpinned OxCaml opam overlay moved on: oxcaml-compiler.5.2.0minus31 can no longer install odoc, ocamlformat.0.26.2+ox1 conflicts, and bisect_ppx never built against OxCaml's patched ppxlib. The OxCaml job now uses 5.2.0minus39 + ocamlformat.0.26.2+ox2; docs and coverage run in the upstream-OCaml 5.2 job (the core is Stdlib-only, so the numbers are identical). bisect_ppx is no longer a declared package dependency.
• Removed zoom-out.*, copied ocam/.github/* TigerBeetle workflows, .deepsource.toml.
• Added CONTRIBUTING.md (incl. jj setup), root LICENSE (Apache-2.0), package metadata in dune-project; updated README, doc/, OCAML_REWRITE.md, BENCHMARK_COMPARISON.md.
• state_machine_property_test.ml changes are formatter-only (dune fmt), needed now that CI enforces formatting.

Verification

Locally on a standard OCaml 5.2.1 switch (the OxCaml compiler fails to build on my machine with cp: ... are the same file in Makefile.common-ox:234): dune build, dune build @doc, dune runtest, dune build @bench (+ ran the bench), dune build @fmt, opam lint, Bisect coverage 79.3%.
On CI: the OxCaml checks job (build, tests, bench, fmt, lint) and the upstream-OCaml coverage job (docs + coverage) both pass.

Link to Devin session: https://app.devin.ai/sessions/c6013392416c4513bc299ebd01acd9ff
Open in Devin Desktop: https://app.devin.ai/desktop/session/c6013392416c4513bc299ebd01acd9ff?variant=devin
Requested by: @gpu004

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[deepsource-io]

DeepSource Code Review

We reviewed changes in c542600...f4a7cc9 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
Secrets		Sep 25, 2026 6:52a.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.