@techspokes/typescript-wsdl-client 1.1.5 → 1.1.8

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
@@ -232,7 +367,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.
+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.
 
 ### Envelope Naming
 

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`.
@@ -133,7 +137,7 @@ 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

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 | 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) |
+| [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
+```

package/docs/direct-values.md

@@ -1,10 +1,10 @@
 # Direct scalar values
 
-Internal direct mapping, bare-root XML codec and portable source contract. See the root [README](../README.md) and [matching contract](content-model-matching.md).
+Internal direct mapping, bare-root XML codec and portable source contract. See the root [README](../README.md) and [matching contract](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-matching.md).
 
 ## Package-root binding for generated direct clients
 
-The unreleased additive root export `checkedDirectRuntimeV1` runs an already generated checked direct client through the existing native source, capsule, schema/scalar, XML and buffered SOAP engines. Package metadata remains 1.1.4; published 1.x packages do not thereby gain structured generation support. Generation remains internal, and existing CLI commands and legacy defaults are unchanged.
+The root export `checkedDirectRuntimeV1` preserves the v1.1.5 execution contract for existing generated direct clients through the native source, capsule, schema/scalar, XML and buffered SOAP engines. The [checked gateway workflow](checked-gateway.md) exposes legacy and component generation; the unpublished intermediate direct-generation choice has been removed. Frozen v1.1.5-issued client and capsule fixtures verify compatibility against the installed candidate runtime. Historical P3 sections below record earlier internal milestones, not another current public generation entry.
 
 Use a matched generated client, capsule and explicitly authorized original local WSDL. The caller supplies its actual owned server endpoint; a WSDL service address never authorizes dispatch.
 
