docs(platform): design forge retry-after error surface (RIG-2255) - #653
Open
rigel-mintaka wants to merge 1 commit into
Open
docs(platform): design forge retry-after error surface (RIG-2255)#653rigel-mintaka wants to merge 1 commit into
rigel-mintaka wants to merge 1 commit into
Conversation
|
Compass engineering docs preview: https://compass-forge-rig-2255-retry.compass-eng-docs.pages.dev Deployed from Changed pages: |
rigel-mintaka
force-pushed
the
compass-forge/rig-2255-retry-after-surface
branch
from
August 26, 2026 07:23
bbacb51 to
e0916be
Compare
Carry the rate-limit reset hint on the forge budget-exhausted error surface
so ForgeCallError.retry_after_ms (structurally always 0 today) is populated:
a dedicated forge.RateLimitError{RetryAfter time.Duration} that unwraps to
ErrBudgetExhausted, emitted from both providers' live and fail-fast sites.
Design record only; impl is a follow-up PR. Ledger delta assigned at freeze.
Refs RIG-2255
Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-forge/rig-2255-retry-after-surface
branch
from
August 26, 2026 07:33
e0916be to
dfeee9a
Compare
rigel-mintaka
marked this pull request as ready for review
August 26, 2026 07:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design record for RIG-2255: the forge write chokepoint's
ForgeCallError.retry_after_mswire field is structurally always 0 because no forge error type carries the rate-limit reset out of the provider client.Approach
A dedicated
*forge.RateLimitError{RetryAfter time.Duration}ingo/internal/forge/provider.gothatUnwrap()s toErrBudgetExhausted, replacing the bare sentinel wrap at every emission site.errors.Is(err, ErrBudgetExhausted)keeps matching (the poll driver's skip contract, the server'sresource_exhaustedarm, and all existing tests are undisturbed);errors.Asrecovers the hint atmapForgeError. The reset is carried as atime.Durationcomputed client-side via the injectable clock, so the server conversion toretry_after_msis clockless clamped arithmetic. Covers GitHub + Linear, both the live-response classifier and the fail-fast gate.Option B (widen
StatusErrorand reroute rate limits through it) rejected on grounded evidence: it breaks the poll driver's sentinel skip/abort classification and misses the dominant carrier (a rate-limited 403/429 never becomesStatusError{429}today).Review history
Design-critic red-team (pre-freeze): 0 blocking, 0 load-bearing forks for Matt; 1 medium + 3 low folded (the
X-Ratelimit-Reset-only-429 dropped-hint edge documented out-of-scope; proto-comment semantic widening; test-site enumeration; count phrasing). Core choices (option A,time.Duration, provenance-agnostic fail-fast hint) all ratified.Scope boundary
Populates the existing
retry_after_msproto field; does not reshape it (confirmed forge-internal with compass-server, the field's lane owner). Design record only — implementation (T1-T5 in the record) is a separate follow-up PR.Refs RIG-2255
Ledger-impact: adds DL-268 (Comms & tools; forge rate-limit reset hint surface) in this PR; no rows superseded. Numbered DL-268 to clear #634's in-flight DL-264..267 block — a temporary 264-267 gap on this branch fills when #634 lands.
Spec-impact: none