@techspokes/typescript-wsdl-client 0.25.0 → 0.26.0

package/docs/roadmap/README.md

@@ -0,0 +1,89 @@
+# Version 1.0 Roadmap Plan
+
+Detailed plan for moving `@techspokes/typescript-wsdl-client` from `0.26.x` to a stable `1.0.0` release.
+
+See the root [README.md](../../README.md) for project overview and the root [ROADMAP.md](../../ROADMAP.md) for the public roadmap summary.
+
+## Purpose
+
+This plan turns the 1.0 roadmap into implementation slices that can be picked up independently. Each slice has its own plan document with scope, testing strategy, acceptance gates, and release implications.
+
+The plan is optimized for preserving quality. Contract mismatches are resolved before new capability work, compatibility research constrains schema changes, and WSDL coverage work turns unsupported behavior into explicit diagnostics.
+
+## Route Summary
+
+| Slice | Document | Outcome |
+|-------|----------|---------|
+| Contract audit | [Contract Audit](v1.0-contract-audit.md) | Public surfaces match behavior |
+| OpenAPI compatibility | [OpenAPI Fastify Compatibility](v1.0-openapi-fastify-compatibility.md) | Schema strategy is proven |
+| Choice union mode | [Choice Union Mode](v1.0-choice-union-mode.md) | Implemented in `0.26.0` |
+| JSON array streaming | [JSON Array Streaming](v1.0-json-array-streaming.md) | `format: "json-array"` works |
+| WSDL coverage matrix | [WSDL Coverage Matrix](v1.0-wsdl-coverage-matrix.md) | Feature support is test-backed |
+| Release candidate | [Release Candidate Gates](v1.0-release-candidate-gates.md) | 1.0 release is repeatable |
+
+## Execution Order
+
+### Slice 1: Contract Audit
+
+Start with contract audit because it defines the exact public promises that later slices must satisfy. This slice updates docs, identifies mismatched flags and options, and creates failing tests for the behavior that must become true.
+
+### Slice 2: OpenAPI Fastify Compatibility
+
+Run compatibility research before changing union schemas or streaming JSON schemas. This keeps schema design constrained by Fastify validation, Fastify serialization, and generated gateway behavior.
+
+### Slice 3: Choice Union Mode
+
+Choice union mode is complete in `0.26.0`. The default `all-optional` mode remains unchanged for backwards compatibility.
+
+### Slice 4: JSON Array Streaming
+
+Implement streaming JSON array output after stream error behavior is researched. This is the next implementation slice after `0.26.0`, and the result must stream records incrementally without buffering the full SOAP response.
+
+### Slice 5: WSDL Coverage Matrix
+
+Build the automated WSDL feature matrix once the two existing public contract gaps are handled. The matrix should then drive the remaining WSDL support and diagnostic decisions.
+
+### Slice 6: Release Candidate Gates
+
+Run the release candidate gates after feature work and documentation have converged. This slice validates docs, tests, generated examples, package contents, skill artifact, release notes, and provenance workflow readiness.
+
+## Quality Principles
+
+- Keep default generated output stable unless a slice explicitly changes it.
+- Add failing tests before generator changes.
+- Prefer fixture-driven WSDL behavior over ad hoc string assertions.
+- Keep OpenAPI output compatible with generated Fastify gateways.
+- Preserve deterministic output ordering in catalogs, generated TypeScript, schemas, and route files.
+- Keep unsupported behavior explicit in diagnostics and documentation.
+
+## 1.0 Gates
+
+### Contract Gate
+
+- `--client-choice-mode union` is implemented and documented in `0.26.0`.
+- `format: "json-array"` is implemented and documented.
+- CLI docs, API docs, configuration docs, and generated behavior agree.
+
+### Compatibility Gate
+
+- Choice union schemas are validated against Fastify request handling.
+- Gateway response schemas stay inside Fastify serialization limits.
+- JSON array streams have documented terminal-error behavior.
+
+### Coverage Gate
+
+- A WSDL feature matrix runs under test automation.
+- Each matrix entry has a fixture and expected behavior.
+- Unsupported features fail loudly or are documented as deliberately unsupported.
+
+### Release Gate
+
+- `npm run docs:validate` passes.
+- `npm test` passes.
+- `npm run smoke:pipeline` passes.
+- `npm run ci` passes.
+- `npm run release:preflight -- v1.0.0` passes during release preparation.
+
+## Changelog Strategy
+
+Each implementation slice should add one concise `CHANGELOG.md` entry under `## [Unreleased]`. Release-only changes move those entries into the release section during normal release preparation.

