feat(datasource-pylon): Pylon datasource for the Ruby agent (EXT-4)

[christophebrun-forest]

Integration branch for EXT-4 — forest_admin_datasource_pylon, feature parity with the Zendesk datasource.

The ten stories of the epic are Done and merged, main is merged in, and the branch touches exactly three files outside the new package.

What is in the branch

A new forest_admin_datasource_pylon package: 44 files under lib, 24 spec files, 786 examples, 100.0% line coverage (1686/1686) and 94.5% branch coverage. Ten story PRs, all reviewed and merged into this branch:

PR	Story	Content
#341	EXT-5	foundation — gem, configuration, resilient client
#347	EXT-6	PylonIssue read-only, cursor pagination
#351	EXT-7	filters, search, count, PK short-circuit hardening
#354	EXT-8	all collections + relations
#358	EXT-9	messages / conversation thread
#359	EXT-10	custom fields introspection
#362	EXT-11	write operations (CRUD)
#366	EXT-12	action plugins: close issue, create issue with notification
#373	EXT-13	story 9 — proactive per-endpoint throttling on top of the 429 retry
#375	EXT-17	bound the boot-time custom-fields introspection

That is every sub-issue of EXT-4 and every PR ever opened against this branch. Re-checked against
Linear on 2026-08-27: EXT-4 has exactly these ten children, all Done, and no eleventh — so the
table above is the whole epic. EXT-4 itself is the only thing left In Progress, this PR being what
closes it.

Three follow-ups were filed out of the review rather than fixed here. They are not sub-issues of
EXT-4 — each is repo-wide, not Pylon's — and they are listed so the table is the full Linear picture:

Ticket	Scope	Why not here
EXT-19	.releaserc.js chains all fourteen successCmd pushes with ;	Fixing only the mambu/pylon boundary the diff touches would leave twelve packages masking failures
EXT-20	No datasource gemspec declares the Forest gems as runtime deps	Declaring them on Pylon alone makes it the only gem with a different contract
EXT-21	A non-positive page limit reads as "no limit" in one place, "empty" in another	Read path of every collection; the two readings have to be settled together

Shape of the package: client.rb + client/writes.rb over the Pylon API with a retry_policy, a rate_limiter / rate_limits / throttle trio metering each endpoint in its own sliding window, a base_collection specialised into cursor_collection / fetch_all_collection, one directory per collection (account, contact, issue, team, user) each with its own api_filters / schema_definition / serializer, a query/ layer translating condition trees into Pylon filters, pagination/cursor_walker, schema/custom_fields_introspector, and two action plugins.

Review pass on the whole branch

65190b9f merges main; the two conflicts were both the #368 sort-decorator cherry-pick, resolved in favour of main, so those files have left this diff. Fifteen commits then close out the review of the assembled branch — these are direct commits, so they appear in no story PR above:

Commit	Kind	Content
b9cb7d15	fix	refuse a Number filter cast to Infinity / NaN; deduplicate action issue ids; stop collect_pages on a cursor already followed
a93474b1	fix	MAX_ID_LOOKUPS bounds a page rather than a selection
24951097	fix	refuse two plugin configurations that misbehave silently
cc015514	fix	keep no column for a projection naming only relations
373f94de	refactor	drop the countable: flag nothing opts into
7033ba1d	fix	stop the custom-field introspection at its first failure
bd55e8ba	docs	the package README, last open item of EXT-13
2a1b4d6d	fix	serve the whole record for an empty projection
67cd786a	fix	refuse an internal note the form never offered
1fd03cbd	fix	keep a select with no option left read-only
96a0575a	docs	record what bounds CloseIssue and what does not
0a2d4e4d	chore	align version.rb with the other packages
d75bab2c	fix	intersect the id conditions of an and, on both the read and the write path
524cc95e	fix	let a refused selection reach the operator of a close action
b6bd085b	docs	correct which scope bounds CloseIssue

Defects fixed