@@ -50,7 +50,7 @@ Failures retain `unsupported`, `missing-authority`, `incompatible-artifact`, `in
 
 ### Restricted supported grammar
 
-This entry supports one safe UTF-8 local WSDL resource and SOAP 1.1 document/literal over explicitly authorized owned IPv4 loopback HTTP. Values are built-in string/int32/Boolean scalar roots, empty sequences or flat sequences of distinct scalar elements with minOccurs 0/1 and maxOccurs 1/unbounded, including declared faults. Source loading and native qualification retain the [direct correspondence restrictions](decisions/003-content-model-contracts.md#qualified-dated-xsd-direct-route).
+This entry supports one safe UTF-8 local WSDL resource and SOAP 1.1 document/literal over explicitly authorized owned IPv4 loopback HTTP. Values are built-in string/int32/Boolean scalar roots, empty sequences or flat sequences of distinct scalar elements with minOccurs 0/1 and maxOccurs 1/unbounded, including declared faults. Source loading and native qualification retain the [direct correspondence restrictions](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/003-content-model-contracts.md#qualified-dated-xsd-direct-route).
 
 Nested complex/group content, attributes, nil, facets, import/include graphs and general XSD completeness are outside this slice. Dependency-reserved names such as `__proto__`, `constructor`, `toString`, inherited Object.prototype names and `prototype` refuse safely. Remote source loading, production endpoints, TLS/auth/WS-Security, arbitrary headers, SOAP 1.2, redirects, attachments, compression and streaming remain unsupported. `admitted:false` remains unchanged.
 
@@ -186,7 +186,7 @@ P3.4 under [#384](https://github.com/TechSpokes/typescript-wsdl-client/issues/38
 
 `encodeDirectXml(contract, mapping, freshValue, options?)` calls `expandDirectValue` before emitting deterministic UTF-8 bytes. It returns `direct-encoded` with caller-owned mutable `bytes`, the authentic `expanded` receipt, encoding and usage. The byte array is data, never authority; changing it cannot change the validated expansion or authenticate another payload.
 
-`decodeDirectXml(contract, mapping, bytes, options?)` accepts a non-shared `Uint8Array` or Buffer, copies its native byte slots without length/buffer/iterator getters, parses ordered observed syntax, then calls `matchDirectOperation` and `assessDirectScalars`. It returns `direct-decoded` with immutable observed `payload`, authentic `validated` receipt and usage. Both APIs are internal exports from [directCodec.ts](../src/compiler/directCodec.ts), absent from the package public API.
+`decodeDirectXml(contract, mapping, bytes, options?)` accepts a non-shared `Uint8Array` or Buffer, copies its native byte slots without length/buffer/iterator getters, parses ordered observed syntax, then calls `matchDirectOperation` and `assessDirectScalars`. It returns `direct-decoded` with immutable observed `payload`, authentic `validated` receipt and usage. Both APIs are internal exports from [directCodec.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/compiler/directCodec.ts), absent from the package public API.
 
 Identity checks precede property/version interpretation. Foreign/copied/JSON/wrong-version handles throw TypeError; genuine future incompatible metadata returns unsupported. Direction and exact root come from the mapping, with no guessed catalog upgrade or source reload. SOAP 1.1 document/literal binding/action remain source metadata and authorize no I/O.
 
@@ -200,7 +200,7 @@ Prefixes are allocated by first source-order use of expanded namespaces, then bo
 
 ### Secure byte boundary and provenance
 
-The codec reuses [orderedSyntax.ts](../src/loader/orderedSyntax.ts) with namespace-aware `saxes` 6.0.0, strict fatal decoding and XML 1.0-only mode. Saxes is an in-memory tokenizer with no resolver or external I/O; DTD declarations are refused, predefined/numeric references are processed, and unknown/general/external entities fail. Schema locations, namespace URIs and xml:base are never fetched; unsupported application attributes, nil and xsi:type fail through the existing matcher.
+The codec reuses [orderedSyntax.ts](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/loader/orderedSyntax.ts) with namespace-aware `saxes` 6.0.0, strict fatal decoding and XML 1.0-only mode. Saxes is an in-memory tokenizer with no resolver or external I/O; DTD declarations are refused, predefined/numeric references are processed, and unknown/general/external entities fail. Schema locations, namespace URIs and xml:base are never fetched; unsupported application attributes, nil and xsi:type fail through the existing matcher.
 
 UTF-8 with optional BOM and BOM-qualified UTF-16LE/BE are supported. XML declaration encoding must agree with the bytes; unsupported encodings, doubled BOMs, isolated surrogates, malformed Unicode, namespace errors, multiple roots and truncated syntax fail without repair. XML 1.1 is unsupported. BOM-less UTF-16 is refused. EOF completion precedes any successful decoded result.
 
@@ -238,15 +238,15 @@ console.log(decoded.validated.value);
 
 ### Qualification and remaining boundary
 
-[Codec controls](../test/unit/direct-codec.test.ts) run the actual Forecast request/response/ForecastError fixture payload bytes against independent expectations, fresh-byte laws, renamed/form/prefix sources, scalar/empty roots, all counts, reserved names, Unicode/CR/escaping, encoding/security failures, authenticity, cancellation and inclusive limits. [Nonauthor controls](../test/unit/direct-codec-independent.test.ts) independently exercise BOM/URN repairs, native byte access, chunk boundaries and observed provenance. These are bare-root tests; their test-only SOAP extraction is not a production envelope parser.
+[Codec controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-codec.test.ts) run the actual Forecast request/response/ForecastError fixture payload bytes against independent expectations, fresh-byte laws, renamed/form/prefix sources, scalar/empty roots, all counts, reserved names, Unicode/CR/escaping, encoding/security failures, authenticity, cancellation and inclusive limits. [Nonauthor controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-codec-independent.test.ts) independently exercise BOM/URN repairs, native byte access, chunk boundaries and observed provenance. These are bare-root tests; their test-only SOAP extraction is not a production envelope parser.
 
-Exact P3.4 review, local/hosted checks and merged-main identities belong to #384 and [roadmap #379](https://github.com/TechSpokes/typescript-wsdl-client/issues/379). The separately scoped P3.5 adapter under #388 now consumes this codec for an internal buffered SOAP 1.1 unauthenticated loopback exchange; its [transport contract and qualifications](content-model-soap-feasibility.md#p35-original-byte-qualification) cover source-byte bootstrap, original response bytes, envelopes, declared Faults and request lifetime. Broad portable bundles, public structured generation, security combinations and activation remain separate work.
+Exact P3.4 review, local/hosted checks and merged-main identities belong to #384 and [roadmap #379](https://github.com/TechSpokes/typescript-wsdl-client/issues/379). The separately scoped P3.5 adapter under #388 now consumes this codec for an internal buffered SOAP 1.1 unauthenticated loopback exchange; its [transport contract and qualifications](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-soap-feasibility.md#p35-original-byte-qualification) cover source-byte bootstrap, original response bytes, envelopes, declared Faults and request lifetime. Broad portable bundles, public structured generation, security combinations and activation remain separate work.
 
 The internal decoder accepts a protocol payload selector over the single parsed observed document. Its selected mapping is authenticated against the same operation, and the payload must be an actual descendant by object identity. It reuses structural/scalar checks without subtree reserialization, preserving the complete original document digest, actual coordinates and inherited namespace bindings on the selected response or fault detail. A synthetic tree cannot acquire observed provenance through this seam.
 
 ## P3.6 internal portable source capsule
 
-[The private capsule module](../src/compiler/directSourceCapsule.ts) consumes authentic operations and existing native mappings. It adds no package export, public CLI, generated client or admission; package 1.1.4 and legacy defaults remain unchanged. This narrow capsule is not the full ADR bundle format or completion of #185/#186.
+[The private capsule module](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/compiler/directSourceCapsule.ts) consumes authentic operations and existing native mappings. It adds no package export, public CLI, generated client or admission; package 1.1.4 and legacy defaults remain unchanged. This narrow capsule is not the full ADR bundle format or completion of #185/#186.
 
 ### Source authority and reconstruction
 
@@ -274,7 +274,7 @@ Reconstruction starts one fresh request-specific inclusive sticky budget for art
 
 Byte/depth/node limits, cancellation, schema inconclusive, incompatible artifacts, unsupported scope and missing authority remain separate failures. These are engineering work/allocation reservations with cooperative checkpoints, not a hard heap limit or preemptive execution guarantee.
 
-[Installed qualification](../test/integration/portable-installed.test.ts) packs and installs the npm tarball in a separate temporary directory and process. The copied test-only TypeScript harness verifies physical private `dist` imports, denies checkout filesystem reads with Node permissions, blocks implicit fetches, requalifies an authorized copy, relocates it and issues fresh mappings and deterministic XML. Private-module testing establishes no supported package subpath; package exports remain root-only.
+[Installed qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/portable-installed.test.ts) packs and installs the npm tarball in a separate temporary directory and process. The copied test-only TypeScript harness verifies physical private `dist` imports, denies checkout filesystem reads with Node permissions, blocks implicit fetches, requalifies an authorized copy, relocates it and issues fresh mappings and deterministic XML. Private-module testing establishes no supported package subpath; package exports remain root-only.
 
 ### Next consumer boundary
 
@@ -282,11 +282,11 @@ The P3.6 handoff to P3.7 under #195/#201 is implemented by the internal consumer
 
 ## P3.7 internal generated TypeScript consumer
 
-[The native-plan generator](../src/client/generateDirectClient.ts) accepts an identity-issued reconstructed source, authenticates compatibility and each mapping, and emits one deterministic strict NodeNext TypeScript file plus its exact capsule. It uses the shared preamble composer with a dedicated internal-artifact preamble. There is no public command or package export for this generator.
+[The native-plan generator](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/client/generateDirectClient.ts) accepts an identity-issued reconstructed source, authenticates compatibility and each mapping, and emits one deterministic strict NodeNext TypeScript file plus its exact capsule. It uses the shared preamble composer with a dedicated internal-artifact preamble. There is no public command or package export for this generator.
 
 ### Typed internal binding
 
-The generated file has no imports. `createClient(runtime)` receives a trusted internal binding with one `execute` method; the generated operation has the exact source operation spelling as a computed quoted key. [The binding owner](../src/client/directClientRuntime.ts) delegates exclusively to the existing capsule, mapping and buffered SOAP owners. The test harness loads this binding by verified physical installed private-module path; that mechanism is not a supported package subpath or plugin interface.
+The generated file has no imports. `createClient(runtime)` receives a trusted internal binding with one `execute` method; the generated operation has the exact source operation spelling as a computed quoted key. [The binding owner](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/src/client/directClientRuntime.ts) delegates exclusively to the existing capsule, mapping and buffered SOAP owners. The test harness loads this binding by verified physical installed private-module path; that mechanism is not a supported package subpath or plugin interface.
 
 The generated capsule literal pins the static contract. Each invocation requires matching loaded capsule bytes, an explicitly authorized physical local source and file roots, and explicit SOAP service, port, endpoint and endpoint authorization. The binding copies options before asynchronous work, refuses accessors/proxies and unsupported options, creates one fresh budget, reconstructs native authority from the authorized file, checks native compatibility and calls `exchangeDirectSoap`. No handle, endpoint permission, budget or source authorization is cached between independent calls.
 
@@ -306,6 +306,6 @@ Emission bounds variable source contributions against a 512 KiB output ceiling b
 
 Native semantic accounting spans qualification and validation without resetting; routine byte copying, base64 comparison, serialization and publication use actual input/output caps. Separate calls get separate budgets; exhausted calls return no partial usable value. Normal calls no longer inherit the old source/capsule/XML test caps or semantic work allowance; cooperative cancellation and any explicit application-selected limits remain available. This is engineering accounting, not a hard heap or preemption guarantee; malformed own-key vector allocation has the same intrinsic qualification as the existing adapter.
 
-[Installed tests](../test/integration/generated-direct-installed.test.ts) generate bounded files for Forecast, renamed and prefix-aliased sources, optional/nonempty-array shapes, scalar and empty roots. They install the actual npm tarball in another directory, compile independently authored valid/invalid TypeScript and execute the emitted wrappers in a child with checkout reads denied. The harness permits only its consumer directory for file reads/writes and verifies real SOAP request namespace/order/scalars, response arrays and HTTP 200/500 declared faults, relocation, stale/mixed inputs, missing permissions, unsupported capabilities, cancellation and exhaustion. Node 24's permission model does not restrict sockets; endpoint restriction remains the native owned-loopback policy. Node versions exposing network permissions additionally receive the explicit loopback grant.
+[Installed tests](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/generated-direct-installed.test.ts) generate bounded files for Forecast, renamed and prefix-aliased sources, optional/nonempty-array shapes, scalar and empty roots. They install the actual npm tarball in another directory, compile independently authored valid/invalid TypeScript and execute the emitted wrappers in a child with checkout reads denied. The harness permits only its consumer directory for file reads/writes and verifies real SOAP request namespace/order/scalars, response arrays and HTTP 200/500 declared faults, relocation, stale/mixed inputs, missing permissions, unsupported capabilities, cancellation and exhaustion. Node 24's permission model does not restrict sockets; endpoint restriction remains the native owned-loopback policy. Node versions exposing network permissions additionally receive the explicit loopback grant.
 
-[Independent controls](../test/unit/generated-direct-independent.test.ts) challenge getters/proxies, mutable option metadata, copied authority, sticky exhausted generation and preserved dependency-name refusals. Hosted Linux and Windows Node24/26 run the generated installed qualification explicitly. Public-interface readiness and any remaining blockers belong to a separate P3.8 task; public activation, legacy defaults, package 1.1.4, root-only exports and `admitted:false` remain unchanged.
+[Independent controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/generated-direct-independent.test.ts) challenge getters/proxies, mutable option metadata, copied authority, sticky exhausted generation and preserved dependency-name refusals. Hosted Linux and Windows Node24/26 run the generated installed qualification explicitly. Public-interface readiness and any remaining blockers belong to a separate P3.8 task; public activation, legacy defaults, package 1.1.4, root-only exports and `admitted:false` remain unchanged.

package/docs/examples/checked-forecast.wsdl

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:t="urn:checked:forecast" targetNamespace="urn:checked:forecast">
+  <wsdl:types>
+    <xs:schema targetNamespace="urn:checked:forecast" elementFormDefault="qualified">
+      <xs:complexType name="ForecastRequest"><xs:sequence><xs:element name="city" type="xs:string"/><xs:element name="days" type="xs:int"/></xs:sequence></xs:complexType>
+      <xs:complexType name="ForecastResponse"><xs:sequence><xs:element name="city" type="xs:string"/><xs:element name="temperature" type="xs:int" minOccurs="0" maxOccurs="unbounded"/><xs:element name="complete" type="xs:boolean"/></xs:sequence></xs:complexType>
+      <xs:complexType name="ForecastFault"><xs:sequence><xs:element name="code" type="xs:string"/><xs:element name="message" type="xs:string"/></xs:sequence></xs:complexType>
+      <xs:element name="GetForecast" type="t:ForecastRequest"/>
+      <xs:element name="GetForecastResponse" type="t:ForecastResponse"/>
+      <xs:element name="ForecastFault" type="t:ForecastFault"/>
+    </xs:schema>
+  </wsdl:types>
+  <wsdl:message name="ForecastInput"><wsdl:part name="parameters" element="t:GetForecast"/></wsdl:message>
+  <wsdl:message name="ForecastOutput"><wsdl:part name="parameters" element="t:GetForecastResponse"/></wsdl:message>
+  <wsdl:message name="ForecastError"><wsdl:part name="detail" element="t:ForecastFault"/></wsdl:message>
+  <wsdl:portType name="ForecastPortType"><wsdl:operation name="GetForecast"><wsdl:input message="t:ForecastInput"/><wsdl:output message="t:ForecastOutput"/><wsdl:fault name="ForecastError" message="t:ForecastError"/></wsdl:operation></wsdl:portType>
+  <wsdl:binding name="ForecastBinding" type="t:ForecastPortType"><soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/><wsdl:operation name="GetForecast"><soap:operation soapAction="urn:checked:GetForecast"/><wsdl:input><soap:body use="literal"/></wsdl:input><wsdl:output><soap:body use="literal"/></wsdl:output><wsdl:fault name="ForecastError"><soap:fault name="ForecastError" use="literal"/></wsdl:fault></wsdl:operation></wsdl:binding>
+  <wsdl:service name="ForecastService"><wsdl:port name="ForecastPort" binding="t:ForecastBinding"><soap:address location="http://127.0.0.1:1/forecast"/></wsdl:port></wsdl:service>
+</wsdl:definitions>

package/docs/gateway-guide.md

@@ -281,7 +281,7 @@ await app.register(async (scope) => {
 await app.listen({ port: 3000 });
 ```
 
