refactor(core)!: RateLimitError extends StitchError

[rejifald]

What

RateLimitError and StitchError were siblings, both extending Error directly. This roots the taxonomy at StitchError and makes RateLimitError a subclass.

Raised while reviewing #639, which adds a second copy of the two-arm instanceof StitchError || instanceof RateLimitError check inside rebuildError — six lines below the one already there.

Why it wasn't just tidiness

CONTRACT.md P10 required the two classes to "guarantee the same field set … so a consumer can branch on any thrown error uniformly", and RateLimitError satisfied it by re-declaring status / attempts / body / url by hand. A written rule enforcing exactly what extends gives for free — and it already failed its own goal on one path:

SafeResult.error is typed StitchError, so .safe() had to coerce a delegate-backoff RateLimitError into a bare one. The instance moved to .cause, instanceof RateLimitError stopped working, and error.body came back undefined — dropping the payload an outer gate reads to pace itself. The mode whose entire purpose is handing back-pressure outward lost its signal on the path the docs otherwise recommend (.safe() over try/catch).

That was found independently from the consumer side by the scenario pass in #638 — docs/scenarios/issue-drafts/body-verdict-footguns.md, item 2, ".safe() downgrades RateLimitError and drops the body", severity medium, "an outer rate-gate backs off blind." This closes it.

The one hazard, and how it's handled

Subclassing makes arm order load-bearing: a leading generic instanceof StitchError now swallows the delegate signal.

• engine.ts's errEvt already had the order right (a RateLimitError also carries .response, so it always had to be tested first) — now commented as load-bearing.
• P10 states the rule; docs/errors/index.mdx and the delegate-backoff guide say it where they branch, and docs/errors/rate-limit.mdx carries a warning callout.
• The errors/index.mdx catalog example was already ordered correctly.

Changed

area	what
resilience.ts	RateLimitError extends StitchError; hand-mirrored P10 fields deleted, status narrowed to number via declare (no emit — a real field would clobber the base under useDefineForClassFields), gains cause
stitch.ts	both two-arm checks collapse to one instanceof StitchError; asStitchError stops downgrading, so .safe() returns the instance await throws
engine.ts	ordering comment only — behaviour unchanged
test-stub.ts	a stubbed RateLimitError keeps its identity, and the streamed error event now carries retryAfter the way the engine's does
docs	errors/rate-limit.mdx, errors/index.mdx, delegate-backoff guide, core README, CONTRACT P10 (parity by inheritance, with the history of why)

Verification

check:types · check:types-d · check:lint · check:format · check:contract · check:docs-links · check:changelog all green; 1440 core tests pass, full workspace suite green.

Two tests changed shape, both to assert the better behaviour: .safe() now yields the real RateLimitError (was: a wrapper with it on .cause), and the public-API surface test pins the hierarchy in both directions. A new test pins the whole inherited P10 field set plus name as the discriminator.

Breaking

Yes, for consumers branching on both classes — see the CHANGELOG entry for the migration. Core is 1.0.0-rc.7, so this is the cheap window; after GA it's a major.

🤖 Generated with Claude Code