@techspokes/typescript-wsdl-client 1.1.8 → 1.3.0

package/docs/checked-generation.md

@@ -1,16 +1,18 @@
 # Try opt-in checked generation
 
-Version 1.1.8 offers an opt-in WSDL-to-checked-gateway workflow for early testing and feedback. Choose `pipeline --model checked-components-v1` to generate a typed SOAP client, OpenAPI, Fastify gateway, runnable app and scaffold tests for supported document/literal SOAP 1.1 contracts. Omitting `--model` keeps the existing legacy behavior.
+Opt-in checked generation supports qualified SOAP 1.1 and SOAP 1.2 document/literal contracts and the bounded SOAP 1.1 RPC/encoded string profile. Choose `pipeline --model checked-components-v1`; omitting `--model` keeps legacy generation. SOAP 1.2 execution is available starting with 1.3.0; see the [binding and artifact contract](checked-gateway.md#component-service-generation). See the root [README](../README.md).
 
 This is a bounded preview, not general WSDL/XSD or production-provider qualification. It adds source-backed request, response, fault and artifact checks for the supported fragment. Generation exposes legacy and components only; the shipped v1.1.5 direct runtime remains a compatibility binding for existing clients. See the [checked gateway reference](checked-gateway.md).
 
 ## Install and try the bundled contract
 
+The examples target 1.3.0. Before that version is published, install a locally packed 1.3.0 tarball instead of requesting an unpublished registry version. After publication, use the explicit registry version below. Earlier releases retain their own documented contracts.
+
 Use Node.js 24 or newer. Run these commands in a new trial directory:
 
 ```powershell
 npm init -y
-npm install --save-dev @techspokes/typescript-wsdl-client@1.1.8
+npm install --save-dev @techspokes/typescript-wsdl-client@1.3.0
 npm install soap
 npx wsdl-tsc pipeline --model checked-components-v1 --wsdl-source node_modules/@techspokes/typescript-wsdl-client/docs/examples/checked-forecast.wsdl --client-dir .generated/forecast/client --openapi-file .generated/forecast/openapi.json --gateway-dir .generated/forecast/gateway --gateway-version-prefix v1 --gateway-service-name forecast --init-app --app-dir .generated/forecast --test-dir .generated/forecast/test --checked-report .generated/forecast-plan.json
 ```
@@ -69,7 +71,7 @@ Read the planning report before editing anything. Unsupported source, mapping, b
 
 Checked planning refusals show the construct or source location, the reason and the next action, then exit nonzero without generating artifacts or invoking SOAP. Save the unchanged structured report with `--checked-report`; set the `DEBUG` environment variable to `wsdl-tsc` when you need the raw error, stack and report details.
 
-For a locationless import, `--checked-draft` can write `service-resolution.json` containing a `REQUIRED_SCHEMA_LOCATION` placeholder. Replace that value with the actual permitted schema location, then rerun with `--checked-config service-resolution.json`. This supplies missing source information; it does not waive native checks or reconstruct a type graph by hand.
+For a locationless import whose referenced components are unavailable, `--checked-draft` can write `service-resolution.json` containing a `REQUIRED_SCHEMA_LOCATION` placeholder. Replace that value with the actual permitted schema location, then rerun with `--checked-config service-resolution.json`. Unused locationless imports need no fabricated schema; native qualification and reference resolution remain mandatory.
 
 Multiple service/port/binding candidates require an explicit choice. Partial configuration and operation subsets are supported; see [selection and recovery details](checked-gateway.md#planning-and-missing-schema-recovery). Reports and drafts are preserved by default; use `--force-checked-files` deliberately to replace them on a later run.
 
@@ -133,7 +135,9 @@ The older `assessSchemaSource` API and `assess` command retain the narrow `check
 
 The qualified component fragment includes imported schemas, nested/repeated and inherited records, attributes, simple content, ordered values and supported scalar restrictions. [Keyed mixed/namespace/open values](checked-gateway.md#mixed-namespaced-and-open-values) additionally preserve source-permitted wildcard data with native strict/lax/skip checks. Escapia qualification retains 15 Main operations and two Content operations against owned services. Content uses explicit companion configuration with scoped validation and buffered delivery; it is not automatic companion discovery or checked streaming.
 
-General XSD, SOAP 1.2/RPC-encoded, broader authentication/security, arbitrary wildcard conversion and checked incremental streaming remain outside this preview. OpenAPI describes the JSON shape but does not express every native scalar/order/wildcard rule. Required declarations and strict wildcard failures cannot become successful unchecked replies.
+The [bounded SOAP 1.1 RPC/encoded profile](supported-patterns.md#checked-soap-11-rpc-string-profile) supports typed scalar parts, native restrictions, one flat required Boolean record and one opaque string result. [NOAA qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) covers all 12 operations against an owned server; ten live operations succeeded and two GML operations returned non-SOAP failures. There is no parsed DWML/GML or geographic correctness claim.
+
+General XSD, general RPC encoding, broader authentication/security, arbitrary wildcard conversion and checked incremental streaming remain outside this preview. SOAP 1.2 document/literal uses the separately versioned binding described in the [checked gateway reference](checked-gateway.md#component-service-generation); live-provider acceptance is separate from owned-server protocol evidence. OpenAPI describes the JSON shape but does not express every native scalar/order/wildcard rule. Required declarations and strict wildcard failures cannot become successful unchecked replies.
 
 [#409](https://github.com/TechSpokes/typescript-wsdl-client/issues/409) supplies the bounded mixed/namespace/open mapping and its schema/serialization slice of [#410](https://github.com/TechSpokes/typescript-wsdl-client/issues/410). Representative unrelated contract qualification remains under [#397](https://github.com/TechSpokes/typescript-wsdl-client/issues/397); broader HTTP translation, source, scalar, group/naming, security and streaming work retains its existing owners. Legacy defaults and full-profile activation remain unchanged. See the [roadmap](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/ROADMAP.md) for direction and [development checkpoint](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/content-model-development-checkpoint.md) for detailed evidence.
 
@@ -158,4 +162,6 @@ With generated defaults, omitted restrictions retain the generated choices; expl
 
 Consumer-owned server/config/test files are preserved unless their existing `--force-init` or `--force-test` option is selected. Review customizations before deliberately refreshing older host scaffolds. Existing v1.1.5-issued direct clients continue using `checkedDirectRuntimeV1` unchanged; new generation uses components.
 
-Legacy users need no model change. Refresh existing consumer dependency lockfiles separately to pick up transitive security fixes.
+Legacy users need no model change. Follow the [1.1.x-to-1.2.0 migration guide](migration.md#from-11x-to-120) for affected generated names, stream values, buffered conversion fixes and rollback. The preview reached npm in 1.1.8; the earlier 1.1.6/1.1.7 candidates were unpublished.
+
+Checked hosts import `@techspokes/typescript-wsdl-client` at runtime. Retain it in production dependencies as emitted by the checked app manifest; do not omit it from a deployment that installs only production dependencies. Refresh separately maintained consumer package/lockfiles deliberately, and preserve adopted app/test customizations when regenerating.

package/docs/cli-reference.md

@@ -1,5 +1,7 @@
 # CLI Reference
 
+Commands and configuration for generation and assessment. See the root [README](../README.md).
+
 Generation offers legacy, the default, and opt-in `pipeline --model checked-components-v1`. Start with [Try Opt-in Checked Generation](checked-generation.md); the [checked gateway reference](checked-gateway.md) covers exact configuration and v1.1.5 runtime compatibility. Checked generation emits source-backed contracts rather than a legacy catalog and refuses unsupported compiler/streaming controls.
 
 The `wsdl-tsc` tool generates TypeScript SOAP clients, OpenAPI specifications, and Fastify gateways from WSDL files.
@@ -44,6 +46,18 @@ Checked modes require all three explicit outputs: `--client-dir`, `--openapi-fil
 
 Run the complete generation pipeline in one pass: WSDL parsing, TypeScript client, OpenAPI spec, Fastify gateway, and optional app. This is the recommended command for most use cases.
 
+### Multi-service configuration
+
+```bash
+npx wsdl-tsc pipeline --services-config ./services.json
+```
+
+`--services-config` selects native legacy composition and is exclusive with the single-source pipeline flags below. The JSON file contains `services: [{key, generation}]`, aggregate `openapi: {outFile}` and aggregate `gateway: {outDir}` settings. Each `generation` uses the programmatic `PipelineOptions` field names, including explicit `wsdl`, `catalogOut`, `clientOutDir`, `openapi.outFile`, `openapi.basePath`, `gateway.outDir`, `gateway.serviceSlug` and `gateway.versionSlug`.
+
+Paths resolve relative to the configuration file. Service keys, normalized gateway service slugs, route prefixes and generated ownership paths must remain distinct; source WSDLs must stay outside generated outputs. The aggregate OpenAPI file must be JSON, and its generated discovery route defaults to `/openapi.json`; set aggregate `gateway.openapiPath` to `false` to disable it.
+
+Keep compiler options, `streamConfigFile` or parsed `streamConfig`, and OpenAPI/gateway options inside the owning service entry. Runtime credentials and client sources belong to the generated `createClients` options, separate from generation configuration. Aggregate app/test scaffolding and checked composition are not supported in this mode; see the [complete configuration and runtime example](gateway-guide.md#multi-service-setup).
+
 ### Usage
 
 ```bash
@@ -56,11 +70,11 @@ npx wsdl-tsc pipeline \
   [options]
 ```
 
-### Required Flags
+### Required Single-Source Flags
 
 | Flag | Description |
 |------|-------------|
-| `--wsdl-source` | Path or URL to WSDL file |
+| `--wsdl-source` | Required WSDL path or URL; `--catalog-file` selects the catalog output |
 
 At least one of `--client-dir`, `--openapi-file`, or `--gateway-dir` must be provided.
 
@@ -162,7 +176,9 @@ Legacy tests need consumer test/runtime dependencies and use their emitted Vites
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--stream-config` | (none) | Path to a JSON stream-configuration file (ADR-002). Marks selected operations as streaming: client emits `AsyncIterable<RecordType>`, gateway serves NDJSON or JSON array output, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`. Buffered output is unchanged when the flag is omitted. |
+| `--stream-config` | (none) | Path to a JSON stream-configuration file; selects operations for mapped record streaming |
+
+Configured client methods return records through `AsyncIterable<RecordType>`; gateway routes serve NDJSON or JSON-array items, and OpenAPI carries `x-wsdl-tsc-stream` record metadata. Unselected operations retain the buffered API, while generated mapper/metadata output can still change across versions. See [1.2.0 migration](migration.md#from-11x-to-120) before regenerating.
 
 `--stream-config` is accepted on the `compile`, `client`, and `pipeline` commands. It is not accepted on `openapi`, `gateway`, or `app` because those consume a pre-compiled `catalog.json` that already carries the normalized stream metadata.
 
@@ -281,7 +297,7 @@ npx wsdl-tsc client --catalog-file <path> --client-dir <path> [options]
 
 | Flag | Description |
 |------|-------------|
-| `--wsdl-source` | Path or URL to WSDL file |
+| `--wsdl-source` or `--catalog-file` | WSDL source or precompiled catalog input |
 | `--client-dir` | Output directory for generated files |
 
 Provide either `--wsdl-source` (compile from WSDL) or `--catalog-file` (use pre-compiled catalog). When using `--wsdl-source`, the catalog is auto-generated in the client directory unless overridden with `--catalog-file`.
@@ -360,7 +376,7 @@ These flags are mutually exclusive.
 
 ### Response Envelope
 
-All responses are wrapped in a standard envelope (always-on since v0.7.1).
+Buffered legacy success responses use the standard envelope. Legacy streams emit NDJSON or a JSON array directly; checked component routes use checked values/faults. Errors after stream commitment truncate output.
 
 Base structure:
 
@@ -467,6 +483,8 @@ Format: `urn:services:{serviceSlug}:{versionSlug}:schemas:{models|operations}:{s
 
 ### Contract Assumptions
 
+These assumptions apply to buffered legacy gateway inputs. Stream response bodies and checked component schemas follow their separate contracts.
+
 - All request/response bodies must use `$ref` to `components.schemas`
 - Every operation must have a default response with `application/json`
 - All referenced schemas must exist in `components.schemas`
@@ -587,6 +605,8 @@ npx wsdl-tsc compile --wsdl-source <file|url> --catalog-file <path> [options]
 
 ### Compiler Flags
 
+The shared [client/compiler flag table](#client-flags) documents import extensions, naming, scalar policies, unresolved references and optionality. `compile --help` lists the complete current surface, including stream configuration.
+
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--client-choice-mode` | `all-optional` | Controls `xs:choice` modeling |

package/docs/concepts.md

@@ -312,8 +312,7 @@ OpenAPI uses operation docs for both `description` and default `summary` values.
 
 ## Response Envelope
 
-All gateway responses follow a uniform envelope structure. This has been
-always-on since v0.7.1.
+Buffered legacy gateway responses use this envelope. Stream success bodies deliver records directly, and checked components use their separate value/fault contract.
 
 ### Success Response
 
@@ -367,7 +366,7 @@ details:
 
 ### Streaming Bypass
 
-Operations opted into streaming with `--stream-config` bypass the success envelope on the `200` response path. The OpenAPI response content is declared as the configured stream media type, and the gateway writes raw NDJSON lines or one streamed JSON array straight to the response body. Error responses (400, 502, and the rest) still use the normal envelope so clients always see structured failures before the first record. See [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the full rationale.
+Legacy stream operations bypass the success envelope. OpenAPI declares the configured media type, and the gateway writes NDJSON lines or one JSON array. Errors handled before response commitment can use the normal error envelope; after commitment, failures truncate output. See [streaming handlers](gateway-guide.md#streaming-handlers).
 
 ### Envelope Naming
 
@@ -497,13 +496,13 @@ The generator produces two response execution models. Buffered is the default an
 
 ### Execution Model Contrast
 
-Buffered operations call `node-soap`, wait for the full response to materialize, and return `{ response, headers, responseRaw, requestRaw }`. Streaming operations bypass `node-soap`, POST a hand-built SOAP envelope via `fetch`, and return `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`. The SAX parser in `runtime/streamXml.ts` walks the configured `recordPath` and yields each record as its closing tag arrives.
+Buffered operations call `node-soap`, wait for the full response to materialize, and return `{ response, headers, responseRaw, requestRaw }`. Streaming operations use node-soap's WSDL serializer and public HTTP `requestStream` transport, returning `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`. The SAX parser walks `recordPath`; each completed record passes through `fromSoapResult` to produce the generated DTO, including flat attributes and typed `$value` content.
 
 The catalog is the source of truth for stream metadata. Each opted-in operation carries an `OperationStreamMetadata` entry, and downstream emitters (client, OpenAPI, gateway, tests) all read from the catalog. OpenAPI carries a derived view via the `x-wsdl-tsc-stream` extension.
 
 ### Terminal-Error Policy
 
-Errors before the first record use the normal gateway error envelope because the response headers and status have not been committed yet. Errors mid-stream truncate the response; NDJSON consumers detect this as an incomplete HTTP response, and JSON array consumers see an incomplete or invalid JSON document. Both cases must be treated as failed streams. This behavior is documented for operators in the [Production Guide](production.md#terminal-error-policy).
+Failures before response commitment can use the normal gateway error handler. After commitment, failures truncate output; an incomplete HTTP response or JSON document is a failed stream. See the [Production Guide](production.md#terminal-error-policy).
 
 ## Companion Catalogs and Shape Resolution
 

package/docs/configuration.md

@@ -102,8 +102,7 @@ Per-operation overrides for method, summary, description, and deprecation.
 ## Stream Configuration
 
 The `--stream-config <file>` flag (available on `compile`, `client`, `pipeline`)
-opts selected WSDL operations into streaming. Buffered output is unchanged for
-operations not listed in the file.
+opts selected WSDL operations into streaming. Unlisted operations retain their buffered API selection; 1.2.0 can still change generated mapper and metadata output.
 
 ```json
 {
@@ -140,7 +139,15 @@ operations not listed in the file.
 See [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale and the
 terminal-error policy.
 
-## Example Files
+## Multi-service configuration
+
+Use `pipeline --services-config services.json` exclusively, without single-source CLI flags. Each `services[].generation` uses programmatic `PipelineOptions` names, not CLI flag names. The canonical schema/example and typed runtime registry are in [Multi-Service Setup](gateway-guide.md#multi-service-setup).
+
+Paths in the services file resolve relative to that file; companion paths inside `streamConfigFile` resolve relative to the stream file. Programmatic `streamConfig` requires normalized metadata from `parseStreamConfig`, whereas raw JSON uses `recordType` and `shapeCatalog`. Do not interchange those shapes.
+
+Use unique lowercase service keys, normalized service slugs, decorators and static base paths, with explicit disjoint output ownership. Aggregate output is JSON only; `gateway.openapiPath` selects discovery or disables it with `false`. Bind runtime WSDL sources and security separately for every client. Checked services and aggregate app/test scaffolding are refused.
+
+## Example configuration files
 
 Example configuration files are available in the `examples/config/` directory:
 

package/docs/corpus.md

@@ -8,7 +8,7 @@ This table is generated from `test/conformance/readiness-corpus.json`; its sourc
 
 | Input | Provenance tier | Mode | Expected result | Evidence stages | Executable evidence |
 |---|---|---|---|---|---|
-| [noaa-ndfd](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/fixtures/wsdl/real-services/noaa-ndfd/ndfd-xml.wsdl) | real | checked | refused | original source decoding and 12-operation inventory, locationless-import planning refusal, zero SOAP dispatch | [noaa-ndfd-qualification.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/noaa-ndfd-qualification.test.ts) |
+| [noaa-ndfd](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/fixtures/wsdl/real-services/noaa-ndfd/ndfd-xml.wsdl) | real | checked | partial | original source decoding and 12-operation inventory, all 12 operations native planning and generation, installed build and every generated HTTP route, owned typed SOAP 1.1 RPC with native restrictions and 73-field Boolean record, exact Latin1 responses and offline provider replay; zero provider calls in tests | [noaa-ndfd-qualification.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/noaa-ndfd-qualification.test.ts), [checked-gateway-installed.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-gateway-installed.test.ts) |
 | [weather](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/examples/minimal/weather.wsdl) | synthetic | legacy | supported | generate, typecheck, OpenAPI, gateway mock, installed package | [gateway-routes.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/gateway-routes.test.ts); `npm run package:smoke` |
 | [checked-forecast](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/forecast.wsdl) | synthetic | checked | supported | generate, install, typecheck, HTTP/SOAP success and faults | [checked-gateway-installed.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-gateway-installed.test.ts) |
 | [application-groups](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/application-groups.wsdl) | synthetic | checked | supported | generate, native SOAP, OpenAPI, installed HTTP/SOAP variant | [checked-application-groups.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-application-groups.test.ts), [checked-gateway-installed.test.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-gateway-installed.test.ts) |

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`](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/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,10 @@ 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.
@@ -140,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({});
@@ -164,6 +168,8 @@ 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](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the rationale and terminal-error policy.
@@ -214,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.

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: