feat: the v1 MVP — eleven packages, the full pipeline, and the gate suite

.changeset/seam-foundations.md → .changeset/2026-08-11-seam-foundations.md

@@ -2,6 +2,6 @@
 "@dexpace/core": minor
 ---
 
-Add the seam foundations: the `Transport` contract with its `composeSignal`/`isTimeoutSignal` cancellation helpers and `CancellationError`, the operation-input projection (`OperationDescriptor`, `buildRequest`, `OperationAssemblyError`), and `DexpaceError` as the new root of the error taxonomy above `DomainModelError`.
+Add the seam foundations: the `Transport` contract with its `composeSignal`/`isTimeoutSignal` cancellation helpers and `CancellationError`, the operation-input projection (`OperationDescriptor`, `buildRequest`, `OperationAssemblyError`), and `DexpaceError` as the root of the error taxonomy.
 
-`DomainModelError` now extends `DexpaceError` instead of `Error`. This is additive — every existing leaf keeps its parent, its behavior, and its `instanceof DomainModelError` narrowing.
+Every existing error leaf keeps its behavior and its message. The taxonomy is two levels: a leaf's own superclass is `DexpaceError` itself, and a family is grouped with an exported type guard rather than an intermediate class.

.changeset/2026-08-25-body-lifecycle-review-fixes.md

@@ -0,0 +1,24 @@
+---
+"@dexpace/core": minor
+---
+
+Body lifecycle review fixes.
+
+Security:
+
+- Body media types are validated as header-safe at construction (`byteArrayBody`, `stringBody`, `streamBody`, and every part rendered into a multipart body), using the same predicate as outbound header-value validation (HTTP-26). A CR/LF in a media type was previously interpolated verbatim into a multipart part header, which allowed arbitrary header injection, arbitrary part content, and a forged closing boundary while the declared content length still matched the corrupted bytes (HTTP-51).
+- `StreamBody.writeTo` now refuses a chunk that would carry the body past its declared `contentLength` *before* writing it, and aborts the sink rather than closing it on any length mismatch. Overrun bytes previously reached the sink and were reported only afterwards, leaving them on the socket behind a stamped `Content-Length` (HTTP-39/BODY-10).
+
+Correctness:
+
+- A body write failure is no longer masked by the close that follows it. All five `Body` implementations share one writer scope that aborts on failure and never lets a close error replace the primary one (RECOV-12), so retry classification still sees the I/O failure in the cause chain (RETRY-2).
+- `TypedResponse.value()` memoizes a parser that throws synchronously; it previously re-ran the handler and re-read the single-use body (HTTP-44).
+- `HttpStatusError.preview()` decodes with the charset declared by the response media type, falling back to UTF-8, and never throws a `RangeError` on an unknown label (HTTP-42).
+- `withRequestLogging(...).materialize()` gives the new wrapper its own tap buffer instead of aliasing the original's, so one wrapper's write can no longer rewrite another's captured preview (BODY-21).
+- `withResponseLogging` treats a zero-length delegate chunk as a stream-contract violation, matching `RetentionWindow` under IO-17 (BODY-25), and `snapshot()` now starts the lazy drain the way `read()` does (BODY-22).
+- `Response.close()` marks the response closed only once the release actually succeeds, memoized so concurrent closers share one cancel — the shape `BufferedSink.close()` already uses (BODY-15, HTTP-43).
+
+Public API:
+
+- New `FormBodyValidationError`, reported by `isBodyError`. A form field whose value cannot be rendered is now raised instead of silently dropped from the body.
+- `FormUrlEncodedInput` accepts the new `FormUrlEncodedValue` (`string | number | boolean | bigint | null`); primitives render rather than vanish (HTTP-38/BODY-35).

.changeset/2026-08-25-body-lifecycle.md

@@ -0,0 +1,7 @@
+---
+"@dexpace/core": minor
+---
+
+Add the core Body domain interface and implementations (ByteArrayBody, StringBody, FormUrlEncodedBody, StreamBody, MultipartBody, materialize, TypedResponse, HttpStatusError, toHttpError, withRequestLogging, withResponseLogging).
+
+`RequestBuilder.body` and `ResponseBuilder.body` narrow from `unknown` to `Body | undefined` and `ReadableStream<Uint8Array> | null` respectively — a breaking parameter-type change per `styleguide/typescript/10-api-design.md`. Resolving Phase 3b's open D1 finding (`docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md`, "Open Findings — Phase 3b Validation Review"): kept as **minor** rather than major because `@dexpace/core` is still pre-1.0 (`0.0.0`), where a 0.x breaking change is conventionally released as minor (semver's own carve-out for initial development, https://semver.org/#spec-item-4). Revisit at 1.0.

