@techspokes/typescript-wsdl-client 0.31.0 → 0.32.0

package/docs/releases/v0.32.0.md

@@ -0,0 +1,33 @@
+# TypeScript WSDL Client v0.32.0
+
+## Gateway Conformance Evidence
+
+This release extends the WSDL capability conformance framework through generated Fastify gateway artifacts and runtime request checks for the current supported and partial capability rows.
+
+## What This Improves
+
+Maintainers can now verify that documented WSDL support survives the full downstream path from fixture compilation to generated client code, OpenAPI output, generated gateway code, and Fastify request handling. This makes the public support matrix more trustworthy before the project moves into the remaining generated-test and app evidence needed for 1.0.
+
+Conformance mini-projects now run under `tmp/conformance/` inside the repository, which keeps TypeScript and Node module resolution aligned with a consumer-style project while avoiding machine-specific temporary-directory behavior.
+
+## Highlights
+
+- Adds generated gateway type-check evidence for supported and partial WSDL conformance rows.
+- Adds Fastify runtime injection checks for generated gateway routes.
+- Documents `tmp/conformance/` as the architecture boundary for generated conformance projects.
+- Updates the roadmap so the next 1.0 slice is generated-test and app conformance evidence.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Agent skill artifact was validated and packaged.
+- Release preflight passed against the target tag.
+
+## Notes
+
+Release tag: `v0.32.0`.

package/docs/roadmap/README.md

@@ -18,8 +18,8 @@ The plan is optimized for preserving quality. The contract and compatibility bas
 | OpenAPI compatibility | [OpenAPI Fastify Compatibility](v1.0-openapi-fastify-compatibility.md)       | baseline complete | Schema strategy is proven       |
 | Choice union mode     | [Choice Union Mode](v1.0-choice-union-mode.md)                               | complete          | Implemented in `0.26.0`         |
 | JSON array streaming  | [JSON Array Streaming](v1.0-json-array-streaming.md)                         | complete          | Implemented in `0.28.0`         |
-| Conformance framework | [Capability Conformance Framework](v1.0-capability-conformance-framework.md) | phase 2 shipped   | Pipeline claims are test-backed |
-| WSDL coverage matrix  | [WSDL Coverage Matrix](v1.0-wsdl-coverage-matrix.md)                         | client and OpenAPI evidence shipped | Feature support is test-backed |
+| Conformance framework | [Capability Conformance Framework](v1.0-capability-conformance-framework.md) | phase 3 shipped   | Pipeline claims are test-backed |
+| WSDL coverage matrix  | [WSDL Coverage Matrix](v1.0-wsdl-coverage-matrix.md)                         | gateway evidence shipped | Feature support is test-backed |
 | Release candidate     | [Release Candidate Gates](v1.0-release-candidate-gates.md)                   | remaining         | 1.0 release is repeatable       |
 
 ## Execution Order
@@ -42,11 +42,11 @@ JSON array streaming is complete in `0.28.0`. The default `ndjson` format remain
 
 ### Slice 5: Capability Conformance Framework
 
-The registry, fixture strategy, compile runner, client evidence, OpenAPI evidence, documentation drift check, and generated support matrix are shipped. The next work is to extend relevant rows into gateway runtime evidence without expanding public APIs.
+The registry, fixture strategy, compile runner, client evidence, OpenAPI evidence, gateway runtime evidence, documentation drift check, and generated support matrix are shipped. The next work is to extend relevant rows into generated-test and app evidence without expanding public APIs.
 
 ### Slice 6: WSDL Coverage Matrix
 
-The first WSDL matrix rows now exist as conformance registry entries with compile, client, OpenAPI, and documentation evidence. The next work is to prove relevant rows through generated gateway runtime artifacts.
+The first WSDL matrix rows now exist as conformance registry entries with compile, client, OpenAPI, gateway runtime, and documentation evidence. The next work is to prove relevant rows through generated-test and app artifacts where those stages apply.
 
 ### Slice 7: Release Candidate Gates
 
@@ -54,8 +54,8 @@ Run the release candidate gates after feature work and documentation have conver
 
 ## Remaining Before 1.0
 
