feat(core): add the HTTP domain model — Request, Response, Headers, Status, MediaType, Protocol, QueryParams, RequestOptions, ETag, HttpRange, RequestConditions.

[Wahbeh-Mohammad]

Phase 1 — Core HTTP Domain Model

Implements the immutable, transport-agnostic HTTP domain model in @dexpace/core: the first real domain code
in the repository, and the first time the Phase 0 toolchain gates run against something other than a stub.

Governed by docs/product-spec/04-core-http-domain-model.md (normative), mapped to TypeScript per
docs/sdk-design-nodejs/04-domain-model-construction.md, planned in
docs/superpowers/plans/2026-07-23-phase1-core-http-domain-model.md.

---

Scope

Implemented: HTTP-3, 4, 5 (construction, immutability, derivation) · HTTP-6, 7, 8, 9 (request and method
legality) · HTTP-10, 11, 12 (status) · HTTP-13 – 22 (headers) · HTTP-23 – 27, 53 (media type) · HTTP-28 – 32
(query params) · HTTP-33 (protocol) · HTTP-34, 35 (request options) · HTTP-46, 47 (URL equality and
construction) · HTTP-48, 49, 50 (conditional-request helpers) · SEAM-29 (shared Builder<T> contract).

Verified, not newly implemented: SEAM-1. Phase 0 already satisfied it with an empty dependencies field;
this phase's job was to not break it while adding real logic, which verify:seam-1 confirms.

Deliberately deferred to Phase 3b: HTTP-36 – 45 (body lifecycle, TypedResponse<T>), HTTP-51
(MultipartBody), HTTP-52 (error-body cap), and HTTP-46's body-by-value equality clause. All depend on body
lifecycle contracts that Phase 3b owns. Request/Response carry body: unknown as an explicit placeholder —
this phase only needs presence-or-absence to enforce HTTP-7/8.

Note: the design doc's scope line still reads "HTTP-3 through HTTP-53" and needs correcting to match the
plan's own amendment (tracked as C1 in docs/open-items.md).

---

Architecture

Every model follows one construction shape. It is worth understanding once, because thirteen files repeat it
and none of it is enforced by tooling:

• #private fields, not TS private. Styleguide 6.7 carves this out for libraries whose internals must
  stay unreachable even reflectively.
• TS private constructor, so no public field-wise constructor reaches the emitted .d.ts and a consumer
  cannot construct around build()'s validation (HTTP-2).
• The createX friend-class hook. TypeScript has no friend classes, so each builder reaches its model's
  private constructor through a module-scoped let createX assigned exactly once inside the class's
  static {} block. Init-once wiring, not mutable state. Six instances: createHeaders, createQueryParams,
  createRequest, createResponse, createRequestOptions, createRequestConditions.
• Object.freeze(this) once, at the end of every constructor. Freeze is shallow and never relied on to
  cascade — nested arrays and Maps are frozen independently at build time (HTTP-5).
• newBuilder() deep-copies every collection, never aliases the source (HTTP-3). Value types with no
  builder (Status, Protocol, MediaType, ETag, HttpRange) use static factories instead, per HTTP-3's
  own carve-out.
• requireField() single-sources HTTP-4's field-named errors so the `${name} is required` message
  cannot drift between models.
• Typed errors only. Eleven classes descending from DomainModelError; no bare throw new Error. Each
  sets this.name = new.target.name; wrap-and-rethrow always passes {cause}.

[Wahbeh-Mohammad]

Known gaps

Full detail in docs/open-items.md. The ones that touch this diff:

• HTTP-24 (decision needed). MediaType.charset returns the parameter verbatim, so charset=bogus yields
  'bogus' where the spec's conformance line says null. There is no encoding registry to resolve "unknown"
  against. Either add a recognized-encoding check or record a deliberate deviation — but the checklist
  currently marks it ✅, which is the actual defect.
• HTTP-22 (checklist wrong, code right). The checklist credits HeaderName.of() with a static intern
  cache. No such cache exists; interning was deliberately dropped as unbounded caller-influenced state. HTTP-22
  is a MAY, so only the checklist row needs fixing.
• HTTP-11 (interpretation unrecorded). Response exposes no range classification of its own; callers go
  through response.status.isSuccess. Defensible, but nobody chose it on purpose.
• RequestConditions.applyTo cannot emit an obs-text ETag. HTTP-48 permits obs-text in an opaque tag;
  HTTP-18 forbids it outbound. The spec text in scope does not resolve the tension, so this keeps the strict
  path rather than guessing. Flagged for Phase 10.

[Wahbeh-Mohammad]

Decisions to agree/disagree with:

Classes over plain frozen objects. Styleguide 6.3 defaults to interface + free functions. This design
overrides that: TypeScript's structural typing means any object literal shaped like interface Request {...}
bypasses construction entirely, so build()'s validation never runs. A class with #private fields cannot be
spelled out structurally. This closes the accidental path, not the deliberate one — Object.create(Request.prototype)
still forges an instance, an acknowledged limitation to be recorded in sdk-design-nodejs/10.

Outbound and inbound header validation are separate paths, not a flag. add/set apply the strict
caller-set grammar (HTAB plus printable ASCII, HTTP-18); addInbound/setInbound relax values to permit
obs-text while still rejecting control characters (HTTP-19). Names are strict on both. Applying the outbound
grammar to responses would silently drop legitimate headers such as a Latin-1 Content-Disposition filename.
Headers.newBuilder() derives through the inbound path, since a Headers built with obs-text must stay
derivable.

Query encode and parse are deliberately asymmetric. encode() is strict RFC 3986 — space is %20 never
+, literal + is %2B, * is %2A, ~ survives — patching encodeURIComponent's known divergence on
!*'() rather than assuming the stdlib is correct (HTTP-29/32). parse() never throws: blank input, a
leading ?, a missing =, a stray &, and malformed percent-encoding all degrade gracefully (HTTP-31). Kept
as two functions rather than one "codec" abstraction precisely because their strictness differs by design.

Error messages never leak. HeaderValidationError performs HTTP-20's redaction in its own constructor
rather than trusting each call site: the offending value is accepted as a parameter but never interpolated
into the message and never stored on the error; an echoed name has its control characters escaped. Enforced by
the constructor's shape, not by caller discipline.

One predicate, not two. HTTP-26 requires media-type construction to reject forbidden bytes "using the same
predicate as outbound header-value validation." Satisfied by literal code reuse — media-type.ts calls the
exact hasForbiddenOutboundByte that headers.ts uses — rather than a second implementation that agrees
today and silently diverges on a future edit.