Model tests: the layout tiles the word, an update writes no handle bit, storage parity checks get and export

[thedavidmeister]

Stacked on #163 (test-lib-support). Merges last in wave 2.

Closes #107
Closes #121
Closes #134
Closes #137
Closes #115
Closes #136
Closes #146
Closes #158
Closes #123
Closes #124
Closes #126
Closes #138
Closes #149

#123, #124, #126, #138 and #149 are split across W2b–W2e. This PR is their closer and merges after those.

Base

This branch merges origin/main (8220918), so it no longer carries #162 itself: #162 is on main. It also merges
test-lib-support at 02043b3, which contains #162, so the diff shows only this PR's three files.
Imports follow the split helpers: LibMemoryKVExport, LibMemoryKVHandle, LibMemoryKVKeys, LibMemoryKVAssert,
LibFreeMemory.

Owned files: test/src/lib/LibMemoryKV.types.t.sol, LibMemoryKV.crossFunction.t.sol,
LibMemoryKV.storageParity.t.sol. No other file is edited.

Changes

types (LibMemoryKV.types.t.sol)

• [A20] [LOW] MemoryKV handle layout is spelled as literals and per-file constants, not one definition #123 (A20), Amendment 4: the test tree defines no copy of a layout value. testLayoutConstantsTileTheWord checks,
  on LibMemoryKV's own constants, that the count sits directly above the last list
  (COUNT_BIT_OFFSET == LIST_COUNT * SLOT_BITS), is the top slot (COUNT_BIT_OFFSET + SLOT_BITS == 256), that
  POINTER_MASK is one slot wide, and that the count slot holds exactly POINTER_MASK. The local SLOTS is gone.
• [A34] [INFO] types.t.sol empty-store layout tests mask the zero word, so their layout claims can't fail #137 (A34): the two zero-word tests are replaced by testCountAndHeadPointersTileTheWord. It fills all fifteen
  lists, checks the count is two words per pair, and checks each head pointer is non-zero and points at the node
  holding that list's key, with its value after it.
• [A21] [LOW] Word count read under three names: wordCount alias, lengthOf, and inline >> 0xf0 #124 (A21) / [A46] [INFO] Tests re-inline lengthOf/headOf/countPair/key/node-crafting instead of using test helpers #149 (A46): the count and heads are read through lengthOf/headOf; countPair(...) != 0 becomes
  assertEq(countPair(...), 1), so each pair is exported exactly once.

crossFunction (LibMemoryKV.crossFunction.t.sol)

• [A18] [LOW] crossFunction test header says no library mutation can falsify its tests; set mutations do #121 (A18) / [A35] [INFO] NatSpec narrates design rationale, replaced figures and killed mutants, not current behaviour #138 (A35): the header states the two properties and names the constants, with no mutation framing.
• [A04] [LOW] crossFunction asymmetry test: NatSpec misstates what an insert changes; update never pins handle #107 (A04): the asymmetry test snapshots every handle word before the update and asserts each is identical after
  it, the handle set returns included. The NatSpec states it: an insert writes the count and the head, an update
  writes no bit.
• [A31] [INFO] buildSaturatedExternal rewinds to SATURATED_BASE without checking it clears the decoded keys #134 (A31): buildSaturatedExternal requires the free memory pointer after decoding keys to be at or below
  SATURATED_BASE ("keys overlap SATURATED_BASE") before it moves the pointer there with setFreePointer ([A23] [LOW] Tests hand-roll free-pointer, cheatcode and approx-assert primitives the dependencies provide #126,
  A23). testSaturatedBuilderRefusesKeysReachingPastItsBase pins both sides: 19 keys build (count 38), 20 revert with
  that exact string.
• [A20] [LOW] MemoryKV handle layout is spelled as literals and per-file constants, not one definition #123 (A20): the local LIST_COUNT/SLOT_BITS/NODE_SIZE and the literal 0xf0 are replaced by LibMemoryKV's
  constants.

storageParity (LibMemoryKV.storageParity.t.sol)

• [A12] [LOW] storageParity testMultiGetSetDouble never checks two live stores against each other #115 (A12) + [A33] [INFO] testMultiGetSetSingle never calls get and only checks exported pairs against storage #136 (A33): one helper, assertMatchesStorage, checks export length == 2 × distinct keys, and for every
  key set: get answers with the value storage holds, and the pair is exported exactly once. Each store has its own
  storage oracle (StorageStore{values, seen, distinct}), written by setBoth.