.changeset/2026-08-25-io-contracts.md

@@ -0,0 +1,5 @@
+---
+"@dexpace/core": patch
+---
+
+Internal: byte-streaming primitives for product-spec §5 (IO-1–IO-42). No public API change.

.changeset/2026-08-26-add-the-node-runtime-conformance-suite.md

@@ -0,0 +1,23 @@
+---
+---
+
+Add the Node-runtime conformance suite.
+
+No published package changes.
+
+Deliberately empty — `changeset --empty` — rather than absent. Every file in this change is repository
+infrastructure that ships to nobody: `test/node-conformance/`, `.github/workflows/ci.yml`, `bunfig.toml`,
+`eslint.config.js`, the root `package.json` scripts, `CLAUDE.md`, and the phase docs. Zero files under
+`packages/` were touched, so there is nothing for `@dexpace/core` to bump and a `patch` here would put a line
+in the published changelog that means nothing to a consumer reading it.
+
+The empty changeset records that the judgement was made, which is the difference between "this change needs no
+release" and "somebody forgot a changeset". Verified before writing it:
+`git show --stat --name-only e3d0b18 | grep '^packages/'` returns nothing.
+
+What the change does, for anyone reading this file from the repository rather than the changelog: `bun test`
+runs the unit suite on Bun and proves nothing about the runtime the SDK ships to. 319 of 516 unit tests
+exercise a runtime-divergent surface — Web Streams, `AbortSignal`, async iteration, `ByteQueue`'s `Uint8Array`
+handling — against two assertions of Node coverage that touched none of it. `test/node-conformance/` adds 30
+`node --test` cases over the built artifact, wired as `test:node` and run by CI as a matrix over the declared
+`engines.node` floor and current LTS. Closes checkpoint §5.9 / roadmap finding E5.

.changeset/2026-08-26-execution-context.md

@@ -0,0 +1,46 @@
+---
+'@dexpace/core': patch
+---
+
+Add the execution-context model for product-spec §7 (`CTX-1`–`CTX-20`, `XCUT-14`). No public API change.
+
+Everything this adds lives under `packages/core/src/context/` and none of it is re-exported from
+`src/index.ts` — `packages/core/etc/core.api.md` is byte-identical before and after. `patch` rather than an
+empty changeset because files under `packages/` did change: the published tarball carries the new
+`dist/context/*.js`, and a consumer stepping through the package in a debugger will see them.
+
+What landed: `ExecutionContext` as a three-member discriminated union — `DispatchContext` (before any
+request), `RequestContext` (an outbound request assembled), `ExchangeContext` (a response arrived, terminal) —
+with `promoteToRequest`/`promoteToExchange` as the pure promotion chain and `createDispatchContext`/
+`createRequestContext`/`createExchangeContext` as the off-chain factories `CTX-5`/`CTX-6` require.
+`InstrumentationBundle` plus the `noopInstrumentationBundle` disabled-tracing default. `ContextStore`, a
+bounded keyed registry with `install`/`installIfAbsent`/`find`/`close`, and `DuplicateContextKeyError`.
+
+Three design calls worth recording:
+
+- **Call keys are `Symbol()`, not a counter or a UUID.** `CTX-4`'s uniqueness requirement cannot lean on any
+  field of the instrumentation bundle, because `noopInstrumentationBundle`'s fields are all constants shared
+  by every context that takes the default. A fresh `Symbol()` per call is distinct across the process and
+  across all three context flavors by construction, and `ContextInit.key` is the pin that makes two contexts
+  deliberately share one store slot (`CTX-5`).
+- **The store's cap drains in a loop, and holds strong references.** `XCUT-14` names context registries first
+  among the caller-keyed process-lived maps that MUST carry a hard cap and drain back under it after each
+  insert — an unbounded one is a memory-exhaustion vector, not merely a leak. The loop (rather than a single
+  check-then-evict) is what makes an insert burst converge. `Map`, never `WeakMap`/`WeakRef`: a registered
+  context keeps its whole `Request`+`Response` graph reachable on purpose, so the cap is the backstop rather
+  than the collector (`CTX-19`).
+- **Promotions never touch a store.** `context.ts` does not import `store.ts`, which is what satisfies
+  `CTX-17`'s negative half structurally — constructing a head context must not auto-register it. Wiring the
+  store into the promotions would invert the layering and make every promotion a global side effect. The
+  positive half — the first store entry, installed by the first promotion — is Phase 4c's `Runtime.send()`.
+
+Two known deviations, both already in the deferral register (`docs/work/mvp/2026-09-04-open-items-dissolution.md`):
+
+- `contextStore` is a module-level mutable singleton, which
+  `docs/knowledge/harvested/variables-and-declarations.md:22` bans. Accepted because threading a store handle through
+  builder → runtime → every step would be a wide API change for no observable gain; logged in the design's
+  Deviation Ledger for Phase 10. Tests build their own `new ContextStore()` rather than asserting through the
+  singleton, which is shared by every file in a `bun test` run.
+- `activeSpan` and `tracerFactory` stay typed `unknown`, and `activeSpan` is `undefined` rather than a no-op
+  span object. `CTX-14`/`CTX-15` ship as the bundle's frozen shape and the disabled default only; real W3C
+  Trace Context generation waits for the Phase 7 tracing adapter that gets to define `Span`.

