@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/docs/checked-generation.md

@@ -0,0 +1,167 @@
+# Try opt-in checked generation
+
+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.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
+```
+
+The bundled [Forecast contract](examples/checked-forecast.wsdl) is synthetic and has no running SOAP backend. Generation selects its one unambiguous service/port/binding and `GetForecast` operation without a configuration file. Its placeholder SOAP address must be replaced with your owned test backend before invoking the operation.
+
+The generated project includes `client/inventory.json`, copied WSDL/XSD sources and provenance, operation clients/contracts, OpenAPI, gateway routes, server configuration and scaffold tests. The planning report lists readiness and blockers; the inventory records discovered, selected and generated operations. Generation does not mean an operation was executed.
+
+## Check and start the generated project
+
+Run from the generated app directory below. Its package supplies test/typecheck dependencies and scripts; scaffold tests check health, selected OpenAPI and invalid-input refusal without upstream SOAP dispatch. See [consumer testing guidance](testing.md#for-consumer-projects) for emitted configuration, customization protection and independent verification boundaries.
+
+```powershell
+Set-Location .generated/forecast
+npm install
+npm run typecheck
+npm test
+npm run build
+npm start
+```
+
+Generation, installation, startup and scaffold tests do not execute business SOAP operations. Startup loads generated bookkeeping, verifies its owned snapshot digests and checks gateway/OpenAPI identity. Native source qualification and source/contract compatibility run independently when an operation is invoked; a healthy server alone does not prove SOAP readiness. In a second terminal, inspect the running gateway:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:3000/health
+Invoke-RestMethod http://127.0.0.1:3000/openapi.json
+```
+
+Stop the foreground server with Ctrl+C when finished. The npm and generation commands also work in POSIX shells. No runtime configuration file is required for ordinary startup.
+
+## Try your WSDL file or URL
+
+Run from the trial directory, using a fresh output directory for a different contract. Replace the source with your local WSDL or an HTTP(S) metadata URL you are permitted to access:
+
+```powershell
+npx wsdl-tsc pipeline --model checked-components-v1 --wsdl-source https://provider.example/service.wsdl --client-dir .generated/service/client --openapi-file .generated/service/openapi.json --gateway-dir .generated/service/gateway --gateway-version-prefix v1 --gateway-service-name service --init-app --app-dir .generated/service --test-dir .generated/service/test --checked-report .generated/service-plan.json --checked-draft service-resolution.json
+```
+
+The loader follows declared WSDL imports and XSD imports/includes recursively, including authorized redirects. Same-origin dependencies require no authored resource map or selectors. For local input, the containing directory is the default permitted root; authorize outside-root files explicitly through `fileRoots` in `--checked-config`.
+
+For a declared dependency on another origin, save a reusable project configuration such as `intake.json` and add `--checked-config intake.json` to the command:
+
+```json
+{
+  "sourceOrigins": ["https://schemas.example"]
+}
+```
+
+During URL acquisition, nonempty `sourceOrigins` adds those exact origins to the root origin. Explicit `sourceOrigins: []` denies all HTTP metadata. An explicit `sourceResources` set is closed, including an empty set, so omit it for ordinary automatic acquisition. HTTP 401/403 are metadata-access failures; the preview does not supply a credential broker.
+
+Generated configuration points runtime calls at copied physical snapshots. Keep the generated source/provenance/configuration files together when moving the project; runtime does not download metadata. Rerunning generation from a URL reacquires its sources.
+
+## Resolve a missing schema or ambiguous selection
+
+Read the planning report before editing anything. Unsupported source, mapping, binding or security cases refuse with a stage and reason; a refusal does not necessarily mean the vendor schema is invalid.
+
+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 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.
+
+The Weather quick-start fixture has multiple ports even though it has one service. Set `service`, `port` and `selectors` in a JSON file supplied through `--checked-config`; the diagnostic lists actual service/port choices and the report lists operation candidates. Legacy mode is a separate generation path with its own support limits, not an automatic fallback after a checked refusal.
+
+## Configure and invoke an owned SOAP backend
+
+The component gateway normally uses the selected WSDL service/port address when a route is invoked. To use an owned test service, create `checked-gateway.local.json` with this complete concise override:
+
+```json
+{
+  "endpoint": "http://127.0.0.1:8081/forecast"
+}
+```
+
+An optional `allowedEndpoints` list narrows the permitted destinations; omitting it permits the selected/configured endpoint, and `[]` denies every call.
+
+Select the optional file and start in PowerShell:
+
+```powershell
+$env:CHECKED_GATEWAY_CONFIG = 'checked-gateway.local.json'
+npm start
+```
+
+In a POSIX shell, use `CHECKED_GATEWAY_CONFIG=checked-gateway.local.json npm start`. Optional `host`, `port` and `caFile` are separate caller choices. Generated `client/source-resources.json` owns source and capsule records; do not copy them into this file.
+
+Restart the gateway after changing runtime configuration. Only after an owned SOAP backend implements the bundled Forecast contract, invoke its JSON route:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:3000/v1/forecast/GetForecast -Method Post -ContentType 'application/json' -Body '{"city":"Paris","days":2}'
+```
+
+This POST executes a real SOAP operation. Supply independently chosen expected values and fault cases for your own service; WSDL and generated scaffold tests cannot establish business correctness. Component responses retain their checked JSON value/fault shapes, while legacy envelopes, raw client fields and streaming behavior remain unchanged.
+
+TLS verification stays enabled. The optional `caFile` supplies a trusted CA; it does not disable verification. SOAP redirects remain disabled, and unsupported authentication or WS-Security requirements refuse. Check the [transport limits](checked-gateway.md#explicit-component-configuration) before trying a provider integration.
+
+## Programmatic planning and generation
+
+The package-root API uses the same loader and native preparation as the CLI:
+
+```typescript
+import {planCheckedComponents, runGenerationPipeline} from '@techspokes/typescript-wsdl-client';
+
+const source = './service.wsdl';
+const report = await planCheckedComponents(source);
+console.log(report.ready, report.blockers);
+await runGenerationPipeline({
+  model: 'checked-components-v1', wsdl: source,
+  clientOutDir: '.generated/service/client',
+  openapi: {outFile: '.generated/service/openapi.json'},
+  gateway: {outDir: '.generated/service/gateway', versionSlug: 'v1', serviceSlug: 'service'},
+  app: {appDir: '.generated/service'}, test: {testDir: '.generated/service/test'},
+});
+```
+
+Partial choices and permissions go in `checkedComponents` for generation or the second argument to `planCheckedComponents`. Planning never invokes SOAP. Generation performs fresh checks even when an earlier planning report was ready.
+
+The older `assessSchemaSource` API and `assess` command retain the narrow `checked-assessment-v1` direct-schema scope and exit codes. They do not assess component generation or provider readiness. Use the component planner and `--checked-report` for this workflow; saved reports are diagnostic data.
+
+## Supported scope and direction
+
+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.
+
+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.
+
+## Send useful feedback
+
+Use [Issues](https://github.com/TechSpokes/typescript-wsdl-client/issues/new/choose) for reproducible defects and [Discussions](https://github.com/TechSpokes/typescript-wsdl-client/discussions) for questions or integration reports. Mention `checked-components-v1` in the title and include:
+
+- Package version, Node version and operating system.
+- The exact generation command, model and relevant configuration choices.
+- WSDL/dependency sources you have permission to share, or a minimal reproducer.
+- The affected service, port, binding and operation, plus the planning blocker or inventory entry.
+- Expected and actual generated types, JSON, SOAP values or refusal behavior.
+- Whether you tested generation, scaffold/startup checks, owned wire execution or provider business acceptance.
+
+Remove credentials and private data from configurations, source URLs, reports and payloads before posting. Include a known expected request/response or fault when reporting wire behavior. Report an unsupported capability as such rather than requesting that typed validation be disabled; this helps prioritize the smallest useful expansion without losing existing guarantees.
+
+## Upgrade and regenerate
+
+Regenerate checked clients, contracts, copied sources, gateways and server scaffolds together with the matching installed runtime. The generated source record now uses the explicit `checked-source-resources-v2` format; it is separate from the component runtime protocol. Complete older runtime configurations remain supported as advanced inputs. Supplying `localSource`, `sourceUri`, `namespaceLocations`, `recordSources` or `capsuleFiles` selects that advanced form and requires all four source fields: `localSource`, `fileRoots`, `sourceResources` and `sourceOrigins`.
+
+With generated defaults, omitted restrictions retain the generated choices; explicit `sourceOrigins: []`, `sourceResources: []`, `standardLibraries: []` and `allowedEndpoints: []` remain restrictive. Incomplete advanced configurations refuse instead of mixing incompatible sources with generated defaults. Runtime paths in the optional JSON file resolve relative to that file; programmatic paths remain caller-owned.
+
+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. 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,9 @@
 # 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.
 
 Generation paths are explicit. Examples use the git-ignored `.generated/` directory for disposable consumer output, while this repository reserves `tmp/` for its own test and release automation.
@@ -22,8 +26,38 @@ TypeScript outputs automatically receive [generated preambles](generated-code.md
 
 ## pipeline
 
+The `--model` selector defaults to `legacy`. `checked-components-v1` derives unambiguous service/port/binding selections and supported mappings from local WSDL or HTTP(S) input. Optional `--checked-config` supplies actual choices or permissions. The catalog/compiler/streaming tables below describe legacy behavior unless stated otherwise.
+
+### Checked generation flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--model checked-components-v1` | Opt into qualified structured component generation |
+| `--checked-config` | JSON path for partial component choices and permissions |
+| `--checked-report` | JSON output path for a component planning report on readiness or refusal |
+| `--checked-draft` | JSON output path for an available component missing-schema recovery draft |
+| `--force-checked-files` | Deliberately replace requested component report/draft files |
+
+Checked planning refusals print a concise reason, construct/location and next action and exit nonzero. Their JSON reports remain available through `--checked-report`; set `DEBUG=wsdl-tsc` to include the raw error, stack and report details. Ambiguous selections use `service`, `port` and `selectors` in `--checked-config`, rather than separate service/port flags.
+
+Component URL intake follows declared same-origin dependencies automatically. Extra origins need a reusable `sourceOrigins` decision in the checked configuration. Generated snapshots supply offline runtime bookkeeping; optional host/endpoint/trust overrides belong to the runtime configuration. The [trial guide](checked-generation.md) shows complete commands and explains the unchanged direct-runtime compatibility binding.
+
+Checked modes require all three explicit outputs: `--client-dir`, `--openapi-file` and `--gateway-dir`, plus `--gateway-service-name` and `--gateway-version-prefix`. For a runnable checked app, supply `--init-app` and an explicit `--app-dir` containing those outputs; scaffold tests use `--test-dir` with app generation. The legacy one-output minimum below does not apply to checked generation.
+
 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