-See [`examples/fastify-gateway`](../examples/fastify-gateway/README.md) for a complete example.
+See [`examples/fastify-gateway`](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/examples/fastify-gateway/README.md) for a complete example.
 
 ## Contract Assumptions
 

package/docs/generated-code.md

@@ -4,6 +4,10 @@ Guide to using the TypeScript SOAP clients and types generated by wsdl-tsc.
 
 See [README](../README.md) for quick start and [Concepts](concepts.md) for type modeling details.
 
+## Installed package definitions
+
+The generator package ships TypeScript declarations for its public ESM API. Definition lookup resolves to those packaged `.d.ts` files; original implementation source and declaration maps are not shipped for public API source navigation. Installed package smoke checks this definition resolution using the consumer's TypeScript language service; editor-specific UI behavior is not asserted.
+
 ## Generated Preambles and ESLint
 
 Every newly written TypeScript client, gateway, app, and generated-test file starts with `/* eslint-disable */`. This includes conditional streaming/security helpers, stub routes, and gateway typecheck fixtures. CLI and programmatic generation use the same defaults with no new flags or required arguments.
@@ -162,7 +166,7 @@ Because `records` is single-pass, each response can be iterated once. Headers ca
 
 Streaming requires the `saxes` runtime dependency. The generated app scaffold pins `saxes ^6.0.0` automatically; consumers that integrate the generated client into their own project must install it explicitly.
 
