Native list pagination, continuation cursors and output budgeting byte-identical to the pm CLI oracle

Merged
UN
8d ago
+1865-101

Native list required JSON for pagination and lacked parent/tag and explicit sort/order controls. It now emits the pinned oracle's JSON and default TOON envelopes from one native selection and budgeting pipeline, including continuation contracts, omission receipts and exact token estimates.

The shared disposable fixtures contain 270 items across all six built-in statuses. Complete stdout, stderr and exit codes are compared against @unbrained/pm-cli@2026.10.14; no fields are removed or normalized before comparison. Walks cover combined filters, all six sort fields in both directions, timestamp aliases, producer limits, snapshot budgets and refusal cases, with no missing or repeated rows. Read projections also reproduce normalized collection ordering and JavaScript Number coercion for unsafe integers. Storage and history numeric handling remain separate.

--cursor is a native alias for published --after. Producer cursors tolerate edits; --output-cursor rejects changed row snapshots. The pinned oracle rejects the literal list --cursor spelling and its TOON codec refuses surrogate cuts during compaction; these distinctions are documented and tested.

Seven independent behavioral revert controls each execute their corresponding regression and fail with Cargo exit 101 against the unchanged oracle. They revert read ordering, TOON measurement, the cursor alias, ordering validation, hierarchy edges, complete brief projection and writer error propagation respectively. Every mutation is restored. See the scenario and revert receipt.

Validation on the final source:

  • just --no-deps release-check: 325/325 ordinary tests and 325/325 instrumented tests across 17 targets per run, zero failed or ignored. Coverage: 6,226/6,226 lines, 586/586 functions, 9,635/9,635 regions and 1,348/1,348 branches (100% in all four dimensions). Formatting, deny-warning clippy and complete rustdoc pass. Identity audit: 7/7. Dependency audit: 134 dependencies, no vulnerabilities, one existing allowed unsafe-libyaml advisory. The PM-linked pagination command passes 18/18 tests.
  • The unchanged release recipes run with a clean home and isolated Git identity configuration. The lockfile oracle was installed with CI's npm ci --prefix tests/oracle --ignore-scripts; just --no-deps release-check reuses that installation.
  • Pinned-oracle health --check-only --require-merge-drivers --strict-exit: 8/8 checks pass with clone-local merge drivers and a clean home. The committed-tree check retains three advisory categories: outdated agent guidance, stale in-progress items and existing provenance-domain values. The claim is released; no items are closed.
  • Changelog regeneration/check and the append-only history/public-path checks pass.

Configured lifecycle/hierarchy registries remain follow-up work in the child item. The parent item stays in progress for orchestrator verification.

PM evidence:

Summary by Sourcery

Match the native list command with the pinned PM CLI across pagination, filtering, sorting, cursor continuation, output budgeting, and JSON/TOON rendering.

New Features:

  • Add native list pagination in JSON and TOON with continuation cursors, output-budget continuations, and exact oracle-compatible envelopes.
  • Support parent and tag filtering, blocked-item selection, six explicit sort fields, sort direction controls, and published timestamp aliases.
  • Provide native --cursor support as an alias for --after, with producer cursors tolerant of edits and snapshot cursors rejecting changed rows.
  • Render compact TOON output with byte-based budgeting, omission receipts, sparse-table encoding, JavaScript-compatible numeric formatting, and complete brief projections.

Bug Fixes:

  • Preserve published cursor refusal diagnostics, exit codes, surrogate-cut encoding failures, and writer or flush errors across list output modes.
  • Apply JavaScript Number coercion only to read projections while retaining existing storage and history numeric behavior.

Enhancements:

  • Unify native list selection, projection, pagination, budgeting, and output generation across JSON and TOON while preserving the legacy SDK list contract.

Documentation:

  • Document native list pagination, filtering, sorting, cursor semantics, TOON budgeting, oracle differences, and remaining compatibility boundaries.

Tests:

  • Add comprehensive differential coverage against the pinned PM CLI for mixed-status fixtures, combined filters, all sort directions, pagination walks, budget continuations, refusal cases, numeric normalization, and both wire formats.
  • Add unit coverage for hierarchy selection, ordering validation, TOON compaction, sparse tables, numeric rendering, surrogate handling, and output error propagation.

Chores:

  • Record PM task and append-only history evidence for the pagination parity work.

Summary by cubic

Native list now emits default TOON envelopes, parent/tag filters, explicit sort/order controls, and continuation cursors byte-identical to the pinned @unbrained/pm-cli@2026.10.14 oracle — previously pagination required JSON and lacked these controls. --output-budget, --output-limit, --all, --full, and --brief no longer require --json; --cursor is a native alias for --after. Default list output changes from JSON to TOON; pass --json to keep the JSON envelope. Read projections match JavaScript Number coercion for unsafe integers; storage and history numerics are unchanged. The oracle differs on the literal list --cursor spelling and refuses unpaired UTF-16 surrogates during TOON compaction; both divergences are documented and tested.

Testing

  • Differential tests compare complete stdout, stderr, and exit codes against the pinned oracle on a 270-item fixture covering all six statuses, all six sort fields in both directions, timestamp aliases, producer limits, snapshot budgets, and refusal cases.
  • Seven revert controls each fail with Cargo exit 101 against the unchanged oracle; all mutations are restored.