-- Extend the capability registry beyond OpenAPI evidence into gateway runtime evidence.
-- Add generated gateway checks for supported and partial WSDL rows where HTTP behavior is part of the contract.
+- Extend the capability registry beyond gateway runtime evidence into generated-test and app evidence.
+- Add generated-test and app checks for supported and partial WSDL rows where those surfaces are part of the contract.
 - Turn remaining unsupported, diagnostic, or partial matrix rows into diagnostics, documentation, or scoped fixes.
 - Confirm `docs/supported-patterns.md` matches the matrix.
 - Run the release-candidate gates.

package/docs/roadmap/v1.0-capability-conformance-framework.md

@@ -1,10 +1,10 @@
 # Version 1.0 Capability Conformance Framework
 
-Status: Phase 2 shipped; gateway runtime evidence remaining before `1.0.0`.
+Status: Phase 3 shipped; generated-test and app evidence remaining before `1.0.0`.
 
 Plan for turning SOAP, WSDL, OpenAPI, gateway, app, generated-test, and documentation support claims into fixture-backed conformance evidence.
 
-Phase 1 shipped a TypeScript registry, reusable WSDL fixtures, compile-stage runner, documentation drift tests, and generated public support matrix. Phase 2 added generated client type-checking, OpenAPI validation, and executable diagnostics for terminal rows. The next slice should extend relevant rows into gateway runtime evidence before adding more feature rows.
+Phase 1 shipped a TypeScript registry, reusable WSDL fixtures, compile-stage runner, documentation drift tests, and generated public support matrix. Phase 2 added generated client type-checking, OpenAPI validation, and executable diagnostics for terminal rows. Phase 3 added generated gateway type-checking and Fastify runtime evidence for current supported and partial rows.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
@@ -362,14 +362,169 @@ Skeptical review notes:
 
 ## Phase 3: Gateway Runtime Evidence
 
-Extend relevant rows to generate gateways and test Fastify runtime behavior through `fastify.inject`. Add mock operations clients and request/response fixtures as part of the registry.
+Phase 3 is implemented for the current supported and partial WSDL rows. Keep this section as the baseline for future gateway conformance rows.
 
