Skip to content

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.

  1. 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.
  2. Wrap for one design language. A wrapper standardizes setup and call syntax: configuration is a frozen dataclass or a settings-facade field, errors are AppException subclasses, 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.