package/docs/roadmap/v1.0-choice-union-mode.md

@@ -0,0 +1,90 @@
+# Version 1.0 Choice Union Mode
+
+Status: implemented for `0.26.0`.
+
+This page records the completed `xs:choice` union support behind `--client-choice-mode union`.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+`0.26.0` completes opt-in `--client-choice-mode union` for TypeScript, OpenAPI, generated gateway schemas, generated mocks, and generated test artifacts. The existing `all-optional` mode remains the default and keeps its current generated output unless a bug is explicitly fixed.
+
+## Completed Scope
+
+- Preserved choice-group metadata during schema compilation.
+- Emitted TypeScript union types for choice groups in union mode.
+- Kept default all-optional TypeScript output stable.
+- Emitted Fastify-compatible OpenAPI schemas that reflect choice exclusivity.
+- Generated mock data that selects a valid choice branch.
+- Generated gateway tests that reject invalid branch combinations.
+- Generated gateway tests that reject missing required choice branches.
+- Updated README, CLI reference, concepts, supported patterns, generated code docs, and production docs.
+
+## Out Of Scope
+
+- Do not make union mode the default before 1.0.
+- Do not change XML runtime mapping for non-choice elements.
+- Do not solve abstract substitution groups in this slice unless required by choice fixtures.
+
+## Implementation Units
+
+### Catalog Metadata
+
+The compiler preserves catalog metadata for choice groups with stable names, branch element names, branch type names, occurrence constraints, nillable flags, and source order. This lets downstream emitters render deterministic output in both `all-optional` and `union` mode.
+
+### TypeScript Emitter
+
+In `all-optional` mode, the emitter keeps the existing interface shape. In `union` mode, it emits a base object for non-choice fields and combines it with a generated branch union.
+
+The generated union uses peer `?: never` properties so TypeScript rejects payloads containing more than one branch. Optional choice groups include an empty branch where the WSDL permits omitting all choice members.
+
+### OpenAPI Emitter
+
+The schema strategy is the one proven by [OpenAPI Fastify Compatibility](v1.0-openapi-fastify-compatibility.md). The generated request-body schema uses `oneOf` over containing-object branches with peer `not` constraints.
+
+Choice member properties remain on the containing object, required non-choice properties stay top-level, and optional choice groups get an empty branch constraint. Closed `oneOf` branches alone were avoided because AJV can remove additional properties before evaluating branch results under Fastify defaults.
+
+### Gateway And Test Emitters
+
+Generated gateway route schemas consume the new OpenAPI shape without hand edits. Generated mock clients select one choice branch in union mode.
+
+Generated validation tests include invalid multi-branch request cases and missing required-branch request cases for top-level request choice groups. Fastify rejection is covered in generated suites.
+
+## Testing Coverage
+
+### Compiler Tests
+
+Coverage asserts catalog metadata for simple, optional, required, nested, attribute-mixed, and sequence-mixed choice groups.
+
+### TypeScript Tests
+
+Coverage checks generated `types.ts` in both `all-optional` and `union` mode. Compile-only tests prove invalid multi-branch payloads fail when union mode is selected.
+
+### OpenAPI Tests
+
+Coverage checks generated schema branches and validates generated specs with the existing OpenAPI validation path.
+
+### Gateway Tests
+
+Coverage checks valid choice request bodies, invalid multi-branch request bodies, and missing required choice request bodies.
+
+### Regression Tests
+
+Snapshot coverage protects default generated output from unintended drift.
+
+## Acceptance Criteria
+
+Satisfied by `0.26.0`:
+
+- `--client-choice-mode union` changes generated output in a test-backed way.
+- `all-optional` mode remains default and stable.
+- TypeScript rejects invalid multi-branch payloads in union mode where the object model can represent exclusivity.
+- OpenAPI schemas validate with the project validator.
+- Generated Fastify routes accept valid branch payloads.
+- Generated Fastify routes reject invalid branch combinations through the selected schema strategy.
+- Docs describe both modes and their tradeoffs accurately.
+
+## Release Implications
+
+This slice shipped as the `0.26.0` user-facing feature release. It remains opt-in before 1.0, with no upgrade steps for users who keep the default mode.

