Skip to content

ADR-0005: One framework-neutral HTTP contract, adapted natively by each framework

Status: accepted (2026-09-11) · Scope: rn-forge-web and every framework adapter package

Decision

rn-forge-web owns the shared HTTP wire: its types, behavior and conformance cases. It imports no web framework. Each framework package adapts that contract through its framework's native request, response, schema and authentication hooks, and does not reimplement it.

Parity is enforced by the conformance table, not by review. Every framework adapter must pass every shared case. Each adapter's OpenAPI document must describe what its service sends; textual identity between generators is not a goal.

Consequences

The conformance table decides cross-stack behavior. A new cross-stack requirement enters rn-forge-web only when the contract itself is framework-neutral. A new framework adapter joins by passing the conformance table, not by extending another adapter. Package guides state the concrete API for each stack.

Influences

This decision shapes E2 HTTP contract, E3 framework adapters and E4 standards re-baseline. ADR-0001 sets the standards the wire follows; ADR-0002 enforces the import direction.

Alternatives considered

Normalizing generated OpenAPI text would require post-processing each framework's generator output; accurate documents and shared wire behavior are the requirement instead. A shared serializer abstraction would replace framework-native interfaces without creating a shared wire guarantee.

Background

Decided 2026-09-11 with the design of rn-forge-web; revised 2026-09-22, when the shared wire types became pydantic models in rn-forge-web (E4, F4.3). The conformance-table rule came from the standards review of 2026-09-21. Recorded here 2026-09-24. Until 2026-09-26 this record also stated that stacks share no ORM abstraction; that part was dropped as a non-decision, since each persistence package simply integrates its own technology.