Phase 4b: recovery-chain primitives — the recovery layer

[Wahbeh-Mohammad]

Part of #15. First of three phase 4b PRs — the code. Its tests are #54 and the phase record is #55.

What lands

§8.2's resilience layer in dexpace-core — 40 files, +1,841 / −33 — and the error primitives four earlier postponements and five later phases have been waiting on. Nothing here talks to a socket, 4b adds no require of any kind beyond require_relative (the visited set is {}.compare_by_identity, never set), and the gemspec keeps zero add_dependency lines.

• Dexpace::Suppressible — the suppressed-exception trail phase 1 postponed to phase 4, as a separate module Dexpace::Error includes and Dexpace.attach_suppressed extends onto a caller's exception (P4-12: rescue M matches a module reached through a singleton class, so the rescue root cannot be the thing extended, or rescue Dexpace::Error would start catching errors the SDK never raised). #suppressed is a frozen array replaced on every attach (P4-14); a frozen primary is a silent no-op (P4-13); the skip-self guard RETRY-34 needs; #detailed_message renders the trail so #full_message and the default printer show it. Dexpace.suppressed(error) reads a trail off anything.
• Dexpace.each_cause (XCUT-9) — yields the error first (P4-16), tracks by reference identity through compare_by_identity — an Array truncates a chain of structurally-equal errors and a Set is defeated by a caller's hash/eql? override, both measured — stops at a #cause that raises or lies, and returns an Enumerator without a block.
• Phase 2's two retrofits, exactly as its postponements asked. Hooks.notify attaches every later handler failure to the first and re-raises it with cause: nil; Dexpace.close_quietly(resource, onto: nil) gains the first of its two disposal routes (the diagnostic half stays phase 5b's). Three phase-2 lib files change and nothing else of phase 2's does.
• Dexpace::Outcome with exactly two variants, Success and Failure (RECOV-1), Data + Model + validating .build, #fold requiring both branches, #response_or_nil / #error_or_nil (P4-21), and deconstruct_keys working under private_class_method :new.
• Dexpace::OutcomeError (R6, P4-19) — a fold's own defect, re-raised by name through the orchestrator rather than demoted to a Failure a recovery step could swallow; Dexpace::ProtocolError — XCUT-4 branch (a), one class carrying #status and #response with no subclass tree (P4-20), .for raising for a non-error status and .for_or_nil returning nil (XCUT-8's two forms), a message of "HTTP 404 Not Found" with no body preview. No #retryable? and no #retryable_by_status? — XCUT-5's flag is postponed to phase 6a, Task 6, and the RECOV-15 checklist row says so.
• Dexpace::Recovery.buffer_error_body(response) — the contract phase 3b fixed: the same object back for a non-error status or a nil body, otherwise Body.buffer_bounded with MAX_BUFFERED_ERROR_BODY_BYTES and no second constant (RECOV-16, BODY-30).
• Dexpace::Recovery::Transform — R8's single-sourced contract 4c's generic adapter consumes: #phase, #apply(value) and the one default #call(value) = apply(value) (P4-25) so a transform installs into a chain by bare reference, beside any lambda. The three shipped transforms: IdempotencyKeyStep (RECOV-32, POST/PUT/PATCH by default, a GET untouched by identity), ClientIdentityStep (RECOV-33), ErrorMappingStep (RECOV-15, PIPE-37: a non-error response passes through by identity with its body never read; an error response is buffered, the original closed, and the factory's error raised carrying the buffered response; factory: overridable, the default a frozen private lambda over ProtocolError.for).
• RequestChain (RECOV-3, a left-to-right fold) and ResponseChain (RECOV-4–RECOV-8: response steps on Success only, recovery steps on every outcome, in order, a throwing step becoming the Failure the next recovery step sees), both dup+freezeing their step lists (RECOV-14, P4-22); the private Ownership helper concentrating RECOV-12/RECOV-13's asymmetry — a response in hand is closed exactly once on a throw, through close_quietly(response, onto: error) so a close failure lands on the primary's trail instead of replacing it, and never on a deliberate substitute outcome. "Exactly once" is phase 2's Closeable latch, not bookkeeping.
• Orchestrator (RECOV-2, RECOV-10, RECOV-11) — a Dexpace::Transport duck type over #call(request, options, cancellation): one rescue region around the request fold, the transport call and the response fold, so a throwing request step reaches after-error handling; the fatal family and OutcomeError pass through untouched with no trail; every unwrap is raise error, cause: nil, because a bare raise error from inside a caller's rescue assigns that caller's unrelated $! as #cause on all three interpreters. RECOV-11 is satisfied structurally: phase 2's token has no clearable flag, so converting a CancelledError into a Failure cannot swallow the signal, and the suite asserts that on the token (P4-17).
• sig/ mirrors lib/ one file per file — sixteen mirrors, ownership.rbs among them with hooks.rbs's comment on why a private_constant still needs one for the strict core target; the module functions declared beside their defining files, sig/dexpace.rbs unchanged. YARD 100% (418 methods). The surface manifest regenerated once (515 → 586 rows, all 71 re-derived by hand from the object model — Data readers and singletons included — and nothing private leaked). The core smoke suite's constant list is on this branch because the code change invalidates it.

