@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

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,11 +47,11 @@ 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
 
-When `--stream-config` opts an operation into streaming (see [ADR-002](decisions/002-streamable-responses.md)), the client emits additional surfaces alongside the buffered ones. Buffered operations in the same client are unaffected.
+When `--stream-config` opts an operation into streaming (see [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md)), the client emits additional surfaces alongside the buffered ones. Buffered operations in the same client are unaffected.
 
 `operations.ts` gains a `StreamOperationResponse<RecordType>` type that stream methods return instead of the buffered `{ response, headers, responseRaw, requestRaw }` shape:
 
@@ -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.

package/docs/start-here.md

@@ -2,6 +2,14 @@
 
 This page helps you understand what this package does, decide if it fits your needs, and find the fastest path to your first result.
 
+See the root [README](../README.md) for installation and the documentation index.
+
+## Upgrade an existing project
+
+Read the [1.1.x-to-1.2.0 migration guide](migration.md#from-11x-to-120) before regenerating an existing gateway. Installing the package does not itself rewrite generated code, but consumer build/install scripts can run generation. Legacy remains the default; affected generated names, stream record shapes and corrected scalar/simple-content results need review.
+
+Use the existing generation command and preserve app/test customizations first. Adopt native composition or checked generation separately; successful representative release tests do not certify migration of every consumer project.
+
 ## What This Package Does
 
 `@techspokes/typescript-wsdl-client` reads a WSDL/XSD definition and generates typed TypeScript code. Depending on the command you run, you get a typed SOAP client, an OpenAPI 3.1 specification, a Fastify REST gateway, or all of the above.
@@ -17,6 +25,8 @@ The generated output is deterministic: re-running the same command produces iden
 
 ## Choose Your Path
 
+Choose legacy single-source generation for existing DTO/envelope integrations. For multiple independent legacy sources, use [native composition](gateway-guide.md#multi-service-setup) with `pipeline --services-config`. For source-backed validation and the bounded SOAP 1.1 RPC/encoded profile, choose [checked generation](checked-generation.md); checked replies remain buffered values, without the legacy success envelope. Neither profile claims universal SOAP support.
+
 ### I need a typed SOAP client
 
 Run the `client` command. This generates TypeScript interfaces for all WSDL types and a typed client class with one method per SOAP operation.
@@ -64,9 +74,15 @@ The gateway transforms JSON HTTP requests into SOAP calls and returns JSON respo
 
 Next: [Gateway Guide](gateway-guide.md) for integration details, then [Migration Playbook](migration-playbook.md) for the full modernization workflow
 
+### I want to try source-backed checked generation
+
+The checked component preview shipped in npm version 1.1.8 after the unpublished 1.1.6/1.1.7 candidates. `pipeline --model checked-components-v1` derives unambiguous selections and supported structured mappings from a WSDL file or URL, acquires declared dependencies, and emits a client, OpenAPI, gateway, app and tests. The existing pipeline remains the default when `--model` is omitted.
+
+Start with [Try Opt-in Checked Generation](checked-generation.md) for a bundled installed trial, endpoint configuration, missing-schema recovery and feedback instructions. Supported contracts get native request/response/fault checks; unsupported capabilities refuse rather than bypassing validation. This preview is buffered and separate from the legacy streaming workflow below.
+
 ### I need to stream large SOAP responses
 
-Some SOAP services return payloads that are too large or too slow to buffer in memory. Opt selected operations into streaming with a small JSON config and the `--stream-config` flag. Operations not listed keep their buffered behavior, so existing output stays byte-for-byte unchanged.
+Some SOAP services return large responses. Opt selected legacy operations into streaming with `--stream-config`. Unlisted operations retain their buffered API selection; generated mapper and metadata output can change in 1.2.0. Stream bodies bypass the legacy success envelope.
 
 ```bash
 npx wsdl-tsc pipeline \
@@ -96,7 +112,7 @@ Stream operations return `StreamOperationResponse<RecordType>` on the client (`r
 
 Set `"format": "json-array"` in the stream config when downstream clients need one `application/json` array document instead of NDJSON lines.
 
-Next: [ADR-002: Streamable Responses](decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
+Next: [ADR-002: Streamable Responses](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
 
 ### I want an AI agent to help in my project
 
@@ -120,5 +136,5 @@ For more on scope boundaries, see the "When NOT to Use This" section of the [REA
 | Plan a full SOAP-to-REST migration | [Migration Playbook](migration-playbook.md) |
 | Set up testing for generated code | [Testing Guide](testing.md) |
 | Review all CLI flags | [CLI Reference](cli-reference.md) |
-| Opt specific operations into response streaming | [ADR-002](decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
+| Opt specific operations into response streaming | [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
 | Install package-specific agent guidance | [Agent Skill Artifact](agent-skill.md) |

package/docs/supported-patterns.md

@@ -2,11 +2,32 @@
 
 This document lists the WSDL and XSD features handled by the generator, along with current limitations. For modeling details, see [Core Concepts](concepts.md).
 
+The matrix describes the existing legacy generator. The unreleased opt-in [checked gateway preview](checked-gateway.md) has a separate, narrower source/value/binding contract and installed HTTP/SOAP evidence; these legacy rows do not imply checked-model support. Synthetic preview success establishes no real-provider or general-XSD coverage.
+
+The qualified checked domain includes [keyed mixed, namespace-collision and source-permitted open values](checked-gateway.md#mixed-namespaced-and-open-values), with production conformance and installed request/response/fault evidence. Native strict/lax/skip checks remain distinct from schema-source wildcard checks and from the legacy rows below.
+
+## Checked SOAP 1.1 RPC string profile
+
+Checked component generation supports the bounded RPC/encoded profile below. The [NOAA qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) distinguishes all-12 owned-server execution, offline provider-response replay and the 2026-11-09 live retest: ten operations succeeded, while two GML operations returned non-SOAP provider errors. No geographic correctness claim follows.
+
+| Capability | Status | Bounded contract |
+|---|---|---|
+| Typed RPC/encoded parts | Partial | Required strings, Booleans, decimal/integer/date/dateTime strings and native restrictions |
+| RPC Boolean record | Partial | One flat required Boolean record with native particle and fixed-value validation |
+| RPC result | Partial | One opaque string result under the original output part name |
+| Component SOAP response encodings | Partial | UTF-8, BOM-marked UTF-16 and exact ISO-8859-1 with assertion agreement |
+| SOAP string references | Partial | Same-Body string `id`/`href`, inline strings and unambiguous roots |
+| Unused locationless imports | Supported | Native component qualification resolves actual required references |
+
+Request accessors follow source declaration order and the WSDL body namespace, with resolved native type names. JSON record property order is immaterial; native all-group validation permits unordered children while canonical writing is deterministic. Response struct and return-accessor local names may vary; the generated JSON response retains the source-owned part name. RPC/literal, other primitives, encoded arrays/shared or cyclic graphs, multiple results, declared RPC faults, headers and `parameterOrder` remain unsupported by this profile.
+
+The component response decoder uses an explicit supported HTTP charset or XML declaration without a BOM and requires all present header/declaration/BOM assertions to agree. Absent assertions default to UTF-8; invalid UTF-8 never triggers Latin1 guessing. ISO-8859-1 preserves byte-to-code-point identity, including C1 bytes; XML 1.0 legality and caller limits still apply. This compatible response extension belongs to the checked component runtime; source decoding and the shipped direct-runtime policy remain separate. Existing string-RPC artifacts retain their identity; typed inputs have a distinct interpretation and fresh source compatibility checks.
+
 ## Capability Evidence Matrix
 
 The rows below are backed by committed conformance fixtures under `test/conformance/fixtures/`. Status means the current product contract, not the full standards surface.
 
-The [S06 research handoff](content-model-s06-research-handoff.md) records separate attribute, derivation, wildcard and calendar evidence.
+The [S06 research handoff](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/content-model-s06-research-handoff.md) records separate attribute, derivation, wildcard and calendar evidence.
 Candidate interpretations and test-only prototypes do not certify production assessment or change these public capability rows.
 
 <!-- support-matrix:start -->
@@ -102,11 +123,11 @@ The compiler scans inline policies for UsernameToken, TransportBinding, and X509
 
 ### xs:group and xs:attributeGroup
 
-The `declared-derivation-boundaries` fixture characterizes the legacy default: its named group elements and attribute-group uses are omitted from the containing compiled type. General group support is therefore unqualified. Internal [reference resolution](content-model-resolution.md) preserves complete group definitions and separate use-site bounds; [companion reuse](content-model-companions.md) carries their required closures. These internal results do not establish public generation support.
+The `declared-derivation-boundaries` fixture characterizes the legacy default: its named group elements and attribute-group uses are omitted from the containing compiled type. General group support is therefore unqualified. Internal [reference resolution](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-resolution.md) preserves complete group definitions and separate use-site bounds; [companion reuse](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-companions.md) carries their required closures. These internal results do not establish public generation support.
 
 ### Extension and restriction
 
-The same executable fixture distinguishes current legacy behavior: extension appends local properties, but restriction also appends them and empty restriction retains base content. A prohibited optional attribute remains in legacy metadata. Faithful restriction, attribute composition and immutable sibling behavior are covered by internal [derivation tests](content-model-composition.md), with full legality assessment assigned to #179. Public faithful derivation support remains unqualified.
+The same executable fixture distinguishes current legacy behavior: extension appends local properties, but restriction also appends them and empty restriction retains base content. A prohibited optional attribute remains in legacy metadata. Faithful restriction, attribute composition and immutable sibling behavior are covered by internal [derivation tests](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-composition.md), with full legality assessment assigned to #179. Public faithful derivation support remains unqualified.
 
 ### xs:list