package/docs/roadmap/v1.0-contract-audit.md

@@ -0,0 +1,74 @@
+# Version 1.0 Contract Audit
+
+Plan for aligning public flags, programmatic options, docs, and generated behavior before implementing the remaining 1.0 features.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+The contract audit makes every public promise explicit before 1.0. A public promise includes CLI flags, programmatic options, configuration files, generated file shapes, documentation examples, release workflow claims, and roadmap statements.
+
+## Why This Slice Comes First
+
+This slice prevents later work from building on ambiguous behavior. It also gives contributors a reliable target when they implement choice union mode, JSON array streaming, and WSDL feature coverage.
+
+## Scope
+
+- Audit CLI flags in `src/cli.ts` against `docs/cli-reference.md`.
+- Audit programmatic options in exported types against `docs/api-reference.md`.
+- Audit configuration file formats against `docs/configuration.md`.
+- Audit generated output claims against snapshots and `examples/generated-output`.
+- Refresh `ROADMAP.md` so shipped work is not listed as future work.
+- Add failing tests for public behavior that must be implemented in later slices.
+
+## Out Of Scope
+
+- Do not implement choice union mode in this slice.
+- Do not implement JSON array streaming in this slice.
+- Do not expand WSDL feature support in this slice.
+- Do not change default generated output unless a contract is already wrong.
+
+## Required Findings
+
+### Choice Mode
+
+`--client-choice-mode union` must stay public because 1.0 requires full union support. The audit should identify every code path and doc section that must change when union mode is implemented.
+
+### JSON Array Streaming
+
+`format: "json-array"` must stay in the 1.0 roadmap because 1.0 requires the format. The audit should identify every parser, client, OpenAPI, gateway, runtime, and docs surface that currently assumes NDJSON.
+
+### Roadmap State
+
+`ROADMAP.md` must reflect `0.25.x` as current. Release preflight and security hardening must be treated as shipped work.
+
+### Release Metadata
+
+Tag gaps before `1.0.0` are not blockers by themselves. The audit should only confirm that release-preflight and release workflows catch missing metadata for the target 1.0 release.
+
+## Testing Approach
+
+### Documentation Validation
+
+Run `npm run docs:validate` after documentation changes. This verifies Markdown links and TypeScript fenced snippets.
+
+### Contract Snapshot
+
+Add or update focused tests that inspect CLI option availability and generated metadata defaults. These tests should fail only when public contract surfaces drift from documentation.
+
+### Negative Tests
+
+Add tests that document the current failing behavior for union mode and JSON array streaming only if the next slice can consume them. These tests should be skipped or marked as expected failures only if the repository already has an accepted pattern for that.
+
+## Acceptance Criteria
+
+- `ROADMAP.md` names `0.25.x` as current.
+- `docs/roadmap/README.md` links every 1.0 slice.
+- CLI, API, and configuration docs agree on required 1.0 behavior.
+- Known contract gaps are linked to implementation slices.
+- `CHANGELOG.md` has one `docs(roadmap):` entry for the audit docs.
+- `npm run docs:validate` passes.
+
+## Release Implications
+
+This slice can ship as a documentation-only minor release if no behavior changes are made. If tests are added that currently fail or are skipped, the release notes must explain that they are roadmap scaffolding rather than completed support.

package/docs/roadmap/v1.0-json-array-streaming.md