• b9cb7d15 — a Number filter the agent cast to Infinity or NaN reached to_i, which raises, and then the JSON encoder, which raises too: a 500 either way, on a value the operator typed. Now refused with a 400 naming the field. Same commit: an action reading issue ids off a column deduplicates them, and collect_pages stops on a cursor it has already followed rather than only on one that did not move.
• a93474b1 — MAX_ID_LOOKUPS bounded a selection where it should bound a page: the ids were truncated to the first 20 before the window was applied, so an offset at or past 20 answered an empty page from records that exist. The window is now taken off the ids before any of them is read, which also spends one request per record the caller asked to see. A lookup carrying a residual condition cannot be paged that way and is refused past the cap rather than answered with a fraction of itself.
• 24951097 — a plugin scope that is neither a symbol nor a string raised NoMethodError instead of the error naming it; duplicate email-template titles, and a template titled like the "pick none" sentinel, are now refused at registration instead of silently sending the wrong message.
• cc015514 — project served the whole record when the projection named no column of the collection, so a row asked for as account:name came back carrying every native column too. Relevant now that main has landed serve only the columns of collections the caller may read. It also changed what an empty projection returns, which is not that case at all; 2a1b4d6d separates the two.
• 7033ba1d — EXT-17 bounded each boot-time introspection per request, not the three of them together, so a Pylon that hangs could add about a minute to a Rails boot rather than the twenty seconds intended. The first failure now stands for the object types after it.

Also

• 373f94de — drops the countable: flag: no collection ever passed it, Pylon having no count endpoint and no total.
• bd55e8ba — the package README, last open item of EXT-13.

Macroscope: 21 review threads across seven passes, every one answered in thread. The seventh pass landed one finding, on base_collection.rb:107, and it was real: fixed in d75bab2c, described below. Two of the last four findings were real and are fixed (67cd786a, 1fd03cbd); one is a false positive (nil.to_i is 0, so the guard already re-raises) and one is not reachable through the agent stack, which rewrites the date operators upstream — both answered with the reasoning. The normalize_templates thread was Macroscope reading a stale index; the method has been there since 24951097.

Recorded on Linear rather than fixed here: SnoozeIssue (EXT-12) and aggregate / Count (EXT-7) are in the epic scope but were never delivered; both are commented on their story with what exists instead. EXT-4's rate-limit figures were low by a factor of 4 to 15 and have been corrected against rate_limits.rb. The three findings declined as repo-wide now have tickets of their own, so they outlive these threads: EXT-19 (.releaserc.js chaining with ;), EXT-20 (no datasource gemspec declares the Forest gems) and EXT-21 (a non-positive page limit).

Behaviour outside the new package

Three files, each additively, to register the gem: .github/workflows/build.yml (test matrix, coverage files:), .releaserc.js (prepareCmd, successCmd, git assets) and .rubocop.yml (MFA opt-out, the version.rb string cops, and the per-file metric excludes the package actually trips).

Two entries in build.yml, not three: #380 replaced the lint job's per-package matrix with a single root bundle exec rubocop, which is where the merge conflict was and what 219d8bcc resolves. That PR also rewrote step 5 of CLAUDE.md to say the lint job needs no entry, so the guidance and the workflow agree again -- the four points of CLAUDE.md are covered against its current text.

Verification

Re-run locally on cbaa5619, Ruby 4.0.2:

• forest_admin_datasource_pylon: 827 examples, 0 failures, line coverage 100.0% (1755/1755).
• The packages the cross-package fixes touch, and their neighbours: forest_admin_agent 1180, forest_admin_datasource_toolkit 486, forest_admin_datasource_customizer 703, forest_admin_datasource_active_record 203 — all 0 failures. RuboCop over the whole repo: 911 files, 0 offense.
• forest_admin_datasource_mongoid could not be run locally (its gems are not installed on this machine); CI covers it.

.releaserc.js was loaded through node to confirm both prepareCmd and successCmd are valid concatenations, and both YAML files were parsed. forest_admin_datasource_pylon is unclaimed on RubyGems, so the first publish creates it.

Three fixes from the seventh pass

Local re-run on b6bd085b, Ruby 4.0.2: 794 examples, 0 failures, line coverage 100.0% (1695/1695), branch 94.3%, RuboCop 71 files / 0 offense.

