The event feed's paging is declared as an absence

[jorgemanrubia]

The account event feed pages by cursor: each GET /events.json or GET /inbox.json answers one page of at most 100 rows carrying its own opaque position, and a next URL while the walk has more to serve. Nothing in the spec said so. Account event feed, inbox, and stream tickets: spec operations and generated clients had to model that paging as an absence — no @basecampPagination trait at all — because the only thing the trait could mean was the Link-header walk, and generating that walk would flatten the pages and swallow every intermediate position, which is the one thing a crashed consumer resumes from. Declaring nothing was the only way to avoid declaring the wrong thing.

The cost is that every catalogue downstream of the spec says these operations answer once. The Rust route table rendered them Pagination::None, which route.rs documents as "a single answer". behavior-model.json and the metadata catalogues said nothing at all. Anything reading the contract — including the MCP catalogues — learned that the feed does not page.

Make the pagination trait's cursor style mean something removed the reason for the silence: style: "cursor" is now implemented in all seven generators and means exactly "one call answers one page, never walked", and Close the malformed-trait pass in the two generators that still had it closed the two holes that left. So the feed can now say what it does, and this is it saying so.

Context: 11 Feed operations in both MCP servers.

What changes

Both poll lanes declare the cursor style. key names the envelope member holding the page (events, items) and maxPageSize is bc3's PAGE_SIZE — 100 on Event::Feed and Event::Inbox alike. totalCountHeader is omitted because the feed sends no X-Total-Count. CreateStreamTicket stays undeclared: it mints one ticket per call and pages in no sense.

No generated method changes anywhere. All six service generators read the cursor style as "no walk", which is exactly what the absent trait produced, so the only SDK diff is the doc comment. What does change is the contract: openapi.json, behavior-model.json, the Ruby and TypeScript metadata catalogues, and the Rust route table, which now says Cursor with the page's key.

SPEC §23 and the Smithy section note both stated the absence as the design. They now state the declaration, and say why it is still not the Link walk.

On the tests

The route table is where the declaration is pinned, because it is the artefact a consumer reads. guarantees.rs asserts the two lanes are the entire cursor set, with their keys, and that CreateStreamTicket pages not at all. Reverting the trait and regenerating turns it red: left: [] right: ["PollEvents", "PollInbox"].

The runtime guard is conformance. The feed's envelope case already served a continuation and asserted one request; the inbox had no such case, so it now has one. Both serve a relative Link: rel="next" (as pagination.json does) beside the absolute body next, so a walker that follows the header makes a second request in every runner instead of depending on each walker's cross-origin refusal. Flipping both lanes to style: "link" and regenerating turns both cases red in the TypeScript and Python runners with Expected 1 requests, got 2.

How a flip goes red differs by SDK, and SPEC §23 now says exactly how: on the request count in TypeScript, Python and a Link-following Go wrapper; on the resulting error in Ruby; at the runner's compile in Kotlin and Swift. Rust's conformance runner stays green on a flip — its link-style method fetches one page and leaves the walk to the caller — so in Rust the route-table test is the guard.

An earlier revision added a TypeScript-only test for this; it duplicated the feed's conformance case and is gone.

Rebased on the error-shapes change

Rebased onto Event feed: split the poll lanes' 410s and give their 400 a reason, which touched the same table rows, doc comments and fixture file. No semantic overlap: that PR is error shapes, this one is paging. Everything regenerated on top of it, and SPEC §23's fixture count now reads thirteen.

Locally, the full make check target list passes except two things this machine cannot run: rs-deny (cargo-deny not installed; passes in CI) and swift-check (macOS only). Swift's generator also could not run here, but its emitted services carry neither operation descriptions nor pagination metadata, and Swift Tests pass in CI.

Review

Adversarial review by separate Opus agents across every head, converged on 262db36d. The first pass found nothing blocking; everything after the first commit is what the passes turned up — the runtime tripwire on the wrong lane, a trait doc claiming nothing guards Go, SPEC §8 under-enumerating, a stale fixture count after the rebase, the absolute Link leaving a same-origin-only walker uncaught, and prose that misstated how Rust and Ruby fail on a flip.

[Copilot]

🔵 Needs a closer look

The Ruby metadata catalogue drops both cursor collection keys, leaving its declared contracts incomplete.

Pull request overview

Declares event-feed polling as cursor pagination without enabling automatic Link walking.

Changes:

• Adds cursor traits for PollEvents and PollInbox.
• Regenerates contracts, metadata, documentation, and Rust routes.
• Adds regression coverage for single-page behavior and route classification.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File summaries

File	Description
SPEC.md	Documents cursor pagination semantics.
behavior-model.json	Catalogues both cursor operations.
openapi.json	Adds pagination extensions.
spec/basecamp.smithy	Declares cursor traits.
typescript/src/generated/schema.d.ts	Updates generated API documentation.
typescript/src/generated/openapi-stripped.json	Mirrors OpenAPI changes.
typescript/src/generated/metadata.ts	Adds complete cursor metadata.
typescript/tests/services/event-feed.test.ts	Guards against automatic Link walking.
ruby/lib/basecamp/generated/types.rb	Refreshes generation timestamp.
ruby/lib/basecamp/generated/metadata.json	Adds cursor metadata but omits collection keys.
python/src/basecamp/generated/services/event_feed.py	Updates generated documentation.
rust/basecamp-sdk/src/generated/services/event_feed.rs	Updates generated documentation.
rust/basecamp-sdk/src/generated/routes.rs	Classifies both routes as cursor-paged.
rust/basecamp-sdk/tests/guarantees.rs	Pins cursor routes and keys.

Review details

• Files reviewed: 6/14 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jorgemanrubia]

🤖 On the Ruby metadata catalogue dropping the cursor collection keys — checked, and it is not a gap this PR opens.

ruby/scripts/generate-metadata.rb has never emitted key for any operation. It copies style, totalCountHeader and maxPageSize and stops there, so all 61 link-paginated operations are missing it too:

$ jq '.operations.ListProjects.pagination' ruby/lib/basecamp/generated/metadata.json
{ "style": "link", "totalCountHeader": "X-Total-Count", "maxPageSize": 50 }

GetPersonProgress, whose items live under an events key in a wrapper object, reads the same. So the two cursor lanes land exactly as complete as every other paginated operation in that file — the omission is uniform, and pre-dates this change by a long way.

It is also inert. Ruby's runtime reads one thing out of metadata.json: Http.operation_retry digs out the retry block (ruby/lib/basecamp/http.rb:621-628). The pagination block is catalogue only, and the key that actually drives Ruby's envelope unwrapping is baked into the generated service method by generate-services.rb, not read back from metadata. Python's metadata emits no pagination block at all, for what it is worth.

Widening the Ruby emitter would be the right fix for the underlying inconsistency, but it belongs in its own change: it touches 63 operations' metadata in a field nothing reads, and its justification is about catalogue parity across the SDKs rather than about the event feed. Happy to open it separately if that is wanted.

For contrast, the TypeScript catalogue copies the trait wholesale and does carry both keys, and the Rust route table carries them in Pagination::Cursor { key } — which is where this PR pins them, in guarantees.rs.