@techspokes/typescript-wsdl-client 1.1.8 → 1.2.0

package/dist/pipeline.js

@@ -21,6 +21,7 @@ import { resolveCompilerOptions } from "./config.js";
 import { emitClientArtifacts, reportCompilationStats, reportOpenApiSuccess, success } from "./util/cli.js";
 import { loadStreamConfigFile } from "./util/streamConfig.js";
 import { applyShapeCatalogs } from "./compiler/shapeResolver.js";
+import { deriveClientName } from "./util/tools.js";
 /**
  * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI/Gateway/App
  *
@@ -129,6 +130,7 @@ export async function runGenerationPipeline(opts) {
             clientDir: opts.clientOutDir ? path.resolve(opts.clientOutDir) : undefined,
             // Reuse the same imports mode as the TypeScript client/types/utils emitters
             imports: finalCompiler.imports,
+            clientClassName: opts.gateway.clientClassName ?? deriveClientName(compiled),
             // Pass catalog for runtime unwrap generation
             catalogFile: path.resolve(opts.catalogOut),
             // Thread flatten flag from OpenAPI options

package/docs/agent-skill.md

@@ -4,6 +4,12 @@ Standalone agent skill artifact for consumer projects using `@techspokes/typescr
 
 ## Purpose
 
+The skill is a light router to canonical product documentation. Its manual instructions cover input discovery, document selection and generated-file ownership; generation profiles, constructors, mappings, compatibility and transport rules remain in the core guides.
+
+Agents prefer the installed package's documentation, which matches the code they are using. The ZIP also includes generated extracts of canonical docs for its recorded release version, including [migration](migration.md#from-11x-to-120), composition, checked generation and streaming. Those extracts are versioned snapshots, not separately authored sources of product truth.
+
+Use a matching repository tag when the installed guide is unavailable, and use target-version docs deliberately during upgrades. Live `main` may contain unreleased behavior; a skill for a newer release must not establish capabilities of an older installed package. `references/SOURCE-MAP.json` records the snapshot's version, tag and source sections.
+
 Release assets include `typescript-wsdl-client-agent-skill-vX.Y.Z.zip` and `SHA256SUMS`. GitHub artifact provenance attests the ZIP, which contains an installable `typescript-wsdl-client/` skill folder for consumer projects.
 
 The skill is for consumer-project agents. It tells agents how to choose `wsdl-tsc` commands, handle generated output boundaries, load reference material, and validate generated code without treating generated files as hand-maintained source.
@@ -18,8 +24,11 @@ typescript-wsdl-client/
   references/
     architecture.md
     consumer-workflows.md
+    checked-generation.md
     cli-reference.md
+    composition.md
     generated-code.md
+    migration.md
     testing.md
     troubleshooting.md
     streaming.md
@@ -28,7 +37,7 @@ typescript-wsdl-client/
 
 ## Evergreen Content
 
-Evergreen content lives under `agent-skill/` and is reviewed as source code. Update evergreen files only when stable agent workflow, architecture guidance, dependency rules, or generated-output safety rules change.
+Evergreen content lives under `agent-skill/` and supplies stable routing and ownership instructions. Update product contracts in the canonical docs and select their sections through the reference manifest; do not copy those details into hand-maintained skill summaries.
 
 The evergreen files are `agent-skill/SKILL.md`, `agent-skill/install.mjs`, `agent-skill/evergreen/architecture.md`, and `agent-skill/evergreen/consumer-workflows.md`.
 

package/docs/api-reference.md

@@ -1,10 +1,12 @@
 # Programmatic API
 
-All CLI commands are available as TypeScript functions. This document covers each exported function, its usage, and its type signatures.
+This reference covers public generation, composition, stream and security APIs. Assessment and checked planning are separate diagnostic surfaces; see [checked generation](checked-generation.md#programmatic-planning-and-generation).
 
 See the main [README](../README.md) for installation, CLI usage, and project overview.
 
-All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Signatures and options are unchanged; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
+All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Adding a preamble does not change an API signature or option; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
+
+Generated-output compatibility is versioned separately from those preambles. Read the [1.1.x-to-1.2.0 migration guide](migration.md#from-11x-to-120) before regenerating existing clients or changing their selected profile.
 
 ## compileWsdlToProject
 
@@ -17,6 +19,8 @@ await compileWsdlToProject({
   wsdl: "./wsdl/Hotel.wsdl",
   outDir: "./src/services/hotel",
   options: {
+    wsdl: "./wsdl/Hotel.wsdl",
+    out: "./src/services/hotel",
     imports: "js",
     catalog: true,
     primitive: {
@@ -38,13 +42,13 @@ await compileWsdlToProject({
 declare function compileWsdlToProject(input: {
   wsdl: string;
   outDir: string;
-  options?: Partial<CompilerOptions>;
+  options?: CompilerOptions;
   streamConfigFile?: string;
   streamConfig?: StreamConfig;
 }): Promise<void>;
 ```
 
-`streamConfigFile` points at a JSON file parsed by `loadStreamConfigFile`. `streamConfig` accepts an already-parsed value; `streamConfigFile` takes precedence when both are set. Buffered generation is unchanged when both are omitted. See [Stream Configuration](configuration.md#stream-configuration) for the file format and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale.
+`streamConfigFile` points at raw JSON parsed by `loadStreamConfigFile`; `streamConfig` accepts normalized metadata from `parseStreamConfig`. The file takes precedence when both are set. Omitting both retains buffered API selection, without a byte-for-byte output guarantee across upgrades. See [Stream Configuration](configuration.md#stream-configuration).
 
 ### CompilerOptions
 
@@ -120,6 +124,7 @@ interface GenerateOpenAPIOptions {
   pathStyle?: "kebab" | "asis" | "lower";
   defaultMethod?: string;
   closedSchemas?: boolean;
+  flattenArrayWrappers?: boolean;
   pruneUnusedSchemas?: boolean;
   tagStyle?: "default" | "first" | "service";
   tagsFile?: string;
@@ -169,10 +174,17 @@ interface GenerateGatewayOptions {
   openapiDocument?: any;
   outDir: string;
   clientDir?: string;
-  versionSlug?: string;
-  serviceSlug?: string;
+  versionSlug: string;
+  serviceSlug: string;
   defaultResponseStatusCodes?: number[];
   imports?: "js" | "ts" | "bare";
+  clientClassName?: string;
+  clientDecoratorName?: string;
+  catalogFile?: string;
+  emitPlugin?: boolean;
+  emitRuntime?: boolean;
+  stubHandlers?: boolean;
+  flattenArrayWrappers?: boolean;
 }
 ```
 
@@ -231,8 +243,10 @@ await runGenerationPipeline({
 
 ```typescript
 declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
-  compiled: CompiledCatalog;
+  compiled: any;
   openapiDoc?: any;
+  checked?: CheckedInventory;
+  planning?: CheckedComponentPlan;
 }>;
 ```
 
@@ -240,8 +254,10 @@ declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
 
 ```typescript
 interface PipelineOptions {
+  model?: "legacy" | "checked-components-v1";
+  checkedComponents?: Partial<CheckedComponentOptions>;
   wsdl: string;
-  catalogOut: string;
+  catalogOut?: string;
   clientOutDir?: string;
   compiler?: Partial<CompilerOptions>;
   openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
@@ -249,7 +265,19 @@ interface PipelineOptions {
   };
   gateway?: Omit<GenerateGatewayOptions, "openapiFile" | "openapiDocument"> & {
     outDir?: string;
+    versionSlug: string;
+    serviceSlug: string;
+  };
+  app?: {
+    appDir: string;
+    openapiMode?: "copy" | "reference";
+    force?: boolean;
+    host?: string;
+    port?: number;
+    prefix?: string;
+    securityConfigFile?: string;
   };
+  test?: {testDir: string; force?: boolean; flattenArrayWrappers?: boolean};
   streamConfigFile?: string;
   streamConfig?: StreamConfig;
 }
@@ -257,6 +285,75 @@ interface PipelineOptions {
 
 `streamConfigFile` and `streamConfig` are threaded through the compile step and into every downstream emitter via `catalog.json`. Relative paths in `shapeCatalogs` resolve against the stream-config file's directory when `streamConfigFile` is used, otherwise against the WSDL's directory.
 
+Legacy calls require `catalogOut` at runtime. Checked component calls use `model: "checked-components-v1"` and optional `checkedComponents`; they return checked inventory/planning instead of a legacy catalog contract. See [the complete programmatic checked example](checked-generation.md#programmatic-planning-and-generation) for source policy and planning before generation. Checked RPC outputs remain opaque strings and buffered checked values; legacy stream configuration does not activate checked streaming.
+
+## runMultiServicePipeline
+
+Generate independent legacy clients and service routers, then publish one aggregate gateway plugin and combined OpenAPI JSON document. The [multi-service guide](gateway-guide.md#multi-service-setup) supplies a complete configuration with explicit, disjoint outputs:
+
+```typescript
+import {loadMultiServiceConfig, runMultiServicePipeline} from "@techspokes/typescript-wsdl-client";
+
+const options = await loadMultiServiceConfig("./services.json");
+const result = await runMultiServicePipeline(options);
+```
+
+```typescript
+interface MultiServiceEntry {
+  key: string;
+  generation: PipelineOptions;
+}
+
+interface MultiServicePipelineOptions {
+  services: readonly MultiServiceEntry[];
+  openapi: OpenApiCompositionOptions & {outFile: string};
+  gateway: {
+    outDir: string;
+    imports?: "js" | "ts" | "bare";
+    openapiPath?: string | false;
+  };
+}
+
+interface MultiServicePipelineResult {
+  openapiDoc: ComposedOpenApiDocument;
+  services: Record<string, {compiled: CompiledCatalog; clientDir: string; gatewayDir: string}>;
+  pluginFile: string;
+  openapiFile: string;
+}
+
+declare function runMultiServicePipeline(options: MultiServicePipelineOptions): Promise<MultiServicePipelineResult>;
+declare function loadMultiServiceConfig(file: string): Promise<MultiServicePipelineOptions>;
+```
+
+`loadMultiServiceConfig` resolves filesystem paths against the JSON configuration file; direct API callers supply paths relative to their process working directory. Every service needs `wsdl`, `catalogOut`, `clientOutDir`, `openapi.outFile`, `openapi.basePath`, `gateway.outDir`, `gateway.serviceSlug` and `gateway.versionSlug`. Service keys use unique lowercase letters, digits and hyphens, starting with a letter; gateway service slugs and decorators must remain unique after normalization.
+
+The API preserves each source's compiler and stream settings, generated client, catalog and SOAP dispatch. It refuses overlapping output ownership, duplicate final paths, lost operation routes, and unsupported app/test/checked settings. A failed later service can leave earlier service artifacts, while the previously published aggregate spec/plugin pair remains intact.
+
+The generated aggregate plugin exports `createClients`, `MultiServiceClientOptions`, `MultiServiceClients` and `openapi`. `createClients` requires exactly the service keys, each with its generated client's constructor options, including an explicit runtime `source`; register the plugin with `{clients}`. Prefixes come from each service's `openapi.basePath`, and the aggregate refuses runtime Fastify prefixes.
+
+## composeOpenApiDocuments
+
+Compose existing OpenAPI 3.1 documents without generating clients or routers:
+
+```typescript
+interface OpenApiCompositionEntry {key: string; document: unknown}
+interface OpenApiCompositionOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: readonly string[];
+}
+
+declare function composeOpenApiDocuments(
+  entries: readonly OpenApiCompositionEntry[],
+  options?: OpenApiCompositionOptions,
+): ComposedOpenApiDocument;
+```
+
+Components become `serviceKey__ComponentName`, while operation IDs and tags become `serviceKey.originalName`. The merger rewrites supported reference-bearing positions, link operation targets, discriminator targets and security scheme names, preserving service-local security and server semantics. It also qualifies the known `x-wsdl-tsc-stream.itemSchema` reference so clients can discover the stream record contract.
+
+Literal examples and unrelated extension payloads remain data. Duplicate paths, unresolved local references, relative external references and unsupported schema resource/anchor contexts are refused.
+
 ## Stream Configuration Helpers
 
 These exports back the `--stream-config` CLI flag and are also usable directly in programmatic flows.
@@ -415,4 +512,25 @@ const streamOp = compiled.operations.find((op) => op.stream);
 console.log(streamOp?.stream?.mediaType); // "application/x-ndjson" by default
 ```
 
-The generated client exports a `StreamOperationResponse<RecordType>` type; each stream-configured operation returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`.
+### Generated stream client contract
+
+Generated `operations.ts` exports `StreamOperationResponse<RecordType>` and `StreamCallOptions`; `client.ts` also re-exports `StreamCallOptions`. Each stream-configured operation accepts `(args, options?)` and returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`:
+
+```typescript
+interface StreamCallOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+interface StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> {
+  records: AsyncIterable<RecordType>;
+  headers: HeadersType;
+  requestRaw?: string;
+}
+```
+
+Records use the public legacy DTO mapping: flattened attributes, projected scalar values, typed simple content, XML lists and declared repeated-element arrays. Each record is mapped after its closing XML tag; the low-level parser still returns lexical values and attribute bags. Gateway wrapper flattening applies per record when enabled, and checked value shapes are unchanged.
+
+Only stream-enabled generated clients add constructor `streamRequestOptions?: IExOptions` from `soap`. These HTTP options are separate from WSDL loading and support a verified HTTPS agent, HTTP timeout and signal; `options.httpClient` must implement `requestStream`, or the standard node-soap HTTP client is used with `options.request`. Stream calls honor the current endpoint override, static headers and supported `ISecurity` hooks; see [transport support and refusals](gateway-guide.md#streaming-transport-settings).
+
+Per-call `timeoutMs` is a positive integer deadline for the upstream HTTP exchange and record consumption, starting after metadata initialization. A per-call signal already aborted rejects before metadata initialization. Exhaust or return the iterator to release transport resources; generated gateways connect downstream disconnects to that signal before waiting for SOAP headers and throughout delivery. Dates retain the existing type-level mapping, and `bigint` has no additional JSON encoding convention.

package/docs/checked-gateway.md

@@ -6,6 +6,8 @@ Generation offers legacy, the default, and opt-in checked components. Start with
 
 The additive `checked-components-v1` mode uses the same command family and native owners for qualified structured operations, imported schema snapshots, attributes, recursive records, simple content and ordered values. It preserves the shipped direct runtime and legacy defaults. Source, mapping, artifact and transport checks remain authoritative; unsupported schema or security features refuse rather than disappearing from a successful service claim. This is a qualified component fragment, not universal XSD, streaming or provider acceptance.
 
+The [bounded SOAP 1.1 RPC/encoded profile](supported-patterns.md#checked-soap-11-rpc-string-profile) adds source-owned scalar and flat Boolean record parts without document element roots. Component responses additionally accept exact Latin1 with encoding agreement. See the [NOAA qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) for native restrictions, opaque string/reference results and separate owned-server/live evidence limits.
+
 For a supported local WSDL or HTTP(S) root URL with one service/port/binding candidate, omit `--checked-config`. The planner selects all operations of that binding and derives supported mappings through the existing native owners. Local sources default to their containing directory; remote sources authorize their same-origin declared dependency graph. Canonical containment, redirect permission checks and native qualification still apply.
 
 ```bash

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.
+The 1.2.0 candidate offers opt-in WSDL-to-checked-gateway generation for supported document/literal SOAP 1.1 contracts and the bounded RPC/encoded string profile. Choose `pipeline --model checked-components-v1`; omitting `--model` keeps legacy 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
 
+Version 1.2.0 is a release candidate until published. During candidate verification, install the locally packed 1.2.0 tarball instead of requesting an unpublished registry version. Earlier published previews retain their historical 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.2.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, SOAP 1.2, general RPC encoding, 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.
 
 [#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) |