• d75bab2c — an and names the records all of its conditions name, so two id leaves name their intersection. Both the lookup short-circuit and the write-resolution bound kept only the first and left the second to be applied later, which put the cap around the wider set: a selection of 25 ids narrowed to 3 was refused over the 25 it named, after reading all 25 one request each. Worth being exact about the failure — the refusal is an explicit UnsupportedOperatorError, never a short page, so this over-refused rather than under-delivered. extract_id_lookup now partitions the id leaves out of the branch and intersects them, leaving the residual, ensure_residual_appliable! and guard_nil_comparisons untouched; disjoint sets reduce to the empty lookup with no request at all. writes.rb#filtered_ids moves with it, that count being what refuse_unresolvable_selection is worded around — its own comment had been excusing the same shape. Narrow on the read side: only PylonIssue reaches the and branch, cursor collections short-circuiting on a bare leaf alone.
• 524cc95e — IssueTargets.resolve_issue_ids rescued StandardError and answered [], which the action reports as "No Pylon issue selected." That swallowed the datasource's own refusals: a bulk CloseIssue on PylonIssue, with a scope or segment set and more than MAX_ID_LOOKUPS records selected, raises inside list and the operator was told nothing was selected about a selection they can see they made. A Pylon outage read the same way. A ValidationError now travels, the agent surfacing its message; everything else still degrades, so a renamed column is still "no issue selected" rather than a stack trace in the panel.
• b6bd085b — the README's CloseIssue caveat had the scope question backwards. It said a scope on PylonIssue does not bound what the action closes, on the grounds that the state is written through the client. The ids are resolved first, through the collection the action sits on, and Actions#get_record_selection intersects the operator's scope into the filter that reads them — so mounted on PylonIssue, the scope bounds exactly what it closes. What the caveat describes is the host-collection form, where the ids come off a column and that column is the authority. As written it told an operator a scope bought them nothing when it bought them the whole selection.

Human review, and main merged in

Three commits since the seventh pass. a08ab420 answers the four findings @matthv raised on the assembled branch, 219d8bcc merges main, e1865da7 closes the last open Macroscope thread of the previous pass.

Commit	Kind	Content
a08ab420	fix	refuse an edit reduced to nothing; bound what one 429 costs; follow the cursor of an endpoint documented unpaginated; pin the residual/page-window order
219d8bcc	chore	merge main, resolving the build.yml conflict
e1865da7	fix	keep the user-info of a base url out of an inspect

The four findings

• update reported a success on a patch it dropped entirely. writable_attributes drops read-only and unknown keys, and a patch reduced to nothing hit return if attributes.empty?: the route then re-reads the record and hands back the values it already had, so the operator watched their change revert with no reason given -- the exact answer the module's preamble says it refuses. Refused now, naming the keys. Deliberately narrow: a dropped key alongside a real edit is still dropped and the edit performed, and a patch naming no field at all (a form whose every field is a relation) still asks for nothing. The refusal also stays settled before the ids are, so a wide selection with an unwritable patch is refused for its patch and spends no request.
• One 429 episode could hold a thread for ~3 minutes. faraday-retry sleeps the raw Retry-After whenever it fits under max_interval, so max_retries: 3 against a per-minute quota meant up to 180s of blocking sleep, plus the Throttle waits inside the retry -- on a request the Forest server had long since timed out, and multiplied by the 20 sequential calls one list view may spend. DEFAULT_MAX_INTERVAL is 12 rather than 65, which is the figure that keeps the sleeps of a whole request under a minute (3 x 12 plus 4 x RateLimiter::DEFAULT_MAX_WAIT = 56s); past it a 429 surfaces as an error instead of being waited out. A spec computes that bound rather than asserting the constant, so it cannot drift silently. The trade is stated in the code and in the README, with the snippet to choose the other way.
• Client#fetch_all ignored the response's pagination block. FetchAllCollection builds its exactness guarantee -- including the package's only exact aggregate -- on "the records in hand are all of them", so the day Pylon paginates GET /users or GET /teams its first page would silently become everything. The cursor is followed now, the way /messages already was, and refused rather than truncated past MAX_COLLECTED_PAGES: a count answered short and presented as exact is the one answer this datasource refuses everywhere else. Zero cost today -- no pagination block is advertised, so the walk leaves after the first page and spends the single request it always did.
• Missing test: residual combined with a page window. Every residual spec used a filter without a page, so the ordering in records_by_id -- residual first, page_window second -- was pinned by nothing. The added example was checked against the regression rather than only against green: flipping the implementation to slice the ids first makes it fail with expected [i3], got [i2].

The inspect hardening, which the previous description had left as a follow-up and which the eighth Macroscope pass then raised as its own finding: base_url is operator-supplied, and an egress proxy fronting Pylon is spelled https://user:pass@proxy.internal. Both places that printed the url printed that user-info in clear. Configuration#redacted_url is now what the two inspects print -- the finding named Client#inspect alone, but Configuration#inspect printed @base_url the same way. Cut with a regexp rather than parsed: nothing validates that the base url parses, and an inspect raising on the way to a Rails error page would replace the page with its own failure.

Open items before merge