-Acceptance criteria:
+Extend current supported and partial rows to generate gateways, type-check generated gateway artifacts, and test Fastify runtime behavior through `fastify.inject`. Add mock operations clients and request/response fixtures as part of each row's registry evidence.
+
+### Phase 3 Goal
+
+A supported or partial row should no longer stop at compile, client, and OpenAPI evidence when gateway behavior is relevant. The row should prove that the generated Fastify plugin can be imported, registered with a mock operations client, and exercised through HTTP injection.
+
+Diagnostic and unsupported rows must continue to stop at compile. They must not generate client, OpenAPI, or gateway artifacts after the expected diagnostic.
+
+### Phase 3 Source Files
+
+- `test/conformance/types.ts`
+- `test/conformance/registry.ts`
+- `test/conformance/runner.ts`
+- `test/conformance/conformance.test.ts`
+- `src/gateway/generateGateway.ts`
+- `test/integration/gateway-routes.test.ts`
+
+Use `test/integration/gateway-routes.test.ts` as the runtime pattern for generated plugin imports, mock clients, Fastify registration, and `fastify.inject` assertions. Keep conformance-specific helpers in `test/conformance/runner.ts`.
+
+### Phase 3 Type Model
+
+Add a small optional `gateway` expectation block to `CapabilityCase`. Keep it internal to `test/conformance/types.ts`; do not export it from `src/index.ts` and do not add a public CLI command.
+
+The initial model should stay close to the current `client` and `openapi` expectations:
+
+```ts
+export interface GatewayArtifacts {
+  clientDir: string;
+  gatewayDir: string;
+  openapiFile: string;
+  catalogFile: string;
+  compiled: CompiledCatalog;
+  doc: any;
+  routeFor: (operationId: string) => {method: string; path: string};
+  readGatewayFile: (relativePath: string) => string;
+}
+
+export interface GatewayRequestExpectation {
+  operationId: string;
+  payload: unknown;
+  mockClient: Record<string, (args: unknown) => Promise<{response: unknown; headers: unknown}>>;
+  expectedStatus: number;
+  assertBody?: (body: any) => void;
+  assertClientArgs?: (args: unknown) => void;
+}
+
+export interface GatewayExpectation {
+  outcome: "success";
+  requests?: GatewayRequestExpectation[];
+  sourceIncludes?: Array<{file: string; text: string}>;
+  assert?: (artifacts: GatewayArtifacts) => void | Promise<void>;
+}
+```
+
+This shape is a starting contract, not a generic assertion language. If implementation reveals a simpler local helper, prefer the simpler helper as long as a fresh agent can still understand how to add a new row.
+
+### Phase 3 Runner Flow
+
+`runGatewayCase` should use one temporary output root per capability row and remove it after success. If a row fails, the thrown error should include the capability ID and the generated path involved.
+
+Generated conformance projects should live under `tmp/conformance/`, not the OS temp directory. Gateway conformance generates a small TypeScript project that imports `soap`, `fastify`, `fastify-plugin`, generated JSON schemas, and generated sibling modules. Keeping that project under the repository lets normal Node and TypeScript ancestor lookup find `node_modules`, package metadata, and tool caches without brittle `paths` shims. OS temp directories remain acceptable for unit probes that do not type-check or import generated project graphs.
+
+The runner should perform these steps:
+
+1. Compile the row fixture with `loadWsdl`, `resolveCompilerOptions`, and `compileCatalog`.
+2. Generate client artifacts into `<temp>/client`.
+3. Write `<temp>/client/catalog.json` with `generateCatalog`.
+4. Type-check generated client artifacts using the existing temporary `tsconfig.json` pattern.
+5. Generate OpenAPI into `<temp>/openapi.json` with validation enabled.
+6. Generate gateway artifacts into `<temp>/gateway` with `generateGateway`.
+7. Pass `clientDir`, `catalogFile`, `versionSlug`, and `serviceSlug` to `generateGateway`.
+8. Type-check generated client and gateway artifacts together.
+9. Dynamically import `<temp>/gateway/plugin.ts`.
+10. Register the plugin with `Fastify({logger: false})` and the row's mock operations client.
+11. Resolve each request path from the generated OpenAPI operation when possible.
+12. Execute `fastify.inject` and run row-specific status and body assertions.
+
+Use stable gateway options unless a row declares a reason to override them:
+
+```ts
+await generateGateway({
+  openapiFile,
+  outDir: gatewayDir,
+  clientDir,
+  catalogFile,
+  versionSlug: "v1",
+  serviceSlug: "conformance",
+});
+```
+
+Keep service and version slugs deterministic. Do not derive slugs from temporary paths.
+
+### Phase 3 Registry Scope
+
+Add `gateway` expectations only to rows that already have successful compile, client, and OpenAPI expectations.
+
+Rows expected to receive gateway evidence in this slice:
+
+- `choice-union-simple`
+- `xs-union-simple-type`
+- `multi-binding-first-soap`
+- `external-policy-reference`
+- `deep-composition-sequence`
+- `xs-anyattribute`
+
+Rows that must not receive gateway evidence in this slice:
+
+- `abstract-complex-type`
+- `substitution-group-element`
+- `mtom-xop-attachment`
+
+### Phase 3 Assertion Guidance
+
+Every row with a `gateway` expectation should at least prove plugin import and registration. Add request assertions when HTTP behavior is part of the row's public contract.
+
+For supported rows, prefer one accepted request with a SOAP-wrapper-shaped mock response and an assertion on the generated success envelope. Add one rejected request only when the generated OpenAPI schema can express a meaningful invalid payload for that capability.
+
+For partial rows, prove the documented subset and avoid implying full support. For `xs-anyattribute`, gateway evidence should prove generation and runtime do not emit or require wildcard attribute bags. For external `PolicyReference`, gateway evidence should prove no generated inbound security requirement appears unless configured elsewhere.
+
+For multi-binding rows, assert that the gateway route calls the operation selected by the deterministic first SOAP binding behavior. Do not implement explicit binding selection in this slice.
+
+### Phase 3 Non-Goals
+
+- Do not add new WSDL feature rows.
+- Do not add a public inspector command.
+- Do not change generated gateway public APIs unless gateway evidence exposes a real bug.
+- Do not snapshot whole generated files.
+- Do not treat plugin generation alone as runtime support.
+- Do not proceed past compile for diagnostic or unsupported rows.
+
+### Phase 3 Acceptance Criteria
+
+- `CapabilityCase` supports optional gateway expectations.
+- `test/conformance/conformance.test.ts` requires gateway expectations for supported and partial rows.
+- `runGatewayCase` generates client, catalog, OpenAPI, and gateway artifacts in a row-local temp directory.
+- Generated client and gateway artifacts type-check together.
+- Generated plugins import and register successfully in Fastify.
+- Gateway request expectations run through `fastify.inject`.
+- Diagnostic and unsupported rows remain compile-terminal.
+- `npm run test:conformance` passes.
+- `npm run typecheck` passes.
+- `npm run docs:validate` passes after any support matrix or roadmap updates.
+
+### Phase 3 Test-First Sequence
+
+Start by adding the type fields, the downstream declaration guard, and the `runGatewayCase` test call. The first focused run of `npm run test:conformance` should fail because registry rows do not yet declare gateway expectations or because the runner is not implemented.
+
+Then implement the runner helper and add the smallest gateway expectations per row. Keep failures local: if one row exposes a real gateway bug, either fix the bug with focused tests or downgrade the row's public contract only when the decision framework supports that change.
+
+### Phase 3 Verification Commands
+
+Run these commands before concluding the slice:
+
+```bash
+npm run test:conformance
+npm run typecheck
+npm run docs:validate
+npm test
+```
 