.changeset/2026-08-26-max-retries-range-check.md

@@ -0,0 +1,14 @@
+---
+"@dexpace/core": patch
+---
+
+Tighten `RequestOptionsBuilder.maxRetries` validation: a defined value must now be a non-negative
+integer. `Infinity`, `NaN`, and fractional values were previously accepted and now throw
+`RequestOptionsValidationError`, the same way a negative value already did.
+
+A retry ceiling is a count of wire sends, so a non-finite one is as out of range as a negative one —
+and worse in effect: a negative value still fails a downstream `>= 1` guard, while `Infinity` or
+`NaN` makes a retry driver's `attempt >= ceiling` test permanently false and its loop unbounded.
+HTTP-35's requirement is that an out-of-range retry count is a loud error at the call site that
+supplied it, never a value reinterpreted somewhere downstream; this closes the half of that
+requirement the setter did not implement.

.changeset/2026-08-26-phase3-conformance-fixes.md

@@ -0,0 +1,51 @@
+---
+"@dexpace/core": minor
+---
+
+Phase 3 conformance fixes, from a review of the shipped `io/` and `body/` layers against the phase 3a/3b plans.
+
+Correctness:
+
+- The request-body logging tee now forwards **both** teardown paths to the sink it was handed. Its adapter stream
+  declared `write` and `close` but no `abort`, and a `WritableStream`'s default abort algorithm is a no-op — so a
+  delegate failure aborted the adapter and stopped there, leaving the caller's sink open, still locked, and never
+  told the message was broken. A truncated body could be committed downstream as a complete one. `writeTo` also
+  releases the writer when a delegate refuses before ever touching the adapter, which is what a `ConsumedBodyError`
+  on a second write does (BODY-17, RECOV-12).
+- `StreamBody.writeTo` no longer cancels the caller's stream when the sink fails. The unknown-length path used
+  `pipeTo`'s default `preventCancel: false`, which cancels the *source* on a destination failure — taking
+  cancellation ownership away from the caller on exactly the failure path, and disagreeing with the
+  declared-length path, which only releases its reader. Both paths now leave the caller's stream alone (BODY-8).
+- Every `Body` variant is frozen at construction. `readonly` is erased at run time, so `contentLength` could be
+  reassigned after construction and desynchronized from the bytes `writeTo` emits — the same declared-length drift
+  `MultipartBody` shares one framing routine to prevent, left open on the field a transport stamps into
+  `Content-Length` (HTTP-1, XCUT-15, HTTP-51).
+- `Response` regained the private constructor and `createResponse` friend hook that the body-lifecycle rewrite
+  dropped. `Response` is exported as a value, so a public field-wise constructor let a caller construct around
+  `build()`'s required-field validation, and it appeared in the published `.d.ts` (HTTP-2).
+- `TeeSink.write` validates its count. `IO-3`'s guard existed as three byte-for-byte copies and the tee — the
+  fourth size-taking surface — had none, so a negative count was rejected only indirectly, and not at all on its
+  `count === 0` and short-source early returns. The guard is now single-sourced in `io/limits.ts`.
+- `withResponseLogging` enforces the zero-length-chunk contract on the exceeds-cap tail path as well as the drain.
+  A rule held in one regime and not the other made the same violating upstream pass or fail depending only on how
+  big the body happened to be (BODY-25).
+
+Public API:
+
+- `Response` and the response-body logging wrapper no longer declare `[Symbol.asyncDispose]`; `close()` is the only
+  teardown interface, matching every other resource-owning class in the package. The symbol postdates the declared
+  `engines.node` floor (`>=18.17`), where it evaluates to `undefined` and binds the method to the string
+  `"undefined"`, and its type reached the package only through a dev-only global — so a consumer compiling against
+  the published `.d.ts` on this package's own declared `lib` failed with
+  `TS2550: Property 'asyncDispose' does not exist on type 'SymbolConstructor'`. It returns, on all seven resource
+  owners at once, when the runtime floor moves.
+- Every public symbol now carries TSDoc. The committed API report had accumulated 62 `(undocumented)` members,
+  including 11 of `Response`/`ResponseBuilder`'s own that a wholesale file rewrite had dropped; it is back to zero.
+
+Internal:
+
+- `http/charset.ts`'s `decodeText` is renamed `decodeBodyText`. It shares a name with `io/text-codec.ts`'s
+  `decodeText` while deliberately disagreeing with it: this one delegates every label to `TextDecoder` (so
+  `iso-8859-1` follows the WHATWG mapping onto windows-1252) and consumes a leading BOM, which is right for a whole
+  message body; the other implements true ISO-8859-1 for IO-13's round-trip and sets `ignoreBOM` so a mid-stream
+  BOM survives as ordinary data (SSE-12). Reaching for the wrong one silently changes bytes.

