ADR-0001: Standards and proven libraries come first; pykit wraps, never reimplements
Status: accepted (2026-09-21) · Scope: every rn-forge-* package,
existing and future
Decision
pykit is a thin, consistent layer over published standards and maintained libraries. It supplies only what they leave missing.
- Don't reimplement a proven library. If a maintained, widely used package already does the job, depend on it. Zero dependencies is not a goal; a small, deliberate dependency set is. Hand-roll only when one of these is true, and say which one in the module docstring: nothing maintained covers the concern (check PyPI, not memory); the candidate drags in a framework that would break a package boundary; or the needed slice is a few lines and the candidate is unmaintained or far heavier.
- Wrap for one design language. A wrapper standardizes setup and call
syntax: configuration is a frozen dataclass or a settings-facade field,
errors are
AppExceptionsubclasses, logging is injected, and public symbols are re-exported from the package's curated__init__.py. It does not add features the library lacks, fork it, or vendor it, and the underlying object stays reachable. - Adopted first. Once a library or framework is adopted for a concern, delete everything in the kit it already does, including code that predates the adoption.
- Published standards set the wire. An RFC or W3C standard governs where one exists. Google's API Improvement Proposals (AIPs) rank below RFCs: they break ties where no RFC applies, and adopting one is not a commitment to the rest.
- Wire indistinguishability. A consumer must not be able to tell from the wire whether an API was built with pykit, with native libraries, or on another stack. There is no house header, envelope or identifier.
- pykit is upstream. Applications are built on these packages rather than re-deriving them. Surveys of existing applications are prior art that informs the design, not compatibility constraints to preserve.
When a plan or a change conflicts with one of these rules, the rule wins unless the deviation is written down with its reason.
Consequences
Adopting a library is also a deletion task; an adoption is not done while the kit still duplicates it. An implementation may keep a focused wrapper where an evaluated library cannot produce the agreed contract, and records why. Framework-native extension points are the first choice for adapter wiring.
Request correlation shows the rules applied together: W3C Trace Context through
OpenTelemetry is the only correlation, and X-Correlation-ID is neither read
nor sent, because no standard names it and a caller would need pykit-specific
knowledge to use it. The rn-forge-web API conventions state the resulting wire
contract.
Influences
This decision shapes every epic, most directly E4 standards re-baseline and E6 consumer reuse. ADR-0002 and ADR-0003 state the package boundaries these rules operate within, and ADR-0005 applies them to the HTTP contract.
Alternatives considered
Replacing focused code with a library that cannot produce the agreed contract
would add a dependency without removing the code. Treating AIPs as a design
commitment would import conventions, such as updateMask or AIP-193 errors,
that conflict with RFCs already in force. Keeping X-Correlation-ID, alone or
as an alias beside Trace Context, would give a correlation value no standard
defines, or two that can disagree.
Background
Rules 1, 2 and 6 were the root README's design principles from 2026-09-07. Rules 3–5 were decided 2026-09-21 in the owner-requested standards review; the adopted-first rule became a standing rule on 2026-09-23. Recorded here 2026-09-24. On 2026-09-26 the README principles moved into this record, and the Trace Context decision was folded in as the worked example above.