@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

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) |

package/docs/supported-patterns.md

@@ -2,13 +2,23 @@
 
 This document lists the WSDL and XSD features handled by the generator, along with current limitations. For modeling details, see [Core Concepts](concepts.md).
 
+The matrix describes the existing legacy generator. The unreleased opt-in [checked gateway preview](checked-gateway.md) has a separate, narrower source/value/binding contract and installed HTTP/SOAP evidence; these legacy rows do not imply checked-model support. Synthetic preview success establishes no real-provider or general-XSD coverage.
+
+The qualified checked domain includes [keyed mixed, namespace-collision and source-permitted open values](checked-gateway.md#mixed-namespaced-and-open-values), with production conformance and installed request/response/fault evidence. Native strict/lax/skip checks remain distinct from schema-source wildcard checks and from the legacy rows below.
+
 ## Capability Evidence Matrix
 
 The rows below are backed by committed conformance fixtures under `test/conformance/fixtures/`. Status means the current product contract, not the full standards surface.
 
+The [S06 research handoff](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/research/docs/content-model-s06-research-handoff.md) records separate attribute, derivation, wildcard and calendar evidence.
+Candidate interpretations and test-only prototypes do not certify production assessment or change these public capability rows.
+
 <!-- support-matrix:start -->
 | Capability ID | Status | Public contract |
 |---|---|---|
+| `declared-derivation-boundaries` | research | Legacy compilation characterizes omitted groups, appended restriction content and named recursive references; faithful resolution/composition remain internal. |
+| `content-model-boundaries` | research | Characterization records current projection limits; it does not claim faithful content-model support. |
+| `content-model-invalid-all` | research | Legacy compiler acceptance is characterized separately from independent schema rejection. |
 | `sequence-occurrence-wrappers` | supported | Wrapping sequences with nonzero maxima propagate element bounds and optionality without crossing choice or all boundaries. |
 | `weather-document-literal-soap` | supported | The canonical weather WSDL compiles through client, OpenAPI, gateway, generated-test, and app artifacts with document-literal SOAP operations. |
 | `sequence-baseline-complex` | supported | Complex type sequences support nested complex references, repeated elements, optional fields, and all-optional request wrappers. |
@@ -37,11 +47,10 @@ Wrapping sequence bounds propagate through uninterrupted sequence ancestry to el
 
 Generated clients normalize present, non-null singleton responses into arrays for repeated element properties. Real SOAP transport regressions cover singleton and multiple items, omitted optional request fields, and gateway serialization with wrapper flattening enabled and disabled. Regenerate clients to receive this runtime correction; omitted optional response properties remain absent.
 
-- Complex types with `<xs:sequence>`, `<xs:all>`, and `<xs:choice>` compositors, including recursive nesting
+- Complex types with nested `<xs:sequence>`, `<xs:all>`, and `<xs:choice>` compositors, subject to the projection limits above
 - Simple content with attributes using the `$value` pattern to preserve text content alongside attribute properties
 - Named simple type restrictions and enumerations emitted as TypeScript aliases and OpenAPI scalar schemas
 - Named `xs:union` simple types emitted as TypeScript alias unions and OpenAPI `oneOf` schemas
-- Type inheritance through `<xs:extension>` and `<xs:restriction>` on both simple and complex content
 - Nested XSD imports across multiple schema files with relative and absolute URI resolution
 - Multiple namespaces with deterministic collision resolution via PascalCase uniqueness
 - `<xs:choice>` elements modeled as parallel optional alternatives by default
@@ -49,7 +58,6 @@ Generated clients normalize present, non-null singleton responses into arrays fo
 - Optional and nillable fields using `minOccurs`, `maxOccurs`, and `nillable` attributes
 - `ArrayOf*` wrapper types with automatic unwrapping in OpenAPI and runtime bridging in gateway code
 - WSDL/XSD documentation annotations propagated into TypeScript JSDoc comments and OpenAPI descriptions
-- Circular type references detected and broken with minimal stub types
 - Multiple WSDL ports and bindings; the first SOAP binding is selected, all ports are documented in service metadata
 - SOAP 1.1 and SOAP 1.2 binding detection
 - Streamable SOAP responses, opt-in per operation via `--stream-config` (ADR-002): client exposes `AsyncIterable<RecordType>`, gateway emits NDJSON or JSON array streams with backpressure, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
@@ -98,7 +106,11 @@ The compiler scans inline policies for UsernameToken, TransportBinding, and X509
 
 ### xs:group and xs:attributeGroup
 
-Groups are inlined into the parent type during schema compilation. The group identity is not preserved as a separate named type in the output, but all elements and attributes from the group appear correctly in the containing type.
+The `declared-derivation-boundaries` fixture characterizes the legacy default: its named group elements and attribute-group uses are omitted from the containing compiled type. General group support is therefore unqualified. Internal [reference resolution](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-resolution.md) preserves complete group definitions and separate use-site bounds; [companion reuse](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-companions.md) carries their required closures. These internal results do not establish public generation support.
+
+### Extension and restriction
+
+The same executable fixture distinguishes current legacy behavior: extension appends local properties, but restriction also appends them and empty restriction retains base content. A prohibited optional attribute remains in legacy metadata. Faithful restriction, attribute composition and immutable sibling behavior are covered by internal [derivation tests](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-composition.md), with full legality assessment assigned to #179. Public faithful derivation support remains unqualified.
 
 ### xs:list
 
@@ -127,7 +139,7 @@ Gateway generation measures the `$ref` graph depth for each operation response.
 
 ### Circular references
 
-Recursive type references are detected during compilation and broken with a minimal stub. The generated TypeScript types are correct for non-recursive paths, but deeply recursive structures may produce simplified types at the recursion boundary.
+The S05 characterization fixture preserves named self and mutual recursive references in legacy metadata. This does not establish complete graph resolution, forbidden-cycle diagnostics or faithful runtime handling. Internal S05 resolution and companion traversal retain complete immutable declarations and terminate on recursive values; those guarantees are not yet activated in public emitters.
 
 ### First binding selection
 

package/docs/testing.md

@@ -2,19 +2,21 @@
 
 Guide to running and writing tests for wsdl-tsc development and for testing generated code in consumer projects.
 
-See [README](../README.md) for quick start and [CONTRIBUTING](../CONTRIBUTING.md) for development setup.
+See [README](../README.md) for quick start and [CONTRIBUTING](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/CONTRIBUTING.md) for development setup.
 
-Generated test files receive an [editable scaffold preamble](generated-code.md#generated-preambles-and-eslint). Remove its ESLint suppression when adopting the tests as maintained source; existing files are preserved unless `--force-test` is used. Full local CI includes `package:smoke`, which installs a tarball outside the checkout and validates generation, consumer compilation, and generated tests.
+Consumer projects should start at [For Consumer Projects](#for-consumer-projects), then choose the legacy [Generated Test Suite](#generated-test-suite) or checked scaffold workflow. The repository-maintenance sections below require a clone and its development dependencies; installing the npm package does not install repository scripts, Vitest projects or the shared verification lock.
 
 ## Test Architecture
 
-The project uses three layers of testing:
+Repository tests verify observable contracts and regressions, diagnose behavior and support confident changes. Choose the smallest meaningful check, retaining representative installed-package and independent SOAP wire/reference checks when those boundaries matter.
 
-1. Unit tests: Pure function tests for utilities, parsers, and type mapping
-2. Snapshot tests: Baseline comparisons for all generated pipeline output
-3. Integration tests: End-to-end gateway tests using Fastify's `inject()` with mock clients
+Scope and resource cost are separate. `test/unit/tools.test.ts` exercises small utility contracts, while `test/unit/client-choice-union-types.test.ts` launches TypeScript compilation and `test/unit/schema-loading-budgets.test.ts` exercises large inputs. A unit-folder label does not imply pure or inexpensive execution; snapshots are an assertion technique, used here to compare generated output baselines.
 
-All tests use [Vitest](https://vitest.dev/) and run in under 3 seconds.
+Tests use [Vitest](https://vitest.dev/). Mock gateway integration uses Fastify injection, while conformance builds consumer-style projects and installed qualification installs tarballs and runs generated projects. Independent reference tests check XML/schema and SOAP wire observations against separately specified expectations; mocks alone cannot establish those contracts.
+
+The [main configuration](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/vitest.config.ts) runs `fast` first with half the available workers and a 30-second default test allowance; it leaves the fast hook allowance at Vitest's default (10 seconds). `workflows` follows with two workers and two-minute test/hook defaults for all integration, conformance and named expensive unit files. The [stage configuration](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/vitest.conformance.config.ts) uses two workers and two-minute test/hook defaults; explicit longer test and cleanup-hook overrides, such as installed checked-gateway qualification, remain effective.
+
+These are safety cutoffs, not performance acceptance criteria. Report slow tests separately; legitimate expensive work needs measured headroom, potentially several times ordinary runtime under load. Split independent behaviors for diagnosis without multiplying costly installation or setup, and preserve product byte, I/O and SOAP limits as separate contracts.
 
 ## Running Tests
 
@@ -24,6 +26,7 @@ npm run test:unit     # Unit tests only
 npm run test:snap     # Snapshot tests only
 npm run test:integration  # Integration tests only
 npm run test:conformance  # WSDL capability conformance tests only
+npm run test:installed    # Installed consumer qualification
 npm run test:watch    # Watch mode for development
 ```
 
@@ -33,9 +36,55 @@ For the full CI pipeline including smoke tests:
 npm run ci
 ```
 
+Use a file and test-name filter for a focused check, or select a delivered project:
+
+```bash
+npm test -- test/unit/tools.test.ts -t pascal
+npm test -- --project fast
+npm run test:conformance:gateway
+```
+
+For interactive debugging, disabling the individual test timeout does not disable hook deadlines or the guarded wrapper's 45-minute outer deadline:
+
+```bash
+npm test -- test/unit/tools.test.ts --test-timeout=0 --no-file-parallelism
+```
+
+Prefer the guarded public commands: `npm test`, `npm run ci`, `npm run test:unit`, `npm run test:integration`, `npm run test:corpus`, `npm run test:installed` and `npm run test:conformance`. Their corresponding `:run` targets are internal, unguarded implementation commands. Direct Vitest, `test:snap`, watch, capability-stage, reference, platform and hosted CI commands are not all wrapped; the guard is not a machine-wide scheduler.
+
+### Verification orchestration
+
+Inspect the current scripts before choosing commands. `ci` runs the reference launcher, build/typechecks, package/docs validation, broad Vitest including conformance and installed tests, smoke generation and installed package smoke. `test:installed`, `test:corpus` and standalone conformance overlap parts of that coverage; hosted quick and compatibility jobs are narrower signals.
+
+Use focused tests during development, then give one owner responsibility for final candidate verification and its evidence. When standalone conformance is required, finish it and its cleanup before starting final CI, or run the two in the opposite order. Preserve both required commands; an overlapping standalone installed run adds contention rather than independent evidence for work already running inside CI.
+
+Read-only inspection and genuinely independent bounded checks may run in parallel when capacity permits. Coordinate expensive builds, package installs and qualification across agents and worktrees because they share CPU and memory. A worktree isolates its files but does not reserve machine resources.
+
+The [verification wrapper](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/scripts/run-verification.ts) shares an owner across worktrees through `tmp/conformance/verification/active.json` beneath the common Git directory's parent. A live owner causes refusal; wait for it or ask its coordinator to cancel and await owned-child cleanup. Quiet output or an expired tool wait does not authorize replacing a run.
+
+Each guarded attempt prints its unique `attempt-*` directory and records `context.json`, `command.log` and `result.json`. Gateway qualification writes `checked-gateway-installed/progress.ndjson` there; schema loading writes `schema-loading/measurements.json` there. CI also copies a newly written `tmp/conformance/product-tests.json` into the attempt directory; interrupted runs may leave incomplete evidence.
+
+Other writers and unguarded invocations can still use fixed paths, including gateway/schema-loading fallback paths under `tmp/conformance/` and the hosted `installed-tests.json` report. Do not assume all evidence is immutable. Preserve failed evidence before paths are reused, wait for termination and cleanup, and remove only task-owned outputs after delivery.
+
+For a stale lock, read the specific `active.json` owner's PID, command and working directory, then inspect actual process state, including possible PID reuse and surviving owned children. Only after confirming the owner has stopped and cleanup is complete, remove that specific lock and start a deliberate replacement. There is no automatic stale-lock reclamation; never remove a live owner's lock, kill unrelated work or broadly clean `tmp/` to recover.
+
+Record the candidate, command, environment and evidence limits when reusing matching results. A fresh independent reviewer reads the coherent diff and relevant results, then approves or returns actionable findings; coordinate additional expensive checks through the verification owner. Copied source snapshots, review-report files and repeated unchanged reviews are unnecessary.
+
+#### Deadlines and failures
+
+Keep the outer tool allowance long enough for the command and cleanup; polling a quiet command is not a new test attempt. The enclosing test or batch watchdog must account for its sequential work, while each child-stage deadline bounds that child. Cancellation must reach owned work and await cleanup; product byte, node, work and transport budgets enforce separate runtime contracts.
+
+A test runner can mark a test failed even when the behavior it checked was correct. For example, loading 64 MiB successfully and rejecting one extra byte can both pass but take about 32 seconds together, exceeding a test runner's 30-second allowance. The verification attempt still failed; retain the command, candidate, competing work and measurements before deciding whether product behavior, test composition or orchestration needs correction.
+
+Inspect active processes and progress before diagnosing a quiet run as stalled; incomplete execution establishes no passing gate. Explain failures using the concrete checks, expected and observed outcomes, delivery impact and next necessary action. If the explanation is unclear, investigate until you understand the result, then explain the facts and their meaning for the user's task; avoid redundant status messages while providing every necessary explanation.
+
+Review how expensive tests group work, not just their subprocesses. Independent acceptance and refusal checks should have separate test cases when combining them makes one ordinary allowance cover two complete workloads. Preserve both checks, their expected outcomes and the product limits; a passing isolated run alone does not establish that every similar test has been audited or that shared-machine contention has been resolved.
+
+Correct the identified cause before a deliberate rerun. Keep the failed attempt visible, rerun affected checks and any unfinished required gates after cleanup, and reuse unchanged evidence without claiming an uninterrupted full-gate pass. Avoid automatic retries, global timeout increases, assertion weakening or product-budget changes to obtain a pass. An independent reviewer assesses the candidate and its evidence; coordinate any additional expensive reproduction with the verification owner rather than duplicating a running gate.
+
 ## Node Support Policy
 
-The package supports Node.js >= 24.0.0. CI runs the complete project check on Node 24 and Node 26 so the supported floor and current Node line are both covered.
+The package supports Node.js >= 24.0.0. Hosted CI runs quick checks on Node 24 and a narrower compatibility smoke on Node 26. Separate installed-product jobs cover Linux and Windows on both lines, with platform checks, Windows reference/feasibility checks and standalone Linux Node 24 conformance; these signals complement broad local CI and do not replace release preflight.
 
 ## Temporary Workspaces
 
@@ -51,7 +100,7 @@ Keep new repository-owned temporary writers under the closest existing subfolder
 
 ## Unit Tests
 
-Unit tests cover pure functions with no I/O or side effects:
+The unit directory includes small function checks, filesystem work, compilation and resource workflows. Select by the behavior and actual setup, not the folder name:
 
 - `tools.test.ts`: `pascal()`, `resolveQName()`, `explodePascal()`, `pascalToSnakeCase()`, `normalizeArray()`, `getChildrenWithLocalName()`, `getFirstWithLocalName()`
 - `casing.test.ts`: `toPathSegment()` with kebab, asis, and lower styles
@@ -104,7 +153,7 @@ Always review the diff before committing updated snapshots.
 
 ## Integration Tests
 
-Integration tests verify the generated gateway works end-to-end by:
+For manual legacy gateway tests, the mock pattern below checks HTTP route behavior without proving live SOAP interoperability:
 
 1. Running the pipeline in `beforeAll` to generate gateway code
 2. Dynamically importing the generated plugin
@@ -113,7 +162,7 @@ Integration tests verify the generated gateway works end-to-end by:
 
 ### Mock Client Pattern
 
-The generated `operations.ts` provides a typed interface for creating test doubles:
+The legacy generated `operations.ts` provides a typed interface for creating test doubles. The following fragments assume the Weather fixture's generated client and gateway; adapt imports and operation names to your consumer project:
 
 ```typescript
 import type { WeatherOperations } from "../client/operations.js";
@@ -124,6 +173,7 @@ function createMockClient(): WeatherOperations {
       response: {
         GetCityWeatherByZIPResult: {
           Success: true,
+          WeatherID: 0,
           ResponseText: "City Found",
           State: "NY",
           City: "New York",
@@ -137,7 +187,7 @@ function createMockClient(): WeatherOperations {
         GetCityForecastByZIPResult: {
           Success: true,
           ResponseText: "Forecast Found",
-          // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+          // Use SOAP wrapper shape; unwrapArrayWrappers() handles conversion
           ForecastResult: { Forecast: [] },
         },
       },
@@ -145,7 +195,7 @@ function createMockClient(): WeatherOperations {
     }),
     GetWeatherInformation: async (args) => ({
       response: {
-        // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+        // Use SOAP wrapper shape; unwrapArrayWrappers() handles conversion
         GetWeatherInformationResult: { WeatherDescription: [] },
       },
       headers: {},
@@ -154,10 +204,12 @@ function createMockClient(): WeatherOperations {
 }
 ```
 
-Each method returns the same `{ response, headers }` shape as the real SOAP client. Use the wrapper object structure matching TypeScript types — the generated `unwrapArrayWrappers()` function handles conversion to the flat array shape expected by JSON schemas.
+Each method returns the same `{ response, headers }` shape as the real SOAP client. Use the wrapper object structure matching TypeScript types; the generated `unwrapArrayWrappers()` function handles conversion to the flat array shape expected by JSON schemas.
 
 ### Using the Mock with Fastify
 
+This fragment assumes your test imports `expect` and the generated `weatherGateway` plugin and defines `createMockClient()` above. Close the Fastify instance in test cleanup.
+
 ```typescript
 import Fastify from "fastify";
 
@@ -180,7 +232,7 @@ expect(res.json().status).toBe("SUCCESS");
 
 ### Dynamic Import of Generated Code
 
-Integration tests dynamically import generated `.ts` files from temp directories. This works because Vitest's Vite module resolution handles TypeScript imports, JSON import attributes, and bare specifiers from the project's `node_modules`:
+When generating into a temporary directory during a test, Vitest's Vite module resolution handles TypeScript imports, JSON import attributes and bare specifiers from the project's `node_modules`. This fragment assumes `join`, `outDir` and the generated gateway directory are already defined:
 
 ```typescript
 import { pathToFileURL } from "node:url";
@@ -212,14 +264,23 @@ When `--openapi-flatten-array-wrappers false` is used, ArrayOf* types are emitte
 
 ### Error Details Serialization
 
-The `classifyError()` function puts `err.message` (a string) in the `details` field for connection and timeout errors, but the error JSON schema defines `details` as `object | null`. This causes Fastify serialization failures for 503/504 error responses. Test error classification directly via `classifyError()` rather than through Fastify's `inject()` for these error types.
+Connection and timeout errors carry an object in `details`, matching the error schema. Generated gateway tests exercise the serialized 503/504 responses through Fastify; direct `classifyError()` tests additionally check classification. Keep both responsibilities covered rather than bypassing HTTP serialization when it exposes a mismatch.
 
 ## Generated Test Suite
 
-The `--test-dir` flag generates a complete, runnable Vitest test suite that validates all generated gateway artifacts out of the box. This is the recommended way to verify generated code in consumer projects.
+For legacy generation, `--test-dir` emits runnable Vitest mock-route and runtime checks. They verify generated HTTP behavior against generated fixtures, not all service semantics. For checked generation use the separate [consumer workflow](#for-consumer-projects).
 
 ### Generating Tests
 
+Run from an ESM consumer project on Node.js >= 24 with an existing `package.json` and your local `service.wsdl` plus its schema dependencies. Install generator, test and runtime dependencies there; the package does not supply this repository's npm scripts:
+
+```bash
+npm install --save-dev @techspokes/typescript-wsdl-client typescript @types/node vitest
+npm install soap fastify fastify-plugin saxes
+```
+
+Generate matched artifacts with explicit paths:
+
 ```bash
 npx wsdl-tsc pipeline \
   --wsdl-source service.wsdl \
@@ -252,13 +313,21 @@ npx wsdl-tsc pipeline \
 
 ### Running Generated Tests
 
+From the same consumer project root:
+
 ```bash
 npx vitest run --config ./.generated/tests/vitest.config.ts
 ```
 
+The emitted config roots discovery at the test directory, includes `gateway/**/*.test.ts` and `runtime/**/*.test.ts`, and sets a 30-second test timeout. It does not emit this repository's `fast`/`workflows` projects, worker bounds or lock. Adapt runner allowances to your workload, and run your project's TypeScript check with generated client/gateway files included; Vitest execution alone does not typecheck them.
+
+An optional legacy app scaffold supplies `start` and `dev`, not `test` or `typecheck`, and does not add Vitest. Install test dependencies where the test files can resolve them and use the explicit config command above or your existing project scripts. See [TypeScript Configuration](troubleshooting.md#typescript-configuration) for consumer compiler setup.
+
 ### Skip-if-Exists Behavior
 
-Test files that already exist are skipped by default. This allows you to customize generated tests without losing changes on regeneration. Use `--force-test` to overwrite all test files.
+Test files that already exist are skipped by default. Customize them as consumer-owned scaffolds; `--force-test` deliberately overwrites existing emitted files. Preserve customizations before refreshing tests after contract changes; skipped files are not automatically updated to match regenerated artifacts.
+
+Generated test files receive an [editable scaffold preamble](generated-code.md#generated-preambles-and-eslint). Remove its ESLint suppression when adopting the tests as maintained source, and keep maintained tests outside disposable or globally ignored output. Regenerate client/gateway artifacts from inputs and configuration; app scaffolds have separate `--force-init` protection.
 
 ### Mock Client
 
@@ -269,7 +338,7 @@ import { createMockClient } from "./helpers/mock-client.js";
 
 const client = createMockClient({
   GetCityWeatherByZIP: async () => ({
-    response: { GetCityWeatherByZIPResult: { Success: false, WeatherID: 0 } },
+    response: { GetCityWeatherByZIPResult: { Success: false, WeatherID: 0, ResponseText: "Not found" } },
     headers: {},
   }),
 });
@@ -277,7 +346,7 @@ const client = createMockClient({
 
 Mock responses use the pre-unwrap SOAP wrapper shape. The generated `unwrapArrayWrappers()` function handles conversion at runtime.
 
-For operations opted in via `--stream-config`, the mock returns `records: AsyncIterable<RecordType>` via a small `asyncIterableOf` helper. Generated happy-path tests assert on the configured content type; NDJSON tests parse record lines, and JSON array tests parse the response body once as an array. Override a stream op with a multi-record iterable to exercise downstream backpressure:
+For operations opted in via `--stream-config`, the mock returns `records: AsyncIterable<RecordType>` via a small `asyncIterableOf` helper. Generated happy-path tests assert on the configured content type; NDJSON tests parse record lines, and JSON array tests parse the response body once as an array. The following contextual fragment assumes your generated helper has a `UnitDescriptiveInfoStream` operation with `Id`/`Name` records; a multi-record iterable exercises record handling, while backpressure needs a separate slow-consumer check:
 
 ```typescript
 const client = createMockClient({
@@ -293,18 +362,35 @@ const client = createMockClient({
 
 ## For Consumer Projects
 
-If you're using wsdl-tsc as a dependency and want to test your integration:
+Choose tests for your integration's observable contracts and regressions. Start with the smallest meaningful check in your project's existing runner; using this generator does not require adopting the generator repository's CI or test configuration. The npm-shipped guide contains maintainer sections for reference, but repository scripts, shared locks and release gates do not apply to consumer projects.
+
+### Choose legacy or checked generation
+
+Legacy is the default. Follow [Generated Test Suite](#generated-test-suite) for complete dependency, WSDL, output and run commands. For manual tests, generate the same client/gateway outputs, import the operations interface, inject a typed mock into the gateway plugin and assert HTTP responses with Fastify injection or your existing HTTP stack; see [Integration Tests](#integration-tests) for contextual Weather fragments.
+
+The legacy operations interface is a TypeScript seam without a runtime `soap` import; executing the real client still needs `soap`. Keep useful mock response and streaming scenarios when integrating tests into another runner.
+
+For opt-in `checked-components-v1`, use Node.js >= 24 and a consumer project with the generator installed as a development dependency. This complete example uses the bundled synthetic contract and places client, gateway, OpenAPI and tests inside the generated app:
+
+```bash
+npm install --save-dev @techspokes/typescript-wsdl-client
+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-service-name forecast --gateway-version-prefix v1 --init-app --app-dir .generated/forecast --test-dir .generated/forecast/test
+cd .generated/forecast
+npm install
+npm run typecheck
+npm test
+```
+
+Checked tests require app generation and emit `test/checked-scaffold.test.ts` at these paths, without a separate Vitest config. The checked app's package provides Vitest, TypeScript and runtime dependencies plus `typecheck`, `test`, `build` and `start` scripts; `npm test` runs `vitest run` with normal consumer discovery/defaults. It does not inherit this repository's project groups or lock. See [checked generation](checked-generation.md#check-and-start-the-generated-project) for build/start steps and how to substitute your source.
+
+### What generated checks establish
+
+Legacy mock checks exercise route validation, envelopes, error serialization and runtime helpers. Checked scaffold checks exercise health, selected OpenAPI and invalid-request refusal without upstream dispatch, using a loopback placeholder and empty endpoint restrictions. Neither proves independent SOAP wire compatibility, provider behavior or business acceptance, and neither authorizes production transactions.
 
-1. Generate code with `npx wsdl-tsc pipeline --test-dir ./tests` to get a ready-to-run test suite
-2. Run `npx vitest run --config ./tests/vitest.config.ts` to verify everything works
-3. Customize generated tests as needed (they won't be overwritten on regeneration)
+Add independent expected request/response and fault fixtures for owned test services where SOAP interoperability matters, then obtain provider/business acceptance separately. Do not derive every expected answer from the same generated implementation. Choose authorized endpoints and operations before making real calls; the bundled checked contract has no running backend.
 
-Alternatively, write tests manually:
+### Regeneration and customization
 
-1. Generate code with `npx wsdl-tsc pipeline`
-2. Import the operations interface from `operations.ts`
-3. Create a mock client implementing the interface
-4. Register the generated gateway plugin with your mock client
-5. Use Fastify's `inject()` to test routes without a running server
+Keep generator/runtime versions, source snapshots, client, gateway and OpenAPI artifacts matched. Test and app scaffolds preserve existing files unless `--force-test` or `--force-init` respectively is selected; inspect and merge intended changes rather than bypassing protection. Remove the editable scaffold's ESLint suppression when adopting maintained source, and retain maintained tests outside disposable generated output.
 
-The operations interface is the recommended seam for dependency injection and testing. It's a pure TypeScript interface with no runtime dependencies on the `soap` package.
+Run the consumer project's typecheck and tests after regeneration. Reuse matching evidence with its source/artifact identity, command, environment and limits; a passing scaffold test is only evidence for the behavior it exercises.