.changeset/2026-08-26-phase3-review-pass-2.md

@@ -0,0 +1,44 @@
+---
+"@dexpace/core": minor
+---
+
+Phase 3 review pass 2. Five defects, each in the same class as one pass 1 already fixed — the earlier fixes
+were correct but did not reach every site the same reasoning applies to.
+
+Correctness:
+
+- `Response.bytes()`, `Response.text()` and `toHttpError()` now acquire the body reader **inside** the try, so
+  the response is closed even when the read cannot start. `getReader()` itself throws a `TypeError` when an
+  external consumer already holds the lock — which `BODY-15` explicitly forbids assuming away, and which
+  `Response.close()` was already hardened for — so the one failure `BODY-16`'s close guarantee most needs to
+  cover was the one that skipped the close entirely and held the connection open.
+- `MultipartBody.writeTo` verifies the bytes it writes against its own declared `contentLength`. The shared
+  framing routine keeps the framing consistent but takes each part's own `contentLength` on trust, and
+  `MultipartPart.body` is the public `Body` interface — so a caller implementation reporting one length and
+  writing another desynchronized the value a transport stamps into `Content-Length` from what reaches the
+  socket. An overrunning chunk is now refused before it is written, and a short total raises inside the writer
+  scope so the sink is aborted rather than cleanly closed (HTTP-51, same shape as `StreamBody`'s HTTP-39 check).
+- `withRequestLogging` closes the primary sink when a delegate resolves without closing the adapter. It is the
+  only place that takes a writer on behalf of someone else's `Body`, so a delegate that ignored `writeTo`'s
+  close-the-sink contract stranded the caller's sink open and locked with nothing thrown to notice it by.
+- A foreign primitive source that over-reports its transferred count now raises `SourceContractViolationError`.
+  It previously surfaced as `EndOfStreamError: delivered 2 of 99 bytes` — a foreign source's broken accounting
+  reported as an exhausted stream, which is the exact confusion `IO-17` forbids and which the under-report
+  direction was already guarded against (IO-17).
+
+Documentation:
+
+- `multipartBody`'s `boundary` parameter and `MultipartBodyBuilder.boundary` now state the obligation a
+  caller-supplied delimiter carries. RFC 2046 requires the sender to pick a boundary that appears in no part,
+  and that half cannot be checked here — a `StreamBody` part's bytes do not exist until the write, and a partial
+  scan would read as a complete guarantee. The generated default (32 random characters from Web Crypto) is the
+  mitigation, and is why it is the default.
+
+Tooling:
+
+- New blocking gate `verify:consumer-types`: compiles a throwaway consumer against the built `.d.ts` using the
+  `lib` and `target` read from `tsconfig.base.json`, with `types: []`. This is the gate whose absence let pass
+  1's `Symbol.asyncDispose` defect ship — `typecheck` passes on dev-only ambient globals, `build` emits
+  regardless, `api` only compares a report, `lint:publish` checks resolution and export shape rather than
+  whether declarations resolve, and `verify:dual-consumption` runs `node`, not `tsc`. Verified to fail on the
+  reintroduced defect and pass once reverted.