@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/docs/direct-values.md

@@ -1,10 +1,10 @@
 # Direct scalar values
 
-Internal direct mapping, bare-root XML codec and portable source contract. See the root [README](../README.md) and [matching contract](content-model-matching.md).
+Internal direct mapping, bare-root XML codec and portable source contract. See the root [README](../README.md) and [matching contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-matching.md).
 
 ## Package-root binding for generated direct clients
 
-The unreleased additive root export `checkedDirectRuntimeV1` runs an already generated checked direct client through the existing native source, capsule, schema/scalar, XML and buffered SOAP engines. Package metadata remains 1.1.4; published 1.x packages do not thereby gain structured generation support. Generation remains internal, and existing CLI commands and legacy defaults are unchanged.
+The root export `checkedDirectRuntimeV1` preserves the v1.1.5 execution contract for existing generated direct clients through the native source, capsule, schema/scalar, XML and buffered SOAP engines. The [checked gateway workflow](checked-gateway.md) exposes legacy and component generation; the unpublished intermediate direct-generation choice has been removed. Frozen v1.1.5-issued client and capsule fixtures verify compatibility against the installed candidate runtime. Historical P3 sections below record earlier internal milestones, not another current public generation entry.
 
 Use a matched generated client, capsule and explicitly authorized original local WSDL. The caller supplies its actual owned server endpoint; a WSDL service address never authorizes dispatch.
 