• PAIRS_PER_STORE = 10 is documented: uncapped arrays push nodes past POINTER_MASK and set reverts
  MemoryKVOverflow (seen as MemoryKVOverflow(65568) without the cap).
• [A43] [INFO] storageParity test KV struct NatSpec calls a key/value pair a "get/set pair" #146 (A43) / [A55] [INFO] storageParity test compares against a no-op wrap/unwrap and names a local after get #158 (A55): struct NatSpec, local got instead of get, the no-op wrap/unwrap dropped.

Deviations from the plan

• Amendment 4 replaces the plan's "library constants equal the test tree's" half of the A20 test. Only the tiling
  half remains, stated on src's constants, renamed testLayoutConstantsTileTheWord.
• testSaturatedBuilderRefusesKeysReachingPastItsBase is added to pin the A31 guard in both directions.
• Renames: testMultiGetSetSingle → testSetSequenceMatchesStorage, testMultiGetSetDouble →
  testTwoLiveStoresEachMatchTheirOwnStorage.
• types' countPair(...) != 0 → exactly once (A46), beyond the plan's types bullet.
• testSetSequenceMatchesStorage gas rises from μ 2.77M to μ ~10M: it now calls get and countPair per key.

Test counts

Owned files: 11 before (base 70a7ab3) → 12 after (types 6, crossFunction 3, storageParity 3). The one new test is
testSaturatedBuilderRefusesKeysReachingPastItsBase; the two zero-word tests become two layout tests.

Full suite, from the CI test job logs: 159 passed of 159 on base test-lib-support at 02043b3
(https://github.com/rainlanguage/rain.lib.memkv/actions/runs/35339867369) → 160 passed of 160 at head 90c3daa
(https://github.com/rainlanguage/rain.lib.memkv/actions/runs/35340530745).

QA

All probes: mutation-probe from rainlanguage/adversarial-mutation-test, base 70a7ab3 (the owned files before this
PR) vs head 83b25c2. The final head 90c3daa differs from 83b25c2 only in LibMemoryKV.gasClaims.t.sol, from
the base merge, which no probe below runs. Raw reports: /home/gildlab/artifacts/memkv/audit-2026-09-18/w2f/.

• Discriminating tests, per-test probe, base vs head:
  • [A04] [LOW] crossFunction asymmetry test: NatSpec misstates what an insert changes; update never pins handle #107 testAsymmetryHoldsAcrossManyLiveHandles, M01 (set's update also re-points the list head at the matched
    node): base SURVIVED, head KILLED.
  • [A12] [LOW] storageParity testMultiGetSetDouble never checks two live stores against each other #115 storageParity file, M12 (get finds a key only at the head of its list): base SURVIVED, head KILLED by
    testSetSequenceMatchesStorage and testTwoLiveStoresEachMatchTheirOwnStorage. M13 (export reads list 1 in place
    of list 0) and M14 (an update also counts two words) are KILLED on both, so the exactly-once and export-length
    assertions are not claimed as new coverage.
  • [A34] [INFO] types.t.sol empty-store layout tests mask the zero word, so their layout claims can't fail #137 base zero-word tests (testEmptyStoreHasNoWordCount, testEmptyStoreHasNoHeadPointerInAnySlot): M02
    (LIST_COUNT 14), M03 (SLOT_BITS 0x11), M05 (COUNT_BIT_OFFSET 0xe0), M07 (insert never writes the new head)
    all SURVIVED. Head testCountAndHeadPointersTileTheWord: M03, M05, M07 KILLED; M02 SURVIVED. The test fills
    LibMemoryKV.LIST_COUNT lists and keyForSlot hashes modulo the same constant, so a smaller count moves the test
    with it. testLayoutConstantsTileTheWord kills M02 (COUNT_BIT_OFFSET 0xf0 ≠ 14 × 0x10).
  • [A20] [LOW] MemoryKV handle layout is spelled as literals and per-file constants, not one definition #123 testLayoutConstantsTileTheWord: M02, M03, M04 (POINTER_MASK 0x7FFF), M05 KILLED; M06 (NODE_BYTES 0x80)
    SURVIVED, since node size is not a tiling fact.
  • [A31] [INFO] buildSaturatedExternal rewinds to SATURATED_BASE without checking it clears the decoded keys #134 testSaturatedBuilderRefusesKeysReachingPastItsBase is new: M10 (guard <= SATURATED_BASE →
    <= type(uint256).max) and M11 (<= → <) both KILLED.