@@ -0,0 +1,99 @@
+# Version 1.0 JSON Array Streaming
+
+Plan for implementing `format: "json-array"` streaming for SOAP operations that already use the stream configuration model.
+
+This is the next planned feature slice after the `0.26.0` choice union mode release.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+`format: "json-array"` must stream records incrementally as a valid JSON array without buffering the full SOAP response. The implementation must be compatible with generated clients, OpenAPI output, Fastify routes, generated tests, and production docs.
+
+## Design Direction
+
+JSON array streaming should write an opening bracket, stream comma-separated JSON records, and write a closing bracket after the async iterable completes. The implementation must preserve backpressure by converting the async iterable into a Node `Readable` stream.
+
+The key research question is error timing. If the route can observe an upstream error before sending the first byte, it should still return the normal error envelope. Once the JSON array response has started, a later error must truncate the response and clients must treat the JSON parse failure as a failed stream.
+
+## Scope
+
+- Implement a runtime helper for JSON array streaming.
+- Preserve existing NDJSON behavior.
+- Emit JSON array route handlers when stream metadata says `format: "json-array"`.
+- Emit `application/json` OpenAPI content with an array item schema.
+- Generate stream-aware mock clients and tests for JSON array operations.
+- Document terminal-error behavior for JSON array clients.
+
+## Out Of Scope
+
+- Do not implement streaming request bodies in this slice.
+- Do not change buffered SOAP operations.
+- Do not make JSON array the default stream format.
+
+## Research Tasks
+
+### First-Byte Timing
+
+Research whether generated routes should prefetch the first record before calling `reply.send`. Prefetching can preserve normal error envelopes for errors that happen before any record is available, but it may delay response headers for slow upstream services.
+
+### Empty Stream Handling
+
+Confirm that an empty stream returns `[]` with `application/json`. The helper must emit a syntactically valid empty array without special route code where possible.
+
+### Backpressure Handling
+
+Confirm that the helper does not pull from the async iterable faster than the HTTP stream can write. Use tests modeled after existing NDJSON backpressure tests.
+
+### Terminal Error Handling
+
+Confirm how Fastify and Node surface stream errors after the JSON array has begun. Document the client-visible behavior in production docs and troubleshooting docs.
+
+## Implementation Units
+
+### Runtime Helper
+
+Add `toJsonArray<T>(records: AsyncIterable<T>): Readable` beside `toNdjson`. The helper should serialize records with `JSON.stringify`, insert commas between records, and close the array when iteration completes.
+
+### Gateway Emitter
+
+Generate stream route handlers that import `toJsonArray` for `json-array` operations and `toNdjson` for `ndjson` operations. The handler must set the media type from stream metadata.
+
+### OpenAPI Emitter
+
+Emit `application/json` with `schema.type = "array"` and `items` pointing at the record schema. Keep `x-wsdl-tsc-stream` metadata so downstream tooling can still identify stream operations.
+
+### Client And Test Emitters
+
+Keep the client method return shape as `StreamOperationResponse<RecordType>`. Generated tests should parse the HTTP response as a JSON array and assert record values.
+
+## Testing Approach
+
+### Unit Tests
+
+Test `toJsonArray` with empty records, one record, multiple records, string escaping, source errors, and backpressure. Mirror the existing `toNdjson` tests where possible.
+
+### OpenAPI Tests
+
+Test that JSON array operations advertise `application/json`, array schema items, and stream extension metadata.
+
+### Gateway Integration Tests
+
+Test Fastify route output for a JSON array stream operation. Assert content type, parseable JSON, and record order.
+
+### Error Tests
+
+Test errors before the first emitted record separately from errors after at least one emitted byte. The expected post-start behavior is a failed or truncated response, not a JSON error envelope.
+
+## Acceptance Criteria
+
+- `format: "json-array"` generates working client, OpenAPI, gateway, and tests.
+- JSON array output is parseable when the source completes normally.
+- Output is streamed incrementally and does not buffer the full response.
+- NDJSON behavior remains unchanged.
+- Terminal-error behavior is documented accurately.
+- `npm test` and `npm run smoke:pipeline` pass.
+
+## Release Implications
+
+This slice is a user-facing feature release. The release notes must state that `json-array` is no longer reserved and can be selected per operation with `stream-config`.

