Pull entitled events
Fetches a page of a pull subscription’s entitled events in arrival-order seq. The read doubles as the acknowledgment (cursor-as-ack): after a successful fetch the highest returned seq is persisted as the subscription’s cursor, monotonically. An explicit after cursor overrides the persisted cursor for the read; a forward seek advances the durable cursor past the unread gap (the skipped range is not re-delivered — caller-owns-the-gap), while a backward seek never rewinds it. The read is rate-limited per tenant. Events are at-least-once; deduplicate on ceId.
Authorizations
A bearer JWT issued by plugin-auth (lib-auth). The tenant identity is resolved from the validated token claims; the /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token via the plugin-auth client-credentials flow. The /admin surface authorizes against an operator scope and carries no tenant context.
Query Parameters
The pull subscription to read. Resolved through an existence gate then a kind gate: an absent, cross-tenant, or non-pull id all return a uniform 404 not_found (no existence or kind oracle).
Explicit keyset cursor (replay). When present it overrides the persisted cursor for the read; absent it, the read resumes from the persisted acknowledged seq (0 = from the beginning). A malformed value is ignored and folds to the persisted cursor.
Page size, clamped to the range 1–500, defaulting to 100.
Response
A page of events in ascending seq order.
A page of events in ascending seq order.
The maximum seq in the page when it filled exactly to limit (a possible next page); null on a short or final page. This diverges deliberately from the subscriptions list cursor (which is a DESC-by-id string with an empty-string sentinel).
42