@@ -50,7 +50,7 @@ Failures retain `unsupported`, `missing-authority`, `incompatible-artifact`, `in
 
 ### Restricted supported grammar
 
-This entry supports one safe UTF-8 local WSDL resource and SOAP 1.1 document/literal over explicitly authorized owned IPv4 loopback HTTP. Values are built-in string/int32/Boolean scalar roots, empty sequences or flat sequences of distinct scalar elements with minOccurs 0/1 and maxOccurs 1/unbounded, including declared faults. Source loading and native qualification retain the [direct correspondence restrictions](decisions/003-content-model-contracts.md#qualified-dated-xsd-direct-route).
+This entry supports one safe UTF-8 local WSDL resource and SOAP 1.1 document/literal over explicitly authorized owned IPv4 loopback HTTP. Values are built-in string/int32/Boolean scalar roots, empty sequences or flat sequences of distinct scalar elements with minOccurs 0/1 and maxOccurs 1/unbounded, including declared faults. Source loading and native qualification retain the [direct correspondence restrictions](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/003-content-model-contracts.md#qualified-dated-xsd-direct-route).
 
 Nested complex/group content, attributes, nil, facets, import/include graphs and general XSD completeness are outside this slice. Dependency-reserved names such as `__proto__`, `constructor`, `toString`, inherited Object.prototype names and `prototype` refuse safely. Remote source loading, production endpoints, TLS/auth/WS-Security, arbitrary headers, SOAP 1.2, redirects, attachments, compression and streaming remain unsupported. `admitted:false` remains unchanged.
 
@@ -186,7 +186,7 @@ P3.4 under [#384](https://github.com/TechSpokes/typescript-wsdl-client/issues/38
 
 `encodeDirectXml(contract, mapping, freshValue, options?)` calls `expandDirectValue` before emitting deterministic UTF-8 bytes. It returns `direct-encoded` with caller-owned mutable `bytes`, the authentic `expanded` receipt, encoding and usage. The byte array is data, never authority; changing it cannot change the validated expansion or authenticate another payload.
 
-`decodeDirectXml(contract, mapping, bytes, options?)` accepts a non-shared `Uint8Array` or Buffer, copies its native byte slots without length/buffer/iterator getters, parses ordered observed syntax, then calls `matchDirectOperation` and `assessDirectScalars`. It returns `direct-decoded` with immutable observed `payload`, authentic `validated` receipt and usage. Both APIs are internal exports from [directCodec.ts](../src/compiler/directCodec.ts), absent from the package public API.
+`decodeDirectXml(contract, mapping, bytes, options?)` accepts a non-shared `Uint8Array` or Buffer, copies its native byte slots without length/buffer/iterator getters, parses ordered observed syntax, then calls `matchDirectOperation` and `assessDirectScalars`. It returns `direct-decoded` with immutable observed `payload`, authentic `validated` receipt and usage. Both APIs are internal exports from [directCodec.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/compiler/directCodec.ts), absent from the package public API.
 
 Identity checks precede property/version interpretation. Foreign/copied/JSON/wrong-version handles throw TypeError; genuine future incompatible metadata returns unsupported. Direction and exact root come from the mapping, with no guessed catalog upgrade or source reload. SOAP 1.1 document/literal binding/action remain source metadata and authorize no I/O.
 
@@ -200,7 +200,7 @@ Prefixes are allocated by first source-order use of expanded namespaces, then bo
 
 ### Secure byte boundary and provenance
 
-The codec reuses [orderedSyntax.ts](../src/loader/orderedSyntax.ts) with namespace-aware `saxes` 6.0.0, strict fatal decoding and XML 1.0-only mode. Saxes is an in-memory tokenizer with no resolver or external I/O; DTD declarations are refused, predefined/numeric references are processed, and unknown/general/external entities fail. Schema locations, namespace URIs and xml:base are never fetched; unsupported application attributes, nil and xsi:type fail through the existing matcher.
+The codec reuses [orderedSyntax.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/loader/orderedSyntax.ts) with namespace-aware `saxes` 6.0.0, strict fatal decoding and XML 1.0-only mode. Saxes is an in-memory tokenizer with no resolver or external I/O; DTD declarations are refused, predefined/numeric references are processed, and unknown/general/external entities fail. Schema locations, namespace URIs and xml:base are never fetched; unsupported application attributes, nil and xsi:type fail through the existing matcher.
 
 UTF-8 with optional BOM and BOM-qualified UTF-16LE/BE are supported. XML declaration encoding must agree with the bytes; unsupported encodings, doubled BOMs, isolated surrogates, malformed Unicode, namespace errors, multiple roots and truncated syntax fail without repair. XML 1.1 is unsupported. BOM-less UTF-16 is refused. EOF completion precedes any successful decoded result.
 
@@ -238,15 +238,15 @@ console.log(decoded.validated.value);
 
 ### Qualification and remaining boundary
 
-[Codec controls](../test/unit/direct-codec.test.ts) run the actual Forecast request/response/ForecastError fixture payload bytes against independent expectations, fresh-byte laws, renamed/form/prefix sources, scalar/empty roots, all counts, reserved names, Unicode/CR/escaping, encoding/security failures, authenticity, cancellation and inclusive limits. [Nonauthor controls](../test/unit/direct-codec-independent.test.ts) independently exercise BOM/URN repairs, native byte access, chunk boundaries and observed provenance. These are bare-root tests; their test-only SOAP extraction is not a production envelope parser.
+[Codec controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-codec.test.ts) run the actual Forecast request/response/ForecastError fixture payload bytes against independent expectations, fresh-byte laws, renamed/form/prefix sources, scalar/empty roots, all counts, reserved names, Unicode/CR/escaping, encoding/security failures, authenticity, cancellation and inclusive limits. [Nonauthor controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-codec-independent.test.ts) independently exercise BOM/URN repairs, native byte access, chunk boundaries and observed provenance. These are bare-root tests; their test-only SOAP extraction is not a production envelope parser.
 
-Exact P3.4 review, local/hosted checks and merged-main identities belong to #384 and [roadmap #379](https://github.com/TechSpokes/typescript-wsdl-client/issues/379). The separately scoped P3.5 adapter under #388 now consumes this codec for an internal buffered SOAP 1.1 unauthenticated loopback exchange; its [transport contract and qualifications](content-model-soap-feasibility.md#p35-original-byte-qualification) cover source-byte bootstrap, original response bytes, envelopes, declared Faults and request lifetime. Broad portable bundles, public structured generation, security combinations and activation remain separate work.
+Exact P3.4 review, local/hosted checks and merged-main identities belong to #384 and [roadmap #379](https://github.com/TechSpokes/typescript-wsdl-client/issues/379). The separately scoped P3.5 adapter under #388 now consumes this codec for an internal buffered SOAP 1.1 unauthenticated loopback exchange; its [transport contract and qualifications](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-soap-feasibility.md#p35-original-byte-qualification) cover source-byte bootstrap, original response bytes, envelopes, declared Faults and request lifetime. Broad portable bundles, public structured generation, security combinations and activation remain separate work.
 
 The internal decoder accepts a protocol payload selector over the single parsed observed document. Its selected mapping is authenticated against the same operation, and the payload must be an actual descendant by object identity. It reuses structural/scalar checks without subtree reserialization, preserving the complete original document digest, actual coordinates and inherited namespace bindings on the selected response or fault detail. A synthetic tree cannot acquire observed provenance through this seam.
 
 ## P3.6 internal portable source capsule
 
-[The private capsule module](../src/compiler/directSourceCapsule.ts) consumes authentic operations and existing native mappings. It adds no package export, public CLI, generated client or admission; package 1.1.4 and legacy defaults remain unchanged. This narrow capsule is not the full ADR bundle format or completion of #185/#186.
+[The private capsule module](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/compiler/directSourceCapsule.ts) consumes authentic operations and existing native mappings. It adds no package export, public CLI, generated client or admission; package 1.1.4 and legacy defaults remain unchanged. This narrow capsule is not the full ADR bundle format or completion of #185/#186.
 
 ### Source authority and reconstruction
 
@@ -274,7 +274,7 @@ Reconstruction starts one fresh request-specific inclusive sticky budget for art
 
 Byte/depth/node limits, cancellation, schema inconclusive, incompatible artifacts, unsupported scope and missing authority remain separate failures. These are engineering work/allocation reservations with cooperative checkpoints, not a hard heap limit or preemptive execution guarantee.
 
-[Installed qualification](../test/integration/portable-installed.test.ts) packs and installs the npm tarball in a separate temporary directory and process. The copied test-only TypeScript harness verifies physical private `dist` imports, denies checkout filesystem reads with Node permissions, blocks implicit fetches, requalifies an authorized copy, relocates it and issues fresh mappings and deterministic XML. Private-module testing establishes no supported package subpath; package exports remain root-only.
+[Installed qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/portable-installed.test.ts) packs and installs the npm tarball in a separate temporary directory and process. The copied test-only TypeScript harness verifies physical private `dist` imports, denies checkout filesystem reads with Node permissions, blocks implicit fetches, requalifies an authorized copy, relocates it and issues fresh mappings and deterministic XML. Private-module testing establishes no supported package subpath; package exports remain root-only.
 
 ### Next consumer boundary
 
@@ -282,11 +282,11 @@ The P3.6 handoff to P3.7 under #195/#201 is implemented by the internal consumer
 
 ## P3.7 internal generated TypeScript consumer
 
-[The native-plan generator](../src/client/generateDirectClient.ts) accepts an identity-issued reconstructed source, authenticates compatibility and each mapping, and emits one deterministic strict NodeNext TypeScript file plus its exact capsule. It uses the shared preamble composer with a dedicated internal-artifact preamble. There is no public command or package export for this generator.
+[The native-plan generator](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/client/generateDirectClient.ts) accepts an identity-issued reconstructed source, authenticates compatibility and each mapping, and emits one deterministic strict NodeNext TypeScript file plus its exact capsule. It uses the shared preamble composer with a dedicated internal-artifact preamble. There is no public command or package export for this generator.
 
 ### Typed internal binding
 
-The generated file has no imports. `createClient(runtime)` receives a trusted internal binding with one `execute` method; the generated operation has the exact source operation spelling as a computed quoted key. [The binding owner](../src/client/directClientRuntime.ts) delegates exclusively to the existing capsule, mapping and buffered SOAP owners. The test harness loads this binding by verified physical installed private-module path; that mechanism is not a supported package subpath or plugin interface.
+The generated file has no imports. `createClient(runtime)` receives a trusted internal binding with one `execute` method; the generated operation has the exact source operation spelling as a computed quoted key. [The binding owner](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/client/directClientRuntime.ts) delegates exclusively to the existing capsule, mapping and buffered SOAP owners. The test harness loads this binding by verified physical installed private-module path; that mechanism is not a supported package subpath or plugin interface.
 
 The generated capsule literal pins the static contract. Each invocation requires matching loaded capsule bytes, an explicitly authorized physical local source and file roots, and explicit SOAP service, port, endpoint and endpoint authorization. The binding copies options before asynchronous work, refuses accessors/proxies and unsupported options, creates one fresh budget, reconstructs native authority from the authorized file, checks native compatibility and calls `exchangeDirectSoap`. No handle, endpoint permission, budget or source authorization is cached between independent calls.
 
@@ -306,6 +306,6 @@ Emission bounds variable source contributions against a 512 KiB output ceiling b
 
 Native semantic accounting spans qualification and validation without resetting; routine byte copying, base64 comparison, serialization and publication use actual input/output caps. Separate calls get separate budgets; exhausted calls return no partial usable value. Normal calls no longer inherit the old source/capsule/XML test caps or semantic work allowance; cooperative cancellation and any explicit application-selected limits remain available. This is engineering accounting, not a hard heap or preemption guarantee; malformed own-key vector allocation has the same intrinsic qualification as the existing adapter.
 
-[Installed tests](../test/integration/generated-direct-installed.test.ts) generate bounded files for Forecast, renamed and prefix-aliased sources, optional/nonempty-array shapes, scalar and empty roots. They install the actual npm tarball in another directory, compile independently authored valid/invalid TypeScript and execute the emitted wrappers in a child with checkout reads denied. The harness permits only its consumer directory for file reads/writes and verifies real SOAP request namespace/order/scalars, response arrays and HTTP 200/500 declared faults, relocation, stale/mixed inputs, missing permissions, unsupported capabilities, cancellation and exhaustion. Node 24's permission model does not restrict sockets; endpoint restriction remains the native owned-loopback policy. Node versions exposing network permissions additionally receive the explicit loopback grant.
+[Installed tests](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/generated-direct-installed.test.ts) generate bounded files for Forecast, renamed and prefix-aliased sources, optional/nonempty-array shapes, scalar and empty roots. They install the actual npm tarball in another directory, compile independently authored valid/invalid TypeScript and execute the emitted wrappers in a child with checkout reads denied. The harness permits only its consumer directory for file reads/writes and verifies real SOAP request namespace/order/scalars, response arrays and HTTP 200/500 declared faults, relocation, stale/mixed inputs, missing permissions, unsupported capabilities, cancellation and exhaustion. Node 24's permission model does not restrict sockets; endpoint restriction remains the native owned-loopback policy. Node versions exposing network permissions additionally receive the explicit loopback grant.
 
-[Independent controls](../test/unit/generated-direct-independent.test.ts) challenge getters/proxies, mutable option metadata, copied authority, sticky exhausted generation and preserved dependency-name refusals. Hosted Linux and Windows Node24/26 run the generated installed qualification explicitly. Public-interface readiness and any remaining blockers belong to a separate P3.8 task; public activation, legacy defaults, package 1.1.4, root-only exports and `admitted:false` remain unchanged.
+[Independent controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/generated-direct-independent.test.ts) challenge getters/proxies, mutable option metadata, copied authority, sticky exhausted generation and preserved dependency-name refusals. Hosted Linux and Windows Node24/26 run the generated installed qualification explicitly. Public-interface readiness and any remaining blockers belong to a separate P3.8 task; public activation, legacy defaults, package 1.1.4, root-only exports and `admitted:false` remain unchanged.

package/docs/examples/checked-forecast.wsdl

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:t="urn:checked:forecast" targetNamespace="urn:checked:forecast">
+  <wsdl:types>
+    <xs:schema targetNamespace="urn:checked:forecast" elementFormDefault="qualified">
+      <xs:complexType name="ForecastRequest"><xs:sequence><xs:element name="city" type="xs:string"/><xs:element name="days" type="xs:int"/></xs:sequence></xs:complexType>
+      <xs:complexType name="ForecastResponse"><xs:sequence><xs:element name="city" type="xs:string"/><xs:element name="temperature" type="xs:int" minOccurs="0" maxOccurs="unbounded"/><xs:element name="complete" type="xs:boolean"/></xs:sequence></xs:complexType>
+      <xs:complexType name="ForecastFault"><xs:sequence><xs:element name="code" type="xs:string"/><xs:element name="message" type="xs:string"/></xs:sequence></xs:complexType>
+      <xs:element name="GetForecast" type="t:ForecastRequest"/>
+      <xs:element name="GetForecastResponse" type="t:ForecastResponse"/>
+      <xs:element name="ForecastFault" type="t:ForecastFault"/>
+    </xs:schema>
+  </wsdl:types>
+  <wsdl:message name="ForecastInput"><wsdl:part name="parameters" element="t:GetForecast"/></wsdl:message>
+  <wsdl:message name="ForecastOutput"><wsdl:part name="parameters" element="t:GetForecastResponse"/></wsdl:message>
+  <wsdl:message name="ForecastError"><wsdl:part name="detail" element="t:ForecastFault"/></wsdl:message>
+  <wsdl:portType name="ForecastPortType"><wsdl:operation name="GetForecast"><wsdl:input message="t:ForecastInput"/><wsdl:output message="t:ForecastOutput"/><wsdl:fault name="ForecastError" message="t:ForecastError"/></wsdl:operation></wsdl:portType>
+  <wsdl:binding name="ForecastBinding" type="t:ForecastPortType"><soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/><wsdl:operation name="GetForecast"><soap:operation soapAction="urn:checked:GetForecast"/><wsdl:input><soap:body use="literal"/></wsdl:input><wsdl:output><soap:body use="literal"/></wsdl:output><wsdl:fault name="ForecastError"><soap:fault name="ForecastError" use="literal"/></wsdl:fault></wsdl:operation></wsdl:binding>
+  <wsdl:service name="ForecastService"><wsdl:port name="ForecastPort" binding="t:ForecastBinding"><soap:address location="http://127.0.0.1:1/forecast"/></wsdl:port></wsdl:service>
+</wsdl:definitions>

package/docs/gateway-guide.md

@@ -201,9 +201,19 @@ export async function registerRoute_v1_weather_getweatherinformation(fastify: Fa
     schema: routeSchema,
     handler: async (request, reply) => {
       const client = fastify.weatherClient;
-      const result = await client.GetWeatherInformation(request.body as GetWeatherInformation);
-      reply.type("application/x-ndjson");
-      return reply.send(toNdjson(result.records));
+      const controller = new AbortController();
+      const disconnected = () => { if (!reply.raw.writableEnded) controller.abort(); };
+      request.raw.once("aborted", disconnected);
+      reply.raw.once("close", disconnected);
+      if (request.raw.aborted || reply.raw.destroyed) controller.abort();
+      try {
+        const result = await client.GetWeatherInformation(request.body as GetWeatherInformation, {signal: controller.signal});
+        reply.type("application/x-ndjson");
+        return await reply.send(toNdjson(result.records));
+      } finally {
+        request.raw.removeListener("aborted", disconnected);
+        reply.raw.removeListener("close", disconnected);
+      }
     },
   });
 }
@@ -211,7 +221,25 @@ export async function registerRoute_v1_weather_getweatherinformation(fastify: Fa
 
 For `format: "json-array"`, the same handler imports `toJsonArray`, sets `reply.type("application/json")`, and sends `reply.send(toJsonArray(result.records))`.
 
-The client method returns `StreamOperationResponse<RecordType>` with a `records: AsyncIterable<RecordType>`. Errors raised before the first record use the normal error envelope. Errors raised mid-stream truncate the response; NDJSON clients see an incomplete HTTP response, and JSON array clients see an incomplete or invalid JSON document.
+The client method returns `StreamOperationResponse<RecordType>` with a single-pass `records` iterable. Failures before response commitment can use the error envelope; errors after commitment truncate the response. Treat an incomplete HTTP response or JSON array as a failed stream, even if earlier records were valid.
+
+Each completed record passes through the legacy client's `fromSoapResult` mapper before delivery. Public DTOs flatten XML attributes, convert boolean/numeric lexical values according to projected types, preserve configured string-first decimal/integer policies, map typed `$value` content, tokenize XML lists and retain repeated-element arrays. Empty complex types without child fields become `{}`; empty primitive strings remain strings. The low-level `streamXml.ts` parser retains lexical values and attribute bags, and checked mapping conventions are unchanged.
+
+For buffered responses, node-soap's `null` empty-object recovery requires a declared non-nillable child of a known complex type without child fields. Nullable and unknown values keep their existing behavior; empty containers with declared optional children are outside this bounded recovery.
+
+When array-wrapper flattening is enabled, the gateway unwraps each mapped record using the same wrapper convention as buffered routes. Both NDJSON and JSON-array delivery stay incremental. A consumer disconnect aborts the upstream request even before SOAP response headers arrive, and remains connected to cancellation throughout record delivery.
+
+### Streaming transport settings
+
+Stream calls use `soap.HttpClient.requestStream` or the configured `options.httpClient.requestStream`, with the configured `options.request` adapter. They honor the current `soapClient().setEndpoint(...)`, static SOAP/HTTP headers, and the current security object's `addHeaders`, `addOptions`, `toXML` and `postProcess` hooks. A custom HTTP client must implement `requestStream`.
+
+Requests pass through `toSoapArgs` and node-soap's WSDL document serializer, preserving unqualified local children and foreign namespace references. The initialized client's `envelopeKey` also governs SOAP headers and security `postProcess`. Stream calls require a compatible live document/literal binding matching the generated operation name and SOAP action; missing or ambiguous incompatible bindings are refused before I/O.
+
+Only clients with stream-configured operations expose constructor `streamRequestOptions`, using node-soap's `IExOptions` HTTP options. Use it for stream-specific HTTP timeouts or an HTTPS agent with trusted CA/client certificates; WSDL-fetch settings remain separate. TLS verification stays enabled by default and uses Node's configured trust; no certificate bypass is added.
+
+Generated stream operations also accept `{signal, timeoutMs}` as an optional second argument. `timeoutMs` covers the upstream HTTP request and record consumption, starting after SOAP metadata initialization. Exhaust the records or return their iterator to release the connection; a per-call signal already aborted rejects before metadata initialization. See the [generated stream client API](api-reference.md#generated-stream-client-contract).
+
+Streaming supports SOAP 1.1 document/literal requests. SOAP 1.2/custom envelope namespaces, functional SOAP headers, SOAP body attributes, MTOM attachments and NTLM transport are explicitly refused. Other node-soap serializer/security combinations require separate qualification; date mappings remain type-level, and `bigint` values retain normal JSON serialization limitations.
 
 ## Error Handling
 
@@ -220,12 +248,14 @@ The centralized error handler (runtime.ts) automatically classifies errors:
 | Error Type         | HTTP Status | Error Code          |
 |--------------------|-------------|---------------------|
 | Validation errors  | 400         | VALIDATION_ERROR    |
-| SOAP faults        | 502         | SOAP_FAULT          |
+| Buffered node-soap faults | 502   | SOAP_FAULT          |
 | Connection refused | 503         | SERVICE_UNAVAILABLE |
 | Timeout            | 504         | GATEWAY_TIMEOUT     |
 | Other errors       | 500         | INTERNAL_ERROR      |
 
-All errors are wrapped in the standard envelope format. See [Concepts](concepts.md) for the envelope structure.
+Legacy errors handled before response commitment use the standard envelope. After stream output begins, errors truncate the response. Checked component values and faults follow their separate [checked contract](checked-gateway.md).
+
+Stream parser faults fail the iterator instead of producing an empty successful result. Before output begins they use the generic error classification; after output begins the response is truncated.
 
 ## Stub Handler Mode
 
@@ -252,39 +282,86 @@ Example: `urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse`
 
 ## Multi-Service Setup
 
-When integrating multiple SOAP services, each service gets its own client, gateway, and OpenAPI spec. Register each in its own Fastify encapsulation scope to prevent decorator collisions:
+Native legacy composition generates independent service clients and routers, one aggregate Fastify plugin, and one combined OpenAPI document. Save a configuration such as `services.json` beside your `sources/` directory:
+
+```json
+{
+  "services": [
+    {
+      "key": "main",
+      "generation": {
+        "wsdl": "./sources/main.wsdl",
+        "catalogOut": "./.generated/main/client/catalog.json",
+        "clientOutDir": "./.generated/main/client",
+        "compiler": {"imports": "js"},
+        "openapi": {"outFile": "./.generated/main/openapi.json", "basePath": "/main"},
+        "gateway": {"outDir": "./.generated/main/gateway", "serviceSlug": "main", "versionSlug": "v1"}
+      }
+    },
+    {
+      "key": "content",
+      "generation": {
+        "wsdl": "./sources/content.wsdl",
+        "catalogOut": "./.generated/content/client/catalog.json",
+        "clientOutDir": "./.generated/content/client",
+        "compiler": {"imports": "js"},
+        "openapi": {"outFile": "./.generated/content/openapi.json", "basePath": "/content"},
+        "gateway": {"outDir": "./.generated/content/gateway", "serviceSlug": "content", "versionSlug": "v1"}
+      }
+    }
+  ],
+  "openapi": {"outFile": "./.generated/aggregate/openapi.json", "title": "Combined SOAP Gateway", "version": "1.0.0"},
+  "gateway": {"outDir": "./.generated/aggregate/gateway", "imports": "js"}
+}
+```
+
+```bash
+npx wsdl-tsc pipeline --services-config ./services.json
+```
+
+Relative paths resolve against `services.json`; companion paths in `streamConfigFile` resolve against that stream file. Each `generation` uses `PipelineOptions` property names. Every service requires explicit outputs and its own static `basePath`; prefixes are baked into routes once. Keys, normalized service slugs, decorators and prefixes must be unique; output ownership must not overlap across services, and source metadata must remain outside outputs.
+
+### Runtime clients
+
+The aggregate plugin exports a typed `createClients` helper. Its registry requires exactly the configured keys, and each value is that service client's constructor options:
 
 ```typescript
 import Fastify from "fastify";
-import weatherPlugin from "./.generated/weather/gateway/plugin.js";
-import inventoryPlugin from "./.generated/inventory/gateway/plugin.js";
-import { Weather } from "./.generated/weather/client/client.js";
-import { Inventory } from "./.generated/inventory/client/client.js";
-
-const app = Fastify({ logger: true });
+import gateway, {createClients} from "./.generated/aggregate/gateway/plugin.js";
+import type {IOptions, ISecurity} from "soap";
 
-// Each plugin gets its own scope to isolate decorators
-await app.register(async (scope) => {
-  await scope.register(weatherPlugin, {
-    client: new Weather({ source: "https://example.com/weather?wsdl" }),
-    prefix: "/api/weather",
-  });
-});
+declare const mainEndpoint: string, contentEndpoint: string;
+declare const mainOptions: IOptions, contentOptions: IOptions;
+declare const mainSecurity: ISecurity, contentSecurity: ISecurity;
 
-await app.register(async (scope) => {
-  await scope.register(inventoryPlugin, {
-    client: new Inventory({ source: "https://example.com/inventory?wsdl" }),
-    prefix: "/api/inventory",
-  });
+const clients = createClients({
+  main: {source: "./sources/main.wsdl", options: mainOptions, security: mainSecurity},
+  content: {source: "./sources/content.wsdl", options: contentOptions, security: contentSecurity},
 });
+(await clients.main.soapClient()).setEndpoint(mainEndpoint);
+(await clients.content.soapClient()).setEndpoint(contentEndpoint);
 
-await app.listen({ port: 3000 });
+const app = Fastify({logger: true});
+await app.register(gateway, {clients});
+await app.listen({port: 3000});
 ```
 
-See [`examples/fastify-gateway`](../examples/fastify-gateway/README.md) for a complete example.
+Runtime `source` supplies WSDL metadata, while `setEndpoint` selects the SOAP destination. Keep source, credentials, trust, headers, stream settings and cancellation decisions scoped to their client; overlapping SOAP operation names still dispatch through their owning route. Alternatively, provide a `{clients}` registry of preconfigured instances or compatible operations mocks directly.
+
+The aggregate serves the combined definition at `/openapi.json`; generation `gateway.openapiPath` can change or disable that route. Do not register the aggregate under a Fastify runtime prefix, including an inherited parent prefix; configure each service's generation-time `openapi.basePath` instead.
+
+Components and operation identifiers are qualified by service key, including stream item schema references. Local references and security scheme names are rewritten, and service-local root security/server semantics are preserved at their applicable operations or paths. Composition rejects duplicate final paths, unresolved/relative references and unsupported schema resources or anchors. Compiler settings and optional stream configuration stay inside each `generation`; checked composition and aggregate app/test scaffolding remain deferred.
+
+The aggregate specification is JSON only. Aggregate spec/plugin staging protects the previous pair on failure, but earlier service-generated dependencies can already have changed. This is not a whole-directory transaction; regenerate and verify matched artifacts after a failure.
+
+Single-source plugins can still be mounted manually in separate Fastify scopes. See [`examples/fastify-gateway`](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/examples/fastify-gateway/README.md) for single-source application wiring and the [composition API](api-reference.md#runmultiservicepipeline) for its supported settings and limits.
+
+The credential-free [native composition example](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/examples/native-composition/README.md) uses two committed generic sources, explicit `.generated/` outputs and a compileable typed registry.
 
 ## Contract Assumptions
 
+The following assumptions describe buffered legacy gateway input. Stream responses use format-specific bodies without success envelopes; checked components use their own value/schema contract. Native composition retains those per-service legacy contracts.
+
 - All request/response bodies must use $ref to components.schemas
 - Every operation must have a default response with application/json content
 - All referenced schemas must exist in components.schemas

package/docs/generated-code.md

@@ -4,6 +4,14 @@ Guide to using the TypeScript SOAP clients and types generated by wsdl-tsc.
 
 See [README](../README.md) for quick start and [Concepts](concepts.md) for type modeling details.
 
+## Upgrading generated output
+
+Installing a generator version does not itself rewrite these files, but a consumer build/install script may regenerate them. For 1.2.0, review the [migration guide](migration.md#from-11x-to-120) before replacing matched artifacts: affected type names, stream records and corrected scalar/simple-content results can require consumer changes. Preserve adopted app/test scaffolds and keep the generator/runtime versions appropriate to the selected profile.
+
+## Installed package definitions
+
+The generator package ships TypeScript declarations for its public ESM API. Definition lookup resolves to those packaged `.d.ts` files; original implementation source and declaration maps are not shipped for public API source navigation. Installed package smoke checks this definition resolution using the consumer's TypeScript language service; editor-specific UI behavior is not asserted.
+
 ## Generated Preambles and ESLint
 
 Every newly written TypeScript client, gateway, app, and generated-test file starts with `/* eslint-disable */`. This includes conditional streaming/security helpers, stub routes, and gateway typecheck fixtures. CLI and programmatic generation use the same defaults with no new flags or required arguments.
@@ -136,20 +144,20 @@ const forecast = await client.GetCityForecastByZIP({
   ZIP: "10001"
 });
 
-console.log(forecast.GetCityForecastByZIPResult.Success);
-console.log(forecast.GetCityForecastByZIPResult.ForecastResult);
+console.log(forecast.response.GetCityForecastByZIPResult?.Success);
+console.log(forecast.response.GetCityForecastByZIPResult?.ForecastResult);
 ```
 
 Operations without input still require an empty object:
 
 ```typescript
 const info = await client.GetWeatherInformation({});
-console.log(info.GetWeatherInformationResult.WeatherDescriptions);
+console.log(info.response.GetWeatherInformationResult?.WeatherDescription);
 ```
 
 ## Calling Stream Operations
 
-Operations opted into streaming with `--stream-config` return `StreamOperationResponse<RecordType>` instead of the buffered shape. `records` is a single-pass `AsyncIterable<RecordType>` that pulls bytes from the upstream SOAP response on demand, so memory stays bounded regardless of payload size.
+Operations opted into streaming with `--stream-config` accept `(args, {signal, timeoutMs}?)` and return `StreamOperationResponse<RecordType>`. The single-pass `records` iterable maps complete records into generated DTOs. Memory depends on record size and transport/parser buffering; there is no constant-memory or byte-cap guarantee.
 
 ```typescript
 const result = await client.UnitDescriptiveInfoStream({});
@@ -160,9 +168,11 @@ for await (const record of result.records) {
 
 Because `records` is single-pass, each response can be iterated once. Headers captured before the first record are available on `result.headers`, and the serialized SOAP envelope that was sent upstream is on `result.requestRaw` when populated.
 
+Exhaust or return the iterator, for example by breaking a `for await` loop, to dispose of transport resources. A per-call deadline starts after metadata initialization; an already-aborted signal rejects before it. Stream-enabled constructors accept `streamRequestOptions` for HTTP settings such as a verified HTTPS agent, separately from WSDL loading. See [transport settings and refusals](gateway-guide.md#streaming-transport-settings).
+
 Streaming requires the `saxes` runtime dependency. The generated app scaffold pins `saxes ^6.0.0` automatically; consumers that integrate the generated client into their own project must install it explicitly.
 
-See [Stream Configuration](configuration.md#stream-configuration) for how to opt specific operations in, and [ADR-002](decisions/002-streamable-responses.md) for the rationale and terminal-error policy.
+See [Stream Configuration](configuration.md#stream-configuration) for how to opt specific operations in, and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the rationale and terminal-error policy.
 
 ## Attributes and Text Content
 
@@ -210,11 +220,11 @@ Generated gateway test suites use one valid branch in union-mode mocks. They als
 All operations and types are fully typed:
 
 ```typescript
-const result: GetCityWeatherByZIPResponse = await client.GetCityWeatherByZIP({
+const result = await client.GetCityWeatherByZIP({
   ZIP: "10001"
 });
 
-result.GetCityWeatherByZIPResult.Temperature;
+result.response.GetCityWeatherByZIPResult?.Temperature;
 ```
 
 Autocomplete and type checking work across all generated interfaces.
@@ -293,10 +303,11 @@ import type { WeatherOperations } from "./client/operations.js";
 
 const mock: WeatherOperations = {
   GetCityWeatherByZIP: async (args) => ({
-    response: { GetCityWeatherByZIPResult: { Success: true } },
+    response: { GetCityWeatherByZIPResult: { Success: true, WeatherID: 0 } },
     headers: {},
   }),
-  // ...other operations
+  GetCityForecastByZIP: async () => ({ response: {}, headers: {} }),
+  GetWeatherInformation: async () => ({ response: {}, headers: {} }),
 };
 ```
 
@@ -306,6 +317,6 @@ The gateway plugin accepts any `WeatherOperations` implementation, so you can pa
 app.register(weatherGateway, { client: mock });
 ```
 
-For stream operations, mock implementations return an async-iterable `records` field. See the [Testing Guide](testing.md) for the full pattern with async generators.
+For stream operations, mock implementations return an async-iterable `records` field. See [generated test mocks](testing.md#mock-client) for the full pattern with async generators.
 
-See [Testing Guide](testing.md) for full integration test patterns.
+See [consumer testing guidance](testing.md#for-consumer-projects) for setup, legacy and checked test commands, ownership and verification limits.

package/docs/mapping-contract.md

@@ -0,0 +1,114 @@
+# Checked XML/JSON Mapping Contract
+
+Source-derived JSON representation for checked generation. See the root [README](../README.md) and [checked gateway guide](checked-gateway.md) for supported scope and configuration.
+
+The checked gateway guide defines executed support. Selected future forms are labeled below; describing a JSON shape does not enable a missing source or runtime capability.
+
+## Selected keyed mapping contract
+
+Names are JSON keys. Derive identity facts from the exact source mapping whenever a slot uniquely identifies them, including qualified attributes inside a fallback channel. Known records/scalars/arrays and reconstructible application groups remain ordinary values; source occurrence bounds choose arrays for compact slots, while each ordered entry is exactly one element occurrence. JSON property insertion order never controls source-fixed XML order. Existing scalar encodings, lexical witnesses and native duties remain authoritative.
+
+Keyed child entries keep familiar field names, text objects make every ordered entry an object without a kind discriminator, direct URI holders handle actual identity choices, and scoped binding deltas avoid repeated full maps. Attribute entries preserve same-name/different-namespace identities without inventing a key-escaping syntax. Existing supported projections do not acquire redundant descriptors; the repository's [exploratory comparison](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/v1.0-xml-json-mapping.md#bounded-primary-source-comparison) records the alternative forms considered.
+
+### Content and recursion
+
+New mixed/open `$content` is an ordered array of objects. Each object has exactly one own property: either `$value` with a text string, or an ordinary child-name key whose value follows that child's selected mapping. No metadata siblings are allowed on an outer entry. Preserve significant spaces; coalesce adjacent text entries and remove zero-length text entries. Do not collapse repeated occurrences across intervening text. An XSD list scalar array is distinct from element repetitions.
+
+```xml
+<p xmlns="urn:msg" id="7">Hello <b>world</b>!</p>
+```
+
+```json
+{"id":"7","$content":[{"$value":"Hello "},{"b":"world"},{"$value":"!"}]}
+```
+
+Here the source declares b as string. A mixed structured b instead has its own `$content`, even when one instance is text-only. Source identity/assessment selects the grammar, not object appearance. Metadata around a scalar encoding v uses a holder with `$value:v`, including object/array scalar encodings; never merge scalar fields into element metadata. A record keeps its own fields. An ordered holder cannot also expose peer child/group fields or a scalar `$value`; source-mapped attributes may accompany it.
+
+### Namespaces have separate owners
+
+`$namespace` is the actual element/attribute/type namespace URI at this location. It does not declare a prefix, set a default binding or cause descendants to inherit element identity. Derive it when the exact source mapping fixes identity; otherwise supply it explicitly, including an empty URI for a no-namespace unknown element. Each child key is its XML name without the prefix unless an established source mapping defines an application alias.
+
+```json
+{"$content":[{"code":{"$namespace":"urn:vendor","$value":"A"}},{"code":{"$namespace":"urn:billing","$value":"B"}}]}
+```
+
+`$namespaces` contains prefix bindings introduced/rebound on this node. Descendants inherit an immutable effective context and apply their local changes; parents and siblings stay unchanged. The first source-defined retained-context boundary captures otherwise unavailable effective bindings; subsequent nodes retain only deltas. A source-known intermediate node retains a delta when a descendant needs it. Prefix keys are data: `""` denotes the default binding and xml is implicit. Default reset uses `{"":""}`; XML Namespaces 1.0 does not permit deleting nonempty prefixes. Redundant deltas normalize away; apparently unused bindings in unassessed data are not pruned.
+
+Element identity and default binding can differ: `<e:extra xmlns:e="urn:open" xmlns="urn:values">Thing</e:extra>` identifies the element in urn:open while a typed QName Thing resolves in urn:values. A child rebinding p changes its applicable lexical scope, not its element URI. Plain unassessed `p:Thing` remains a string; neither object appearance nor a colon grants QName semantics.
+
+For assessed data without retained context, the codec can allocate compatible prefixes from actual identities. It must preserve protected effective contexts for unassessed lexical data and lexical witnesses. Reject combinations that cannot coexist in XML, including a no-namespace element retaining a nonempty default or a namespaced attribute lacking an available nonempty prefix in a protected scope. JSON shape alone does not establish these codec duties. Fresh reconstruction uses complete JSON, source mapping and inherited context; arbitrary extracted-subtree portability is not promised.
+
+### Attribute channel
+
+Existing unambiguous source-mapped peer attributes retain their shape. When a source mapping requires the new fallback, `$attributes` is an array of one-name entries, not an array of generic name/value descriptors. At a uniquely mapped key, a bare scalar derives its complete identity from that source slot, including a qualified namespace; redundant identity holders are rejected.
+
+A closed source with one qualified code attribute and one code child can therefore use `{"$attributes":[{"code":"attribute"}],"code":"child"}`. For an open/unresolved key without a unique mapped identity, a bare scalar denotes an unqualified attribute and a qualified identity uses `{$namespace:nonemptyURI,$value:scalar}`. Empty-URI holders are rejected in that open grammar rather than being a second spelling.
+
+A source key whose permitted identities remain ambiguous requires the explicit namespace selection needed to distinguish them; its generated mapping/schema declares that domain. Unknown attributes retain lexical strings; typed values use their selected scalar encodings. The bag never infers attribute identity from the default element namespace.
+
+```json
+{"$attributes":[{"id":"attribute"},{"id":{"$namespace":"urn:vendor","$value":"external"}}],"id":"child"}
+```
+
+The container preserves two attributes with the same name from different namespaces without inventing escaping rules or aliases. Source-owned slot attribution determines whether an identity is already fixed; object appearance does not override that attribution. Attribute order is not semantic; canonical output sorts by expanded identity. Duplicate expanded attributes, duplicate peer/bag identities, undeclared attributes and invalid values fail. A selected type uses one placement consistently across nil/non-nil instances. No attribute holder owns children, `$nil` or `$type`.
+
+### Open values, type and nil
+
+Genuinely unassessed elements always use ordered holders, including empty/text-only instances, with their required identity and retained context. They do not become guessed scalar types. Native assessment applies independently to each location: strict/lax/skip cannot be selected by a JSON flag. Raw unassessed xsi:nil/xsi:type stay lexical attributes in the XSI namespace, not semantic `$nil`/`$type`. Missing declarations are not repaired by an open representation.
+
+The selected research shape for a future assessed dynamic type is the flat XML identity `{$type:{$name:"Dog",$namespace:"urn:animals"}}`. Assessed dynamic `$type` execution and its `$name` identity field remain unsupported by the generated checked pipeline; this shape is not an accepted capability switch. A child entry already has its name as its key, and no `$localName`, `$kind`, `$text` or `$element` alias is allocated.
+
+Display type/schema aliases do not rename an XML type. Any future implementation must establish native existence, derivation and attribute duties before admitting the selected research shape.
+
+The explicit nil contract below remains authoritative. Identity/type/context metadata can accompany nil only when that exact source mapping declares the necessary combination and implements its native duties; it is not admitted by the nil marker alone. Nil forbids every text/child/group content field, even empty content. Neither semantic xsi processing nor QName scalar assessment is guessed from familiar names.
+
+### Compatibility, HTTP shape and implementation proof
+
+New grammar selection is per exact source declaration/type/assessment mapping. Legacy, accepted component scalar/record/array/simple/ordered values and checkedDirectRuntimeV1 remain unchanged. A reused already-accepted ordered descendant inside a new mixed parent retains its old entry grammar in both directions; the implementation dispatches through its existing mapping. Unifying those old public shapes requires a separate migration decision, not a new mode introduced here.
+
+HTTP schemas describe actual JSON fields and source-selected recursive alternatives, with closed one-property entries, text string slots, namespace strings, flat type identity and nil/attribute/content exclusions. Named structured choice alternatives reference their union, or an array of it for repetition. Use oneOf only where JSON alternatives are disjoint. Native owners enforce names, bindings, particles/correlation, scalar/default/fixed/type/nil duties and SOAP construction. Serialization must independently preserve every accepted field. Reject unknown metadata and invalid combinations without mutation, coercion, default insertion or field removal; legal __proto__/constructor names remain safe own data properties.
+
+The [keyed prototype](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-mapping.ts) and [independent examples](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-mapping.test.ts) reuse the earlier parser/syntax inverse and its fixture-specific source facts. They exercise mixed/nested text, order and namespace collisions, scopes/defaults/siblings, attribute collisions, raw xsi values, safe names, flat type and explicit nil, with malformed-input and realizability controls. The [qualified attribute fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-attributes.xsd) supplies a closed same-name attribute/child case whose qualified attribute identity is independently checked through native source attribute assessment; unassessed data with the same root name must retain its open grammar.
+
+The [HTTP structure sketches](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-schema.test.ts) execute recursive JSON Schema examples and rejection/non-mutation cases. They are not a generic source-to-DTO generator or production native validation; existing native projection/scalar controls and nil examples remain separate evidence. The old public candidate grammar is historical; its fixture-specific conversion helpers remain dependencies of the research adapter, not an independent new inverse.
+
+The [checked nil implementation](checked-gateway.md#nil-values) and [keyed execution](checked-gateway.md#mixed-namespaced-and-open-values) supply the supported nil/mixed/open slices and preserve them through HTTP. Scalar/context validation and HTTP-shape generation retain their separate native duties. Application groups and configured aliases are described below and in the checked gateway guide.
+
+## Selected nil contract
+
+Checked nil values use one explicit object, preserving attributes and the distinction between absent, empty and nil elements. This contract does not change legacy, accepted non-nil component values or `checkedDirectRuntimeV1`; the [checked nil reference](checked-gateway.md#nil-values) records supported configuration and limits.
+
+| Case | JSON rule |
+|---|---|
+| Absent optional element | Omit its property; omission is not nil |
+| Present nil without attributes | `{"$nil":true}` |
+| Present nil with attributes | `{"$nil":true,"id":"7"}` for an applicable mapped string attribute `id` |
+| Empty non-nil | Retain the ordinary source-selected value, such as `""`, `{"$value":""}` or an empty permitted record |
+| Nil repeated item | Put the explicit nil object at that item's position in the declared array |
+| Nil wrapper | Put the explicit nil object at the wrapper element's property; it contains no items |
+
+Both accepted input and canonical output use the explicit object; plain `null` is rejected, including as an array item. `$nil` is exactly Boolean `true`, never false, a string or a caller-selected assessment policy. XML `xsi:nil="true"` and `"1"` project to this same marker after native lexical assessment. XML false/zero uses the ordinary non-nil projection with no `$nil`; reconstruction of nil uses a permitted canonical true lexical form. Property order does not control XML order.
+
+The only newly allocated nil metadata is `$nil`. Additional fields are exactly the applicable attribute properties already defined by the selected source mapping, using their existing scalar encodings and identities. Required attributes remain required on nil elements; optional/default/fixed attributes follow the shared native assessment and adopted augmentation rules, not Ajv defaults. Empty string attributes are data and remain subject to their type. Do not invent a new nil attribute bag or rename existing scalar descriptors. Contextual attribute families, attribute collisions/wildcards and dynamic types require their actual native owners and an explicit compatible shape before emission; the nil marker alone does not establish those capabilities or silently narrow #421's acceptance.
+
+Nil objects prohibit all element/text/group content fields, including `$value`, `$content`, synthetic choice containers and ordinary child properties, even when their supplied values are empty or null. Reject unknown metadata, undeclared/invalid attributes, sparse/malformed arrays and object/array substitutions without mutation or silent field removal. `$type` and `$namespaces` are not implicitly accepted by this nil contract. A later independently selected contextual/type contract must explicitly describe its combination with nil; callers cannot enable it with extra keys.
+
+Each object's XML element identity comes from its selected declaration/position; `$nil` never emits an XML child. Nillability, nil/content legality, attribute use and applicable fixed/default/scalar duties remain native checks, at the actual item or wrapper element. Genuinely unassessed lexical xsi attributes are not promoted to semantic nil by familiar spelling. No checked failure may fall back to legacy conversion, and no missing native duty may be hidden by weakening validation.
+
+For the example with optional string attribute `id`, TypeScript is `{ $nil: true; id?: string }`. Its HTTP schema is concrete:
+
+```json
+{"type":"object","required":["$nil"],"additionalProperties":false,"properties":{"$nil":{"const":true},"id":{"type":"string"}}}
+```
+
+Include `id` in `required` where the source requires it. Compose this nil schema with the ordinary non-nil schema for a nillable element, with exactly-one composition only when the JSON alternatives are disjoint. Optionality belongs to the containing property and item versus wrapper nillability belongs to the corresponding element position. Every accepted attribute must survive response serialization; HTTP structure validation does not replace native XML checks. No discriminator, response envelope or new runtime mode is introduced.
+
+The [explicit nil contract examples](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/nil-contract.test.ts) exercise independent hand JSON, true/one XML lexicals, attribute-preserving fresh syntax reconstruction, canonical explicit output, absent/empty/item/wrapper distinctions and malformed combinations. They reuse the existing parser and research inverse for a fixture with string `id`; they do not implement native nillability, complete attribute semantics or generated HTTP/SOAP execution. The old null-based tests remain historical candidate evidence, not accepted aliases.
+
+The implementation consumes this contract through existing source planning, projection/inverse, codec and HTTP-shape generation, preserving shared resource and error boundaries. Its [codec controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-projection-nil.test.ts) and [installed gateway checks](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/helpers/checkedGatewayInstalledProcess.ts) supply independent request/response/fault, serialized HTTP and owned-SOAP evidence, including non-nillable/content-bearing refusals and attribute/default/fixed duties.
+
+## Application groups
+
+Checked generation implements opt-in source-derived application groups and definition-scoped configured names. [Configuration and compatibility](checked-gateway.md#application-groups-and-configured-names), [the production fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/application-groups.wsdl), [native inverse controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/application-groups.test.ts) and [pipeline/reload evidence](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-application-groups.test.ts) provide regression evidence; installed HTTP/SOAP checks cover both defaults and configured aliases. Wider native source, dynamic-type and protocol duties retain their documented limits.
+
+Reconstructible singleton/repeated/nested choices, repeated sequences, independent sites, cross-record named-group reuse and finite recursive references share the source-owned mapping. Empty-capable and ambiguous records retain ordered normalization; mixed/open records keep their selected owner. Inventory tokens include a selected-record shape guard and survive physical relocation, unrelated declaration reorder and alias changes; relevant source edits require copying fresh targets.

package/docs/migration-playbook.md

@@ -4,6 +4,10 @@ A step-by-step guide for modernizing a SOAP API into a typed TypeScript client a
 
 For CLI flag details, see [CLI Reference](cli-reference.md). For gateway integration, see [Gateway Guide](gateway-guide.md).
 
+See the root [README](../README.md) and [1.1.x-to-1.2.0 migration](migration.md#from-11x-to-120) before regenerating. Native legacy composition retains per-client ownership; checked/RPC generation has a separate buffered validation contract.
+
+This playbook describes adopting a SOAP-to-REST integration. Updating an existing generated gateway is a separate package-upgrade task: keep its profile first, review matched regenerated artifacts and preserved scaffolds, and use the version migration guide's verification and rollback steps. Adopting checked generation or composition should be a deliberate follow-up rather than an incidental upgrade effect.
+
 ## Overview
 
 The typical migration follows this sequence:
@@ -89,7 +93,7 @@ npx wsdl-tsc pipeline \
   --init-app
 ```
 
-The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Set `format: "json-array"` for `application/json` array streaming. Operations not listed in the config are unchanged. See [Stream Configuration](configuration.md#stream-configuration) for the full file reference and [ADR-002](decisions/002-streamable-responses.md) for the terminal-error policy.
+The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Set `format: "json-array"` for `application/json` array streaming. Operations not listed in the config are unchanged. See [Stream Configuration](configuration.md#stream-configuration) for the full file reference and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the terminal-error policy.
 
 ## Step 3: Generate the REST Gateway