@@ -36,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.
 
@@ -131,6 +165,8 @@ When `--init-app` is used and `--openapi-servers` is not provided, servers defau
 
 ### Test Suite Flags
 
+Legacy tests need consumer test/runtime dependencies and use their emitted Vitest config. Checked tests require app generation and use the checked app's scripts; see [consumer testing guidance](testing.md#for-consumer-projects) for complete setup/run examples and coverage limits. Existing scaffold files are preserved unless their force option is selected.
+
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--test-dir` | (none) | Generate Vitest test suite in this directory (requires client, gateway) |
@@ -140,7 +176,9 @@ When `--init-app` is used and `--openapi-servers` is not provided, servers defau
 
 | 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.
 
@@ -259,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`.
@@ -338,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:
 
@@ -445,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`
@@ -565,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 |
@@ -639,7 +681,7 @@ cat ./debug/catalog.json | jq '.operations'
 
 ## assess
 
-Inspect source schema evidence without generating artifacts or dispatching SOAP. The [assurance contract](decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) defines the native scope and qualified correspondence route.
+Inspect source schema evidence without generating artifacts or dispatching SOAP. The [assurance contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) defines the native scope and qualified correspondence route.
 
 ```bash
 npx wsdl-tsc assess --wsdl-source examples/minimal/weather.wsdl --report .generated/assessment.json