-See [Stream Configuration](configuration.md#stream-configuration) for how to opt specific operations in, and [ADR-002](decisions/002-streamable-responses.md) for the rationale and terminal-error policy.
+See [Stream Configuration](configuration.md#stream-configuration) for how to opt specific operations in, and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the rationale and terminal-error policy.
 
 ## Attributes and Text Content
 
@@ -293,10 +297,11 @@ import type { WeatherOperations } from "./client/operations.js";
 
 const mock: WeatherOperations = {
   GetCityWeatherByZIP: async (args) => ({
-    response: { GetCityWeatherByZIPResult: { Success: true } },
+    response: { GetCityWeatherByZIPResult: { Success: true, WeatherID: 0 } },
     headers: {},
   }),
-  // ...other operations
+  GetCityForecastByZIP: async () => ({ response: {}, headers: {} }),
+  GetWeatherInformation: async () => ({ response: {}, headers: {} }),
 };
 ```
 
@@ -306,6 +311,6 @@ The gateway plugin accepts any `WeatherOperations` implementation, so you can pa
 app.register(weatherGateway, { client: mock });
 ```
 
-For stream operations, mock implementations return an async-iterable `records` field. See the [Testing Guide](testing.md) for the full pattern with async generators.
+For stream operations, mock implementations return an async-iterable `records` field. See [generated test mocks](testing.md#mock-client) for the full pattern with async generators.
 
-See [Testing Guide](testing.md) for full integration test patterns.
+See [consumer testing guidance](testing.md#for-consumer-projects) for setup, legacy and checked test commands, ownership and verification limits.

package/docs/mapping-contract.md

@@ -0,0 +1,114 @@
+# Checked XML/JSON Mapping Contract
+
+Source-derived JSON representation for checked generation. See the root [README](../README.md) and [checked gateway guide](checked-gateway.md) for supported scope and configuration.
+
+The checked gateway guide defines executed support. Selected future forms are labeled below; describing a JSON shape does not enable a missing source or runtime capability.
+
+## Selected keyed mapping contract
+
+Names are JSON keys. Derive identity facts from the exact source mapping whenever a slot uniquely identifies them, including qualified attributes inside a fallback channel. Known records/scalars/arrays and reconstructible application groups remain ordinary values; source occurrence bounds choose arrays for compact slots, while each ordered entry is exactly one element occurrence. JSON property insertion order never controls source-fixed XML order. Existing scalar encodings, lexical witnesses and native duties remain authoritative.
+
+Keyed child entries keep familiar field names, text objects make every ordered entry an object without a kind discriminator, direct URI holders handle actual identity choices, and scoped binding deltas avoid repeated full maps. Attribute entries preserve same-name/different-namespace identities without inventing a key-escaping syntax. Existing supported projections do not acquire redundant descriptors; the repository's [exploratory comparison](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/v1.0-xml-json-mapping.md#bounded-primary-source-comparison) records the alternative forms considered.
+
+### Content and recursion
+
+New mixed/open `$content` is an ordered array of objects. Each object has exactly one own property: either `$value` with a text string, or an ordinary child-name key whose value follows that child's selected mapping. No metadata siblings are allowed on an outer entry. Preserve significant spaces; coalesce adjacent text entries and remove zero-length text entries. Do not collapse repeated occurrences across intervening text. An XSD list scalar array is distinct from element repetitions.
+
+```xml
+<p xmlns="urn:msg" id="7">Hello <b>world</b>!</p>
+```
+
+```json
+{"id":"7","$content":[{"$value":"Hello "},{"b":"world"},{"$value":"!"}]}
+```
+
+Here the source declares b as string. A mixed structured b instead has its own `$content`, even when one instance is text-only. Source identity/assessment selects the grammar, not object appearance. Metadata around a scalar encoding v uses a holder with `$value:v`, including object/array scalar encodings; never merge scalar fields into element metadata. A record keeps its own fields. An ordered holder cannot also expose peer child/group fields or a scalar `$value`; source-mapped attributes may accompany it.
+
+### Namespaces have separate owners
+
+`$namespace` is the actual element/attribute/type namespace URI at this location. It does not declare a prefix, set a default binding or cause descendants to inherit element identity. Derive it when the exact source mapping fixes identity; otherwise supply it explicitly, including an empty URI for a no-namespace unknown element. Each child key is its XML name without the prefix unless an established source mapping defines an application alias.
+
+```json
+{"$content":[{"code":{"$namespace":"urn:vendor","$value":"A"}},{"code":{"$namespace":"urn:billing","$value":"B"}}]}
+```
+
+`$namespaces` contains prefix bindings introduced/rebound on this node. Descendants inherit an immutable effective context and apply their local changes; parents and siblings stay unchanged. The first source-defined retained-context boundary captures otherwise unavailable effective bindings; subsequent nodes retain only deltas. A source-known intermediate node retains a delta when a descendant needs it. Prefix keys are data: `""` denotes the default binding and xml is implicit. Default reset uses `{"":""}`; XML Namespaces 1.0 does not permit deleting nonempty prefixes. Redundant deltas normalize away; apparently unused bindings in unassessed data are not pruned.
+
+Element identity and default binding can differ: `<e:extra xmlns:e="urn:open" xmlns="urn:values">Thing</e:extra>` identifies the element in urn:open while a typed QName Thing resolves in urn:values. A child rebinding p changes its applicable lexical scope, not its element URI. Plain unassessed `p:Thing` remains a string; neither object appearance nor a colon grants QName semantics.
+
+For assessed data without retained context, the codec can allocate compatible prefixes from actual identities. It must preserve protected effective contexts for unassessed lexical data and lexical witnesses. Reject combinations that cannot coexist in XML, including a no-namespace element retaining a nonempty default or a namespaced attribute lacking an available nonempty prefix in a protected scope. JSON shape alone does not establish these codec duties. Fresh reconstruction uses complete JSON, source mapping and inherited context; arbitrary extracted-subtree portability is not promised.
+
+### Attribute channel
+
+Existing unambiguous source-mapped peer attributes retain their shape. When a source mapping requires the new fallback, `$attributes` is an array of one-name entries, not an array of generic name/value descriptors. At a uniquely mapped key, a bare scalar derives its complete identity from that source slot, including a qualified namespace; redundant identity holders are rejected.
+
+A closed source with one qualified code attribute and one code child can therefore use `{"$attributes":[{"code":"attribute"}],"code":"child"}`. For an open/unresolved key without a unique mapped identity, a bare scalar denotes an unqualified attribute and a qualified identity uses `{$namespace:nonemptyURI,$value:scalar}`. Empty-URI holders are rejected in that open grammar rather than being a second spelling.
+
+A source key whose permitted identities remain ambiguous requires the explicit namespace selection needed to distinguish them; its generated mapping/schema declares that domain. Unknown attributes retain lexical strings; typed values use their selected scalar encodings. The bag never infers attribute identity from the default element namespace.
+
+```json
+{"$attributes":[{"id":"attribute"},{"id":{"$namespace":"urn:vendor","$value":"external"}}],"id":"child"}
+```
+
+The container preserves two attributes with the same name from different namespaces without inventing escaping rules or aliases. Source-owned slot attribution determines whether an identity is already fixed; object appearance does not override that attribution. Attribute order is not semantic; canonical output sorts by expanded identity. Duplicate expanded attributes, duplicate peer/bag identities, undeclared attributes and invalid values fail. A selected type uses one placement consistently across nil/non-nil instances. No attribute holder owns children, `$nil` or `$type`.
+
+### Open values, type and nil
+
+Genuinely unassessed elements always use ordered holders, including empty/text-only instances, with their required identity and retained context. They do not become guessed scalar types. Native assessment applies independently to each location: strict/lax/skip cannot be selected by a JSON flag. Raw unassessed xsi:nil/xsi:type stay lexical attributes in the XSI namespace, not semantic `$nil`/`$type`. Missing declarations are not repaired by an open representation.
+
+The selected research shape for a future assessed dynamic type is the flat XML identity `{$type:{$name:"Dog",$namespace:"urn:animals"}}`. Assessed dynamic `$type` execution and its `$name` identity field remain unsupported by the generated checked pipeline; this shape is not an accepted capability switch. A child entry already has its name as its key, and no `$localName`, `$kind`, `$text` or `$element` alias is allocated.
+
+Display type/schema aliases do not rename an XML type. Any future implementation must establish native existence, derivation and attribute duties before admitting the selected research shape.
+
+The explicit nil contract below remains authoritative. Identity/type/context metadata can accompany nil only when that exact source mapping declares the necessary combination and implements its native duties; it is not admitted by the nil marker alone. Nil forbids every text/child/group content field, even empty content. Neither semantic xsi processing nor QName scalar assessment is guessed from familiar names.
+
+### Compatibility, HTTP shape and implementation proof
+
+New grammar selection is per exact source declaration/type/assessment mapping. Legacy, accepted component scalar/record/array/simple/ordered values and checkedDirectRuntimeV1 remain unchanged. A reused already-accepted ordered descendant inside a new mixed parent retains its old entry grammar in both directions; the implementation dispatches through its existing mapping. Unifying those old public shapes requires a separate migration decision, not a new mode introduced here.
+
+HTTP schemas describe actual JSON fields and source-selected recursive alternatives, with closed one-property entries, text string slots, namespace strings, flat type identity and nil/attribute/content exclusions. Named structured choice alternatives reference their union, or an array of it for repetition. Use oneOf only where JSON alternatives are disjoint. Native owners enforce names, bindings, particles/correlation, scalar/default/fixed/type/nil duties and SOAP construction. Serialization must independently preserve every accepted field. Reject unknown metadata and invalid combinations without mutation, coercion, default insertion or field removal; legal __proto__/constructor names remain safe own data properties.
+
+The [keyed prototype](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-mapping.ts) and [independent examples](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-mapping.test.ts) reuse the earlier parser/syntax inverse and its fixture-specific source facts. They exercise mixed/nested text, order and namespace collisions, scopes/defaults/siblings, attribute collisions, raw xsi values, safe names, flat type and explicit nil, with malformed-input and realizability controls. The [qualified attribute fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-attributes.xsd) supplies a closed same-name attribute/child case whose qualified attribute identity is independently checked through native source attribute assessment; unassessed data with the same root name must retain its open grammar.
+
+The [HTTP structure sketches](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/keyed-schema.test.ts) execute recursive JSON Schema examples and rejection/non-mutation cases. They are not a generic source-to-DTO generator or production native validation; existing native projection/scalar controls and nil examples remain separate evidence. The old public candidate grammar is historical; its fixture-specific conversion helpers remain dependencies of the research adapter, not an independent new inverse.
+
+The [checked nil implementation](checked-gateway.md#nil-values) and [keyed execution](checked-gateway.md#mixed-namespaced-and-open-values) supply the supported nil/mixed/open slices and preserve them through HTTP. Scalar/context validation and HTTP-shape generation retain their separate native duties. Application groups and configured aliases are described below and in the checked gateway guide.
+
+## Selected nil contract
+
+Checked nil values use one explicit object, preserving attributes and the distinction between absent, empty and nil elements. This contract does not change legacy, accepted non-nil component values or `checkedDirectRuntimeV1`; the [checked nil reference](checked-gateway.md#nil-values) records supported configuration and limits.
+
+| Case | JSON rule |
+|---|---|
+| Absent optional element | Omit its property; omission is not nil |
+| Present nil without attributes | `{"$nil":true}` |
+| Present nil with attributes | `{"$nil":true,"id":"7"}` for an applicable mapped string attribute `id` |
+| Empty non-nil | Retain the ordinary source-selected value, such as `""`, `{"$value":""}` or an empty permitted record |
+| Nil repeated item | Put the explicit nil object at that item's position in the declared array |
+| Nil wrapper | Put the explicit nil object at the wrapper element's property; it contains no items |
+
+Both accepted input and canonical output use the explicit object; plain `null` is rejected, including as an array item. `$nil` is exactly Boolean `true`, never false, a string or a caller-selected assessment policy. XML `xsi:nil="true"` and `"1"` project to this same marker after native lexical assessment. XML false/zero uses the ordinary non-nil projection with no `$nil`; reconstruction of nil uses a permitted canonical true lexical form. Property order does not control XML order.
+
+The only newly allocated nil metadata is `$nil`. Additional fields are exactly the applicable attribute properties already defined by the selected source mapping, using their existing scalar encodings and identities. Required attributes remain required on nil elements; optional/default/fixed attributes follow the shared native assessment and adopted augmentation rules, not Ajv defaults. Empty string attributes are data and remain subject to their type. Do not invent a new nil attribute bag or rename existing scalar descriptors. Contextual attribute families, attribute collisions/wildcards and dynamic types require their actual native owners and an explicit compatible shape before emission; the nil marker alone does not establish those capabilities or silently narrow #421's acceptance.
+
+Nil objects prohibit all element/text/group content fields, including `$value`, `$content`, synthetic choice containers and ordinary child properties, even when their supplied values are empty or null. Reject unknown metadata, undeclared/invalid attributes, sparse/malformed arrays and object/array substitutions without mutation or silent field removal. `$type` and `$namespaces` are not implicitly accepted by this nil contract. A later independently selected contextual/type contract must explicitly describe its combination with nil; callers cannot enable it with extra keys.
+
+Each object's XML element identity comes from its selected declaration/position; `$nil` never emits an XML child. Nillability, nil/content legality, attribute use and applicable fixed/default/scalar duties remain native checks, at the actual item or wrapper element. Genuinely unassessed lexical xsi attributes are not promoted to semantic nil by familiar spelling. No checked failure may fall back to legacy conversion, and no missing native duty may be hidden by weakening validation.
+
+For the example with optional string attribute `id`, TypeScript is `{ $nil: true; id?: string }`. Its HTTP schema is concrete:
+
+```json
+{"type":"object","required":["$nil"],"additionalProperties":false,"properties":{"$nil":{"const":true},"id":{"type":"string"}}}
+```
+
+Include `id` in `required` where the source requires it. Compose this nil schema with the ordinary non-nil schema for a nillable element, with exactly-one composition only when the JSON alternatives are disjoint. Optionality belongs to the containing property and item versus wrapper nillability belongs to the corresponding element position. Every accepted attribute must survive response serialization; HTTP structure validation does not replace native XML checks. No discriminator, response envelope or new runtime mode is introduced.
+
+The [explicit nil contract examples](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/tests/xml-json-mapping/nil-contract.test.ts) exercise independent hand JSON, true/one XML lexicals, attribute-preserving fresh syntax reconstruction, canonical explicit output, absent/empty/item/wrapper distinctions and malformed combinations. They reuse the existing parser and research inverse for a fixture with string `id`; they do not implement native nillability, complete attribute semantics or generated HTTP/SOAP execution. The old null-based tests remain historical candidate evidence, not accepted aliases.
+
+The implementation consumes this contract through existing source planning, projection/inverse, codec and HTTP-shape generation, preserving shared resource and error boundaries. Its [codec controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/direct-projection-nil.test.ts) and [installed gateway checks](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/helpers/checkedGatewayInstalledProcess.ts) supply independent request/response/fault, serialized HTTP and owned-SOAP evidence, including non-nillable/content-bearing refusals and attribute/default/fixed duties.
+
+## Application groups
+
+Checked generation implements opt-in source-derived application groups and definition-scoped configured names. [Configuration and compatibility](checked-gateway.md#application-groups-and-configured-names), [the production fixture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/conformance/fixtures/assessment/application-groups.wsdl), [native inverse controls](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/unit/application-groups.test.ts) and [pipeline/reload evidence](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/test/integration/checked-application-groups.test.ts) provide regression evidence; installed HTTP/SOAP checks cover both defaults and configured aliases. Wider native source, dynamic-type and protocol duties retain their documented limits.
+
+Reconstructible singleton/repeated/nested choices, repeated sequences, independent sites, cross-record named-group reuse and finite recursive references share the source-owned mapping. Empty-capable and ambiguous records retain ordered normalization; mixed/open records keep their selected owner. Inventory tokens include a selected-record shape guard and survive physical relocation, unrelated declaration reorder and alias changes; relevant source edits require copying fresh targets.

package/docs/migration-playbook.md

@@ -89,7 +89,7 @@ npx wsdl-tsc pipeline \
   --init-app
 ```
 
-The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Set `format: "json-array"` for `application/json` array streaming. Operations not listed in the config are unchanged. See [Stream Configuration](configuration.md#stream-configuration) for the full file reference and [ADR-002](decisions/002-streamable-responses.md) for the terminal-error policy.
+The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Set `format: "json-array"` for `application/json` array streaming. Operations not listed in the config are unchanged. See [Stream Configuration](configuration.md#stream-configuration) for the full file reference and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for the terminal-error policy.
 
 ## Step 3: Generate the REST Gateway
 

package/docs/output-anatomy.md

@@ -49,7 +49,7 @@ Contains runtime metadata and helper functions. Includes `unwrapArrayWrappers()`
 
 ### Stream Operations
 
-When `--stream-config` opts an operation into streaming (see [ADR-002](decisions/002-streamable-responses.md)), the client emits additional surfaces alongside the buffered ones. Buffered operations in the same client are unaffected.
+When `--stream-config` opts an operation into streaming (see [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md)), the client emits additional surfaces alongside the buffered ones. Buffered operations in the same client are unaffected.
 
 `operations.ts` gains a `StreamOperationResponse<RecordType>` type that stream methods return instead of the buffered `{ response, headers, responseRaw, requestRaw }` shape:
 

package/docs/start-here.md

@@ -64,6 +64,12 @@ The gateway transforms JSON HTTP requests into SOAP calls and returns JSON respo
 
 Next: [Gateway Guide](gateway-guide.md) for integration details, then [Migration Playbook](migration-playbook.md) for the full modernization workflow
 
+### I want to try source-backed checked generation
+
+From version 1.1.6, `pipeline --model checked-components-v1` opts into the checked component preview. It derives unambiguous selections and supported structured mappings from a WSDL file or URL, acquires declared dependencies, and emits a client, OpenAPI, gateway, app and tests. The existing pipeline remains the default when `--model` is omitted.
+
+Start with [Try Opt-in Checked Generation](checked-generation.md) for a bundled installed trial, endpoint configuration, missing-schema recovery and feedback instructions. Supported contracts get native request/response/fault checks; unsupported capabilities refuse rather than bypassing validation. This preview is buffered and separate from the legacy streaming workflow below.
+
 ### I need to stream large SOAP responses
 
 Some SOAP services return payloads that are too large or too slow to buffer in memory. Opt selected operations into streaming with a small JSON config and the `--stream-config` flag. Operations not listed keep their buffered behavior, so existing output stays byte-for-byte unchanged.
@@ -96,7 +102,7 @@ Stream operations return `StreamOperationResponse<RecordType>` on the client (`r
 
 Set `"format": "json-array"` in the stream config when downstream clients need one `application/json` array document instead of NDJSON lines.
 
-Next: [ADR-002: Streamable Responses](decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
+Next: [ADR-002: Streamable Responses](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
 
 ### I want an AI agent to help in my project
 
@@ -120,5 +126,5 @@ For more on scope boundaries, see the "When NOT to Use This" section of the [REA
 | Plan a full SOAP-to-REST migration | [Migration Playbook](migration-playbook.md) |
 | Set up testing for generated code | [Testing Guide](testing.md) |
 | Review all CLI flags | [CLI Reference](cli-reference.md) |
-| Opt specific operations into response streaming | [ADR-002](decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
+| Opt specific operations into response streaming | [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
 | Install package-specific agent guidance | [Agent Skill Artifact](agent-skill.md) |