undici transport parity: header rejections degrade, fileBody short-write detection, SOCKS refusal (#81)

[Wahbeh-Mohammad]

Closes #81. Part of #67, milestone 5. Wave 6a; #82 lands on top of this.

Decision followed: D19, with two documented departures from its letter (below).

What changed

1. Headers the native client refuses degrade to a logged drop (TRANSPORT-11/12/13)

undiciTransport().send() failed outright for four model-valid headers. undici 6.28.0 rejects
expect (NotSupportedError), keep-alive and upgrade (InvalidArgumentError) unconditionally
(lib/core/request.js:398,409), connection with any value but close/keep-alive (:400-404),
and any name outside RFC 9110 token (lib/core/util.js:547-587) — while @dexpace/core admits
every printable ASCII byte in a name (http/ascii-validation.ts:29-33), so X Custom is
model-valid and unsendable. All five reached toDispatchError as a bare non-retryable TypeError;
nothing was sent.

• UNDICI_FORBIDDEN_HEADERS gains expect, keep-alive, upgrade.
• toUndiciHeaders validates each name against RFC 9110 token and each connection value against
  undici's own two (case-insensitively, as undici compares), dropping and logging what fails. Values
  are deliberately not re-checked: undici's value grammar admits obs-text 0x80–0xFF, strictly
  wider than the outbound rule mapOutboundHeaders already applied (HTTP-18).
• connection stays out of the by-name drop set — §17's own note — so close/keep-alive still
  reach the wire and dropsConnectionHeader: false is still true.

FETCH_FORBIDDEN_HEADERS widened too, and a row proves it. D19 made that conditional. Measured
2026-09-05: on Node, fetchTransport() rejects all three with TransportFailureError —
retryable, so a permanent misconfiguration spends the caller's whole retry budget re-proving
itself — because Node's global fetch is undici-backed and undici's Headers deliberately does not
implement the WHATWG forbidden-name list. On Bun 1.3.14 it diverges a third way: expect and
keep-alive go to the wire, and upgrade hangs indefinitely. Neither is TRANSPORT-12's outcome.

2. A file body goes through its own writeTo (BODY-13, TRANSPORT-28)

The file branch of prepareBody handed createReadStream(path, {start, end}) to undici, skipping
the descriptor's writeTo and so @dexpace/body-file's transferred === count invariant.
content-length is dropped outbound, so undici framed the body chunked and the wire could not see a
short write either: a 1 MB fileBody truncated to 10 bytes before send() POSTed 10 bytes and
resolved 200, where @dexpace/transport-fetch raised TransportFailureError.

Departure from D19's letter, accepted: D19 said the file branch "takes the same pumpBody path
the streamed case uses". The branch is deleted instead, so prepareBody is now the same two
decisions on both transports — buffered at or below 1,000,000 declared bytes, streamed above. That
is pumpBody for a large file and the buffered sibling for a small one, and it is the only version
in which the two adapters cannot drift again. The zero-count branch goes with it:
isMaterializable admits contentLength === 0 and materializeBody never opens a read stream.

Framing changed, as D19 asked to be told. A file body at or below 1,000,000 bytes is now sent
with content-length where it used to be chunked. Above that it stays chunked. Both match the fetch
twin exactly.

TRANSPORT-28's zero-copy clause is a SHOULD no user-space path in either client can honour
(docs/deviations.md item 13, recorded since Phase 8a — the createReadStream path was never
sendfile(2) either). Its MUSTs — replayable, and exactly the declared range on the wire — are the
descriptor's, honoured on both transports by one code path, and asserted by a row.

3. A SOCKS proxy is refused at the factory (TRANSPORT-30)

toProxyAgentOptions used proxy.type as the URI scheme unchecked, so
undiciTransport({proxy: createProxyOptions({type: 'socks5', …})}) threw undici's
InvalidArgumentError('Invalid URL protocol: socks5:') straight out of a public factory. Core
resolves ALL_PROXY's socks:, socks4:, socks4a:, socks5: and socks5h: onto ProxyType
quite legitimately (CFG-22, config/proxy.ts:372-380).

selectDispatchers now refuses anything but http with a TypeError naming the type, matching its
existing dispatcher-plus-proxy refusal and deliberately outside the IoError tree so
retry/classify.ts's allow-list makes it non-retryable (RETRY-2). The check runs before
new undici.Agent(...), so a refused construction allocates nothing. @throws on undiciTransport
and on UndiciTransportOptions.proxy. ProxyType keeps socks4/socks5 (D19; narrowing a
@public union is a release-pass call). fetchTransport() needs no equivalent — it has no proxy
option at all.

Test rows added

Shared suite (packages/transport-conformance/src/{run-suite,fixtures}.ts), both transports run
every one:

Row	Before
Expect: 100-continue dropped, logged, request still dispatches	red on undici, red on fetch
Keep-Alive: timeout=5 — same	red on undici, red on fetch
Upgrade: websocket — same	red on undici, red on fetch (hung to the 5 s deadline)
X Custom (non-token name) — same	red on undici, green on fetch
Connection: upgrade is dropped on both	red on undici
an intact ranged file body puts exactly its declared bytes on the wire, through writeTo	red on undici (writes.count === 0)
a file body truncated after its length was captured fails the send, naming transferred-of-total	red on undici (resolved 200)
an unsupported proxy type fails at construction, typed and naming the type	red on undici (raw InvalidArgumentError)

TransportCapabilities gains an optional unsupportedProxy: {type, build()} — only the adapter
knows which ProxyType values its client refuses. Where it is absent (fetch) the row asserts
supportsProxy === false rather than skipping, so "no proxy surface" and "an unasserted gap" cannot
look alike.

New fixture: fileBodyFixture(path, {start?, count, writes?}) in fixtures.ts — a kind: 'file'
descriptor carrying BODY-13's check itself. Deliberately a stand-in, not the real fileBody():
@dexpace/transport-conformance is private, resolves unbuilt and depends on @dexpace/core
alone, and taking @dexpace/body-file would add a fifth entry to the root build:deps chain plus a
lockfile change for one row — all three files outside this task's partition.

Unit rows in packages/transport-undici/src/undici-transport.test.ts: every refused header absent
from the dispatched argument array with a sibling surviving; Connection carried for
close/Keep-Alive and dropped for upgrade; both SOCKS values refused with no Agent
constructed. The two existing file-body rows now assert writeTo was called (they asserted it
must not be).

Node conformance (tests/node-conformance/transport.test.mjs, both transports):

• the four refused names on Node, where an undropped one rejects the send and the Bun rows prove a
  weaker claim;
• the streamed-path truncate-after-stat, with a real fileBody() over a 1.1 MB file.

Findings

Bun 1.3.14's Readable.fromWeb leaks unhandled rejections when the web readable behind it is
aborted mid-pull — two or three per abort. That is exactly what a producer failure on the streamed
request-body path does, and bun:test scores them against whichever row is running. Isolated to
sixteen lines with no SDK code in them; node --test is clean on both transports. It is why the
streamed leg of the truncate row lives in the Node tree, and TRUNCATED_FILE_BYTES's TSDoc says so
in case anyone raises it past 1,000,000. Reachable in production only under Bun, only on a >1 MB
streaming request body whose producer fails mid-flight — not this task's to fix, and not this SDK's
bug, but #82 should know, because D20's producer-failure-race item is in the same code.

packages/transport-fetch/README.md:53 is now stale — it lists the drop set as
"Content-Length, Host, Transfer-Encoding, and Connection". Outside this task's partition
(which names src/fetch-transport.ts only), so left alone per contract item 4. One-line fix for
#82 or the supervisor: add Expect, Keep-Alive and Upgrade to that list.

tests/node-conformance/transport.test.mjs was edited outside the partition, as #72/#76 did
before, for the reason CLAUDE.md's membership rule gives: the divergence is real and measured (Bun
forwards expect/keep-alive and hangs on upgrade; Node rejects all three), and that file is the
only layer where a real fileBody() meets a real transport — its own header comment says so.