Decisions taken in the open, against the plan's text

Twenty-seven are itemised in the checklist's "Deviations from the plan" and ten carry ledger rows P4-40–P4-49. The ones a reader should know: Suppressible#detailed_message(options = nil) takes one optional positional Hash, not **kwargs — Dexpace/NoKeywordSplat forbids the splat on a public lib method, and the forwarding was measured identical for the default printer, full_message and did_you_mean on 3.2.11, 3.4.10 and 4.0.6 (P4-40); Orchestrator#call takes three required positionals, matching phase 2's bridges and Transport.conforms?(arity: 3), not the plan's two optionals; Transform's RBS is the generic [T] (T) -> T because Steep could not type the overloaded forward; boundary validation the design did not name (a step's non-Request/Response return, a factory's non-Exception, a transport's non-Response — P4-45); Ownership closes through close_quietly(onto:) and rescues StandardError only, so the design's rescue ::Exception; raise arm is its behaviourally equivalent absence (P4-47, proven by experiment and by mutation).

Layering

Each tip of the stack is green under every gate on its own tree. This branch is green on the SimpleCov floor too — 94.64% on 4.0.6 (1,154 runs, 0 failures), because the phase-2 suites reach the retrofits and the smoke suite loads the layer. The tests PR takes the same tree to 99.97% (3,396 / 3,397; the one uncovered line is phase 2's registry race-only branch).

Verification

• Independent reviewer, approve on round 0 — 0 blocking, 0 should-fix, 4 nits (below). It re-ran all seventeen gates individually here on 4.0.6, bundle exec rake on the two upper tips, the matrix set on 3.2.11 (both this tip and the tests tip) and 3.4.10, and the probe.
• 43 single-edit mutations applied by the reviewer (39 by the implementer), every one caught: the bare raise error on the unwrap and the Array/Set visited-set spellings red on 3.2.11 as well as 4.0.6 (a raise-built pair is not == there, which is why the fixture constructs and never raises); OutcomeError and LoadError rescued into a Failure; response steps run on a Failure; the fold interleaved; Ownership closing zero and two times; the step lists aliased; ErrorMappingStep reading a 200's body; a literal 1_048_576 for the constant.
• By experiment on both interpreters: RECOV-10 with a constructed versus a raised fixture (the surfaced error is the same object with #cause nil only for the constructed one); the trail on a bare ::IOError (is_a?(Suppressible) true, is_a?(Dexpace::Error) false, rescue Dexpace::Error does not catch it, a frozen primary returns unchanged); the three cycle fixtures under timeout; three raising on_cancel handlers; RECOV-11 asserted on the token; the ownership counts over RecordingBody; a 2 MiB error body truncated to exactly the constant with the original released once; case/in under private new.
• grep over the added lib: zero plain requires, zero synchronize/Mutex/Thread, one rescue region in the orchestrator, every unwrap cause: nil, Dexpace::ArgumentError never defined, the sixth cop 0 offenses; honest RuboCop 261 files, no offenses.

Known follow-ups from the review (not blocking)

• R0-2 — no literal rescue ::Exception; raise arm in the orchestrator or Ownership; the tree's rescue OutcomeError; raise; rescue ::StandardError is equivalent (fatal family and OutcomeError pass through, mutations widening either region go red). Recorded as P4-47; add the literal arm only if the design's R6 shape is wanted verbatim.
• R0-4 — the three transforms, both chains and the orchestrator are not freezed after .build; their members are frozen and they hold no per-call state, which is what RECOV-14 asks, and no ID or design sentence requires the instance frozen. A cheap hardening if wanted.
• Two committed phase-2 sentences are now false and are the manager's to rewrite, not this stack's: phase 2's design paragraph "Every handler runs, whatever an earlier one did" / its plan's "drops the rest" bullet, and the four places naming Dexpace::Error#suppressed as the carrier (it is Dexpace::Suppressible). Design §10 item 6 and §5.2 say the same and are frozen — routed to docs/first-release.md's C1–C13 blocker as C14 on Phase 4b: recovery-chain primitives — documentation and phase record #55.
• The Body.stream-over-a-closed-stream ::IOError from Phase 3b: body lifecycle — the body layer #50 and the C14 placement are noted on Phase 4b: recovery-chain primitives — documentation and phase record #55.