• CI is green. Run 33509392217 on e17c4328, and 33498265681 on the merge commit 219d8bcc -- the latter being what validates the resolved workflow, the lint job now being the single root RuboCop run of ci(build): halve CI wall clock by parallelizing jobs and caching gems #380 while pylon keeps its two test jobs and its coverage entry. The run for cbaa5619 is in flight at the time of writing. Earlier: 33158331718 on 3e38d094, 33084670532 on b6bd085b, both successful on Ruby 3.4 and 4.0.
• The eighth Macroscope pass is answered. Thirteen findings, verified one by one; seven led to a change (e17c4328, cbaa5619), six are answered in thread. What it caught, and what it got wrong:
  • Its best catch was on this branch's own new code. collect_pages treated an empty page advertising a cursor, and a cursor answered twice, as the end of the collection -- so refuse_past_cap had closed the exactness hole for the page cap alone. Only next_cursor being nil is Pylon saying there is nothing more; every other stop is now a truncation the caller reads as a warning or as a refusal.
  • Four more real, and fixed: an integer custom field past 2**53 read through a Float (parsed as an integer now, in base 10 explicitly -- Integer("012") is 10, so the suggested patch would have renumbered every zero-padded value); a timezone checked stripped and stored unstripped, falling back to UTC on a padded identifier; CloseIssue letting two variants configured with the same name overwrite each other in the collection's action hash; and an :action_name given as a Symbol reaching the schema, where get_action_slug calls strip on it and GeneratorCollection sorts it against a String -- schema generation, so the whole agent, not the action.
  • Two bugs outside the package, both found by verifying a finding rather than in it. Charts#compute_value indexed result[0]['value'] while Aggregation#apply answers an empty selection with no row, so a filtered value chart matching nothing was a 500 where the figure is zero -- reachable from every collection that aggregates in memory. And Aggregation compared Max with <, so every Max chart over an in-memory aggregation answered with the minimum, on every datasource; no spec covered Max at all. Both fixed, with specs.
  • Its one Critical does not hold. messages is not a relation: it is a single column whose column_type is [MESSAGE_THREAD_SCHEMA], a nested object shape the agent projects whole, and every field the finding names (is_private, author_email, both author ids) is a declared member of that column's own type -- covered by the operator's permission on the column. No agent path produces the messages: sub-projection it assumes. The comparison with RelationEmbedder is what misleads: that one re-projects because it embeds records of another collection, carrying their own permissions.
  • One High is not reproducible as described. update_summary_in_place guards with if value, so false is skipped and no TrueClass/FalseClass comparison ever happens. It answers wrongly rather than raising -- a Boolean Min can never report false -- which is filed with the Sum/Avg-over-a-String finding as EXT-23, both being the same method applying an operation the column type cannot take.
  • Two accurate limitations, filed rather than rushed: a nested and carrying an id is refused instead of resolved, on the read and the write path (EXT-22). It fails closed, and ConditionTreeFactory.group flattens one level, so every shape the agent builds keeps its id at the top level.
  • One already answered in the code: the Date/Dateonly operators the validator rejects are described in the comment above TIME_OPS, with the toolkit contradiction tracked as PRD-989. And one left as it is: Time/DateTime filter bounds losing their fractional seconds is unreachable through the agent, Transforms::Times already handing over second-truncated strings from the same iso8601 call one layer up.
• The 44 qlty threads are resolved without a change, deliberately. 26 function-parameters (count = 4), 16 function-complexity, one file-complexity on base_collection.rb and one identical-code on the scaffold Gemfiles -- which are identical because CLAUDE.md asks for them to be mirrored. The repo carries no .qlty config, qlty check reports No blocking issues, and the three raised on this pass's own code (collect_pages, refuse_truncated_walk, log_truncated_walk) are all the 4-parameter threshold, where each parameter is a value the message or the walk names. Resolved so that an open thread on this PR means feedback still to answer, rather than advisory noise.
• Deliberately not fixed here, each with the reasoning recorded in thread:
  • CloseIssue's batch is uncapped: one request per selected record, so a wide bulk selection is a long sequential run the request may time out on, leaving what it already closed closed. Stated in the README (96a0575a, reworded in b6bd085b); putting a cap on a bulk action is a product call, not a defect fix. Worth knowing that Writes::MAX_WRITE_REQUESTS refuses exactly this shape at 20 requests on the collection itself, so the datasource currently answers the same question two ways.
  • NIL_UNSAFE_OPERATORS and residual_leaf_appliable? are derived from two different sets, so the guard is narrower than what the residual admits and only the upstream OperatorsEquivalence rewrite closes the gap. Not reachable today; deriving the guard from the equivalence touches the filtering path of every collection.
  • Configuration#validate! checks neither that base_url parses nor that it is https, so a typo surfaces as a raw URI error at the first request and an http:// base url would carry the bearer token in clear on the wire. Refusing http would break local mock servers, so this wants a warning rather than a refusal, in its own change. (What an inspect prints is no longer part of this item: e1865da7 closes that half.)