package/docs/roadmap/v1.0-openapi-fastify-compatibility.md

@@ -0,0 +1,97 @@
+# Version 1.0 OpenAPI Fastify Compatibility
+
+Plan for proving schema choices against Fastify before changing choice union output or JSON array streaming output.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+This slice confirms which OpenAPI 3.1 and JSON Schema constructs are safe for generated Fastify gateways. The result should constrain choice union mode, JSON array streaming, and any future schema complexity work.
+
+## Why This Slice Comes Before Implementation
+
+Fastify compatibility is part of the generated gateway contract. A TypeScript type shape can be correct while the generated OpenAPI schema is unusable for Fastify request validation or response serialization.
+
+## Scope
+
+- Test `oneOf`, `anyOf`, and `allOf` request schemas through Fastify validation.
+- Test generated response schemas through Fastify serialization where applicable.
+- Test route schemas that omit response serialization for streamed responses.
+- Verify how schema complexity interacts with the existing response-depth safety limit.
+- Document the allowed schema strategy for choice union mode.
+- Document the allowed schema strategy for JSON array streaming.
+
+## Out Of Scope
+
+- Do not implement choice union mode in this slice.
+- Do not implement JSON array streaming in this slice.
+- Do not change public WSDL feature coverage in this slice.
+
+## Research Questions
+
+### Choice Request Validation
+
+The research must determine whether `oneOf` with mutually exclusive object branches behaves correctly for request bodies. It must also determine whether additional branch exclusion properties are needed to reject payloads that send more than one choice branch.
+
+### Choice Response Serialization
+
+The research must determine whether generated response schemas should use union constructs or stay envelope-based with permissive payload branches. If Fastify serialization becomes fragile, generated route response schemas must stay conservative.
+
+### JSON Array Streaming Schema
+
+The research must determine how to advertise an incrementally streamed JSON array in OpenAPI while keeping generated Fastify route schemas valid. Stream routes already omit normal response serialization because the response is not a single buffered object.
+
+## Local Fastify Findings
+
+The initial probes use the current project Fastify dependency and `fastify.inject` in `test/integration/fastify-schema-compatibility.test.ts`.
+
+### Choice Request Validation
+
+Fastify's default AJV options remove additional properties when `additionalProperties: false` is present. Because of that, closed `oneOf` branch schemas are not enough for `xsd:choice`: a payload containing both choice fields can be mutated into one valid branch before the `oneOf` result is evaluated.
+
+The allowed request strategy is:
+
+- Put the choice member properties on the containing object schema.
+- Use `oneOf` for exact branch selection.
+- Add peer `not` constraints to each branch so a branch fails when another choice member is present.
+- Keep `additionalProperties: false` at the containing object level when the generator already owns the full object shape.
+
+Do not use bare `anyOf` for exclusive choices. The local probe confirms it accepts a payload containing more than one choice field when branches are open.
+
+### Choice Response Serialization
+
+Keep generated gateway response schemas conservative for this slice. The local probe confirms current envelope-style responses with `anyOf` payload branches serialize under Fastify, so no generator response-schema expansion is required before the choice implementation slice.
+
+### JSON Array Streaming Schema
+
+Keep streamed Fastify routes free of response serialization schemas. The local probe confirms a route can stream an `application/json` array body without registering a Fastify response schema. OpenAPI can advertise the array response, while generated route registration should omit the response schema for streamed handlers.
+
+### Response Schema Complexity
+
+The existing response complexity guard walks `$ref` values inside `allOf`, `anyOf`, and `oneOf`. Unit coverage now locks that behavior so future union work does not bypass the depth safety limit.
+
+## Testing Approach
+
+### Local Fastify Probes
+
+Create focused Vitest tests that instantiate Fastify, register minimal schemas, and call `fastify.inject`. These tests should use the project dependency versions rather than external assumptions.
+
+### Generator Contract Tests
+
+Once a schema strategy is chosen, add tests that assert generated OpenAPI and gateway operation schemas use only approved constructs.
+
+### Compatibility Fixtures
+
+Use small synthetic schemas for compatibility probes. Do not require WSDL fixtures until the generator implementation slices.
+
+## Acceptance Criteria
+
+- A documented schema strategy exists for choice union request bodies.
+- A documented schema strategy exists for choice union response schemas.
+- A documented schema strategy exists for JSON array stream responses.
+- Tests prove the selected strategy against local Fastify behavior.
+- Existing gateway integration tests still pass.
+
+## Release Implications
+
+This slice may ship without user-facing generator changes if it only adds tests and docs. If it changes schema generation defaults, it must be paired with snapshot updates and migration notes.

