@fluojs/testing 2.0.0 → 3.0.0

package/README.ko.md

@@ -2,10 +2,12 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-Node.js 20+ fluo 애플리케이션을 위한 기본 request-level 테스트 헬퍼, 모듈 구성, 프로바이더 오버라이드 유틸리티입니다.
+Node.js `>=24.0.0 <27` fluo 애플리케이션을 위한 기본 request-level 테스트 헬퍼, 모듈 구성, 프로바이더 오버라이드 유틸리티입니다.
 
 `@fluojs/testing`은 fluo 애플리케이션 테스트를 위한 공식적인 기준(Baseline)을 제공합니다. 격리된 테스트 환경을 구축하고, 의존성을 가짜(Fake)나 목(Mock)으로 교체하며, 모듈 그래프에서 직접 컴포넌트를 resolve하거나 `createTestApp(...).request(...).send()`로 가상 HTTP 요청을 실행하여 e2e 스타일 테스트를 수행할 수 있게 합니다.
 
+Coordinated Node 24 릴리스를 준비한다면 패키지 업그레이드 전에 [소비자 마이그레이션 가이드](../../docs/getting-started/migrate-node24.ko.md)를 따르세요.
+
 ## 목차
 
 - [설치](#설치)
@@ -13,6 +15,7 @@ Node.js 20+ fluo 애플리케이션을 위한 기본 request-level 테스트 헬
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
 - [canonical TDD ladder](#canonical-tdd-ladder)
+- [React Consumer Testing Recipe](#react-consumer-testing-recipe)
 - [공개 API](#공개-api)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -23,9 +26,9 @@ Node.js 20+ fluo 애플리케이션을 위한 기본 request-level 테스트 헬
 pnpm add -D @fluojs/testing vitest
 ```
 
-`vitest`는 mock 헬퍼와 `@fluojs/testing/vitest` 엔트리포인트가 요구하는 peer dependency입니다. `@babel/core`는 Vitest decorators plugin이 사용하는 워크스페이스의 Babel을 로드하기 때문에 peer로 선언되어 있습니다. 따라서 non-Vitest harness subpath만 사용하더라도 패키지 매니저가 해당 peer 경고를 표시할 수 있습니다.
+Vitest `^4.1.11`은 mock 헬퍼와 `@fluojs/testing/vitest` 엔트리포인트가 요구하는 peer dependency입니다. `@babel/core`는 Vitest decorators plugin이 사용하는 워크스페이스의 Babel을 로드하기 때문에 peer로 선언되어 있습니다. 따라서 non-Vitest harness subpath만 사용하더라도 패키지 매니저가 해당 peer 경고를 표시할 수 있습니다.
 
-`@fluojs/testing/vitest`를 사용할 때는 `fluoBabelDecoratorsPlugin()`이 런타임에 Babel을 호출하므로, 사용하는 워크스페이스에 `@babel/core`도 함께 설치해야 합니다. Vitest 플러그인은 Vite query/hash suffix를 제거한 뒤 `.ts`, `.tsx`, `.mts`, `.cts` 소스 id를 변환하고, `node_modules`는 건너뛰며, 가장 가까운 root Babel config인 `babel.config.cjs`, `babel.config.mjs`, `babel.config.js`, `babel.config.json`을 해석합니다.
+`@fluojs/testing/vitest`를 사용할 때는 `fluoBabelDecoratorsPlugin()`이 런타임에 Babel을 호출하므로, 사용하는 워크스페이스에 `@babel/core`도 함께 설치해야 합니다. Vitest 플러그인은 `enforce: 'pre'`로 실행되어 decorator가 있는 TypeScript가 Vite 8 normal-stage Rolldown/Oxc transform보다 먼저 Babel에 도달하게 합니다. Vite query/hash suffix를 제거한 뒤 `.ts`, `.tsx`, `.mts`, `.cts` 소스 id를 변환하고, `node_modules`는 건너뛰며, 가장 가까운 root Babel config인 `babel.config.cjs`, `babel.config.mjs`, `babel.config.js`, `babel.config.json`을 해석합니다.
 
 ```bash
 pnpm add -D @babel/core
@@ -76,12 +79,44 @@ const module = await createTestingModule({ rootModule: AppModule })
   })
   .compile();
 
-const service = await module.resolve(UserService);
+let testError: unknown;
+let testFailed = false;
+let disposeError: unknown;
+let disposeFailed = false;
+
+try {
+  const service = await module.resolve(UserService);
+} catch (error: unknown) {
+  testError = error;
+  testFailed = true;
+} finally {
+  try {
+    await module.container.dispose();
+  } catch (error: unknown) {
+    disposeFailed = true;
+    disposeError = error;
+  }
+}
+
+if (testFailed) {
+  if (disposeFailed) {
+    throw new AggregateError(
+      [testError, disposeError],
+      'Test and testing module disposal both failed.',
+    );
+  }
+
+  throw testError;
+}
+
+if (disposeFailed) {
+  throw disposeError;
+}
 ```
 
-Testing builder는 route-pipeline 테스트에서 cross-cutting behavior를 교체할 수 있도록 `overrideProviders([[token, value], ...])`, `overrideGuard(...)`, `overrideInterceptor(...)`, `overrideFilter(...)`도 지원합니다. Guard와 interceptor override는 route가 같은 token을 `@UseGuards(...)` 또는 `@UseInterceptors(...)`로 참조할 때 request path에서도 안전하게 검증할 수 있습니다. Filter override는 컴파일된 module graph의 token을 교체하므로, 해당 filter가 runtime app 표면에 등록되는 경우 request-level coverage와 함께 사용하세요.
+Testing builder는 route-pipeline 테스트에서 cross-cutting behavior를 교체할 수 있도록 `overrideProviders([[token, value], ...])`, `overrideGuard(...)`, `overrideInterceptor(...)`, `overrideFilter(...)`도 지원합니다. Guard와 interceptor override는 route가 같은 token을 `@UseGuards(...)` 또는 `@UseInterceptors(...)`로 참조할 때 request path에서도 안전하게 검증할 수 있습니다. Filter override는 컴파일된 module graph의 token을 교체하므로, 해당 filter가 runtime app 표면에 등록되는 경우 request-level coverage와 함께 사용하세요. 성공적으로 컴파일된 모든 `TestingModuleRef`를 보관하고 caller-owned `container`는 `finally`(suite setup은 `afterEach`)에서 dispose하여 통과, 실패, 조기 반환 테스트 모두 lifecycle resource를 해제하세요. 완료된 `container.dispose()` 호출은 idempotent합니다. Teardown 실패는 surface되며, in-flight assertion도 실패할 수 있다면 어느 하나를 suppress하거나 assertion failure를 대체하지 말고(예: `AggregateError`) 두 오류를 함께 보고하세요.
 
-`compile()`은 lifecycle hook이 있는 singleton provider에 대해 production module bootstrap과 같은 의미를 따릅니다. effective provider graph를 해석하고, testing module을 반환하기 전에 provider 순서대로 각 instance의 `onModuleInit()`을 실행한 뒤 `onApplicationBootstrap()`을 실행합니다. `get()`은 synchronous singleton 및 multi-provider 경로에서도 DI ownership 의미를 보존하므로, 반복 sync read는 같은 singleton contribution을 재사용하고 `module.container.dispose()`가 해당 instance를 계속 정리할 수 있습니다.
+`compile()`은 module에 선언했거나 override한 factory provider를 포함해 lifecycle hook이 있는 singleton provider에 대해 production module bootstrap과 같은 의미를 따릅니다. effective provider graph를 해석하고, testing module을 반환하기 전에 provider 순서대로 각 instance의 `onModuleInit()`을 실행한 뒤 `onApplicationBootstrap()`을 실행합니다. Builder는 반환 시점까지 내부에서 생성한 container를 소유합니다. Override 적용, lifecycle hook 실행, resolved singleton 동기화가 실패하면 reject하기 전에 container를 dispose합니다. Cleanup이 성공하면 원래 compile 실패를 그대로 보존하고, cleanup도 실패하면 원래 실패와 cleanup 실패를 `AggregateError`로 함께 보고합니다. 성공한 `TestingModuleRef`의 동작은 바뀌지 않으며 호출자는 unconditional `finally` 또는 `afterEach` cleanup을 통해 `module.container.dispose()`의 소유권을 계속 가집니다. `get()`은 synchronous singleton 및 multi-provider 경로에서도 DI ownership 의미를 보존하므로, 반복 sync read는 같은 singleton contribution을 재사용하고 container가 해당 instance를 계속 정리할 수 있습니다.
 
 ### `overrideModule()` 사용 시 모듈 identity 보존
 
@@ -120,7 +155,18 @@ try {
 
 `app.request(...).send()`는 수동 `FrameworkRequest`/`FrameworkResponse` stub 없이 HTTP 의미에 가까운 테스트를 작성하게 해 주고 runtime dispatch와 같은 isolated request-scoped DI boundary를 생성하므로 애플리케이션 개발자의 기본 경로입니다. Assertion 실패가 runtime resource 누수로 이어지지 않도록 반환된 app은 `finally` 블록에서 닫으세요. `app.dispatch(...)`, `makeRequest(...)`, raw `FluoFactory.create(...)` 테스트는 adapter/runtime contract, framework internal, 또는 low-level dispatch boundary 자체를 증명해야 하는 compatibility case에 남겨 둡니다.
 
-`createTestApp(...)`은 runtime HTTP bootstrap과 같은 application bootstrap option을 받습니다. 여기에는 `providers`, `filters`, `converters`, `interceptors`, `middleware`, `observers`, `versioning`, diagnostics option이 포함됩니다. 테스트 헬퍼는 request-context middleware를 앞에 추가하되, 호출자가 넘긴 middleware를 같은 app middleware chain 안에 보존합니다.
+Cookie-bound route에는 adapter가 정규화한 cookie 값을 담는 object request overload를 사용하세요.
+
+```ts
+const response = await app.request({
+  path: '/session',
+  cookies: { session: 'test-session' },
+}).send();
+```
+
+`cookies`는 `FrameworkRequest.cookies`에 직접 할당됩니다. `Cookie` header를 parse하거나 adapter별 cookie 의미를 도입하지 않습니다. `TestingModuleRef.dispatch(...)`도 같은 정규화된 cookie record를 받습니다.
+
+`createTestApp(...)`은 runtime HTTP bootstrap과 같은 application bootstrap option을 받습니다. 여기에는 `providers`, `filters`, `converters`, `interceptors`, `middleware`, `observers`, `versioning`, `conditionalRequest`, `errorRepresentation`, diagnostics option이 포함됩니다. 따라서 application test는 같은 virtual request pipeline으로 canonical JSON, negotiated HTML, conditional `304`/`412`, `HEAD`, 406, provider fallback을 검증할 수 있습니다. 테스트 헬퍼는 request-context middleware를 앞에 추가하되, 호출자가 넘긴 middleware를 같은 app middleware chain 안에 보존합니다.
 
 ### 명시적 서브패스의 mock 헬퍼
 
@@ -132,20 +178,34 @@ const repo = createMock<UserRepository>({ findById: vi.fn() });
 const mailer = createDeepMock(MailService);
 ```
 
-`asMock(value)`는 기존 값을 mock-friendly 타입으로 좁히고, `mockToken(token, value)`는 token 기반 override를 위해 `{ provide: token, useValue: value }` 형태의 `ValueProvider` descriptor를 만듭니다. `createMock(..., { strict: true })`는 지정하지 않은 member 접근을 거부합니다. `DeepMocked<T>`는 root `@fluojs/testing` 패키지, `@fluojs/testing/types`, `@fluojs/testing/mock`에서 모두 노출됩니다. 세 경로는 Vitest peer declaration을 non-mock runtime helper로 끌어들이지 않으면서 같은 Vitest-compatible mock type boundary를 공유합니다. Vitest를 사용하지 않는 소비자는 `@fluojs/testing/app`, `@fluojs/testing/module`, 또는 harness subpath에서 non-mock helper만 import하세요.
+`asMock(fn)`은 함수만 받아 Vitest `Mock<T>`로 좁히며, 임의의 값을 변환하는 cast가 아닙니다. `mockToken(token, value)`는 token 기반 override를 위해 `{ provide: token, useValue: value }` 형태의 `ValueProvider` descriptor를 만듭니다. `createMock(..., { strict: true })`는 지정하지 않은 member 접근을 거부합니다. `DeepMocked<T>`는 root `@fluojs/testing` 패키지, `@fluojs/testing/types`, `@fluojs/testing/mock`에서 모두 노출됩니다. 세 경로는 Vitest peer declaration을 non-mock runtime helper로 끌어들이지 않으면서 같은 Vitest-compatible mock type boundary를 공유합니다. Vitest를 사용하지 않는 소비자는 `@fluojs/testing/app`, `@fluojs/testing/module`, 또는 harness subpath에서 non-mock helper만 import하세요.
 
 배포된 런타임 import가 안정적으로 해석되도록, mock 헬퍼를 사용할 워크스페이스에는 `vitest`를 함께 설치해야 합니다.
 
 ### 적합성 및 이식성 하니스
 
-프레임워크 지향 플랫폼 패키지를 작성할 때는 `@fluojs/testing/platform-conformance`, `@fluojs/testing/http-adapter-portability`, `@fluojs/testing/web-runtime-adapter-portability` 같은 서브패스를 사용해 적합성 및 이식성 검증을 수행합니다.
+프레임워크 지향 플랫폼 패키지를 작성할 때는 `@fluojs/testing/platform-conformance`, `@fluojs/testing/platform-shell-lifecycle-conformance`, `@fluojs/testing/http-adapter-portability`, `@fluojs/testing/web-runtime-adapter-portability` 같은 서브패스를 사용해 적합성 및 이식성 검증을 수행합니다.
+
+`createPlatformShellLifecycleConformanceHarness({ createShell })`는 active `start()` / `stop()` overlap 전체가 `PlatformLifecycleConflictError`로 reject되는지, callback reentry가 synchronous 시점과 임의의 await 이후에도 conflict-safe한지, 실패한 transition이 settle된 뒤 호출자가 retry할 수 있는지 검증합니다. 컴포넌트 수준 검사는 `createPlatformConformanceHarness(...).assertAll()`에 유지하세요. PlatformShell lifecycle 계약은 의도적으로 별도 harness입니다.
 
 이식성 하니스의 cleanup도 계약에 포함됩니다. 앱이 bootstrap된 뒤 setup, `listen()`, partial app을 노출한 run callback, assertion이 실패하면 하니스는 해당 partial app을 닫습니다. `app.close()`가 실패하면 하니스는 cleanup 실패를 보고하며, setup 또는 assertion이 이미 실패한 경우에는 원래 실패와 cleanup 실패를 모두 보존하는 aggregate error를 발생시킵니다.
 
-`HttpAdapterPortabilityHarness`와 web-runtime portability harness 메서드는 공개 어댑터 계약 체크입니다. 직접 같은 검증을 다시 만들기보다 `assertPreservesMalformedCookieValues()`, `assertSupportsSseStreaming()`, `assertPreservesRawBodyForJsonAndText()`, `assertPreservesExactRawBodyBytesForByteSensitivePayloads()`, `assertExcludesRawBodyForMultipart()`, `assertDefaultsMultipartTotalLimitToMaxBodySize()`, `assertSettlesStreamDrainWaitOnClose()`, `assertReportsConfiguredHostInStartupLogs()`, `assertReportsHttpsStartupUrl(...)`, `assertRemovesShutdownSignalListenersAfterClose()`처럼 초점이 분명한 assertion을 사용하세요.
+`HttpAdapterPortabilityHarness`와 web-runtime portability harness 메서드는 공개 어댑터 계약 체크입니다. 직접 같은 검증을 다시 만들기보다 `assertSupportsCustomHttpRouteMethods()`, `assertPreservesMalformedCookieValues()`, `assertSupportsSseStreaming()`, `assertPreservesRawBodyForJsonAndText()`, `assertPreservesExactRawBodyBytesForByteSensitivePayloads()`, `assertExcludesRawBodyForMultipart()`, `assertDefaultsMultipartTotalLimitToMaxBodySize()`, `assertSettlesStreamDrainWaitOnClose()`, `assertReportsConfiguredHostInStartupLogs()`, `assertReportsHttpsStartupUrl(...)`, `assertRemovesShutdownSignalListenersAfterClose()`처럼 초점이 분명한 assertion을 사용하세요.
+
+Adapter가 body-bearing `QUERY`와 대표 `PURGE` route를 real listener 또는 fetch dispatch seam으로 실행하는지 증명하려면 `assertSupportsCustomHttpRouteMethods()`를 사용하세요. 이 assertion은 `CONNECT`를 일반 routing conformance 범위 밖에 두며 custom method에 native route handoff를 요구하지 않습니다.
 
 HTTP 어댑터가 런타임 전반에서 `rawBody`의 byte-sensitive payload byte를 그대로 보존하는지 증명해야 할 때는 `assertPreservesExactRawBodyBytesForByteSensitivePayloads()`를 사용하세요.
 
+JSON, HTML, `HEAD`, unsupported `Accept` 406, already-committed response 동작을 증명하려면
+`assertSupportsHttpErrorRepresentations()`를 사용하세요. Network harness는 shared
+`NetworkHttpErrorRepresentationBootstrapOptions`를 adapt하고 fetch-style harness는
+`WebHttpErrorRepresentationBootstrapOptions`를 adapt합니다. Adapter bootstrap type에 추가 required field가
+있다면 `createErrorRepresentationBootstrapOptions`를 제공하세요. Typed builder는 common fixture field만 받아 cast
+없이 해당 adapter의 complete bootstrap option을 반환합니다.
+`assertDoesNotCommitAbortedHttpErrorRepresentations()`는 HTML provider를 시작한 뒤 adapter의 native request
+surface를 통해 abort하고, cancellation 이후 provider result와 canonical JSON fallback 어느 쪽도 write되지 않음을
+증명합니다.
+
 ## canonical TDD ladder
 
 애플리케이션 기능 테스트는 가장 작은 명시적 dependency boundary에서 시작해 바깥쪽으로 확장합니다.
@@ -167,14 +227,35 @@ test/
 
 fluo는 테스트가 명시적인 `rootModule`을 이름으로 지정해야 한다는 점에서 NestJS와 다릅니다. 테스트 유틸리티는 legacy TypeScript design metadata나 reflection flag에서 dependency를 추론하지 않고, 작성자가 만든 module graph를 컴파일합니다.
 
+## React Consumer Testing Recipe
+
+React 애플리케이션은 같은 testing ladder를 유지하고 React-specific testing helper 대신 기존 boundary에
+build/browser evidence를 추가합니다.
+
+1. Render-policy 및 metadata composition을 pure value로 unit test합니다.
+2. Direct page return, missing-renderer diagnostic, DTO validation, request-scope identity, response ownership,
+   guard, interceptor, native mutation route는 `createTestApp({ rootModule })`로 검증하고 `finally`에서 app을
+   닫습니다.
+3. CI에서 `fluo typegen ... --check`를 실행하고 generated-route fixture를 TypeScript로 compile합니다.
+   Positive route-id/params case와 negative unknown-id, missing-param, extra-param, stale-output case를 유지합니다.
+4. React DOM으로 server markup을 hydrate합니다. Aligned tree는 diagnostic 없이 interactive해야 하고,
+   의도적으로 mismatch한 tree 하나는 `onRecoverableError`를 capture해야 합니다.
+5. Production asset을 대상으로 Playwright를 실행한 뒤 별도 `javaScriptEnabled: false` context에서 native
+   form scenario를 반복해 일반 `POST` → `303` → `GET` fallback을 executable 상태로 유지합니다.
+
+Runnable map은 [`@fluojs/react`](../react/README.ko.md#consumer-testing-loop)와
+[`examples/react-vite-ssr`](../../examples/react-vite-ssr/README.ko.md#canonical-consumer-test-map)에
+문서화되어 있습니다. 이 layer들은 이미 real HTTP dispatcher와 application page renderer를 compose하므로
+synthetic React test runtime은 필요한 setup을 줄이기보다 coverage를 약화시킵니다.
+
 ## 공개 API
 
 - **루트 패키지**: `createTestingModule(...)`, `Test.createTestingModule(...)`, `createTestApp(...)`, 모듈 introspection 헬퍼, `DeepMocked<T>`를 포함한 공용 app/module 테스트 타입
 - **서브패스**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock` (`DeepMocked<T>` 포함), `@fluojs/testing/types` (`DeepMocked<T>` 포함), `@fluojs/testing/vitest`, `@fluojs/testing/vitest/tooling`
-- **하니스 서브패스**: `platform-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`
+- **하니스 서브패스**: `platform-conformance`, `platform-shell-lifecycle-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`. HTTP portability harness는 adapter-owned bootstrap typing을 위해 `assertSupportsConditionalRequests()`, `assertSupportsCustomHttpRouteMethods()`, `assertSupportsSingleByteRanges()`, `assertSupportsHttpErrorRepresentations()`, `assertDoesNotCommitAbortedHttpErrorRepresentations()`, `assertSupportsPortableResponseCookies()`, `createConditionalRequestBootstrapOptions`, `createErrorRepresentationBootstrapOptions`, `NetworkHttpErrorRepresentationBootstrapOptions`, `WebHttpErrorRepresentationBootstrapOptions`를 노출합니다.
 - **도구 지원**: `@fluojs/testing/vitest`의 `fluoBabelDecoratorsPlugin()` 및 `@fluojs/testing/vitest/tooling`의 Vitest workspace config helper (`vitest`와 `@babel/core`를 함께 요구)
 
-Package manifest는 `engines.node >=20.0.0`을 선언합니다. 문서화된 경우 non-Node runtime 애플리케이션 테스트에서 runtime-native 도구를 사용할 수 있지만, 배포된 `@fluojs/testing` 패키지 자체는 이 Node.js engine floor를 따릅니다.
+Package manifest는 public body-bearing RFC `QUERY` portability assertion이 사용하는 검증된 Node listener window와 일치하도록 `engines.node >=24.0.0 <27`을 선언합니다. Node 24 미만과 Node 27 이상은 제외됩니다. 문서화된 경우 non-Node runtime 애플리케이션 테스트에서 runtime-native 도구를 사용할 수 있지만, 배포된 `@fluojs/testing` 패키지 자체는 이 정확한 Node.js engine 범위를 따릅니다.
 
 `@fluojs/testing/vitest/tooling`은 각 package의 공개 `exports`에 선언된 entrypoint만 workspace alias로 매핑합니다. Private source file, internal helper, export되지 않은 source entrypoint는 의도적으로 제외하므로 테스트가 published package 소비자에게 제공되는 import boundary와 같은 경계를 검증합니다.
 
@@ -187,5 +268,6 @@ Package manifest는 `engines.node >=20.0.0`을 선언합니다. 문서화된 경
 ## 예제 소스
 
 - `packages/testing/src/module.test.ts`
+- `packages/testing/src/portability/error-representation-portability.ts`
 - `examples/minimal/src/app.test.ts`
 - `examples/auth-jwt-passport/src/app.test.ts`

package/README.md

@@ -2,7 +2,9 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-Node.js 20+ request-level testing helpers, testing module construction, and provider overrides for fluo applications.
+Node.js `>=24.0.0 <27` request-level testing helpers, testing module construction, and provider overrides for fluo applications.
+
+Preparing for the coordinated Node 24 release? Follow the [consumer migration guide](../../docs/getting-started/migrate-node24.md) before upgrading packages.
 
 ## Table of Contents
 
@@ -11,6 +13,7 @@ Node.js 20+ request-level testing helpers, testing module construction, and prov
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
 - [Canonical TDD Ladder](#canonical-tdd-ladder)
+- [React Consumer Testing Recipe](#react-consumer-testing-recipe)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -21,9 +24,9 @@ Node.js 20+ request-level testing helpers, testing module construction, and prov
 pnpm add -D @fluojs/testing vitest
 ```
 
-`vitest` is a required peer dependency for the mock helpers and the `@fluojs/testing/vitest` entrypoint. `@babel/core` is declared as a peer because the Vitest decorators plugin loads Babel from the consuming workspace; package managers may surface that peer even when you only use the non-Vitest harness subpaths.
+Vitest `^4.1.11` is a required peer dependency for the mock helpers and the `@fluojs/testing/vitest` entrypoint. `@babel/core` is declared as a peer because the Vitest decorators plugin loads Babel from the consuming workspace; package managers may surface that peer even when you only use the non-Vitest harness subpaths.
 
-If you use `@fluojs/testing/vitest`, install `@babel/core` in the consuming workspace as well because `fluoBabelDecoratorsPlugin()` invokes Babel at runtime. The Vitest plugin transforms `.ts`, `.tsx`, `.mts`, and `.cts` source ids after removing Vite query/hash suffixes, skips `node_modules`, and resolves the nearest root Babel config named `babel.config.cjs`, `babel.config.mjs`, `babel.config.js`, or `babel.config.json`:
+If you use `@fluojs/testing/vitest`, install `@babel/core` in the consuming workspace as well because `fluoBabelDecoratorsPlugin()` invokes Babel at runtime. The Vitest plugin runs with `enforce: 'pre'` so decorator-bearing TypeScript reaches Babel before Vite 8 normal-stage Rolldown/Oxc transforms. It transforms `.ts`, `.tsx`, `.mts`, and `.cts` source ids after removing Vite query/hash suffixes, skips `node_modules`, and resolves the nearest root Babel config named `babel.config.cjs`, `babel.config.mjs`, `babel.config.js`, or `babel.config.json`:
 
 ```bash
 pnpm add -D @babel/core
@@ -74,12 +77,44 @@ const module = await createTestingModule({ rootModule: AppModule })
   })
   .compile();
 
-const service = await module.resolve(UserService);
+let testError: unknown;
+let testFailed = false;
+let disposeError: unknown;
+let disposeFailed = false;
+
+try {
+  const service = await module.resolve(UserService);
+} catch (error: unknown) {
+  testError = error;
+  testFailed = true;
+} finally {
+  try {
+    await module.container.dispose();
+  } catch (error: unknown) {
+    disposeFailed = true;
+    disposeError = error;
+  }
+}
+
+if (testFailed) {
+  if (disposeFailed) {
+    throw new AggregateError(
+      [testError, disposeError],
+      'Test and testing module disposal both failed.',
+    );
+  }
+
+  throw testError;
+}
+
+if (disposeFailed) {
+  throw disposeError;
+}
 ```
 
-The testing builder also supports `overrideProviders([[token, value], ...])`, `overrideGuard(...)`, `overrideInterceptor(...)`, and `overrideFilter(...)` for route-pipeline tests that need to replace cross-cutting behavior. Guard and interceptor overrides are request-path safe when the route references the same token via `@UseGuards(...)` or `@UseInterceptors(...)`; filter overrides replace the token in the compiled module graph and should be paired with request-level coverage where that filter is registered in the runtime app surface.
+The testing builder also supports `overrideProviders([[token, value], ...])`, `overrideGuard(...)`, `overrideInterceptor(...)`, and `overrideFilter(...)` for route-pipeline tests that need to replace cross-cutting behavior. Guard and interceptor overrides are request-path safe when the route references the same token via `@UseGuards(...)` or `@UseInterceptors(...)`; filter overrides replace the token in the compiled module graph and should be paired with request-level coverage where that filter is registered in the runtime app surface. Retain every successfully compiled `TestingModuleRef` and dispose its caller-owned `container` from `finally` (or `afterEach` for suite setup) so passing, failing, and early-returning tests all release lifecycle resources. A completed `container.dispose()` is idempotent. Teardown failures surface; when an in-flight assertion can also fail, report both errors (for example with `AggregateError`) rather than suppressing or replacing the assertion failure.
 
-`compile()` follows production module-bootstrap semantics for lifecycle-bearing singleton providers: it resolves the effective provider graph, runs `onModuleInit()` for each resolved instance, then runs `onApplicationBootstrap()` in the same provider order before the testing module is returned. `get()` keeps DI ownership semantics for synchronous singleton and multi-provider paths, so repeated sync reads reuse the same singleton contributions and `module.container.dispose()` can still clean them up.
+`compile()` follows production module-bootstrap semantics for lifecycle-bearing singleton providers, including module-declared and overridden factory providers: it resolves the effective provider graph, runs `onModuleInit()` for each resolved instance, then runs `onApplicationBootstrap()` in the same provider order before the testing module is returned. The builder owns its internally created container until that return: if applying overrides, running lifecycle hooks, or synchronizing resolved singletons fails, it disposes the container before rejecting. Successful cleanup preserves the original compile failure; a cleanup failure is reported with the original failure in an `AggregateError`. Successful `TestingModuleRef` behavior is unchanged, and callers retain ownership of `module.container.dispose()` through an unconditional `finally` or `afterEach` cleanup. `get()` keeps DI ownership semantics for synchronous singleton and multi-provider paths, so repeated sync reads reuse the same singleton contributions and the container can still clean them up.
 
 ### Preserve module identity with `overrideModule()`
 
@@ -118,7 +153,18 @@ try {
 
 `app.request(...).send()` is the preferred app-developer path because it keeps tests close to HTTP semantics without manual `FrameworkRequest`/`FrameworkResponse` stubs and creates the same isolated request-scoped DI boundary as runtime dispatch. Close the returned app from a `finally` block so assertion failures do not leak runtime resources. Keep `app.dispatch(...)`, `makeRequest(...)`, and raw `FluoFactory.create(...)` tests for adapter/runtime contracts, framework internals, or compatibility cases where the low-level dispatch boundary itself is what the test must prove.
 
-`createTestApp(...)` accepts the same application bootstrap options as the runtime HTTP bootstrap, including `providers`, `filters`, `converters`, `interceptors`, `middleware`, `observers`, `versioning`, and diagnostics options. The testing helper prepends its request-context middleware while preserving caller-provided middleware in the same app middleware chain.
+For cookie-bound routes, use the object request overload with adapter-normalized cookie values:
+
+```ts
+const response = await app.request({
+  path: '/session',
+  cookies: { session: 'test-session' },
+}).send();
+```
+
+`cookies` is assigned directly to `FrameworkRequest.cookies`; it does not parse a `Cookie` header or introduce adapter-specific cookie semantics. `TestingModuleRef.dispatch(...)` accepts the same normalized cookie record.
+
+`createTestApp(...)` accepts the same application bootstrap options as the runtime HTTP bootstrap, including `providers`, `filters`, `converters`, `interceptors`, `middleware`, `observers`, `versioning`, `conditionalRequest`, `errorRepresentation`, and diagnostics options. This lets application tests assert canonical JSON, negotiated HTML, conditional `304`/`412`, `HEAD`, 406, and provider fallback behavior through the same virtual request pipeline. The testing helper prepends its request-context middleware while preserving caller-provided middleware in the same app middleware chain.
 
 ### Mock helpers from explicit subpaths
 
@@ -130,20 +176,34 @@ const repo = createMock<UserRepository>({ findById: vi.fn() });
 const mailer = createDeepMock(MailService);
 ```
 
-`asMock(value)` narrows an existing value to a mock-friendly type, and `mockToken(token, value)` creates a `ValueProvider` descriptor shaped as `{ provide: token, useValue: value }` for token-based overrides. `createMock(..., { strict: true })` rejects access to unspecified members. `DeepMocked<T>` is exposed from the root `@fluojs/testing` package, `@fluojs/testing/types`, and `@fluojs/testing/mock`; all three paths intentionally share the same Vitest-compatible mock type boundary without importing Vitest peer declarations through non-mock runtime helpers. Consumers that do not use Vitest should import only non-mock helpers from `@fluojs/testing/app`, `@fluojs/testing/module`, or the harness subpaths.
+`asMock(fn)` accepts only a function and narrows it to Vitest `Mock<T>`; it is not an arbitrary-value cast. `mockToken(token, value)` creates a `ValueProvider` descriptor shaped as `{ provide: token, useValue: value }` for token-based overrides. `createMock(..., { strict: true })` rejects access to unspecified members. `DeepMocked<T>` is exposed from the root `@fluojs/testing` package, `@fluojs/testing/types`, and `@fluojs/testing/mock`; all three paths intentionally share the same Vitest-compatible mock type boundary without importing Vitest peer declarations through non-mock runtime helpers. Consumers that do not use Vitest should import only non-mock helpers from `@fluojs/testing/app`, `@fluojs/testing/module`, or the harness subpaths.
 
 Install `vitest` in the consuming workspace before using the mock helpers so the published runtime import resolves consistently.
 
 ### Conformance and portability harnesses
 
-Use subpaths like `@fluojs/testing/platform-conformance`, `@fluojs/testing/http-adapter-portability`, and `@fluojs/testing/web-runtime-adapter-portability` when authoring framework-facing platform packages.
+Use subpaths like `@fluojs/testing/platform-conformance`, `@fluojs/testing/platform-shell-lifecycle-conformance`, `@fluojs/testing/http-adapter-portability`, and `@fluojs/testing/web-runtime-adapter-portability` when authoring framework-facing platform packages.
+
+Use `createPlatformShellLifecycleConformanceHarness({ createShell })` to verify every active `start()` / `stop()` overlap rejects with `PlatformLifecycleConflictError`, callback reentry remains conflict-safe before and after arbitrary awaits, and callers can retry after a failed transition settles. Keep component-level checks in `createPlatformConformanceHarness(...).assertAll()`; the PlatformShell lifecycle contract is intentionally a separate harness.
 
 Portability harness cleanup is part of the contract: if setup, `listen()`, a run callback that surfaces a partial app, or an assertion fails after an app has been bootstrapped, the harness closes that partial app. If `app.close()` fails, the harness reports that cleanup failure, and when setup or an assertion already failed it raises an aggregate error that preserves both the original failure and the cleanup failure.
 
-`HttpAdapterPortabilityHarness` and web-runtime portability harness methods are the public adapter contract checks. Prefer focused assertions such as `assertPreservesMalformedCookieValues()`, `assertSupportsSseStreaming()`, `assertPreservesRawBodyForJsonAndText()`, `assertPreservesExactRawBodyBytesForByteSensitivePayloads()`, `assertExcludesRawBodyForMultipart()`, `assertDefaultsMultipartTotalLimitToMaxBodySize()`, `assertSettlesStreamDrainWaitOnClose()`, `assertReportsConfiguredHostInStartupLogs()`, `assertReportsHttpsStartupUrl(...)`, and `assertRemovesShutdownSignalListenersAfterClose()` instead of hand-rolled equivalents.
+`HttpAdapterPortabilityHarness` and web-runtime portability harness methods are the public adapter contract checks. Prefer focused assertions such as `assertSupportsCustomHttpRouteMethods()`, `assertPreservesMalformedCookieValues()`, `assertSupportsSseStreaming()`, `assertPreservesRawBodyForJsonAndText()`, `assertPreservesExactRawBodyBytesForByteSensitivePayloads()`, `assertExcludesRawBodyForMultipart()`, `assertDefaultsMultipartTotalLimitToMaxBodySize()`, `assertSettlesStreamDrainWaitOnClose()`, `assertReportsConfiguredHostInStartupLogs()`, `assertReportsHttpsStartupUrl(...)`, and `assertRemovesShutdownSignalListenersAfterClose()` instead of hand-rolled equivalents.
+
+Use `assertSupportsCustomHttpRouteMethods()` to prove that the adapter executes body-bearing `QUERY` and representative `PURGE` routes through its real listener or fetch dispatch seam. The assertion keeps `CONNECT` outside ordinary routing conformance and does not require custom methods to use a native route handoff.
 
 Use `assertPreservesExactRawBodyBytesForByteSensitivePayloads()` when an HTTP adapter must prove `rawBody` keeps byte-sensitive payload bytes intact across runtimes.
 
+Use `assertSupportsHttpErrorRepresentations()` to prove JSON, HTML, `HEAD`, unsupported `Accept`
+406, and already-committed response behavior. Network harnesses adapt the shared
+`NetworkHttpErrorRepresentationBootstrapOptions`; fetch-style harnesses adapt
+`WebHttpErrorRepresentationBootstrapOptions`. Supply `createErrorRepresentationBootstrapOptions`
+when an adapter's bootstrap type contains additional required fields—the typed builder receives only
+the common fixture fields and returns that adapter's complete bootstrap options without casts.
+Use `assertDoesNotCommitAbortedHttpErrorRepresentations()` to start an HTML provider, abort through
+the adapter's native request surface, and prove that neither the provider result nor canonical JSON
+fallback is written after cancellation.
+
 ## Canonical TDD Ladder
 
 For application features, build tests from the smallest explicit dependency boundary outward:
@@ -165,14 +225,37 @@ test/
 
 fluo differs from NestJS by requiring tests to name an explicit `rootModule`. The testing utilities compile the module graph you authored instead of inferring dependencies from legacy TypeScript design metadata or reflection flags.
 
+## React Consumer Testing Recipe
+
+React applications keep the same testing ladder and add build/browser evidence at the existing
+boundaries instead of introducing a React-specific testing helper:
+
+1. Unit-test render-policy and metadata composition as pure values.
+2. Use `createTestApp({ rootModule })` for direct page returns, missing-renderer diagnostics, DTO
+   validation, request-scope identity, response ownership, guards, interceptors, and native mutation
+   routes. Close the app in `finally`.
+3. Run `fluo typegen ... --check` in CI and compile generated-route fixtures with TypeScript. Keep
+   positive route-id/params cases and negative unknown-id, missing-param, extra-param, and stale-output
+   cases.
+4. Hydrate server markup with React DOM. Assert an aligned tree is interactive without diagnostics,
+   and capture `onRecoverableError` for one deliberately mismatched tree.
+5. Run Playwright against production assets, then repeat the native form scenario in a separate
+   `javaScriptEnabled: false` context so the ordinary `POST` → `303` → `GET` fallback stays executable.
+
+The runnable map is documented in
+[`@fluojs/react`](../react/README.md#consumer-testing-loop) and
+[`examples/react-vite-ssr`](../../examples/react-vite-ssr/README.md#canonical-consumer-test-map).
+These layers already compose the real HTTP dispatcher and application page renderer, so a synthetic
+React test runtime would reduce coverage rather than remove necessary setup.
+
 ## Public API
 
 - **Root package**: `createTestingModule(...)`, `Test.createTestingModule(...)`, `createTestApp(...)`, module introspection helpers, and shared app/module testing types including `DeepMocked<T>`
 - **Subpaths**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock` (including `DeepMocked<T>`), `@fluojs/testing/types` (including `DeepMocked<T>`), `@fluojs/testing/vitest`, `@fluojs/testing/vitest/tooling`
-- **Harness subpaths**: `platform-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`
+- **Harness subpaths**: `platform-conformance`, `platform-shell-lifecycle-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`. The HTTP portability harnesses expose `assertSupportsConditionalRequests()`, `assertSupportsCustomHttpRouteMethods()`, `assertSupportsSingleByteRanges()`, `assertSupportsHttpErrorRepresentations()`, `assertDoesNotCommitAbortedHttpErrorRepresentations()`, `assertSupportsPortableResponseCookies()`, `createConditionalRequestBootstrapOptions`, `createErrorRepresentationBootstrapOptions`, `NetworkHttpErrorRepresentationBootstrapOptions`, and `WebHttpErrorRepresentationBootstrapOptions` for adapter-owned bootstrap typing.
 - **Tooling**: `@fluojs/testing/vitest` with `fluoBabelDecoratorsPlugin()` and `@fluojs/testing/vitest/tooling` with Vitest workspace config helpers (requires `vitest` and `@babel/core` in the consuming workspace)
 
-The package manifest declares `engines.node >=20.0.0`. Non-Node runtime application tests can still use runtime-native tools where documented, but the published `@fluojs/testing` package itself is governed by that Node.js engine floor.
+The package manifest declares `engines.node >=24.0.0 <27`, matching the verified Node listener windows used by its public body-bearing RFC `QUERY` portability assertion. Node versions below 24 and Node 27+ are excluded. Non-Node runtime application tests can still use runtime-native tools where documented, but the published `@fluojs/testing` package itself is governed by that exact Node.js engine range.
 
 `@fluojs/testing/vitest/tooling` maps workspace aliases only for each package's declared public `exports`. Private source files, internal helpers, and unexported source entrypoints are intentionally excluded so tests exercise the same import boundaries that consumers receive from published packages.
 
@@ -185,5 +268,6 @@ The package manifest declares `engines.node >=20.0.0`. Non-Node runtime applicat
 ## Example Sources
 
 - `packages/testing/src/module.test.ts`
+- `packages/testing/src/portability/error-representation-portability.ts`
 - `examples/minimal/src/app.test.ts`
 - `examples/auth-jwt-passport/src/app.test.ts`

package/dist/babel-decorators-plugin.d.ts

@@ -16,6 +16,7 @@ export declare function resolveNearestBabelConfigFile(filePath: string): string;
  */
 export declare function createFluoBabelDecoratorsPlugin(resolveConfigFile: (filePath: string) => string): {
     name: string;
+    enforce: "pre";
     transform(code: string, id: string): Promise<{
         code: string;
         map: {

package/dist/babel-decorators-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"babel-decorators-plugin.d.ts","sourceRoot":"","sources":["../src/babel-decorators-plugin.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2BtE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM;;oBAIvB,MAAM,MAAM,MAAM;;;;;;;;;;;;EAwB3C;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,UAAU,CAAC,OAAO,+BAA+B,CAAC,CAAC"}
+{"version":3,"file":"babel-decorators-plugin.d.ts","sourceRoot":"","sources":["../src/babel-decorators-plugin.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2BtE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM;;;oBAKvB,MAAM,MAAM,MAAM;;;;;;;;;;;;EAwB3C;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,UAAU,CAAC,OAAO,+BAA+B,CAAC,CAAC"}

package/dist/babel-decorators-plugin.js

@@ -54,6 +54,7 @@ export function resolveNearestBabelConfigFile(filePath) {
 export function createFluoBabelDecoratorsPlugin(resolveConfigFile) {
   return {
     name: 'fluo-babel-decorators',
+    enforce: 'pre',
     async transform(code, id) {
       const filePath = normalizeTransformId(id);
       if (!isTypeScriptSource(filePath) || isNodeModulesPath(filePath)) {

package/dist/byte-range-portability-consumer.test-fixture.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=byte-range-portability-consumer.test-fixture.d.ts.map

package/dist/byte-range-portability-consumer.test-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-range-portability-consumer.test-fixture.d.ts","sourceRoot":"","sources":["../src/byte-range-portability-consumer.test-fixture.ts"],"names":[],"mappings":""}

package/dist/byte-range-portability-consumer.test-fixture.js

@@ -0,0 +1,11 @@
+import { createByteRangeResponse } from '@fluojs/http';
+import { createHttpAdapterPortabilityHarness } from '@fluojs/testing/http-adapter-portability';
+import { createWebRuntimeHttpAdapterPortabilityHarness } from '@fluojs/testing/web-runtime-adapter-portability';
+const bytes = Uint8Array.from([0, 1, 2]);
+const options = {
+  contentType: 'application/octet-stream'
+};
+const source = bytes;
+void createByteRangeResponse(source, options);
+void createHttpAdapterPortabilityHarness;
+void createWebRuntimeHttpAdapterPortabilityHarness;

package/dist/conformance/fetch-style-websocket-conformance.d.ts

@@ -6,6 +6,7 @@ export interface FetchStyleWebSocketConformanceHarnessOptions<TAdapter extends H
     createAdapter: () => TAdapter;
     expectedReason: string;
     expectedSupport?: FetchStyleHttpAdapterRealtimeCapability['support'];
+    expectedVersion?: FetchStyleHttpAdapterRealtimeCapability['version'];
     name: string;
 }
 /**

package/dist/conformance/fetch-style-websocket-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-style-websocket-conformance.d.ts","sourceRoot":"","sources":["../../src/conformance/fetch-style-websocket-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uCAAuC,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,4CAA4C,CAC3D,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IAEhE,aAAa,EAAE,MAAM,QAAQ,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,qBAAa,qCAAqC,CAChD,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,4CAA4C,CAAC,QAAQ,CAAC;IAE5F,0CAA0C,IAAI,IAAI;CAoCnD;AAED;;;;;GAKG;AACH,wBAAgB,2CAA2C,CACzD,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB,EAEhE,OAAO,EAAE,4CAA4C,CAAC,QAAQ,CAAC,GAC9D,qCAAqC,CAAC,QAAQ,CAAC,CAEjD"}
+{"version":3,"file":"fetch-style-websocket-conformance.d.ts","sourceRoot":"","sources":["../../src/conformance/fetch-style-websocket-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uCAAuC,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,4CAA4C,CAC3D,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IAEhE,aAAa,EAAE,MAAM,QAAQ,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,qBAAa,qCAAqC,CAChD,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,4CAA4C,CAAC,QAAQ,CAAC;IAE5F,0CAA0C,IAAI,IAAI;CAoCnD;AAED;;;;;GAKG;AACH,wBAAgB,2CAA2C,CACzD,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB,EAEhE,OAAO,EAAE,4CAA4C,CAAC,QAAQ,CAAC,GAC9D,qCAAqC,CAAC,QAAQ,CAAC,CAEjD"}

package/dist/conformance/fetch-style-websocket-conformance.js

@@ -25,7 +25,7 @@ export class FetchStyleWebSocketConformanceHarness {
     if (capability.mode !== 'request-upgrade') {
       throw new Error(`${this.options.name} adapter changed the fetch-style raw websocket upgrade mode.`);
     }
-    if (capability.version !== 1) {
+    if (capability.version !== (this.options.expectedVersion ?? 1)) {
       throw new Error(`${this.options.name} adapter changed the fetch-style raw websocket contract version.`);
     }
     if (capability.support !== expectedSupport) {

package/dist/conformance/platform-shell-lifecycle-conformance.d.ts

@@ -0,0 +1,30 @@
+import type { PlatformComponent, PlatformShell } from '@fluojs/runtime';
+/**
+ * Describes the PlatformShell lifecycle conformance harness options contract.
+ */
+export interface PlatformShellLifecycleConformanceHarnessOptions {
+    createShell: (component: PlatformComponent) => PlatformShell;
+}
+/**
+ * Represents lifecycle exclusivity checks for a PlatformShell implementation.
+ */
+export declare class PlatformShellLifecycleConformanceHarness {
+    private readonly options;
+    constructor(options: PlatformShellLifecycleConformanceHarnessOptions);
+    assertAll(): Promise<void>;
+    assertOverlappingTransitionsRejectImmediately(): Promise<void>;
+    assertCallbackReentryRejects(): Promise<void>;
+    assertSettledTransitionsPermitRetries(): Promise<void>;
+    assertSequentialTransitionsRemainIdempotent(): Promise<void>;
+    private assertSynchronousStartCallbackReentryRejects;
+    private assertAwaitedStopCallbackReentryRejects;
+    private assertFailedTransitionPermitsRetry;
+}
+/**
+ * Create PlatformShell lifecycle conformance harness.
+ *
+ * @param options The options.
+ * @returns The create PlatformShell lifecycle conformance harness result.
+ */
+export declare function createPlatformShellLifecycleConformanceHarness(options: PlatformShellLifecycleConformanceHarnessOptions): PlatformShellLifecycleConformanceHarness;
+//# sourceMappingURL=platform-shell-lifecycle-conformance.d.ts.map

package/dist/conformance/platform-shell-lifecycle-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-shell-lifecycle-conformance.d.ts","sourceRoot":"","sources":["../../src/conformance/platform-shell-lifecycle-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EAIjB,aAAa,EAId,MAAM,iBAAiB,CAAC;AA4GzB;;GAEG;AACH,MAAM,WAAW,+CAA+C;IAC9D,WAAW,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,aAAa,CAAC;CAC9D;AAED;;GAEG;AACH,qBAAa,wCAAwC;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,+CAA+C;IAE/E,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAO1B,6CAA6C,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC9D,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7C,qCAAqC,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtD,2CAA2C,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBpD,4CAA4C;YAkB5C,uCAAuC;YAqBvC,kCAAkC;CAsBjD;AAkDD;;;;;GAKG;AACH,wBAAgB,8CAA8C,CAC5D,OAAO,EAAE,+CAA+C,GACvD,wCAAwC,CAE1C"}