package/docs/concepts.md

@@ -29,6 +29,141 @@ interface Price {
 }
 ```
 
+## Mapping terminology and naming
+
+Use one term for one concept across source analysis, internal code, generated types, application JSON, OpenAPI descriptions and documentation. Different concepts must not share a convenient label merely because their current representations look alike. This section owns the conceptual vocabulary; the reserved-key inventory below owns mapping-property spellings and their implementation status.
+
+| Term | Meaning |
+|---|---|
+| Element | An XML element declaration or instance, distinguished explicitly by context |
+| Attribute | An XML attribute; its identity and rules are distinct from a child element |
+| Sequence | A source constraint requiring its members in order |
+| Choice | A source constraint permitting alternatives |
+| Alternative | One permitted member of a choice; it can itself contain several fields |
+| All group | The XSD `all` compositor, with its own rules; not a synonym for sequence |
+| Application group | A generated object keeping related values and constraints together; it need not be an XML wrapper |
+| Occurrence bounds | The allowed minimum and maximum repetitions of the particular source particle |
+| Content | An element's ordered text and child elements; attributes are separate |
+| Value | Data assessed under the selected type; use text, scalar value or structured value when specificity matters |
+| Projection | The mapping between source-defined XML values and application values |
+| Expanded name | Namespace URI plus local name, independently of the chosen prefix |
+| Namespace binding | A prefix-to-namespace association in the applicable scope |
+| Nil | Explicit absence of content on a present element, distinct from a missing element or empty non-nil value |
+
+A choice is a rule, an alternative is a permitted branch, and a selection is an instance's use of a branch. They are not interchangeable glossary terms. The research now uses `$choice` for a choice site; source occurrence bounds determine whether its value is one object or an array, just as they do for other items.
+
+Keep the canonical word stem when deriving related names: normal TypeScript casing for internal identifiers and type names, and `$` plus lower camel case for mapper-owned application properties. Source-derived XML data names and established profile mappings retain their declared spellings. The bounded allocator below names opt-in checked groups without renaming ordinary business fields.
+
+Private source-graph and configuration objects do not need `$` prefixes merely to follow the payload namespace rule, but their names and descriptions must use the same concepts. Standards-owned names such as XSD `minOccurs`, existing graph `occurs`, and JSON Schema `oneOf` have explicit semantic mappings rather than mechanical renames. Choose `oneOf`, `anyOf` or other schema operators for their actual validation meaning, not because their names resemble a source term.
+
+An OpenAPI property must use the exact JSON key accepted by the mapper, validator and serializer; titles and descriptions must explain that same concept. Schema definition and TypeScript type names derive deterministically from the source identity and role, with collision handling; human-readable names alone are not component identity.
+
+Reuse a shared name constant or source-owned mapping description where code and schemas need the same key. Keep independently authored test inputs literal so they can expose drift instead of reproducing the implementation's mistake. When terminology or a key changes, update its inventory entry, code, schemas, examples, errors and tests together; record any compatibility handling explicitly rather than silently accepting a synonym.
+
+This convention does not create another architecture layer, public mode or mandatory vocabulary migration. Existing mismatches remain visible review work, not templates for introducing more synonyms. File and directory names continue to follow [file naming and path organization](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/file-naming-and-path-organization.md).
+
+### Choice groups and named alternatives
+
+Enable checked groups with `applicationGroups: {}` in the existing checked generation configuration. Each record uses reconstructible structured groups or retains its existing ordered presentation, with its disposition/reason in `inventory.json`. Absence of this option preserves existing checked shapes and generated artifacts.
+
+Use `$choice`, `$choice2` and subsequent numbers for independent choice sites in one containing application object, in retained source order. Repeated sequences use `$sequence`, `$sequence2` and subsequent numbers. Repeating a site uses one array without pluralizing its key or item type; JSON property order never controls XML order.
+
+| Source bounds | Application value | Schema |
+|---|---|---|
+| `1..1` | One alternative object | Required property referencing the choice union |
+| `0..1` | Omitted or one alternative object | Optional property referencing the choice union |
+| `1..3` | Array, including for one occurrence | Required array with `minItems: 1`, `maxItems: 3` |
+| `0..unbounded` | Optional array | Array with no finite maximum |
+
+Optional repeated groups with nonempty bodies accept an empty array and canonically omit that property without mutating input. Required minima and finite maxima retain source bounds. Empty-capable bodies and ambiguous partitions retain ordered values and ADR-003 normalization; optional occurrence bounds alone do not make a body empty-capable.
+
+Every structured alternative has a named object schema and TypeScript type, including singleton choices. For a source type `Request`, defaults are union `RequestChoice` and objects `RequestChoiceAlternative1` and `RequestChoiceAlternative2`. A repeated sequence references its named item object; recursive types remain finite references rather than unrolled combinations.
+
+A single property references the union directly; an array references the same union in `items`, and TypeScript uses `RequestChoice[]`. Sharing application schema structure does not merge the distinct native source declarations used for reconstruction.
+
+Default type stems use the owning named type's local name, or the anonymous type's containing element and scoped path digest, followed by `Choice` or `Sequence`. Nonalphanumeric source characters use injective `_u<hex>_` escaping; anonymous stems use `___Anonymous_<digest>`. Nested generated roles use `___` boundaries, which cannot occur in escaped source stems, and contribute once; alternatives append `Alternative1`, `Alternative2` and subsequent numbers in source order.
+
+Several source type namespaces with the same local name receive a namespace digest suffix.
+
+Retain complete business names ending in `Choice`, `Choices` or `Sequence`; source type `PaymentChoice` therefore produces `PaymentChoiceChoice`. Default collisions append an underscore and the first twelve hexadecimal digits of the source-target digest. Ordinary fields and unrelated distinct declarations keep their names; explicit names never receive silent collision suffixes.
+
+Several occurrences of one choice site use one array. Several independent choice sites need distinct reserved properties and distinct contextual schemas; merging them into one array would lose their separate rules. The source identity and structural position distinguish such sites even when the alternatives have identical field names; display names do not establish identity.
+
+### Configured application names
+
+The optional `applicationGroups.names` array configures the synthetic property, union/item type and structured alternative names independently. Generate with `applicationGroups: {}`, copy opaque tokens from `inventory.json` under `applicationGroups.targets`, and regenerate with entries containing `target`, optional `propertyName` and optional `typeName`. The same data works in `--checked-config` and `PipelineOptions.checkedComponents`; no additional command or flag is needed.
+
+| Naming target | Prototype default | Example configured name |
+|---|---|---|
+| Synthetic group property | `$choice` | `$payment` |
+| Union type and schema | `RequestChoice` | `PaymentMethod` |
+| First alternative type and schema | `RequestChoiceAlternative1` | `CardPayment` |
+| Second alternative type and schema | `RequestChoiceAlternative2` | `BankPayment` |
+
+Such names change presentation, not the source definition: `$payment` can reference `PaymentMethod` or `PaymentMethod[]`, and the union references `CardPayment` and `BankPayment`. Group bounds, required fields, alternative membership, source XML names/namespaces and native validation remain governed by the same selected source contract. Renaming an alternative's schema does not add a discriminator or an XML wrapper.
+
+Target overrides by exact scoped source identity and structural role, including the choice site and alternative, rather than only by a generated display name, field spelling or an occurrence in one value. Source order provides the prototype's alternative numbers but is not by itself a stable configuration selector across source revisions. Provide discoverable source selectors; unknown or ambiguous targets fail rather than silently doing nothing, and an alias never becomes another selector for an alias chain.
+
+Resolve default and configured names before emission and use that one mapping for TypeScript declarations, OpenAPI components and references, JSON validation, adapters, serializers, diagnostics and examples. A synthetic property keeps the `$` prefix after renaming; type/schema aliases must be valid for their generated targets. Reject conflicting aliases in the relevant property/type/schema scopes, including collisions with other configured names, source-derived names and reserved mapping keys; do not silently overwrite or suffix an explicitly requested name.
+
+A configured alias selects the emitted/accepted name for that generated contract, not additional runtime synonyms. For example, a contract configured with `$payment` does not also accept `$choice` by default. Changing published keys or type names needs an explicit compatibility disposition and regenerated matching artifacts; runtime callers cannot submit naming configuration or change the native source binding through the payload.
+
+Choice and sequence targets accept either override; alternative targets accept only `typeName`. Properties must be `$` followed by a lower-camel ASCII identifier and cannot use reserved metadata keys; type names must be non-reserved ASCII TypeScript identifiers that are unchanged valid OpenAPI component keys. Unknown fields, duplicate targets, stale targets, accessors, proxies, malformed arrays and scoped collisions fail before artifact emission.
+
+Tokens are `ag1:` plus a SHA-256 digest of scoped owning/source/use-site identities, structural role and a guard of the selected record's effective particle shape. They are independent of physical snapshot paths, unrelated global declaration order, display names and aliases. A relevant particle edit invalidates old tokens; regenerate defaults and copy new tokens rather than migrating by position.
+
+Names are definition-scoped within the selected service, including recursive references and reuse across request, response and fault directions. Named-group uses in different owning records remain distinct targets. Inventory is diagnostic data only; capsules persist the selected options and reconstruction rederives them against authenticated authorized sources, while mismatched generated artifacts refuse.
+
+## Reserved mapping keys
+
+Keys introduced by the mapper into XML-derived application objects must start with `$`. XML element and attribute names remain source-derived data keys; generated grouping objects, text slots and interpretation metadata must not occupy that same unprefixed namespace. The XML name grammar excludes `$`, so an actual XML child `choice` and the synthetic `$choice` container remain distinct.
+
+This convention applies recursively to synthetic mapping properties, including metadata descriptors if retained. It does not rename private TypeScript variables, source graph fields, artifact/configuration schemas or actual XML data keys. Entries inside data dictionaries, such as prefixes in `$namespaces` and XML names in an attribute bag, are data rather than additional synthetic property names.
+
+### Mapping-key inventory and status
+
+The inventory distinguishes existing behavior from the [selected mapping contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/mapping-contract.md#selected-keyed-mapping-contract). [Checked mixed/namespace/open mappings](checked-gateway.md#mixed-namespaced-and-open-values) implement the qualified keyed slice, and opt-in application groups implement the bounded reconstructible grammar above. Research-only dynamic-type forms remain handoffs rather than production capability claims.
+
+| Key | Meaning and scope | Status |
+|---|---|---|
+| `$value` | Scalar text/simple content alongside attributes; exact scalar policy belongs to the selected mapping | Existing legacy/component convention |
+| `$attributes` | Attribute channel; named entries derive unique source identities, otherwise distinguish unqualified scalars and namespaced holders | Existing legacy bags unchanged; qualified checked keyed fallback |
+| `$content` | Ordered content; new entries are text objects or one named child occurrence | Existing ordered shapes unchanged; qualified checked keyed mixed/open grammar |
+| `$choice`, `$choice2`, ... | Complete source choice; object or array from source bounds | Opt-in checked application groups |
+| `$sequence`, `$sequence2`, ... | Source sequence item; array for repeated groups | Opt-in checked application groups |
+| `$nil` | Explicit assessed nil marker, exactly `true`, alongside applicable source-mapped attributes | [Checked component nil values](checked-gateway.md#nil-values); no null shorthand |
+| `$namespace` | Actual namespace URI of the element/attribute/type identity at this location | Qualified checked element/attribute metadata; type execution remains separate |
+| `$namespaces` | Prefix bindings introduced/rebound here, inherited by descendants | Qualified checked snapshot-at-boundary plus local-delta contract |
+| `$type` | Explicit assessed type identity with flat `$name`/`$namespace` strings | Selected research shape; native type checks remain required |
+| `$name` | XML type name string within `$type` | Selected research shape; never a nested name object or child-name duplicate |
+
+Configured group aliases allocate only their selected `$` property spelling. `$selection` and `$selections` were superseded research spellings; `$choices` is not a plural alias. `$text` and `$element` occur in comparison alternatives only and are not additional accepted spellings.
+
+### Existing unprefixed descriptors requiring a deliberate correction
+
+Existing checked ordered entries contain `name` and `value`, with `namespace` and `local` inside their identity descriptor. Those describe the mapping rather than XML business properties; their existing implementation is recorded compatibility work, not justification for using unprefixed metadata in new mappings.
+
+| Existing descriptor property | Prefixed spelling if that descriptor is retained | Disposition |
+|---|---|---|
+| `name` | Named child entry key | New keyed entries remove the descriptor wrapper |
+| `value` | `$value` | Reuse the existing reserved word where its role is explicitly defined |
+| `namespace` | `$namespace` where needed | URI supplied only when source mapping cannot determine identity |
+| `local` | Named entry key, or `$name` inside `$type` | No `$localName` alias is allocated |
+
+This table describes the new research grammar, not aliases accepted by existing runtimes. Current accepted component/QName shapes and the shipped direct-runtime protocol retain their contracts, including reused descendants inside new mappings. A migration requires an explicit compatibility decision and fresh inverse/serializer tests. Ordinary XML properties actually named `name`, `value`, `namespace` or `local` remain ordinary data keys.
+
+### Transport, schema and implementation namespaces
+
+| Name | Actual role | Application-mapping disposition |
+|---|---|---|
+| `$xml`, `_xml` | Dependency-owned SOAP/XML serialization hooks | Not generic fields accepted by the application mapping |
+| `attributes`, `$` | Existing configurable/dependency attribute containers and aliases | Existing adapter behavior, not new canonical metadata keys |
+| `$schema`, `$id`, `$ref` | JSON Schema dialect/identity/reference keywords | Schema documents, not XML-derived payload properties |
+| `$raw/...`, `/$hypothetical/...`, `$semantic-content/...`, `$semantic-builtin-anyType/...` | Internal source/candidate reference paths and generated component paths | Path strings, not public JSON mapping keys |
+| `$env`, `$_` | Shell/documentation syntax encountered during the inventory | Not mapping keys |
+
+A `$` prefix identifies a reserved namespace, not permission to submit arbitrary metadata. The selected mapping and HTTP schema must declare every accepted key, reject unknown/conflicting metadata without mutation, preserve accepted fields during serialization, and consume synthetic groups without inventing XML wrapper elements. Legacy configurable attribute-key overrides remain their existing separate contract.
+
 ## Primitive Mapping
 
 All XSD numeric and date-time types map to `string` by default. This prevents
@@ -177,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
 
@@ -232,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](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
 
@@ -362,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

@@ -4,6 +4,10 @@ Optional JSON configuration files for customizing OpenAPI generation. Pass these
 
 See [CLI Reference](cli-reference.md) for flag details and [README](../README.md) for quick start.
 
+## Planned application naming overrides
+
+Choice-group property names, union type/schema names and individual alternative type/schema names must support developer-configured aliases in the planned application mapping. The [configured application names contract](concepts.md#configured-application-names) defines the naming targets, reserved `$` prefix, source identity, collision and consistency requirements. This is a design requirement under #420; no corresponding configuration fields or CLI options are implemented yet.
+
 ## Security Configuration
 
 Pass via `--openapi-security-config-file`.
@@ -98,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
 {
@@ -133,10 +136,18 @@ operations not listed in the file.
 - Structural name collisions across catalogs fail the build; structurally
   identical types dedupe silently.
 
-See [ADR-002](decisions/002-streamable-responses.md) for rationale and the
+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

@@ -0,0 +1,33 @@
+# Product Corpus Evidence
+
+Representative inputs and their maintained product checks. See the root [README](../README.md) and [Supported Patterns](supported-patterns.md) for the separate legacy and checked support boundaries.
+
+## Evidence index
+
+This table is generated from `test/conformance/readiness-corpus.json`; its source identity and permission records are checked by the readiness inventory tests. A row indexes executable evidence, not a percentage of WSDL/XSD support or a claim of live provider acceptance.
+
+| 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 | 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) |
+
+## Run the corpus
+
+```bash
+npm run test:corpus
+```
+
+The command selects the existing tests once and delegates installed-package checks to their existing script. Refused rows prove their named failure and dispatch boundary; they do not count as successfully generated services.
+
+Installed variant evidence uses independently checked source-derived variants where named; it does not assert an unchanged production-provider contract. Private service evidence remains separate and is not required by this public corpus command.
+
+## Maintain the index
+
+Add rights-cleared inputs and independent expected exchanges to the existing conformance framework. Preserve supported behavior, invalid-input checks, compatibility and security requirements alongside corpus growth.
+
+```bash
+npm run docs:corpus
+npm run docs:corpus:check
+```