refactor(cpp): ♻️ extract the row hash table from OperatorIndex

[robertodr]

🤖 AI text below 🤖

Stacked on #302 — review that first; this PR's diff against it is RowHashTable.h plus the OperatorIndex rewrite.

Summary

Second of five PRs carved out of #226. OperatorIndex carries two things that have nothing to do with each other: a keyless open-addressing hash table, and the packed row storage the table indexes into. A second row backend is coming, and it needs the table and not the rows, so the table moves out first, on its own, with no behaviour change.

RowHashTable is the table alone — power-of-two slots, linear probing, load factor 0.7, a 32-bit folded hash kept beside each slot as an equality pre-filter. It stores no keys: hashing, equality and prefetch arrive as callables from the owner, which is what lets a caller key its rows in whatever form it already has them in. OperatorIndex keeps its own API and forwards to it.

This is deliberately inert. The table's slot layout fixes for_each_slot order, which fixes evolved-term order, which fixes floating-point accumulation order — so a reordering here would move energies. Verified against main's implementation over 4000 random monomials: identical iteration order, find / find_batch results, clone order and memory_bytes.

Changes

• cpp/monoprop/detail/operator/RowHashTable.h: new. The table, TermIndexCeilingReached, kIndexCeiling, fold, find / find_batch / emplace / insert_distinct / insert_distinct_range, for_each_slot, reserve, slot_bytes.
• cpp/monoprop/detail/operator/OperatorIndex.h: keeps the rows, delegates the table. -195 lines.
• cpp/monoprop/detail/operator/CMakeLists.txt: list the new header.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable

Covered by the existing operator_index_tests.cpp; the gate for a change of this kind is just diff-baseline (#302), which must come out byte-identical.

AI/LLM disclosure

• I used the following tool to help write this PR description: ClaudeCode (claude-opus-5)
• I used the following tool to generate or modify code: ClaudeCode (claude-opus-5)

[github-actions]

Docs preview: https://pr-303.monoprop-docs.pages.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (c5e88c8) to head (3c0d67e).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #303   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[coderabbitai]

Warning

Review limit reached

Next included review available in 17 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 74eb9f04-b1fe-4006-9662-5761fa182c50

📥 Commits

Reviewing files that changed from the base of the PR and between c5e88c8 and 3c0d67e.

📒 Files selected for processing (3)

• cpp/monoprop/detail/operator/CMakeLists.txt
• cpp/monoprop/detail/operator/OperatorIndex.h
• cpp/monoprop/detail/operator/RowHashTable.h

---

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

[ludmilaasb]

LGMT

Just remove the narrative comments and I think we can merge.

[ludmilaasb]

I think we can remove this

Suggested change

	// Operator-term store: entropy-packed position-list rows plus a RowHashTable keyed over them. The rows
	// are this class's business and the index is not: nothing below reads a slot, and nothing in
	// RowHashTable reads a row -- the two meet only through the hash and equality callables passed in.
	// Row layout: slot 0 = popcount c (or kOverflowMarker if c > inline_width_), slots 1..c =

[ludmilaasb]

Suggested change

	// The keyless open-addressing index a row store puts over its rows: power-of-2 slot count, linear
	// probing, max load factor 0.7 (the group-prefetch win erodes at higher load -- longer probe chains add
	// un-prefetched reads). A slot holds a row index plus a 32-bit hash used only as an equality
	// pre-filter, so the table never stores or compares a key itself.
	//
	// Keyless is why the hash and the equality test arrive as callables rather than as members: the whole
	// point is that the caller owns the row representation. `eq(row_index)` confirms a pre-filter hit
	// against the caller's rows, and no operation here reads a row.
	//
	// The layout this produces is load-bearing, not an implementation detail: it fixes the iteration order
	// of for_each_slot(), which sets the order of a propagator's user-visible evolved-term list and
	// therefore its floating-point accumulation order. A store that keyed rows through its own copy of this
	// logic could diverge on that while still looking correct, which is the reason the index lives apart
	// from the row representation rather than inside one.

[ludmilaasb]

Suggested change

	// Refused before anything grows: an append that would pass the ceiling cannot be unwound, and a
	// store's size must never reach a count whose last index is unrepresentable. Written as a
	// subtraction because base + n is the sum that would wrap.

[ludmilaasb]

That's confusing, remove or change

Suggested change

	// Insert with no duplicate probe -- callers on this path insert provably distinct keys
	// (+G-injective miss batches, clone re-insertion).
	// insert_distinct over consecutive row indices [base, base + n), hashing each through hash_at(k).
	// The stores' bulk_insert is this and nothing else, so it lives here rather than once per backend.

[ludmilaasb]

Suggested change

	// Group-prefetch batch find: out[i] = row index of keys[i], or kNotFound. Same result as n find()
	// calls, but overlaps dram misses via a per-group hash/probe/confirm pipeline. An h collision falls
	// back to an exact find. Must not run concurrently with inserts.
	//
	// The three callables are what make the pipeline possible without the table knowing a row:
	// hash(key) -> uint32_t, prefetch_row(row_index) issued between probe and confirm (which is the
	// whole reason confirmation is deferred rather than folded into the probe), and
	// eq(row_index, key) -> bool.

[ludmilaasb]

Remove or simplify

Suggested change

	// find_batch over keys reached through key_at(i) rather than an array: a query form that is not an
	// array of keys (a flattened position list, say) keeps this one pipeline instead of copying it.
	// key_at is called once per key in the hash pass and again in the confirm pass, so it must be cheap
	// and stable. When hash_out is non-empty it receives every key's folded hash, which is what an
	// insert of the misses hands back to insert_distinct_range.

[ludmilaasb]

Suggested change

	// First slot on h's probe chain whose stored hash matches, or kEmptySlot if the chain ends first.
	// Matches on h alone and leaves confirmation to the caller -- that deferral is what lets find_batch
	// prefetch the row between probe and confirm, so do not fold eq in here (find() deliberately keeps
	// its own confirming variant). `start` must already be masked; the table must not be mutated
	// concurrently.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
51.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud