@techspokes/typescript-wsdl-client 1.1.8 → 1.2.0

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:

package/docs/migration.md

@@ -1,23 +1,141 @@
 # Migration Guide
 
-This guide covers upgrade steps between major versions of `@techspokes/typescript-wsdl-client`.
+This guide covers package upgrades and generated-project compatibility for `@techspokes/typescript-wsdl-client`.
 
 Versions are listed newest first. Find your current version and follow the steps for each version you need to cross.
 
+See the root [README](../README.md). Historical version sections below describe their original releases; 1.2.0 compatibility guidance supersedes earlier unchanged-output statements for this upgrade.
+
 ## General Upgrade Steps
 
 These steps apply to every version upgrade:
 
-1. Update the package: `npm install --save-dev @techspokes/typescript-wsdl-client@latest`
-2. Read the migration section for your version jump below
-3. Regenerate all output by running your generation script or pipeline command
-4. Run `tsc --noEmit` to verify the generated code compiles
-5. Test your application
+1. Read the migration section for the installed and intended versions before updating dependencies.
+2. Preserve the working dependency lockfile, inputs, generation settings and application customizations.
+3. Install an explicit target version in an upgrade branch.
+4. Regenerate matched generator-owned artifacts using the existing generation script and options.
+5. Review the generated diff and run the consumer project's TypeScript build and tests.
+
+## From 1.1.x to 1.2.0
+
+### Published starting points
+
+Both 1.1.5 and 1.1.8 were published to npm. Versions 1.1.6 and 1.1.7 were unpublished candidates whose preview work was carried into 1.1.8; their GitHub tags and release-note files do not make them installable npm versions. This publication history was checked against the [npm registry metadata](https://registry.npmjs.org/@techspokes%2Ftypescript-wsdl-client) on 2026-11-10.
+
+Use these instructions for either published starting point. A project upgrading from 1.1.5 also crosses the checked-generation preview and legacy conversion corrections already shipped in 1.1.8. Historical release notes remain a record of their original candidates, not additional required installation steps.
+
+### Package installation versus regeneration
+
+Publishing a package does not change a deployed gateway. Installing a newer generator does not itself rewrite existing generated files; a consumer's install/build scripts may run generation, and dependency resolution or package-runtime imports can change behavior without regeneration.
+
+| Project action | Upgrade effect |
+|---|---|
+| Keep the installed package, lockfile and deployed build | No automatic switch to 1.2.0 |
+| Update the package without running generation | Existing generated files remain; runtime dependencies still need verification |
+| Run generation during a build or install | New output can appear in that next build |
+| Regenerate using the existing legacy command | Legacy remains selected; compiler and mapper corrections take effect |
+| Select checked generation or native composition | Deliberate adoption with separate contracts and configuration |
+
+A dependency range of `^1.1.5` or `^1.1.8` permits 1.2.0 when npm resolves an update. An exact version pin or a `~1.1.x` range does not permit this minor upgrade. Commit the lockfile and use `npm ci` to reproduce its recorded dependency tree; updating or replacing that lockfile is a separate deliberate step. See [npm version ranges](https://docs.npmjs.com/about-semantic-versioning/) and [npm ci](https://docs.npmjs.com/cli/v11/commands/npm-ci/).
+
+### Changes that can affect existing projects
+
+The 1.2.0 compiler correction separates declarations that previously collapsed into one generated type. Distinct inline `Entry` declarations under `Left` and `Right` now receive separate owner-qualified names. Non-colliding exported names and XML/JSON member names are preserved; residual Pascal-case or namespace collisions receive deterministic suffixes.
+
+This minor release includes corrective compatibility changes: affected exported DTO names can break source imports after regeneration, and stream records now use generated DTOs rather than lexical attribute bags. The 1.2.0 version number is not a guarantee of a drop-in regeneration upgrade; review the following impacts before deploying the regenerated project.
+
+| Existing use | What to review |
+|---|---|
+| Buffered legacy gateway | Keep its model and envelope; inspect regenerated schemas and DTO conversion |
+| Colliding declaration names | Update affected imports, type annotations and stream `recordType` references |
+| Legacy streaming | Update consumers expecting lexical strings or nested attribute bags |
+| Boolean attributes or simple content | Review corrected scalar conversion and `$value` objects |
+| Adopted app or test scaffolds | Merge intended updates; existing files are preserved by default |
+| Published 1.1.5 checked direct clients | Retain the versioned binding and its original execution restrictions |
+
+Regeneration can also change OpenAPI model names and generated SDK names that depend on them. Preserving an XML/JSON member name does not preserve a previously incorrect value shape or scalar conversion. Do not mix a newly generated client with an older catalog, metadata helper, gateway or OpenAPI document to suppress these changes.
+
+### Stream record migration
+
+Configured stream methods still return `records: AsyncIterable<RecordType>`, but each completed XML record now passes through generated DTO mapping. Flattened attributes, typed `$value` content, configured scalar policies, XML lists and repeated fields follow the generated model. The gateway sends those mapped records as NDJSON or JSON-array items without a legacy success envelope.
+
+For a record with Boolean `Enabled` and integer `Rank` attributes and an integer `Count` child, a previous parser-shaped record using the default output attribute key could look like this:
+
+```json
+{"attributes":{"Enabled":"1","Rank":"7"},"Count":"42"}
+```
+
+The corresponding mapped DTO fields are:
+
+```json
+{"Enabled":true,"Rank":7,"Count":42}
+```
+
+This is a field-level illustration, not a complete SOAP payload or a rule that all numbers become JavaScript numbers. Decimal and int64 policies remain configurable and string-first by default; JavaScript `bigint` still requires a consumer-owned JSON strategy. Update stream consumers and review their advertised OpenAPI schemas together.
+
+Stream calls add optional `{signal, timeoutMs}` and supported node-soap serializer/transport hooks. Requests now use the WSDL serializer and supported client endpoint/security settings; verify those settings against the intended backend. SOAP 1.2, functional SOAP headers, SOAP body attributes, MTOM and NTLM remain refused stream combinations. See the [stream API](api-reference.md#generated-stream-client-contract) and [transport boundaries](gateway-guide.md#streaming-transport-settings).
+
+### Buffered conversion corrections since 1.1.5
+
+The intervening published 1.1.8 includes corrections for Boolean XML attributes and simple-content responses. Valid Boolean spellings become actual Booleans; invalid spellings reject instead of producing misleading successful values. Text-only complex simple content retains its `$value` object, including when optional attributes are absent. Review application code that compensated for the previous incorrect results.
+
+The ordinary buffered legacy call still exposes its generated `.response` value, and its gateway retains the legacy success envelope. Omitting stream configuration does not promise byte-identical generated output: shared mapper and metadata corrections also apply to buffered clients.
+
+### Upgrade an existing legacy gateway
+
+Keep Node.js >= 24 and the existing ESM project setup. Keep the generator as a development dependency and `soap` as a runtime dependency; retain the gateway's other runtime dependencies. A separately maintained generated app has its own package and lockfile, so upgrading the generator in its parent project does not automatically refresh that app's dependencies.
+
+After 1.2.0 is published, install the explicit target in the project that owns generation:
+
+```bash
+npm install --save-dev --save-exact @techspokes/typescript-wsdl-client@1.2.0
+```
+
+Before publication, use a locally packed candidate as described in [checked-generation installation guidance](checked-generation.md#install-and-try-the-bundled-contract), rather than requesting an unpublished registry version. Do not add a checked model flag just to upgrade a legacy project.
+
+1. Preserve a known-working revision with its dependency lockfiles and generation inputs.
+2. Run the existing generation script with the same profile, paths, naming and mapping options.
+3. Regenerate matched catalog, client, metadata helpers, OpenAPI and gateway artifacts from original WSDL/XSD sources.
+4. Review generated type/schema names, buffered values and any configured stream records.
+5. Merge app/configuration/package and test scaffold updates deliberately.
+6. Run the consumer project's TypeScript check with generated files included and its maintained tests.
+7. Verify representative request, response and fault behavior against an authorized test backend before deployment.
+
+Existing app and generated-test scaffold files are skipped by default. `pipeline --force-init` and `--force-test` explicitly replace their respective scaffolds; standalone `app --force` has the app replacement role. Preserve custom server, authentication, environment, package and test changes before selecting any force option. Do not delete an entire app directory merely to refresh the replaceable client/gateway files inside it.
+
+The compiled catalog format remains unchanged. Old catalogs remain readable as stored, but cannot recover declarations lost through an earlier merge; loading one does not fetch its WSDL or reconstruct missing types. Companion catalogs retain their existing conservative same-name structural conflict checks.
+
+### Optional adoption of new capabilities
+
+| Capability | Adoption boundary |
+|---|---|
+| Native legacy multi-service gateway | Use `pipeline --services-config`; retain independent sources, clients and security |
+| Checked document/literal or bounded RPC | Trial `pipeline --model checked-components-v1` in separate output paths |
+| Existing manual gateway mounting | Continue registering single-source plugins in separate Fastify scopes |
+
+Native composition emits one aggregate plugin and OpenAPI document for legacy services; it does not supply an aggregate app/test scaffold or compose checked routes. See the [multi-service guide](gateway-guide.md#multi-service-setup). Check downstream tooling when adopting service-qualified OpenAPI components and operation identifiers.
+
+Checked generation is a bounded buffered preview, not an automatic replacement for a legacy gateway. Its JSON values, validation and fault contracts differ from legacy DTO/envelope behavior, and unsupported contracts refuse. Checked hosts import this package at runtime, so retain it as a production dependency according to the emitted app manifest; a generator-only development dependency is insufficient for that deployment. Keep runtime version, source snapshots and generated checked artifacts matched. Checked streaming remains outside this profile.
+
+Existing published 1.1.5-issued direct clients retain `checkedDirectRuntimeV1` and its original owned-loopback restrictions; installed compatibility fixtures exercise that specific binding. A deployed host importing that retained binding also needs this package as a production dependency, even when its generator tooling lives elsewhere. The unchanged direct protocol allows those retained artifacts to use the newer compatible package binding; it does not grant component-runtime capabilities.
+
+The unpublished `checked-direct-v1` generation choice is not a current generation mode. New checked generation uses components; moving an old direct client to components is deliberate regeneration and adoption, not a runtime capability upgrade. See [checked-generation upgrade guidance](checked-generation.md#upgrade-and-regenerate).
+
+### Consumer verification and rollback
+
+Release verification exercises representative generated/installed consumers, compatibility fixtures and owned SOAP exchanges. It cannot certify every existing consumer project or provider operation. Generated mock/scaffold tests do not replace maintained application tests, TypeScript checks or independent SOAP/provider acceptance; follow [consumer testing guidance](testing.md#for-consumer-projects).
+
+Verify affected type imports, OpenAPI/SDK changes, scalar and `$value` conversions, stream item shapes and cancellation/error handling. Retain endpoint, credentials, TLS trust and array-wrapper settings explicitly. The published preview does not provide a universal migration checker or a guarantee of complete WSDL/XSD support.
+
+For rollback, restore the known-working application revision, generator/app package manifests and lockfiles, matched generated artifacts and source/configuration inputs together, then reinstall with `npm ci` and rebuild. Projects that do not commit generated output should regenerate using the original pinned generator and inputs. Restoring only the generator version leaves newly generated code in place and is not a complete rollback.
 
 ## Version Compatibility
 
+The 1.2.0 scaffold row records the current legacy app template pins, not an automatic rewrite of an existing consumer's package. Follow the emitted manifest for new apps and review separately maintained runtime dependencies when upgrading older ones.
+
 | wsdl-tsc | Node.js | TypeScript | soap | Fastify | saxes |
 |----------|---------|------------|------|---------|-------|
+| 1.2.0 legacy scaffold | >= 24.0 | ^6.0.3 | ^1.14.0 | ^5.12.8 | ^6.0.0 |
 | 1.0.x | >= 24.0 | >= 6.0 | >= 1.9 | >= 5.10 | >= 6.0 |
 | 0.35.x and later | >= 24.0 | >= 6.0 | >= 1.9 | >= 5.8 | >= 6.0 |
 | 0.17.x | >= 20.0 | >= 6.0 | >= 1.9 | >= 5.8 | >= 6.0 |

package/docs/output-anatomy.md

@@ -2,9 +2,11 @@
 
 This document describes each file produced by the generator, what it contains, and how to work with it. For CLI flags that control output, see [CLI Reference](cli-reference.md).
 
+See the root [README](../README.md) for the documentation index. This catalog-based flow describes legacy output; [checked generation](checked-generation.md) emits source-backed artifacts with a separate value/validation contract.
+
 ## TypeScript File Preambles
 
-All complete emitted TypeScript files receive one [generated preamble](generated-code.md#generated-preambles-and-eslint), including optional helpers and `_typecheck.ts`. App and generated-test scaffolds use editable-source wording and retain their existing skip/force behavior. Data outputs and existing consumer source remain unchanged.
+All complete emitted TypeScript files receive one [generated preamble](generated-code.md#generated-preambles-and-eslint), including optional helpers and `_typecheck.ts`. App and generated-test scaffolds use editable-source wording and retain their existing skip/force behavior. Preambles do not alter data files or existing consumer source; regeneration compatibility follows the [version migration guide](migration.md#from-11x-to-120).
 
 ## Generation Flow
 
@@ -25,15 +27,15 @@ Generated into the directory specified by `--client-dir`.
 
 | File | Purpose |
 |------|---------|
-| types.ts | All TypeScript interfaces derived from WSDL/XSD types |
+| types.ts | TypeScript models projected from WSDL/XSD types |
 | client.ts | SOAP client class with one typed method per operation |
 | operations.ts | Pure interface matching client methods, for mocking without importing `soap` |
-| utils.ts | Runtime helpers including array unwrapping and type metadata |
+| utils.ts | JSON/SOAP conversion metadata |
 | catalog.json | Compiled WSDL data in JSON format, used by other generation stages |
 
 ### types.ts
 
-Contains one interface per WSDL complex type. Attributes and elements are flattened into peer properties. Inheritance is expressed with TypeScript `extends`. All numeric and date-time types map to `string` by default to prevent precision loss.
+Declares generated interfaces and aliases with flattened attribute and element properties. Inheritance can use TypeScript `extends`. Scalar types follow compiler policies: int64, arbitrary-size integers, decimal and date/time default to strings; ordinary numeric and Boolean types retain their projected types.
 
 ### client.ts
 
@@ -45,7 +47,7 @@ Exports a TypeScript interface with the same method signatures as the client cla
 
 ### utils.ts
 
-Contains runtime metadata and helper functions. Includes `unwrapArrayWrappers()` for bridging between SOAP array wrapper objects and flattened OpenAPI array schemas.
+Provides metadata used by the client's `toSoapArgs` and `fromSoapResult` methods. Optional array-wrapper flattening belongs to gateway `runtime.ts` and applies per record for streams.
 
 ### Stream Operations
 
@@ -61,7 +63,7 @@ export type StreamOperationResponse<RecordType, HeadersType = Record<string, unk
 };
 ```
 
-`client.ts` gains a protected `callStream()` transport. Stream methods bypass `node-soap` (which buffers the full response before invoking its callback, as confirmed in phase-0 research) and instead POST a hand-built SOAP envelope via global `fetch`, piping the response body through a SAX-driven record parser. `node-soap` remains the transport for buffered operations.
+`client.ts` gains a protected `callStream()` transport using node-soap's WSDL serializer and public HTTP `requestStream`. Completed parser records pass through the generated DTO mapper; iterator return, per-call abort/deadline and downstream disconnect release the upstream transport. See [stream transport settings](gateway-guide.md#streaming-transport-settings).
 
 Generated imports required at runtime: `saxes` for SAX parsing. The generated app scaffold pins `saxes ^6.0.0` automatically; manual consumers must install it explicitly.
 
@@ -73,7 +75,7 @@ Generated at the path specified by `--openapi-file`.
 |------|---------|
 | openapi.json (or .yaml) | Complete OpenAPI 3.1 specification |
 
-The spec includes one POST path per WSDL operation, request and response schemas in `components/schemas`, and descriptions derived from WSDL documentation annotations. Schemas are generated from the same catalog used for TypeScript types, so the two outputs stay aligned.
+The spec defaults to one POST path per WSDL operation, with request/response schemas in `components/schemas` and source documentation descriptions. Configured defaults and operation overrides can select other HTTP methods. Schemas and TypeScript models use the same catalog.
 
 CLI OpenAPI generation always validates the generated spec using `@apidevtools/swagger-parser`.
 
@@ -120,7 +122,7 @@ JSON array streams default to `application/json` and declare the record schema a
 }
 ```
 
-OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document, so the extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators. JSON array streams use a normal array schema and keep the extension for downstream tooling. Error responses (400, 502, and the rest) still use the normal envelope.
+OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document, so the extension makes the item schema explicit. JSON-array streams use an array schema and retain the extension. Errors handled before response commitment can use the legacy error envelope; later failures truncate output.
 
 ## Gateway Output
 
@@ -143,7 +145,7 @@ Each route file in `routes/` follows the same pattern: validate the JSON request
 
 ### Stream Routes
 
-Stream-configured operations generate a different route shape. The Fastify response serialization schema is omitted because the handler sends a `Readable` directly. NDJSON handlers set `reply.type("application/x-ndjson")` and return `reply.send(toNdjson(result.records))`; JSON array handlers set `reply.type("application/json")` and return `reply.send(toJsonArray(result.records))`. `runtime.ts` gains `toNdjson<T>(records: AsyncIterable<T>): Readable` and `toJsonArray<T>(records: AsyncIterable<T>): Readable` helpers. See the [Gateway Guide](gateway-guide.md#streaming-handlers) for the full handler example and terminal-error policy.
+Stream routes omit Fastify response serialization and deliver a `Readable` using `toNdjson` or `toJsonArray`. Completed records are mapped and optionally unwrapped per record; the route connects downstream disconnects to a per-call abort signal before waiting for upstream headers and throughout delivery. See [Streaming Handlers](gateway-guide.md#streaming-handlers) for the cancellable flow and pre-commit versus mid-stream failure policy.
 
 ### Generated Test Surface
 
@@ -155,26 +157,27 @@ The generated plugin exports a Fastify plugin function. Register it with your Fa
 
 ```typescript
 import Fastify from "fastify";
-import { myServiceGateway } from "./.generated/gateway/plugin.js";
-import { createMyServiceClient } from "./.generated/client/client.js";
+import gateway from "./.generated/gateway/plugin.js";
+import { Weather } from "./.generated/client/client.js";
 
 const app = Fastify();
-const client = await createMyServiceClient("https://soap-endpoint.example.com");
-await app.register(myServiceGateway, { client, prefix: "/v1/my-service" });
+const client = new Weather({source: "./weather.wsdl"});
+await app.register(gateway, { client, prefix: "/v1/weather" });
 ```
 
 ## App Output
 
-Generated when `--init-app` is passed. Creates a runnable Fastify application in a sibling `app/` directory.
+Generated with `pipeline --init-app` or the `app` command. `--app-dir` selects the output location; the default is a sibling `app/` directory.
 
 | File | Purpose |
 |------|---------|
-| index.ts | Application entry point with server startup |
+| server.ts | Application entry point with server startup |
+| config.ts | Environment-based configuration loader |
 | .env.example | Environment variable template for WSDL URL, port, host |
 | package.json | Dependencies and npm scripts |
 | tsconfig.json | TypeScript configuration for the app |
 
-App files have overwrite protection: they are written only if they do not already exist. This prevents regeneration from overwriting your customizations. Use `--force-app` to override this behavior.
+App scaffolds are preserved by default. Use `pipeline --force-init` or standalone `app --force` only for deliberate replacement after reviewing adopted customizations.
 
 ## What to Commit
 
@@ -182,6 +185,6 @@ All generated files are deterministic. Committing them to version control is saf
 
 ## What to Customize
 
-- App files (`index.ts`, `.env`): these are your entry points; customize freely after first generation
+- Adopted app files (`server.ts`, `config.ts`, `.env`) are consumer-owned customization points.
 - Gateway plugin, routes, and schemas: do not edit manually; they are overwritten on regeneration
 - Add custom middleware, auth, logging, and error handling in your app code, not in generated gateway files

package/docs/production.md

@@ -71,11 +71,13 @@ Records flow through `Readable.from` in the generated `runtime.ts`. The iterator
 
 ### Connection Timeouts
 
-Stream responses can stay open for the full duration of the upstream SOAP call. The Fastify `keepAliveTimeout`, `requestTimeout`, and any reverse proxy (nginx, ALB, CloudFront) must allow the maximum expected upstream duration. Default Fastify timeouts are shorter than typical long-running SOAP batch responses.
+Stream responses can stay open for the duration of the upstream SOAP call. Configure an upstream operation deadline and align reverse-proxy/load-balancer limits with the expected duration and idle gaps. Supported legacy stream calls accept `{signal, timeoutMs}`; their per-call deadline starts after SOAP metadata initialization.
+
+Fastify's `requestTimeout` limits receipt of the incoming request, while HTTP keep-alive settings govern idle connection reuse; neither is a substitute for the SOAP operation deadline. Review the [Fastify server options](https://fastify.dev/docs/latest/Reference/Server/) separately from [stream transport settings](gateway-guide.md#streaming-transport-settings). Do not assume a universal Fastify default will bound an active upstream call.
 
 ### Memory Profile
 
-Memory stays bounded regardless of payload size because records are parsed and emitted one at a time. The SAX parser buffers only within the current record element. This is the primary reason to opt into streaming: buffered operations load the full response into memory before yielding.
+Streaming avoids materializing the entire response, but memory depends on record size and transport/parser buffering. A large record still requires memory before DTO mapping; no constant-memory or total-byte-cap guarantee is provided.
 
 ### Observability
 
@@ -83,7 +85,7 @@ Log the time to first record, not just the time to response completion. First-re
 
 ### Terminal-Error Policy
 
-Errors raised before the first record use the normal gateway error envelope because the JSON array helper prefetches the first record before emitting `[`. Errors raised mid-stream truncate the response. NDJSON consumers detect this as an incomplete HTTP response, and JSON array consumers must treat an incomplete or invalid JSON document as a failed stream. Document this behavior for downstream API consumers so they distinguish truncation from a legitimate empty stream.
+Errors handled before response commitment can use the gateway error envelope. The JSON-array helper prefetches before emitting `[`, but a first-record boundary alone is not a universal commitment guarantee. After commitment, failures truncate output; consumers must treat incomplete HTTP or JSON as a failed stream, even when earlier records were valid.
 
 ## Known Limitations
 
@@ -107,6 +109,6 @@ Single-child sequences with maxOccurs>1 become array schemas. Sequences with mul
 
 `ndjson` is the default stream format. `json-array` is supported for operations that need a single JSON document response; it streams records incrementally as a JSON array and does not buffer the full SOAP response.
 
-### Stream Transport Bypasses node-soap
+### Stream transport settings
 
-Stream operations bypass `node-soap` entirely and POST a hand-built SOAP envelope via `fetch`. Any `node-soap` middleware, interceptors, or custom security handlers that your buffered operations rely on will not apply to stream operations. Authentication headers, proxies, and TLS options must be configured on the stream transport path separately.
+Stream operations use node-soap's WSDL serializer and public HTTP `requestStream`, including supported static headers, endpoint and security hooks. Configure stream HTTP options separately from WSDL acquisition; see [transport support and refusals](gateway-guide.md#streaming-transport-settings). On supported Node versions, `node --use-system-ca` uses verified system trust; caller-specific CA/HTTPS agent settings remain client-owned. Keep certificate verification enabled.