For #82

• run-suite.ts gained registerNativeRejectionRows and registerFileBodyRows (registered between
  registerHeaderRows and registerInboundHeaderRows) and registerProxyRefusalRows (after
  registerDropSetRows); fixtures.ts gained fileBodyFixture. Merge seams for D20's rows.
• TransportCapabilities is now four fields, the fourth optional.
• prepareBody in undici-transport.ts no longer imports node:fs or FileBodyDescriptor.
• UNDICI_FORBIDDEN_HEADERS and FETCH_FORBIDDEN_HEADERS both changed; D20's CONTROL_BYTE and
  body === null work sits beside them.
• defaultTimeoutMs is still unvalidated on both transports (carried from Domain-model input validation: prototype keys, invalid Date, fractional timeoutMs, lone surrogates, frozen getAll #76 to fetch transport: permanent-error classification; both transports: 204/304/HEAD rows, CONTROL_BYTE regex, producer-failure race #82, untouched
  here).
• An ftp:// URL still reaches dispatcher.request({origin: …}) unchecked — D20's classification
  item.

Gates

node .claude/skills/ci-preflight/run-ci.mjs --clean — all 20 steps passed (install,
verify:knowledge-structure, typecheck, lint, build, test, test:scripts, api,
lint:publish, verify:dual-consumption, verify:consumer-types, verify:seam-1,
verify:sse-37, verify:runtime-floor, verify:test-partition, test:examples,
verify:import-cycles, verify:reproducible-build, audit, test:node). 2466 Bun tests across
166 files; 178 Node tests. Run without --node-floor, so CI's Node 20.3.0 leg is untested locally.
housekeeping/probe.mjs: no drift. check-fences.mjs: pass.

api:local regenerated for transport-undici and transport-fetch; both reports are
byte-identical — the changed TSDoc is prose on existing signatures, which api-extractor's report
does not carry. Nothing to commit. bun run api verifies all nine.

Deviations recorded

One row appended at the end of docs/deviations.md's "Deviations recorded outside a phase" (D0):
CFG-22's SOCKS proxy types are resolved by the configuration layer and supported by neither
shipped transport; the refusal is at the transport factory, and ProxyType keeps them.

No phase-ledger edits, no §10 edits. Nothing else is a deviation: TRANSPORT-12 and BODY-13 are now
satisfied rather than departed from, and TRANSPORT-11's drop set is transport-specific by its own
text.

Deferred — release machinery

Suspended under D1; nothing below was done.

• Patch changeset for @dexpace/transport-undici: send() no longer fails for Expect,
  Keep-Alive, Upgrade, a non-token header name, or a Connection value other than
  close/keep-alive — each is dropped and logged instead (behaviour change: a send that used to
  throw now succeeds without that header). A file body is written through its own writeTo, so a
  short write now fails the send, and a file body at or below 1 MB is framed with content-length
  rather than chunked. undiciTransport() throws TypeError for a non-http proxy.type that
  previously escaped as undici's InvalidArgumentError. Shipped .d.ts prose changed for
  undiciTransport (@throws) and UndiciTransportOptions.proxy.
• Patch changeset for @dexpace/transport-fetch: Expect, Keep-Alive and Upgrade are now
  dropped outbound. On Node these previously failed the send with a retryable
  TransportFailureError; on Bun Expect/Keep-Alive reached the wire and Upgrade hung. No
  .d.ts change.
• ProxyType narrowing, and the question behind it. @dexpace/core's ProxyType still admits
  socks4 and socks5, and resolveProxyOptions still resolves them from the environment, while
  no shipped transport can send over one. Dropping them from the union is free only before the first
  version bump — but it would also put @dexpace/core in breach of CFG-22, whose MUST enumerates
  "HTTP, SOCKS4, SOCKS5" for the proxy model. Recommendation: keep the union and leave the
  docs/deviations.md row standing. The model is complete and the transport layer is not, which
  is an honest state and one a future SOCKS transport closes without a public-shape change. If the
  release pass disagrees, it is a minor changeset for @dexpace/core (breaking for anyone
  naming the type) plus a matching one for @dexpace/transport-undici.
• No docs/first-release.md edits.