• A human review.

🤖 Generated with Claude Code

Note

Add ForestAdminDatasourcePylon datasource with API client, collections, and plugins

• Introduces the ForestAdminDatasourcePylon gem, exposing Issue, Account, Contact, User, and Team collections backed by the Pylon API.
• Adds an HTTP client with retry policies, per-endpoint rate limiting, and Pagination::CursorWalker to handle cursor-based pagination.
• Implements read and write operations for all collections, including custom field introspection and relation embedding.
• Adds CloseIssue and CreateIssueWithNotification plugins for issue management actions.
• Fixes ConditionTreeBranch#match in condition_tree_branch.rb to preserve nested branch structure during matching.
• Risk: The ConditionTreeBranch#match fix changes how nested And/Or branches are evaluated; verify existing toolkit consumers depending on flattened leaf evaluation are unaffected.

Changes since #369 opened

• Added credential redaction to URL display in ForestAdminDatasourcePylon package [e1865da]
• Fixed Max aggregation returning minimum value instead of maximum and value charts crashing on empty result sets [e17c432]
• Added explicit truncation detection and handling for paginated cursor walks in Pylon datasource client [e17c432]
• Prevented silent action name collisions when registering CloseIssue plugin with multiple scopes [e17c432]
• Preserved full integer precision and base-10 interpretation in numeric field coercion [e17c432]
• Stripped surrounding whitespace from timezone identifiers in filter value initialization [e17c432]
• Modified ForestAdminDatasourcePylon::Plugins::CloseIssue.name_for to coerce action names to strings and added documentation comments [cbaa561]
• Added test coverage for string coercion and collision detection of action names in ForestAdminDatasourcePylon::Plugins::CloseIssue [cbaa561]

^{Macroscope summarized 219d8bc.}

[linear-code]

EXT-4

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.5%.

Modified Files with Diff Coverage (46)

