feat(list): cursor pagination for all kb.list_* methods

[Tet-9]

Fixes #245

What

All six kb.list_* methods now support cursor pagination. Clients pass limit and cursor params; responses return a {items, _meta} envelope with next_cursor and total.

Changes

storage.py

• Added _paginate_paths helper — id-ordered path slicing shared by all paged variants
• Added list_claims_page, list_pages_page, list_entities_page, list_relations_page, list_sources_page, list_proposals_page

jsonl_server.py

• Added _resolve_list_limit (reads retrieval.default_limit from config.yaml, falls back to 10)
• Added _paged_envelope builder
• Rewrote all six _h_list_* handlers to use paged storage methods and return {items, _meta} envelope

server.py

• Same helpers and rewrites for all six MCP kb_list_* tools
• Tools now accept limit: int | None and cursor: str | None params

tests/test_list_pagination.py (new file, 12 tests)

• Basic pagination contract for each of the 6 list methods
• Edge cases: empty collection, limit > total, cursor resume
• Fuzz test: 1 000 claims walked with irregular page size, asserts every id returned exactly once in sorted order with no gaps

Deprecation

Flat-array response shape is deprecated. A _meta.deprecation notice is included in every response. Clients that currently do result[0] or len(result) on list responses need to update to result["items"][0] and len(result["items"]).

Checklist

• make check passes (ruff + mypy + pytest, 685 passed)
• CHANGELOG.md updated under [Unreleased]
• Targets test branch
• No new dependencies

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b607a3e3-cee1-4baa-991b-21d5a11543fa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[Tet-9]

@plind-junior , ready for review

[Tet-9]

@plind-junior , same for this as well