Status: Design proposal. This document is not normative in the sense product-spec.md is — it mints no
requirement IDs — but every architectural decision below is justified against, or deliberately deviates from, a
specific requirement in that specification. Read product-spec.md first; this document assumes its vocabulary
(SEAM-*, HTTP-*, IO-*, BODY-*, CTX-*, PIPE-*, RECOV-*, RETRY-*, REDIR-*, AUTH-*, PAGE-*,
SSE-*, SERDE-*, OBS-*, CFG-*, TRANSPORT-*, ASYNC-*, XCUT-*, NFR-* — 645 requirements across 19
prefixes) and cites IDs inline rather than re-deriving them. Where an argument turns on exact wording, the
requirement is quoted verbatim.
Scope. This is a gem-and-seam-level architecture for a Ruby implementation of the same product: an HTTP-client
toolkit, not an HTTP client. It covers the monorepo and gem layout, the idiomatic Ruby mapping of each of the
spec's five seams and its async pivot, domain-model construction under Data.define, both pipeline layers,
resilience (retry/redirect/auth), pagination/SSE/serde, instrumentation and configuration, and the toolchain that
enforces mechanically the quality bar the reference build enforces mechanically. It does not contain Ruby
source, a gemspec, a Rakefile, a Steepfile, RuboCop configuration, RBS signatures, or CI YAML — those are
downstream of this document, produced when the port is actually undertaken. It does not specify a code-generation
layer; it specifies only the runtime primitives a generator would target (§3.5). It does not choose a wire
protocol beyond HTTP/1.1 for the reference transport, nor does it design the service-client surface a generator
would emit on top of it.
Reconciled 2026-09-25 against the as-built tree. The chapters below were written before the code and are kept
as written, except where the shipped code proved a sentence wrong: each such sentence is corrected in place with a
dated, bracketed note quoting what it replaced and citing its amendment in docs/deviations.md (C1–C25), and
§10 — the deviation ledger — gains entries 20–38, consolidating every deviation from the reference contract the
phases' own ledgers recorded and the chapter did not. §12 is brought into line with both.
- Porting Method
- 1. Overview
- 2. Gem and Workspace Layout
- 3. Seam-by-Seam Idiomatic Mapping
- 4. Domain Model Construction
- 5. Pipeline Architecture
- 6. Retry, Redirect, and Authentication
- 7. Pagination, SSE, and Serialization
- 8. Instrumentation and Configuration
- 9. Toolchain and Quality Gates
- 10. Deliberate Deviations from the Reference Contract
- 11. Appendix: Reference-Spec Ambiguities and How This Port Resolves Them
- 12. Appendix: Requirement Coverage Index