-- Supported gateway rows register generated plugins successfully.
-- Valid request fixtures return expected envelopes or streams.
-- Invalid request fixtures fail with expected status codes.
-- Stream rows prove NDJSON and JSON array behavior separately.
+Run `npm run smoke:pipeline` as a final end-to-end guard if gateway generator behavior changes outside the conformance runner.
 
 ## Phase 4: Generated Test And App Evidence
 

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

@@ -1,10 +1,10 @@
 # Version 1.0 WSDL Coverage Matrix
 
-Status: client and OpenAPI evidence shipped; gateway runtime evidence remaining before `1.0.0`.
+Status: gateway runtime evidence shipped; generated-test and app evidence remaining before `1.0.0`.
 
 Plan for turning WSDL and XSD support claims into automated, fixture-backed evidence before 1.0. This is the first domain under the [Capability Conformance Framework](v1.0-capability-conformance-framework.md).
 
-The initial fixture-backed compile matrix shipped in `0.30.2` and `0.30.3`. Client and OpenAPI evidence now prove the current supported and partial rows, and terminal rows have executable diagnostics. The remaining work is to prove generated gateway runtime artifacts and keep public support claims tied to registry rows.
+The initial fixture-backed compile matrix shipped in `0.30.2` and `0.30.3`. Client, OpenAPI, and gateway runtime evidence now prove the current supported and partial rows, and terminal rows have executable diagnostics. The remaining work is to prove generated-test and app artifacts where those surfaces are part of the contract.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
@@ -23,14 +23,15 @@ Each matrix row should have a minimal fixture, an expected support status, and a
 - `test/conformance/conformance.test.ts` runs compile-stage expectations for runnable rows.
 - Supported and partial rows generate client artifacts that type-check.
 - Supported and partial rows generate validated OpenAPI specs with targeted contract assertions.
+- Supported and partial rows generate gateway artifacts that type-check and run through Fastify injection.
 - Diagnostic and unsupported rows have executable compiler error expectations.
 - `docs/supported-patterns.md` includes a generated capability evidence matrix.
 - `npm run docs:support-matrix:check` prevents support matrix drift.
 
 ## Remaining Scope
 
-- Add stage expectations for generated gateway output and runtime behavior.
-- Add generated request and response fixtures where HTTP behavior is part of a capability contract.
+- Add stage expectations for generated tests and app scaffolds where those surfaces are part of a capability contract.
+- Add generated request and response fixtures for generated-test coverage where HTTP behavior is part of a capability contract.
 - Keep diagnostics executable as more unsupported rows are added.
 - Keep fixture metadata useful for a future public conformance fixture corpus.
 - Preserve the weather smoke fixture as the canonical end-to-end happy path.
