list: a plugin-declared order per type, next's filters, and --paginate (nxf 6j6v.n698)

[cabcookie]

Stacked on #46 (q29p): this branch builds on its shared paging helpers (Paging, Watermark, page_through). Merge #46 first; until then the diff here includes #46's commit.

Third cut of kfs7. Owner decision 2026-10-09: long-lived objects that are not tasks (persons, say) are ranked through nxf list, never through next.

Plugin declaration

[ranking.next]
order = [ { field = "status", precedence = ["in_progress", "open"] }, { field = "priority", dir = "asc" } ]

[ranking.list]
types = ["person", "project"]          # cross-type order, as for next
# order = [ ... ]                      # optional; defaults to the [ranking.next] default order
[ranking.list.person]
order = [ { field = "title", dir = "asc" } ]
[ranking.list.project]
order = [ { field = "priority", dir = "desc" } ]

• The key language, the per-type tables, types, and the load-time rules are the same as z9jk's [ranking.next]. The same code parses and validates both; errors name [ranking.list…].
• Ranking::list is always resolved at load. Without [ranking.list], or without its own order, the list default order is the [ranking.next] default order. That is exactly what list --sort rank ranked by before, so nothing changes for a plugin that declares nothing, both bundled plugins included.

Behaviour

• The default list order stays id. The plugin order is selected with the existing --sort rank flag; no new sort key. The code comment on rank_cmp had already reserved this for n698.
• Mixed types work as in z9jk: items of different types compare by their position in types (or in the default order's first precedence key on type). Unlisted types come after the listed ones, ordered by type name. Within one type, items compare by that type's own order (or the default order), then by id.
• blocked and the lane verbs' --sort rank are unchanged: they use the [ranking.next] default order.

API (facade: changed, additive)

• read::ListQuery (non_exhaustive builder: new/status/sort/filter/limit/paginate/token).
• read::list_page(&PluginConfig, &Store, &ListQuery) -> Result<NextPage>.
• Engine::list_query(&ListQuery) -> Result<NextPage>, Engine::list_query_value(&ListQuery) -> Result<Value>.
• plugin::Ranking::list: RankSpec (new field; Ranking is non_exhaustive).
• Internal: NextRank is now TypeRank over a &RankSpec, with TypeRank::next(cfg) and TypeRank::list(cfg). It is the one comparator for both verbs, so derived keys (x0wf) plug in once.

CLI

nxf list [--status S] [--type T]... [--in ID] [--label L] [--sort rank|id] [--limit N [--paginate [--token T]]]

• --json without --limit: the same plain array as before.
• With --limit: {"items": [...], "total": n}.
• With --paginate, two more keys: next_token (null on the last page) and restarted.
• The human view prints showing n of total and a next page: --paginate --token … line.

Paging uses next's machine-local cache, with the same expiry, caps and invalidation. The snapshot key names the read ("list"), the status, sort and filter, and a fingerprint of [ranking.list], so tokens never cross between next, mentioned_by and list, or between plugin orders.

Tests

• crates/facade/tests/list_query.rs: 14 tests at the Engine::list_query seam, using two fixture plugins (per-type list order, and none).
• plugin::tests: 5 new load/validation tests.
• crates/cli/tests/list.rs: 5 new black-box tests.
• Goldens under both plugins, guide EN/DE, docs/generated.

Run locally (all green): facade lib, list_query, next_rank_per_type, mentioned_by, read, engine, external_plugin_registration; cli list, golden, guide_examples, verb_seam, mention, next, sort, parity; cargo xtask docs check; cargo xtask changelog check origin/main; cargo fmt --all --check. Clippy is left to CI.

Not in this PR

• The MCP flow_list tool did not gain the filters or paging; flow_next has not got them yet either. flow_list's sort: rank does use [ranking.list], because it goes through read::list.

🤖 Generated with Claude Code

https://claude.ai/code/session_016q5uMUkZJQW4fckJoA3FME

[cabcookie]

Contained in #49, which folds #46, #47 and #48 plus the review mitigation and was merged in one squash.