package/docs/roadmap/v1.0-release-candidate-gates.md

@@ -0,0 +1,77 @@
+# Version 1.0 Release Candidate Gates
+
+Plan for validating that `1.0.0` is repeatable, documented, test-backed, and ready to publish.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+The release candidate gates define what must be true before tagging `v1.0.0`. They turn release readiness into concrete checks rather than subjective confidence.
+
+## Scope
+
+- Verify public docs match shipped behavior.
+- Verify generated examples are current.
+- Verify package contents and agent skill artifact.
+- Verify supported Node.js coverage.
+- Verify provenance publish workflow readiness.
+- Verify release notes and changelog.
+
+## Out Of Scope
+
+- Do not add new generator features in this slice.
+- Do not accept known contract gaps as release notes caveats.
+- Do not publish `1.0.0` until all gates pass.
+
+## Required Gates
+
+### Documentation Gate
+
+Run `npm run docs:validate`. Confirm README, CLI reference, API reference, configuration docs, supported patterns, production docs, and roadmap agree on choice union mode and JSON array streaming.
+
+### Test Gate
+
+Run `npm test`. Confirm unit, snapshot, and integration suites cover the 1.0 contract.
+
+### Smoke Gate
+
+Run `npm run smoke:pipeline`. Confirm the canonical weather fixture still generates the full stack.
+
+### CI Gate
+
+Run `npm run ci`. Confirm build, typecheck, docs validation, package validation, skill validation, tests, and smoke pipeline pass together.
+
+### Example Gate
+
+Run the generated example freshness check through release preflight. Confirm committed examples match regenerated output.
+
+### Node Gate
+
+Run the supported Node.js floor and the newest active Node.js line in CI before the release candidate is accepted.
+
+### Release Gate
+
+Run `npm run release:preflight -- v1.0.0` during release preparation. Confirm release notes, changelog, dependency pins, generated examples, CI, and skill packaging pass.
+
+## Documentation Checklist
+
+- README names supported 1.0 capabilities accurately.
+- CLI reference lists implemented flags only.
+- API reference lists implemented options only.
+- Configuration docs describe both stream formats.
+- Supported patterns reflects the WSDL matrix.
+- Production docs describe terminal-error behavior for both stream formats.
+- Migration docs explain any behavior changes since `0.x`.
+
+## Acceptance Criteria
+
+- All required gates pass without skipped 1.0 blockers.
+- `docs/releases/v1.0.0.md` exists and follows the release note structure.
+- `CHANGELOG.md` has a dated `1.0.0` section during release preparation.
+- The package dry-run contents include required runtime templates and docs.
+- The agent skill artifact validates and packages deterministically.
+- The release workflow can publish with provenance.
+
+## Release Implications
+
+This slice is the final release preparation work. It should produce the `1.0.0` release commit only after all feature slices have shipped or merged into the release branch.

package/docs/roadmap/v1.0-wsdl-coverage-matrix.md

