@techspokes/typescript-wsdl-client 1.1.5 → 1.1.8

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

@@ -1,582 +0,0 @@
-# Version 1.0 Capability Conformance Framework
-
-Status: Phase 5 shipped; release-candidate gate pass 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. Phase 3 added generated gateway type-checking and Fastify runtime evidence for current supported and partial rows. Phase 4 added generated-test and app scaffold evidence for those rows. Phase 5 wired conformance into validation gates through broad Vitest discovery and release preflight script verification.
-
-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 internal conformance framework that proves what each important SOAP and WSDL capability does across the full generation pipeline. A capability claim is not complete until the relevant compile, client, OpenAPI, gateway, app, generated-test, runtime, and documentation surfaces either pass or fail with an explicit diagnostic.
-
-The framework should also give maintainers a repeatable issue triage path. When a user reports that a WSDL pattern does not work, maintainers should be able to reduce the report to a fixture, add a matrix row, run the conformance suite, and state exactly which stage supports, rejects, or partially supports that pattern.
-
-## Values To Preserve
-
-- Preserve deterministic generated output.
-- Preserve strict TypeScript and NodeNext behavior.
-- Preserve the current smoke fixture as the canonical happy path.
-- Prefer small minimized fixtures over large real-world WSDL files.
-- Prefer diagnostics and documented deferrals over silent miscompilation.
-- Keep generated gateway behavior proven through Fastify, not only snapshots.
-- Keep OpenAPI behavior proven through schema assertions and validation.
-- Keep docs aligned with machine-readable capability IDs.
-- Avoid new dependencies unless the existing toolchain cannot provide the evidence.
-- Keep public CLI changes separate from internal conformance infrastructure.
-
-## Capability Model
-
-A capability is a named repository behavior that can be detected, documented, and tested. Examples include `xs:choice` union mode, JSON array streaming, external `PolicyReference`, abstract complex types, substitution groups, multi-binding WSDLs, and MTOM/XOP attachments.
-
-Each capability should have a stable ID, a status, one or more fixtures, and per-stage expectations. The status describes the product contract. The stage expectations describe how the repository proves the contract.
-
-## Capability Statuses
-
-- `supported`: the capability works through every relevant stage.
-- `partial`: the capability has deliberate limits that docs must describe.
-- `diagnostic`: the capability is rejected or warned about clearly.
-- `unsupported`: the capability is intentionally out of scope.
-- `research`: the capability needs fixture evidence before a final status.
-
-## Stage Expectations
-
-Each matrix row should declare only the stages that apply to that capability. A diagnostic row might stop at compile. A supported gateway feature should prove compile, client, OpenAPI, gateway, and runtime behavior.
-
-### Compile Stage
-
-The compile stage proves WSDL loading, schema compilation, catalog shape, and diagnostics. Assertions should prefer catalog metadata and structured errors over brittle full generated-file comparisons.
-
-### Client Stage
-
-The client stage proves generated `types.ts`, `operations.ts`, `client.ts`, and helpers type-check under the repository TypeScript settings. Capability-specific assertions should inspect generated types only where the type shape is part of the public contract.
-
-### OpenAPI Stage
-
-The OpenAPI stage proves the generated spec validates and uses the expected schema strategy. Assertions should cover schema shape, media types, operation metadata, extensions such as `x-wsdl-tsc-stream`, and security output where relevant.
-
-### Gateway Generation Stage
-
-The gateway generation stage proves route, schema, runtime, plugin, and type-check fixture output can be generated from the OpenAPI result. Assertions should cover route registration shape and generated helper selection when those are part of the capability contract.
-
-### Gateway Runtime Stage
-
-The gateway runtime stage proves generated Fastify routes with a mock operations client behave correctly under `fastify.inject`. Assertions should cover valid requests, invalid requests, response envelopes, response content types, stream formats, and terminal-error behavior where relevant.
-
-### App Stage
-
-The app stage proves the standalone app scaffold can consume the generated gateway when the capability affects app wiring, package dependencies, environment variables, or gateway plugin registration. Most rows can skip this stage unless the capability changes app behavior.
-
-### Generated Test Stage
-
-The generated test stage proves `--test-dir` emits tests that compile and pass for supported capabilities. It should also prove generated tests include capability-specific invalid cases when request validation is part of the contract.
-
-### Documentation Stage
-
-The documentation stage proves `docs/supported-patterns.md` agrees with the capability registry. It should prevent docs from claiming support, partial support, or non-support without a matching conformance row.
-
-The public evidence matrix in `docs/supported-patterns.md` should be generated from registry rows. The rest of the page should remain human-authored so supported-pattern explanations stay useful to readers.
-
-## Registry Shape
-
-The first implementation should use a TypeScript manifest because tests can import it with full type safety. JSON can be added later if external tooling needs a stable data format.
-
-```ts
-declare const capabilities: CapabilityCase[];
-
-interface CapabilityCase {
-  id: string;
-  title: string;
-  status: "supported" | "partial" | "diagnostic" | "unsupported" | "research";
-  featureTags: string[];
-  fixture: string;
-  docsAnchor?: string;
-  publicContract: string;
-  stages: CapabilityStages;
-}
-```
-
-Stage payloads should stay small and explicit. Avoid a generic assertion language in the first version; use typed expectation objects and small runner helpers instead.
-
-## Standards And External Corpus
-
-Use WSDL 1.1, SOAP 1.1, XML Schema 1.0, and WS-I Basic Profile as the authority stack for Phase 1 capability expectations.
-
-WSDL 1.1 defines the service description model used by this project: `types`, `message`, `portType`, `binding`, `port`, and `service`, plus SOAP 1.1, HTTP, and MIME binding extensions.
-
-SOAP 1.1 defines the envelope and processing model that generated clients ultimately target through `node-soap`.
-
-XML Schema 1.0 defines the schema constructs compiled into TypeScript and OpenAPI shapes. XML Schema 1.1 test suites are useful as edge-case inspiration, but the project should not imply full XML Schema 1.1 support.
-
-WS-I Basic Profile 1.1 and 1.2 define interoperability constraints across SOAP, WSDL, XML Schema, and HTTP. Treat WS-I rules as the best available profile for portable SOAP behavior, not as a complete fixture source.
-
-Do not vendor third-party WSDL or XSD corpora wholesale in Phase 1. Prefer minimized synthetic fixtures derived from standard rules and clearly cite the relevant standard or profile section in the registry row.
-
-Third-party suites can inform future rows:
-
-- W3C WSDL 2.0 Test Suite: useful for conformance-suite structure, but not directly applicable to this WSDL 1.1 generator.
-- W3C XML Schema test suite: useful for XSD edge-case discovery, but it validates schema processors rather than WSDL-to-client generation.
-- WS-I test assertions and analyzer tools: useful for interoperability rule vocabulary, but heavy and not a direct TypeScript generation oracle.
-- Apache Axis or Apache CXF sample WSDL files: useful as real-world smoke candidates when license and fixture scope are clear.
-
-## Public Fixture Corpus Direction
-
-The conformance framework should be designed so its fixtures can later seed a standalone public project, tentatively named `wsdl-conformance-fixtures`.
-
-The public fixture project would be an experimental, curated corpus of small WSDL and XSD fixtures for SOAP client and code-generation tools. It should not claim to be an official standards' suite. It should provide practical, source-backed examples for valid, partial, diagnostic, unsupported, recovery, and real-world-compatible behaviors.
-
-The public corpus should preserve clean licensing and clear provenance. Do not copy external corpora wholesale. Prefer original minimized fixtures derived from standards, profiles, and observed real-world patterns.
-
-Phase 1 should add metadata that will make extraction possible later without changing every row:
-
-- `authority`: the standard, profile, or real-world source category behind the case.
-- `provenance`: a short explanation of whether the fixture is original, minimized from a report, or inspired by a third-party example.
-- `license`: the fixture license or repository default license.
-- `fixtureKind`: one of `standards-valid`, `interop-profile`, `real-world-compatible`, `diagnostic-required`, or `recovery`.
-
-Do not publish the standalone fixture project before the internal registry has proven the metadata shape with multiple useful rows. The first public release should happen only after maintainers can explain how another tool would consume the fixtures without depending on this repository's internals.
-
-## Fixture Corpus Goals
-
-The internal corpus should serve this repository first. It should make generator behavior explicit, prevent silent miscompilation, and give maintainers a repeatable way to classify WSDL reports.
-
-The future public corpus should serve the SOAP tooling community. It should offer small, understandable fixtures that other generators, validators, and migration tools can run against or inspect.
-
-The corpus should distinguish standards conformance from product policy. A fixture can be standards-valid while unsupported by this generator, or non-ideal but common enough to justify recovery behavior.
-
-The corpus should be useful without a live network. Every fixture should be committed with local relative imports and no dependency on public SOAP endpoints.
-
-The corpus should be explainable. Each fixture should say what behavior it exercises, what source justifies the expectation, and which outcomes are acceptable.
-
-## Decision Framework
-
-Use this framework before changing a capability from `research` to a final status. The decision should optimize for truthful generation, deterministic output, and maintainable SOAP modernization rather than broad standards' completeness.
-
-First decide whether the construct is important enough for this project. Favor support when the feature is common in WSDLs, important for enterprise modernization, or already required by existing generated outputs. Favor deferral when the feature is rare, can be worked around, or requires a runtime contract outside the current product surface.
-
-Then decide whether the construct can be modeled honestly in `catalog.json`. If the catalog can represent the shape without losing semantics, support or partial support may be appropriate. If the catalog hid polymorphism, transport behavior, binary parts, external network policy, or runtime ambiguity, prefer a diagnostic or unsupported decision.
-
-Then check downstream stages. A `supported` row must work through every relevant stage. A feature that compiles but cannot be represented in generated TypeScript, OpenAPI, gateway runtime, or generated tests should be `partial` unless those stages do not apply.
-
-Then check implementation locality. Local schema transforms such as simple aliases, deterministic metadata retention, and documented first-choice behavior are good support candidates. Features that require broad runtime semantics, wire-protocol changes, or public API design should usually become diagnostics or explicit deferrals before 1.0.
-
-Use these decisions:
-
-- `support`: implement and prove the feature through relevant stages.
-- `partial-support`: implement the honest subset and document the limit.
-- `diagnostic`: reject or warn clearly to avoid silent miscompilation.
-- `defer`: keep a fixture and rationale, but do not claim support yet.
-- `out-of-scope`: document that the feature is intentionally outside the 1.0 product contract.
-
-When full support is clearly local, deterministic, and representable, implement it rather than leaving unnecessary diagnostics. When full support would imply semantics the generator cannot preserve, prefer diagnostics to partial, misleading output.
-
-## Phase 1 Decisions
-
-Phase 1 shipped in the `0.30.x` line. Keep this section as the historical baseline and as guardrails for future registry changes.
-
-Phase 1 is internal test infrastructure. It must not add exports from `src/index.ts`, new public CLI commands, or new consumer-facing APIs.
-
-The first registry should live under `test/conformance/registry.ts`. It should export types and data for repository tests only. Public package exports can be reconsidered after the inspector has a stable use case.
-
-The first runner should live under `test/conformance/runner.ts`. It should execute compile-stage checks by calling `loadWsdl`, `compileCatalog`, and `resolveCompilerOptions` directly.
-
-The first Vitest entry point should be `test/conformance/conformance.test.ts`. Add `npm run test:conformance` and keep it included in `npm test` through Vitest's normal test discovery.
-
-Fixtures should live under `test/conformance/fixtures/`. Each fixture should be a committed `.wsdl` or `.xsd` file, use relative files only, and require no network access.
-
-Documentation drift checks should start as a lightweight test in `test/conformance/docs.test.ts`. The test should verify that each registry row with a `docsAnchor` points to an existing heading anchor in `docs/supported-patterns.md`.
-
-The public evidence matrix should be generated from the registry with `npm run docs:support-matrix`. The check command should fail when the generated table and committed table drift.
-
-## Phase 1 File Map
-
-The Phase 1 file map is implemented. Keep these ownership boundaries in place while extending the framework.
-
-`test/conformance/types.ts` owns shared registry types. Keep these types out of `src/` until a public API is justified.
-
-`test/conformance/registry.ts` owns the initial capability rows. Include new priority features from the WSDL coverage matrix here before changing generator behavior.
-
-`test/conformance/runner.ts` owns compile-stage execution helpers. Resolve fixture paths relative to `test/conformance/fixtures/` and create one temporary output directory per case under the OS temp directory.
-
-`test/conformance/conformance.test.ts` owns manifest-driven compile tests. Supported and partial rows should compile successfully; diagnostic rows should assert the error shape or explicit warning behavior.
-
-`test/conformance/docs.test.ts` owns registry-to-docs alignment. It should validate existing heading anchors and prove that the public evidence matrix matches generated registry output.
-
-`test/conformance/fixtures/` contains minimal WSDL fixtures. Keep each fixture synthetic, deterministic, and scoped to one capability.
-
-`package.json` exposes `test:conformance` with `vitest run test/conformance`.
-
-Modify `docs/supported-patterns.md` only when the registry reveals a real mismatch. Generate only the evidence matrix from the registry in Phase 1; do not rewrite the explanatory sections from registry data.
-
-## Phase 1 Type Contract
-
-Use these internal test types as the starting point:
-
-```ts
-export type CapabilityStatus = "supported" | "partial" | "diagnostic" | "unsupported" | "research";
-
-export type CompileExpectation =
-  | { outcome: "success"; typeNames?: string[]; aliasNames?: string[]; operationNames?: string[]; diagnosticNotes?: string[] }
-  | { outcome: "error"; errorClass?: "WsdlCompilationError"; messageIncludes?: string[]; userMessageIncludes?: string[]; context?: Partial<WsdlErrorContext> }
-  | { outcome: "research"; reason: string };
-
-export interface CapabilityCase {
-  id: string;
-  title: string;
-  status: CapabilityStatus;
-  featureTags: string[];
-  fixture: string;
-  docsAnchor?: string;
-  publicContract: string;
-  decision: CapabilityDecision;
-  decisionReason: string;
-  compile: CompileExpectation;
-}
-```
-
-`docsAnchor` values should use the same heading slug rules as the repository docs validator. Phase 1 may point rows to broad section anchors such as `fully-supported`, `partially-supported`, `not-yet-supported`, or `known-edge-cases`. Add feature-level headings to `docs/supported-patterns.md` only when a broad section anchor is too ambiguous for a row.
-
-`error` expectations should assert `instanceof WsdlCompilationError` when `errorClass` is `WsdlCompilationError`. `messageIncludes` checks should inspect `error.message`, `userMessageIncludes` checks should inspect `error.toUserMessage()`, and `context` checks should inspect `error.context`.
-
-`unsupported` rows should not silently pass. They should either use an `error` compile expectation or remain `research` until a diagnostic exists.
-
-`partial` rows should compile successfully only when the limitation is explicitly documented. The row should include a `docsAnchor` and an assertion that proves the supported subset.
-
-`research` rows should not pretend to validate support. They should load the fixture only if useful, then state the unresolved decision in the registry.
-
-## Phase 1 Conventions
-
-Prefer committed fixture files over inline WSDL strings. Inline WSDL builders are useful for focused unit tests, but conformance cases should be inspectable as standalone artifacts.
-
-Use the taxonomy path convention in [File Naming And Path Organization](../file-naming-and-path-organization.md) for reusable fixtures. Put imported schemas beside the root WSDL when a capability needs multiple files.
-
-Use a runner-owned temporary directory per capability case. Do not share a module-level temp root across the suite, because conformance failures should leave case-local paths easy to inspect.
-
-Assert catalog shape through stable names and metadata. Avoid full catalog snapshots in Phase 1 because the registry should describe capability contracts, not freeze incidental serialization details.
-
-Assert diagnostics through `WsdlCompilationError` and catalog `diagnostics.notes`. Do not assert full formatted messages unless the exact text is part of the public contract.
-
-Prefer adding feature-level headings in `docs/supported-patterns.md` when a broad section anchor would make the docs check too weak. Keep those headings short and user-facing.
-
-## Fixture Strategy
-
-Fixtures should live under a dedicated conformance fixture directory, separate from the weather smoke fixture. Each fixture should be minimal, synthetic, deterministic, and focused on one capability unless the purpose is to prove a composition case.
-
-Reported user WSDLs should not be committed wholesale by default. Maintainers should reduce them to the smallest reproducible fixture and remove private endpoints, credentials, business names, and proprietary type names.
-
-## Fastify Gateway Testing Pattern
-
-Gateway conformance rows should generate the gateway into a temporary directory, import the generated plugin, provide a mock operations client, and call routes with `fastify.inject`. This proves the generated gateway works as a Fastify integration, not just as emitted text.
-
-Supported request-validation capabilities should include at least one accepted request and one rejected request when the schema can represent invalid input. Response capabilities should assert envelope shape, status code, content type, and serialized payload.
-
-Streaming capabilities should assert the configured content type, NDJSON or JSON array parsing behavior, and terminal-error behavior. JSON array rows should keep the pre-first-record and post-first-byte error cases distinct.
-
-## Issue Triage Workflow
-
-When a user reports a WSDL incompatibility, maintainers should first run or approximate the future inspector output. The report should be classified by capability IDs before generator code changes are considered.
-
-The triage flow should be:
-
-1. Reduce the reported WSDL to a minimal fixture.
-2. Add or update a capability row.
-3. Mark the row as `research`, `diagnostic`, `partial`, or `supported`.
-4. Run the relevant conformance stages.
-5. Decide whether to implement support, add diagnostics, or document a deferral.
-6. Link the issue to the capability ID in the changelog or release notes when behavior changes.
-
-## WSDL Inspector Direction
-
-The WSDL inspector should be built after the first conformance registry exists. It should reuse the same capability IDs and statuses rather than maintaining a separate feature list.
-
-The inspector should analyze a WSDL and report detected patterns, support status, known limitations, and suggested workarounds. It should have a JSON output for CI and issue templates, and a Markdown or text output for humans.
-
-The inspector should not be treated as proof that generation will succeed. It is an orientation and triage tool. The conformance runner remains the proof mechanism.
-
-## Inspector Research Questions
-
-- Which feature signals are visible in the raw WSDL and XSD AST before compilation?
-- Which feature signals require the compiled catalog?
-- Which current limitations silently compile and need diagnostics first?
-- Which recommendations can be stable enough for user-facing output?
-- Which output shape should be public if the inspector becomes a CLI command?
-
-## Phase 1: Registry And Compile Matrix
-
-The capability registry, fixture directory, and Vitest runner for compile-stage expectations are implemented. Keep unsupported rows diagnostic or research-only until behavior is proven.
-
-Start with these capability IDs:
-
-| ID | Status | Compile expectation |
-|---|---|---|
-| `choice-union-simple` | supported | success |
-| `xs-union-simple-type` | supported | success |
-| `abstract-complex-type` | diagnostic | error or research |
-| `substitution-group-element` | diagnostic | error or research |
-| `multi-binding-first-soap` | partial | success with documented behavior |
-| `external-policy-reference` | partial | success with documented limitation |
-| `deep-composition-sequence` | supported | success |
-| `xs-anyattribute` | supported | success with wildcard attribute bag evidence |
-| `mtom-xop-attachment` | unsupported | error or research |
-
-Acceptance criteria:
-
-- The registry includes every priority row from the WSDL coverage slice.
-- Each row has a stable ID, status, fixture, and compile expectation.
-- `docs/supported-patterns.md` has matching capability IDs or anchors.
-- The runner works without network access.
-- `npm run test:conformance` passes.
-- `npm test` includes the conformance suite.
-- No Phase 1 change expands the public API.
-
-## Phase 2: Client And OpenAPI Evidence
-
-Phase 2 is implemented for the current supported and partial WSDL rows. Keep this section as the baseline for future client and OpenAPI evidence.
-
-Extend supported rows to generate clients and OpenAPI specs. Add type-check verification for generated clients and schema assertions for OpenAPI output.
-
-Acceptance criteria:
-
-- Supported rows type-check generated client output.
-- OpenAPI specs validate for supported rows.
-- Capability-specific schema strategies are asserted where they matter.
-- Diagnostic rows stop before downstream stages.
-
-Recommended scope:
-
-- Add optional `client` and `openapi` expectation blocks to `CapabilityCase`.
-- Generate artifacts into a temporary directory owned by each capability row.
-- Emit a temporary `tsconfig.json` that includes generated client artifacts and uses repository NodeNext settings.
-- Validate OpenAPI documents through the same validator used by existing OpenAPI tests.
-- Assert public schema contracts for rows that already claim support or partial support.
-
-Skeptical review notes:
-
-- A `supported` status should not rely on compile-only evidence after this phase.
-- `diagnostic` rows currently using `research` compile expectations need either real diagnostics or clearer deferral language.
-- Whole-file snapshots would make conformance brittle; prefer targeted assertions on generated types, schemas, paths, and operation metadata.
-- The support matrix generator should remain limited to the public evidence table, not the human-authored explanatory sections.
-- Keep the inspector out of this slice unless the stage evidence reveals a stable detection model.
-
-## Phase 3: Gateway Runtime Evidence
-
-Phase 3 is implemented for the current supported and partial WSDL rows. Keep this section as the baseline for future gateway conformance rows.
-
-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. External `PolicyReference` should not imply fetched or enforced external policy. The `xs-anyattribute` row is supported once generated TypeScript, OpenAPI, gateway, generated-test, and app evidence prove the configured wildcard attribute bag.
-
-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
-```
-
-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
-
-Phase 4 is implemented for the current supported and partial WSDL rows. Keep this section as the baseline for future generated-test and app conformance rows.
-
-Extend relevant rows to generate `--test-dir` output and app scaffolds. Run generated tests only for rows where generated-test behavior is part of the capability contract.
-
-Generated-test and app evidence must consume generated artifacts as a consumer would. Route paths, operation IDs, schemas, and app wiring must come from generated OpenAPI, gateway, test, and app files. Do not add conformance-only route overrides or fixture-specific route maps to make generated tests pass.
-
-Acceptance criteria:
-
-- Generated tests pass for supported rows that request them.
-- Generated validation tests include capability-specific invalid cases.
-- App scaffolds type-check when the capability affects app wiring.
-- Runtime dependency assumptions stay aligned with `package.json`.
-- Generated app `tsconfig.json` covers sibling client and gateway artifacts when those folders are outside the app directory.
-- Diagnostic and unsupported rows remain compile-terminal.
-
-## Phase 5: Documentation And Release Gates
-
-Phase 5 is implemented. Keep this section as the baseline for conformance gate ownership.
-
-`npm run test:conformance` remains the complete maintainer command for WSDL capability rows. Stage commands under `test:conformance:<stage>` provide contracts, compile, client, OpenAPI, gateway, generated-test, and app feedback without running unrelated evidence layers. `npm test` and `npm run ci` cover the canonical full suite through broad Vitest discovery, so release preflight does not run a duplicate full conformance pass. Release preflight instead runs a cheap `conformance-gate` script check that fails if the full command disappears, if `npm test` becomes scoped away from `test/conformance`, or if `npm run ci` stops running the broad test command.
-
-The complete suite generates consumer-style projects and launches nested TypeScript and Vitest processes. A maintained Windows run takes about three to four minutes. Maintainers and agents should allow at least six minutes and inspect the active process before diagnosing a quiet interval as a stall.
-
-Acceptance criteria:
-
-- `docs/supported-patterns.md` cannot drift from the registry.
-- CI runs conformance through broad Vitest discovery.
-- Release preflight verifies conformance command and CI wiring.
-- Full conformance can run locally before `1.0.0`.
-- Release notes can cite capability IDs for behavior changes.
-
-## Post-1.0 WSDL Inspector
-
-The WSDL inspector is explicitly deferred until after `1.0.0`. Build it after the registry has enough stable coverage to be useful, starting with a programmatic API and internal CLI output before committing to public command semantics.
-
-Acceptance criteria:
-
-- The inspector maps detected WSDL patterns to capability IDs.
-- JSON output is stable enough for issue templates.
-- Human output includes status, limitation, and workaround text.
-- Inspector findings link back to matrix evidence.
-
-## Post-1.0 Decisions
-
-- Decide whether an inspector output format should become public.
-- Decide whether docs should remain manually maintained or eventually generated from the registry.
-
-## Release Implications
-
-This framework is 1.0 readiness infrastructure. Stage-specific maintainer commands ship in `0.40.1`, while the canonical full suite stays release-blocking.
-
-Do not block `1.0.0` on the WSDL inspector. The registry and runner create the durable foundation; the post-1.0 inspector should reuse that foundation after it proves useful.