Rating	File	% Diff	Uncovered Line #s
	...est_admin_agent/lib/forest_admin_agent/routes/charts/charts.rb	100.0%
	...forest_admin_datasource_pylon/collections/cursor_collection.rb	100.0%
	...pylon/lib/forest_admin_datasource_pylon/collections/contact.rb	100.0%
	...orest_admin_datasource_pylon/collections/contact/serializer.rb	100.0%
	..._pylon/lib/forest_admin_datasource_pylon/query/filter_value.rb	100.0%
	...tasource_pylon/lib/forest_admin_datasource_pylon/datasource.rb	100.0%
	...pylon/lib/forest_admin_datasource_pylon/query/operator_maps.rb	100.0%
	..._pylon/lib/forest_admin_datasource_pylon/collections/writes.rb	100.0%
	...st_admin_datasource_pylon/lib/forest_admin_datasource_pylon.rb	100.0%
	...b/forest_admin_datasource_pylon/collections/base_collection.rb	100.0%
	...ce_pylon/lib/forest_admin_datasource_pylon/collections/team.rb	100.0%
	...ce_pylon/lib/forest_admin_datasource_pylon/collections/user.rb	100.0%
	...rest_admin_datasource_pylon/collections/contact/api_filters.rb	100.0%
	...est_admin_datasource_pylon/collections/fetch_all_collection.rb	100.0%
	..._admin_datasource_pylon/collections/issue/messages_embedder.rb	100.0%
	...e_pylon/plugins/create_issue_with_notification/form_builder.rb	100.0%
	...lon/lib/forest_admin_datasource_pylon/plugins/issue_targets.rb	100.0%
	...pylon/lib/forest_admin_datasource_pylon/plugins/close_issue.rb	100.0%
	...dmin_datasource_pylon/collections/account/schema_definition.rb	100.0%
	...t_admin_datasource_pylon/collections/issue/id_lookup_reader.rb	100.0%
	...source_pylon/plugins/create_issue_with_notification/payload.rb	100.0%
	...rest_admin_datasource_pylon/collections/account/api_filters.rb	100.0%
	.../forest_admin_datasource_pylon/plugins/close_issue/messages.rb	100.0%
	...min_datasource_pylon/plugins/create_issue_with_notification.rb	100.0%
	...asource_pylon/lib/forest_admin_datasource_pylon/issue_enums.rb	100.0%
	...n_datasource_pylon/lib/forest_admin_datasource_pylon/client.rb	100.0%
	...ource_pylon/lib/forest_admin_datasource_pylon/configuration.rb	100.0%
	...forest_admin_datasource_pylon/collections/relation_embedder.rb	100.0%
	.../forest_admin_datasource_pylon/collections/issue/serializer.rb	100.0%
	..._admin_datasource_pylon/collections/issue/schema_definition.rb	100.0%
	...est_admin_datasource_pylon/collections/record_serialization.rb	100.0%
	...orest_admin_datasource_pylon/collections/account/serializer.rb	100.0%
	...forest_admin_datasource_pylon/collections/issue/api_filters.rb	100.0%
	...e_pylon/lib/forest_admin_datasource_pylon/collections/issue.rb	100.0%
	...pylon/lib/forest_admin_datasource_pylon/collections/account.rb	100.0%
	.../lib/forest_admin_datasource_pylon/pagination/cursor_walker.rb	100.0%
	...dmin_datasource_pylon/collections/contact/schema_definition.rb	100.0%
	...rest_admin_datasource_pylon/query/condition_tree_translator.rb	100.0%
	...ource_pylon/lib/forest_admin_datasource_pylon/client/writes.rb	100.0%
	...components/query/condition_tree/nodes/condition_tree_branch.rb	100.0%
	...orest_admin_datasource_toolkit/components/query/aggregation.rb	100.0%
	...asource_pylon/lib/forest_admin_datasource_pylon/rate_limits.rb	100.0%
	...source_pylon/lib/forest_admin_datasource_pylon/rate_limiter.rb	100.0%
	...st_admin_datasource_pylon/schema/custom_fields_introspector.rb	100.0%
	...source_pylon/lib/forest_admin_datasource_pylon/retry_policy.rb	100.0%
	...datasource_pylon/lib/forest_admin_datasource_pylon/throttle.rb	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[matthv]

Review of the assembled branch at 3e38d094 — the important points (full detail available on request):

1. update reports success on a patch it dropped entirely — collections/writes.rb:53-54. writable_attributes silently drops unknown and read-only fields; a patch reduced to nothing hits return if attributes.empty? and the agent reports a successful edit that never landed — the exact failure the module's own preamble says it refuses. A non-empty patch with zero writable attributes should raise UnsupportedWriteError naming the dropped fields.

2. One Pylon 429 episode can hold a server thread for ~3 minutes — retry_policy.rb:52. faraday-retry sleeps the raw Retry-After whenever it is ≤ max_interval (65), so max_retries: 3 × Retry-After: 60 is up to 180s of blocking sleep, plus up to 4 × 5s of Throttle waits (the throttle sits inside the retry); f.options.timeout covers only the adapter. A few concurrent list views park most of a Puma pool during a 429 episode. Worth a wall-clock budget per request, or max_retries: 1 at this interval.

3. Client#fetch_all ignores the response's pagination block — client.rb:157-159. FetchAllCollection builds its exactness guarantee — including the package's only exact aggregate — on "the records in hand are all of them". If Pylon starts paginating GET /users/GET /teams (the client already follows cursors defensively on /messages for this very eventuality), the first page silently becomes "everything": counts and filters turn into fractions presented as exact, with no log and no error. One if pagination['has_next_page'] — follow with collect_pages, or raise — buys the tripwire.

4. Missing test: residual + page window combined — spec/.../collections/issue_spec.rb:604. Every residual test uses a filter without a page, so the ordering in records_by_id — apply the residual first, slice page_window second — is pinned by nothing; a regression slicing first would answer pages with silently missing records and pass the suite. One example locks it: And(id IN [i1,i2,i3], state = new) where only i2/i3 match, page(offset: 1, limit: 1) expecting [i3].

Also: the latest Macroscope finding is not addressed — client.rb:134 (2026-08-28, High: Client#inspect prints @configuration.url unredacted, so a base URL carrying user-info leaks credentials into logs/error pages). No reply in the thread and the code at 3e38d094 is unchanged.

[forest-bot]

🎉 This PR is included in version 1.41.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