@@ -0,0 +1,89 @@
+# Version 1.0 WSDL Coverage Matrix
+
+Plan for turning WSDL and XSD support claims into automated, fixture-backed evidence before 1.0.
+
+See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
+
+## Goal
+
+The project should have an automated feature matrix that proves which WSDL and XSD patterns are supported, partially supported, or rejected with diagnostics. The matrix should feed `docs/supported-patterns.md` and protect 1.0 from silent miscompilation.
+
+## Design Direction
+
+Each matrix row should have a minimal fixture, an expected support status, and a test that proves the status. A supported feature must compile and generate aligned client, OpenAPI, and gateway artifacts where applicable. An unsupported feature must fail with a clear diagnostic or be documented as intentionally out of scope.
+
+## Scope
+
+- Add a fixture directory for WSDL feature coverage.
+- Add a manifest that lists features, status, expected commands, and expected diagnostics.
+- Add Vitest coverage that reads the manifest and runs the relevant generation steps.
+- Update `docs/supported-patterns.md` from the matrix findings.
+- Include priority gaps from the roadmap.
+
+## Out Of Scope
+
+- Do not implement every unsupported WSDL feature in this slice.
+- Do not replace the existing weather fixture for smoke tests.
+- Do not make docs generated from the manifest unless that is a deliberate later decision.
+
+## Priority Feature Rows
+
+| Feature | Expected 1.0 Status | Notes |
+|---------|---------------------|-------|
+| `xs:choice` union mode | supported | Implemented in `0.26.0` |
+| `xs:union` | supported or diagnostic | Decide after fixture work |
+| Abstract types | diagnostic | Avoid silent concrete treatment |
+| Substitution groups | diagnostic | Avoid silent omission |
+| Multi-binding WSDLs | documented behavior | First binding or explicit selection |
+| External `PolicyReference` | partial or diagnostic | Inline policy already exists |
+| Deep composition | supported | Prove current recursion behavior |
+| `xs:anyAttribute` | diagnostic | Current support is not full |
+| MTOM/XOP attachments | unsupported diagnostic | Keep out of 1.0 scope unless required |
+
+## Manifest Shape
+
+The manifest should be small and reviewable. A JSON or TypeScript manifest is acceptable if tests can import it deterministically.
+
+```json
+{
+  "features": [
+    {
+      "id": "choice-union-simple",
+      "fixture": "choice-union-simple.wsdl",
+      "status": "supported",
+      "commands": ["compile", "client", "openapi", "gateway"]
+    }
+  ]
+}
+```
+
+## Testing Approach
+
+### Matrix Runner
+
+Create a Vitest suite that reads the manifest and executes the requested commands through programmatic APIs where possible. CLI smoke behavior should remain covered by existing smoke scripts.
+
+### Supported Feature Tests
+
+For supported rows, assert successful compilation, generated TypeScript type-checking, OpenAPI validation, and gateway schema generation when applicable.
+
+### Diagnostic Feature Tests
+
+For diagnostic rows, assert the exact error class or user-facing message shape. Avoid brittle full-message assertions unless the message is part of the public contract.
+
+### Documentation Tests
+
+Ensure every documented unsupported or partial feature has a corresponding matrix row. This can be a lightweight consistency test that compares feature IDs with anchors or explicit markers in `docs/supported-patterns.md`.
+
+## Acceptance Criteria
+
+- The matrix includes every roadmap priority feature.
+- Supported rows have passing fixtures.
+- Unsupported rows fail with clear diagnostics.
+- `docs/supported-patterns.md` reflects the matrix.
+- No known feature silently miscompiles in matrix coverage.
+- The matrix can run in CI or release preflight without network access.
+
+## Release Implications
+
+This slice may reveal features that should be implemented before 1.0. It may also justify explicit post-1.0 deferrals if diagnostics and documentation are strong enough.

package/docs/supported-patterns.md

@@ -12,7 +12,8 @@ These patterns are handled end-to-end: WSDL parsing, TypeScript type generation,
 - 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
+- `<xs:choice>` elements modeled as parallel optional alternatives by default
+- Opt-in `<xs:choice>` union mode with exclusive TypeScript branch unions and OpenAPI request constraints
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",
@@ -95,14 +95,14 @@
     "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
     "fast-xml-parser": "^5.8.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "saxes": "^6.0.0",
     "soap": "^1.9.3",
     "yargs": "^18.0.0"