@@ -104,20 +105,46 @@ Ensure every documented unsupported or partial feature has a corresponding matri
 - No known feature silently miscompiles in matrix coverage.
 - The matrix can run in CI or release preflight without network access.
 
-## Next Slice
+## Gateway Runtime Evidence
 
-The next slice should implement Phase 3 gateway runtime evidence for the current registry rows before adding more feature rows. This keeps the matrix honest: support claims become pipeline evidence, while diagnostic and unsupported claims remain stopped before downstream generation.
+Phase 3 gateway runtime evidence is shipped for the current supported and partial rows. The current matrix now proves the WSDL to client to OpenAPI to Fastify path for rows that claim support or partial support.
 
-Work items:
+Use [Capability Conformance Framework](v1.0-capability-conformance-framework.md) as the detailed implementation baseline. This section defines the WSDL-matrix-specific shipped scope.
+
+### Phase 3 Shipped Scope
+
+- Optional `gateway` expectations exist in the conformance type model.
+- Gateway artifacts are generated from each relevant row's OpenAPI document.
+- The generated `catalog.json` is written before gateway generation.
+- Generated gateway artifacts type-check with the generated client artifacts.
+- Mock operations clients and `fastify.inject` assertions cover HTTP behavior.
+- Diagnostic and unsupported rows stop at compile.
+- The generated public support matrix remains status-focused.
+
+### Phase 3 Row Scope
+
+Rows that should gain gateway evidence:
+
+- `choice-union-simple`
+- `xs-union-simple-type`
+- `multi-binding-first-soap`
+- `external-policy-reference`
+- `deep-composition-sequence`
+- `xs-anyattribute`
+
+Rows that should stay compile-terminal:
+
+- `abstract-complex-type`
+- `substitution-group-element`
+- `mtom-xop-attachment`
+
+### Phase 3 Runtime Expectations
+
+Each gateway-enabled row should prove plugin import, plugin registration, and at least one `fastify.inject` request when route behavior is relevant. Assertions should inspect the generated success or error envelope, not just the existence of generated files.
 
-- Add optional `gateway` expectations to the conformance type model.
-- Generate gateway artifacts from each relevant row's OpenAPI document.
-- Type-check generated gateway artifacts with the generated client artifacts.
-- Add mock operations clients and `fastify.inject` assertions where request or response behavior is part of the contract.
-- Leave diagnostic and unsupported rows stopped at compile.
-- Update the generated public support matrix only when a row status or public contract changes.
+Partial rows must prove only the documented subset. `xs:anyAttribute` should not imply generated wildcard attribute bags. External `PolicyReference` should not imply fetched or enforced external policy.
 
-Gotchas:
+### Phase 3 Gotchas
 
 - Do not overclaim `supported` when gateway behavior is relevant but unproven.
 - Do not snapshot whole generated files for conformance rows; assert stable contract surfaces instead.
@@ -125,6 +152,32 @@ Gotchas:
 - Do not let diagnostic or unsupported rows proceed to client, OpenAPI, or gateway generation.
 - Do not add a public inspector command in this slice.
 
+### Next Slice
+
+The next slice is Phase 4 generated-test and app evidence. Implement it before adding more feature rows unless a production bug requires a focused diagnostic or support decision.
+
+Work items:
+
+- Add optional generated-test expectations for rows where `--test-dir` behavior is part of the contract.
+- Generate app scaffolds for rows where app wiring is affected by the capability.
+- Type-check generated app artifacts when an app expectation is present.
+- Run generated tests only for rows that request generated-test evidence.
+- Keep diagnostic and unsupported rows stopped at compile.
+- Update public docs only when a row status or public contract changes.
+
+### Verification
+
+Run these commands before the slice is considered ready:
+
+```bash
+npm run test:conformance
+npm run typecheck
+npm run docs:validate
+npm test
+```
+
+Run `npm run smoke:pipeline` if the gateway generator or pipeline behavior changes.
+
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.31.0",
+  "version": "0.32.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",