• File-level probe, owned files only (--match-path test/src/lib/LibMemoryKV.{types,crossFunction,storageParity}.t.sol):
  • Base 70a7ab3: 9/9 src mutants KILLED (M01–M09), so file level shows no base/head split; the per-test probes above
    carry the before/after evidence.
  • Head 83b25c2: 10/11 KILLED (M01–M11). M06 survives the owned files. At base, the saturated-handle test killed it
    only because it spaced nodes with its own NODE_SIZE = 0x60. That copy is gone, so the test reads
    LibMemoryKV.NODE_BYTES and moves with it. At head, LibMemoryKV.setCapacity.t.sol KILLS M06 (for example
    testSet682PairsFitAnOtherwiseEmptyFrame).
• Oracle: types reads the layout from the MemoryKV NatSpec (fifteen 16-bit head slots, the count in the top slot,
  POINTER_MASK the widest pointer and count). The tiling test's expected node contents are the keys and values it
  inserted. crossFunction's expected handle word is built from the addresses the building frame was forced to allocate
  at. The asymmetry test's expected words are the same handles snapshotted before the update. The guard's fit comes
  from the ABI layout of a decoded bytes32[] (entry pointer 0x80, a length word, one word per key). storageParity's
  oracle is one Solidity storage mapping plus a distinct-key counter per store.
• Category check: [A04] [LOW] crossFunction asymmetry test: NatSpec misstates what an insert changes; update never pins handle #107 update writes no handle bit (asymmetry snapshot); [A18] [LOW] crossFunction test header says no library mutation can falsify its tests; set mutations do #121 header; [A31] [INFO] buildSaturatedExternal rewinds to SATURATED_BASE without checking it clears the decoded keys #134 guard + test; [A34] [INFO] types.t.sol empty-store layout tests mask the zero word, so their layout claims can't fail #137 zero-word
  tests replaced; [A12] [LOW] storageParity testMultiGetSetDouble never checks two live stores against each other #115 get, exactly-once export and export length; [A33] [INFO] testMultiGetSetSingle never calls get and only checks exported pairs against storage #136 one oracle per store; [A43] [INFO] storageParity test KV struct NatSpec calls a key/value pair a "get/set pair" #146 struct NatSpec;
  [A55] [INFO] storageParity test compares against a no-op wrap/unwrap and names a local after get #158 local got, no-op wrap dropped; [A20] [LOW] MemoryKV handle layout is spelled as literals and per-file constants, not one definition #123 local layout constants and 0xf0 replaced by src's, and the tiling test
  (Amendment 4 drops the equality half); [A21] [LOW] Word count read under three names: wordCount alias, lengthOf, and inline >> 0xf0 #124 lengthOf/headOf; [A23] [LOW] Tests hand-roll free-pointer, cheatcode and approx-assert primitives the dependencies provide #126 setFreePointer; [A35] [INFO] NatSpec narrates design rationale, replaced figures and killed mutants, not current behaviour #138 present-tense header;
  [A46] [INFO] Tests re-inline lengthOf/headOf/countPair/key/node-crafting instead of using test helpers #149 exactly-once countPair. Each is this PR's owned-file part; the other files are W2b–W2e's.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 57 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: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 64f84295-c812-4fe8-91ce-de71ea2df1d6

📥 Commits

Reviewing files that changed from the base of the PR and between e442de9 and 90c3daa.

📒 Files selected for processing (3)

• test/src/lib/LibMemoryKV.crossFunction.t.sol
• test/src/lib/LibMemoryKV.storageParity.t.sol
• test/src/lib/LibMemoryKV.types.t.sol

---

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

[thedavidmeister]

Superseded by per-issue PRs: #107 → #174 (merged), #121 → #185 (merged), #134 → #187 (merged), #124 → #180 (merged), #146 → #183 (merged), #136 → #179, #115 → #186, #158 → #184, #137 → #188, #149 → #190, #123 → #192, #126 → #191, #138 → #189.