No test pins the behavior of get_history_page and get_history_page_with_meta against each other: the documented equivalence (identical items) is unasserted

[usmanimamu17-create]

Problem

get_history_page_with_meta (src/lib.rs/src/history.rs) promises: "The items slice is identical to what get_history_page returns for the same (offset, limit)". The two accessors are implemented separately (companion issue on the duplication), and the test suite does not contain a direct comparison test — the pagination tests exercise each accessor's own contract but not the equivalence the docstring promises.

Consequences:

• The equivalence guarantee is unverified: if the two implementations diverge (e.g. one clamps limit differently — the saturating logic is duplicated), consumers that switch between the two accessors (the meta variant exists so consumers can avoid a second call) get different items for the same arguments with no test catching it.
• The docstring is the only spec: the "identical items" claim lives in prose; a future refactor of one accessor can silently break it.
• The total/has_more fields compound the risk: has_more is computed from the same end used for slicing, so a slicing bug corrupts the pagination metadata too — and nothing cross-checks has_more against a manual count.

Root cause

The two accessors were written together but tested separately; the equivalence invariant was documented, not asserted.

Why this is architecturally hard

1. The direct fix is a parametrized test (for each offset/limit pair, assert items equality and has_more correctness against a known history) — mechanically simple, but it must be written against the policy (issue Create a policy note for history pagination size and offset safety when consumers rely on page-based lookups #263) not the current implementation, so the test survives the storage redesign (companion issue).
2. The equivalence is only meaningful with a defined history state; the test must build a history of known length and iterate a range of offsets/limits including the edge cases (offset >= len, limit 0, limit > remaining).
3. This test is a prerequisite for the de-duplication refactor (companion issue): consolidating the two implementations is only safe if the equivalence test exists first.

Acceptance criteria

• A test asserts get_history_page_with_meta(offset, limit).items == get_history_page(offset, limit) across a matrix of offsets/limits on a fixed history.
• The test covers edge cases (empty history, offset beyond end, limit 0, limit exceeding remaining).
• has_more is asserted against a manual count for the same matrix.

Out of scope

The pagination de-duplication (companion issue) and the storage redesign (companion issue).

Getting started

just test

Good first files to read: apexchainx_calculator/src/lib.rs (get_history_page, get_history_page_with_meta), docs/HISTORY_PAGINATION_POLICY.md.

[Alhaji-naira]

@Alhaji-naira has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

hello maintainer, can i work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Alhaji-naira to this issue.

[drips-wave]

Congratulations, @Alhaji-naira! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Alhaji-naira: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Alhaji-naira's PR #536 was approved and merged by @usmanimamu17-create.

🏆 @Alhaji-naira: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (424 total points). Track your full progress on GrantFox.

👏 Great work, @Alhaji-naira! Keep contributing to ApexChainx.