@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/docs/decisions/001-test-generation.md

@@ -1,36 +0,0 @@
-# ADR 001: Generated Test Suite for Gateway Artifacts
-
-## Status
-
-Accepted
-
-## Context
-
-Users of generated Fastify gateways have no automated way to verify the generated code works. The only testing path is to manually write Vitest tests following the pattern in this project's own `test/integration/gateway-routes.test.ts`. The FST_ERR_FAILED_ERROR_SERIALIZATION bug (fixed in 0.11.1) proved that generated code can have subtle runtime issues that only surface under specific conditions. Generated tests would catch these immediately.
-
-## Decision
-
-Add an opt-in `--test-dir` flag to the pipeline command that generates a complete, runnable Vitest test suite validating all generated gateway artifacts.
-
-### Why generated tests (not a test library)
-
-A reusable test library would require users to configure imports, mock data, and test structure themselves. Generated tests are zero-config: they import the exact generated modules with correct relative paths, use mock data derived from the actual catalog types, and run immediately with `npx vitest run`.
-
-### Why full mocks (not placeholders)
-
-Placeholder mocks (empty objects, `TODO` comments) require manual effort before tests pass. Full mocks generated from catalog type metadata produce passing tests out of the box. Property names and types come from the compiled catalog's `meta.childType` map, so mock data matches the actual SOAP response shape.
-
-### Why skip-if-exists
-
-Test files are meant to be customized after generation. Re-running the pipeline should not overwrite user modifications. The `--force-test` flag provides an explicit override when regeneration is desired.
-
-### Relationship to operations.ts interface
-
-The generated `{ClassName}Operations` interface (from `operations.ts`) is the natural seam for mock injection. The mock client helper implements this interface with full default responses per operation. This matches the pattern established in `test/integration/gateway-routes.test.ts`.
-
-## Consequences
-
-- Users get immediate test coverage for generated gateway code
-- Mock data stays in sync with WSDL schema changes (regenerate to update)
-- Test files can be customized without risk of overwrite
-- Additional CLI flag and pipeline step increase the surface area to maintain

package/docs/decisions/002-streamable-responses.md

@@ -1,330 +0,0 @@
-# ADR 002: Streamable SOAP Responses and JSON Gateway Output
-
-Proposal for opt-in streamable SOAP response support, with Escapia EVRN Content Service as the concrete driver.
-
-See the root [README](../../README.md) for the authoritative documentation index and [Architecture](../architecture.md) for the current generator pipeline.
-
-## Status
-
-Accepted (2026-04-20). Implementation shipped in 0.17.0 across five phases
-(Phase 0 research → Phase 5 integration). See
-`scratches/plans/v017/streamable-responses.plan.yaml` for phase-by-phase
-notes and verification gates.
-
-## Context
-
-The current generator handles WSDL operations as buffered request and response calls. A generated client method awaits the SOAP runtime callback, receives a fully materialized result object, and returns `{ response, headers, responseRaw, requestRaw }`. The generated OpenAPI document describes each operation as `application/json`. The generated Fastify route calls the client method, optionally unwraps array wrapper types, and returns the standard response envelope.
-
-Escapia exposes two related SOAP services:
-
-- `EVRNService` contains the normal operation and type model.
-- `EVRNContentService` contains content-oriented operations that are intended for large responses.
-
-The Escapia content WSDL includes stream-like operations such as `UnitDescriptiveInfoStream` and `UnitCalendarAvailBatch`. Their output wrapper types contain schema and wildcard payload sections instead of clean concrete response members. The practical record shapes come from the main EVRN service WSDL, for example `UnitDescriptiveContentType` and `UnitCalendarAvailType`.
-
-This means the current package has two gaps:
-
-- It does not stream SOAP responses through generated clients or gateways.
-- It does not let users map opaque WSDL response wrappers to concrete JSON record shapes from the same or a companion WSDL.
-
-## Current Architecture Review
-
-The compile stage produces `catalog.json`, which is the only artifact that understands WSDL types, operation input and output elements, attribute metadata, child type metadata, and primitive mapping options.
-
-The client stage generates a `node-soap` wrapper. Every operation is generated as a promise-returning method. The public operations interface mirrors that buffered shape, which is useful for mocks but cannot currently express an `AsyncIterable` or stream response.
-
-The OpenAPI stage generates paths from catalog operations. It assumes every operation has a JSON request body and a JSON response body. Since version 0.7.1, successful responses are always wrapped in the standard envelope schema.
-
-The gateway stage reads the OpenAPI document first and enriches operation metadata from `catalog.json` when the catalog is available. This lets route generation stay OpenAPI-driven, but stream support needs metadata that OpenAPI alone cannot represent.
-
-The app and test generators assume ordinary JSON route responses. Generated tests use mock clients that implement the buffered operations interface.
-
-## Requirements
-
-- Existing buffered generation must remain unchanged unless a user opts in.
-- Stream support must be configurable per operation.
-- Users must be able to map an opaque output wrapper to a concrete record type.
-- Record types must be resolvable from the current catalog or from a companion catalog.
-- Gateway output must be able to emit records before the full SOAP response has arrived.
-- Generated routes must respect Node and Fastify backpressure.
-- OpenAPI output must describe the wire media type without pretending that NDJSON is a single JSON object.
-- Error handling must distinguish errors before the first byte from errors after streaming has started.
-- The feature must be testable with a local chunked SOAP server, not only static XML fixtures.
-
-## Proposed Configuration Model
-
-Add a stream configuration file passed with `--stream-config`. The same option should be available on `compile`, `client`, `openapi`, `gateway`, and `pipeline` so each stage can be run independently.
-
-```json
-{
-  "shapeCatalogs": {
-    "evrn": {
-      "wsdlSource": "https://api.escapia.com/EVRNService.svc?singleWsdl"
-    }
-  },
-  "operations": {
-    "UnitDescriptiveInfoStream": {
-      "mode": "stream",
-      "format": "ndjson",
-      "mediaType": "application/x-ndjson",
-      "recordType": "UnitDescriptiveContentType",
-      "recordPath": [
-        "UnitDescriptiveInfoStream",
-        "EVRN_UnitDescriptiveInfoRS",
-        "UnitDescriptiveContents",
-        "UnitDescriptiveContent"
-      ],
-      "shapeCatalog": "evrn"
-    },
-    "UnitCalendarAvailBatch": {
-      "mode": "stream",
-      "format": "ndjson",
-      "mediaType": "application/x-ndjson",
-      "recordType": "UnitCalendarAvailType",
-      "recordPath": [
-        "EVRN_UnitCalendarAvailBatchRS",
-        "EVRN_UnitCalendarAvailBatchRS",
-        "UnitCalendarAvails",
-        "UnitCalendarAvail"
-      ],
-      "shapeCatalog": "evrn"
-    }
-  }
-}
-```
-
-`shapeCatalogs` names additional WSDL or catalog inputs used only to resolve stream record shapes.
-
-`operations` marks specific WSDL operations as streamed. Operations not listed keep the existing buffered behavior.
-
-`recordPath` is an ordered XML element path from the SOAP body payload to the repeated record element. Duplicate local names must be allowed because Escapia uses nested elements with the same name in at least one response.
-
-`recordType` is the TypeScript and schema model to emit for each streamed record.
-
-`format` supports `ndjson` and `json-array`. `ndjson` remains the default; `json-array` is available for clients that require a single JSON array response.
-
-## CLI and Programmatic API
-
-The CLI should add `--stream-config <file>` to all generation commands. The pipeline command should pass the parsed and normalized configuration to every stage.
-
-The programmatic API should add optional stream configuration fields to:
-
-```typescript
-export interface PipelineOptions {
-  streamConfigFile?: string;
-  streamConfig?: StreamConfig;
-}
-
-export interface GenerateOpenAPIOptions {
-  streamConfigFile?: string;
-  streamConfig?: StreamConfig;
-}
-
-export interface GenerateGatewayOptions {
-  streamConfigFile?: string;
-  streamConfig?: StreamConfig;
-}
-```
-
-The compiler options should accept normalized stream metadata only when compilation needs to persist it into the catalog.
-
-## Catalog Model
-
-The compiled catalog should carry normalized stream metadata beside operation metadata:
-
-```typescript
-export interface Operation {
-  name: string;
-  inputTypeName?: string;
-  outputTypeName?: string;
-  stream?: OperationStreamMetadata;
-}
-
-export interface OperationStreamMetadata {
-  mode: "stream";
-  format: "ndjson" | "json-array";
-  mediaType: string;
-  recordPath: string[];
-  recordTypeName: string;
-  shapeCatalogName?: string;
-  sourceOutputTypeName?: string;
-}
-```
-
-The compiler should also represent wildcard schema particles explicitly. Today Escapia stream wrappers compile into misleading `xs:schema` properties and drop the wildcard payload. A better model is to retain both the schema marker and a wildcard marker so diagnostics and stream candidate detection are honest.
-
-## Shape Resolution
-
-The first implementation should support companion catalogs in one of two forms:
-
-- A `catalogFile` path for a catalog already produced by `wsdl-tsc compile`.
-- A `wsdlSource` path or URL that the pipeline compiles before normalizing stream metadata.
-
-For generated types, the MVP should copy the reachable record type graph from the companion catalog into the current generated output when there is no name collision. If a collision occurs, generation should fail with a clear diagnostic instead of silently renaming public API types.
-
-A future version can support external type imports from another generated client directory.
-
-## Client Runtime
-
-Generated clients should keep the existing buffered method signatures for ordinary operations.
-
-Stream operations should return a separate response type:
-
-```typescript
-export type StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> = {
-  records: AsyncIterable<RecordType>;
-  headers: HeadersType;
-  requestRaw?: string;
-};
-```
-
-The operations interface should use the same stream response type so generated gateway tests and user mocks can implement streaming behavior without importing the concrete SOAP client.
-
-The transport layer should be proven by a chunked integration test. If `node-soap` with stream or SAX options can deliver records incrementally, it can be used for the MVP. If it buffers before yielding, the feature must use a dedicated SOAP HTTP transport for stream operations before release.
-
-> **Phase 0 research outcome (2026-04-20):** `node-soap` **buffers** the full response before invoking the operation callback. Measured with `test/research/node-soap-streaming.test.ts` against a chunked HTTP fixture: first chunk flushed at ~48 ms, server closed at ~701 ms, node-soap callback fired at ~659 ms (~40 ms before close — that is parse time, not streaming). Generated stream operations therefore use a dedicated streaming HTTP transport emitted into the client runtime; `node-soap` remains the transport for buffered operations only. SAX streaming was validated with `saxes` 6.0.0; `test/research/sax-record-path.test.ts` chunk-fuzzes the Escapia-shaped XML (duplicate `EVRN_UnitDescriptiveInfoRS` wrappers) across every single-byte split and every byte-pair split and produces identical records each time. See `scratches/plans/v017/streamable-responses.plan.yaml` for the full findings.
-
-## XML to JSON Streaming Conversion
-
-The runtime needs a streaming XML parser. `fast-xml-parser` is suitable for buffered documents but not for this use case. A SAX-style parser should track the configured `recordPath`, build a record object as the target element closes, and yield each record immediately.
-
-The converter must reuse catalog metadata for:
-
-- XML attributes and the configured attributes key
-- Child element type lookup
-- Repeated elements
-- Nillable elements
-- Text content and `$value`
-- Primitive mapping
-
-The converter should collect SOAP faults, response errors, and warnings when they appear before the first record. After streaming starts, terminal errors cannot be represented as a normal JSON error envelope. The shipped behavior aborts the stream; NDJSON clients see an incomplete HTTP response, and JSON array clients see an incomplete or invalid JSON document.
-
-## OpenAPI Output
-
-Stream operations should not use the standard success envelope for `200` responses. The response content should use the configured stream media type.
-
-```json
-{
-  "description": "Successful streamed SOAP operation response",
-  "content": {
-    "application/x-ndjson": {
-      "schema": { "type": "string" },
-      "x-wsdl-tsc-stream": {
-        "format": "ndjson",
-        "itemSchema": {
-          "$ref": "#/components/schemas/UnitDescriptiveContentType"
-        }
-      }
-    }
-  }
-}
-```
-
-OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document. The `x-wsdl-tsc-stream` extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators.
-
-For `format: "json-array"`, OpenAPI uses an array schema under the configured media type while keeping the same extension:
-
-```json
-{
-  "description": "Successful streamed SOAP operation response",
-  "content": {
-    "application/json": {
-      "schema": {
-        "type": "array",
-        "items": {
-          "$ref": "#/components/schemas/UnitDescriptiveContentType"
-        }
-      },
-      "x-wsdl-tsc-stream": {
-        "format": "json-array",
-        "itemSchema": {
-          "$ref": "#/components/schemas/UnitDescriptiveContentType"
-        }
-      }
-    }
-  }
-}
-```
-
-## Gateway Output
-
-Generated stream routes should call the stream operation and send a Node stream through Fastify.
-
-```typescript
-handler: async (request, reply) => {
-  const client = fastify.escapiaContentClient;
-  const result = await client.UnitDescriptiveInfoStream(request.body);
-
-  reply.type("application/x-ndjson");
-  return reply.send(toNdjson(result.records));
-}
-```
-
-The generated operation schema should keep request validation but omit the Fastify response serialization schema for streamed `200` responses. Fastify cannot serialize an unbounded stream with a normal JSON response schema.
-
-The gateway runtime adds `toNdjson()` and `toJsonArray()` helpers. These helpers are deterministic, backpressure-aware, and safe for large payloads.
-
-## Test Strategy
-
-Add unit tests for stream config parsing, operation matching, catalog normalization, wildcard compiler metadata, and record path matching.
-
-Add converter tests that split XML chunks across element boundaries to prove the parser does not rely on convenient chunking.
-
-Add a local Escapia-like WSDL fixture with `xs:any` output wrappers and a companion WSDL fixture with the concrete record types.
-
-Add an integration test with a fake SOAP HTTP server that writes one record, waits, writes another record, and then closes the envelope. The test should assert that the gateway emits the first NDJSON line or JSON array record before the upstream response completes.
-
-Add snapshot tests for generated `client.ts`, `operations.ts`, OpenAPI output, gateway route files, and gateway runtime helpers.
-
-Run `npm run smoke:pipeline` after implementation to verify ordinary buffered generation is unchanged.
-
-## Implementation Plan
-
-1. Define `StreamConfig`, parser, validation errors, and normalized operation metadata.
-2. Add `--stream-config` to the CLI and thread it through the programmatic API.
-3. Update the compiler to preserve wildcard particles and emit stream candidate diagnostics.
-4. Implement companion catalog loading and record type graph copying.
-5. Generate stream method signatures in `client.ts` and `operations.ts`.
-6. Add a streaming XML converter with catalog-aware JSON shape conversion.
-7. Generate OpenAPI stream responses with `x-wsdl-tsc-stream` metadata.
-8. Generate Fastify streaming handlers and runtime helpers.
-9. Add unit, snapshot, and chunked integration tests.
-10. Update README, CLI reference, configuration docs, gateway guide, testing guide, and supported patterns.
-
-## Acceptance Criteria
-
-- Existing generated output is unchanged when no stream config is provided.
-- A stream-configured Escapia content WSDL generates typed stream client methods.
-- The generated gateway emits configured stream records incrementally.
-- The generated OpenAPI document identifies stream operations and record schemas.
-- The converter maps XML attributes, arrays, text values, and nillable values consistently with buffered responses.
-- The chunked integration test proves the first record is sent before the full SOAP response is available.
-- Stream route errors before the first byte use the normal gateway error envelope.
-- Stream route errors after the first byte follow a documented terminal error policy.
-
-## Consequences
-
-The generator gains a second response execution model. This increases complexity in the client, OpenAPI, gateway, and test generators, but keeps the complexity opt-in and operation-scoped.
-
-The catalog becomes more important as the shared source of truth because OpenAPI alone cannot carry enough stream conversion metadata.
-
-NDJSON remains the default stream format because it is simple and broadly consumable. JSON array streaming is available for clients that require one JSON document and still streams without buffering the full response.
-
-Companion catalogs are required for vendors that split stream wrappers and concrete record shapes across separate WSDLs.
-
-## Implementation Notes
-
-Captured after the 0.17.0 ship for future maintainers:
-
-- `--stream-config` is wired onto the `compile`, `client`, and `pipeline` CLI commands. It is intentionally not accepted on `openapi`, `gateway`, or `app` because those commands consume a pre-compiled `catalog.json` that already carries the normalized `OperationStreamMetadata`. The original proposal text that listed the flag on every command reflected the design intent; the shipped surface is narrower for that reason.
-- `GenerateOpenAPIOptions` and `GenerateGatewayOptions` in the programmatic API do not carry stream-config fields for the same reason. `compileWsdlToProject` and `runGenerationPipeline` (PipelineOptions) do.
-- The client stream transport is emitted from two templates (`clientStreamMethods.tpl.txt`, `operationsStreamHelper.tpl.txt`). They embed the `StreamOperationResponse<T>` type and a `callStream()` method that POSTs a hand-built SOAP envelope via global `fetch`, bypassing `node-soap` as required by the phase-0 finding.
-- `saxes ^6.0.0` was promoted from devDependency to runtime dependency on the package, and added as a pinned dependency in the generated app scaffold so stream-enabled consumers install it automatically.
-- The `json-array` format is implemented in `0.28.0`. The helper prefetches the first record before emitting `[`, which preserves normal error envelopes for failures before the first record and documents truncation or invalid JSON for failures after streaming starts.
-
-## References
-
-- Escapia EVRN API documentation: <https://eweb.escapia.com/distribution/api/evrn-api-documentation>
-- Escapia EVRN service WSDL: <https://api.escapia.com/EVRNService.svc?WSDL>
-- Escapia EVRN content service WSDL: <https://api.escapia.com/EVRNContentService.svc?WSDL>
-- Escapia batch API support article: <https://support.escapia.com/articles/en_US/Article/HASW-Batch-API-Methods-EVRN?category=Website_Services>

package/docs/file-naming-and-path-organization.md

@@ -1,213 +0,0 @@
-# File Naming And Path Organization
-
-Contributor guide for naming files and organizing fixture paths. See the root [README.md](../README.md) for the authoritative documentation index.
-
-## Preamble Resources
-
-Raw comment-only headers live under `src/generation/preambles/` with the filename `typescript.preamble`. Subdirectories express logical artifact scopes rather than consumer output paths. See [generated source policy](architecture.md#generated-source-policy) for fallback and packaging rules.
-
-Package-smoke tarballs and logs belong in `tmp/preflight/package/`; the isolated consumer installation uses a verified temporary directory outside the checkout to prove that package resources resolve independently.
-
-## Purpose
-
-Paths should classify files before a reader opens them. The left side of a path carries the broadest concept; each segment to the right narrows the classification until the filename states the exact artifact purpose.
-
-This convention is especially important for conformance fixtures. A maintainer should be able to search or list paths and see which WSDL, XSD, SOAP, policy, and recovery concepts already have evidence.
-
-## Authority Model
-
-This convention borrows from resource-oriented API design. REST APIs commonly use noun-based paths, hierarchy through `/`, and readable lowercase path segments.
-
-Google AIP-122 describes resource names as slash-separated paths and says collection identifiers are usually plural nouns. Zalando REST guidelines require plural resource names, kebab-case path segments, verb-free URLs, and domain-specific resource names. Microsoft Azure API guidelines prefer kebab-casing for URL path segments. REST URI naming guidance uses nouns for resources, `/` for hierarchy, and hyphens for readability.
-
-Filesystem paths are not REST APIs, but the same retrieval model applies: a path is a resource name for a contributor, a terminal command, an IDE index, and an agent.
-
-## Shell Examples
-
-Use `bash` fences for portable command examples in repository documentation and GitHub workflow notes. Use `powershell` fences only when the command is intentionally Windows-specific.
-
-Prefer `rg` for retrieval examples because agents already use it for fast file and content search. Write path filters so they tolerate `/` and `\` separators when possible.
-
-On Windows PowerShell, keep `rg` regex arguments in single quotes when the pattern contains backslashes, brackets, or alternation. The examples in this document were checked in PowerShell with single-quoted regexes. A no-match `rg` filter exits with code `1`; that is expected for negative checks such as confirming `service.wsdl` is absent.
-
-## Progressive Discovery
-
-Start broad, then narrow. A path should answer these questions from left to right:
-
-1. What repository area owns this artifact?
-2. What artifact family is this?
-3. What standards domain or product domain does it belong to?
-4. What feature family does it exercise?
-5. What exact purpose does the file serve?
-
-For conformance fixtures, this means the preferred shape is:
-
-```text
-test/conformance/fixtures/<domain>/<feature-family>/<feature-name>.<ext>
-```
-
-Use deeper nesting only when it improves retrieval. Do not create a folder level that only repeats the filename.
-
-## Folder Names
-
-Folder names are taxonomy terms. They classify a set of files.
-
-- Use lowercase kebab-case.
-- Prefer one noun per segment.
-- Prefer plural nouns when the term is naturally countable.
-- Preserve standards terms when pluralizing them would reduce clarity.
-- Avoid verbs, implementation steps, and filler words.
-- Place the broadest useful classifier on the left.
-- Add a narrower folder only when it groups multiple related files or distinguishes a standards boundary.
-
-Acceptable standards-domain folders include `wsdl`, `xsd`, `soap`, `ws-policy`, `ws-security`, `interop`, and `recovery`.
-
-Acceptable feature-family folders include `types`, `elements`, `bindings`, `policies`, `attachments`, `wildcards`, `compositors`, `sequences`, and `choices`.
-
-## File Names
-
-File names state the exact purpose and content of the artifact. They should remain useful when shown without the full path.
-
-- Use lowercase kebab-case.
-- Use general-to-specific segment order.
-- Put the broad feature classifier first.
-- Put variable-like qualifiers on the right side.
-- Keep recognized standards terms when they identify the feature.
-- Avoid filler words such as `service`, `sample`, `fixture`, and `test`.
-- Use the file extension to identify format, not the basename.
-
-Good file names classify sorted terminal output:
-
-```text
-attachment-mtom-xop.wsdl
-binding-soap-first-multi.wsdl
-choice-union-simple.wsdl
-element-substitution-group.wsdl
-policy-reference-external.wsdl
-sequence-composition-deep.wsdl
-type-complex-abstract-extension.wsdl
-type-union-simple.wsdl
-wildcard-attribute-any.wsdl
-```
-
-Avoid names that only read naturally in English but group poorly in file listings:
-
-```text
-abstract-complex-type-extension.wsdl
-any-attribute.wsdl
-deep-sequence-composition.wsdl
-mtom-xop-attachment.wsdl
-multi-binding-first-soap.wsdl
-xs-union-simple-type.wsdl
-```
-
-## Conformance Fixtures
-
-Conformance fixtures should be committed XML files, not inline strings in tests. Inline XML is acceptable only for throwaway probes or very small unit tests that do not represent a reusable fixture.
-
-The fixture path should support discovery by partial path search. A contributor should be able to search `xsd/wildcards`, `soap/attachments`, or `wsdl/bindings` and see what exists.
-
-The registry ID should remain stable for test reporting. The fixture path may use taxonomy folders and a more precise filename when that improves retrieval.
-
-## Multi-file Fixtures
-
-Use a folder when a fixture needs a root WSDL plus imported schemas or companion files. Keep the root filename aligned with the feature name.
-
-```text
-test/conformance/fixtures/xsd/wildcards/wildcard-attribute-any.wsdl
-test/conformance/fixtures/xsd/wildcards/wildcard-attribute-any-types.xsd
-test/conformance/fixtures/xsd/wildcards/wildcard-attribute-any-shared.xsd
-```
-
-Use purpose suffixes such as `types`, `messages`, `shared`, `policy`, and `binding` for companion files.
-
-## Retrieval Examples
-
-List every conformance fixture path:
-
-```bash
-rg --files test/conformance/fixtures | sort
-```
-
-Find every XSD wildcard fixture:
-
-```bash
-rg --files test/conformance/fixtures | rg '(^|[\\/])xsd[\\/]wildcards[\\/]'
-```
-
-Find whether a SOAP attachment fixture exists:
-
-```bash
-rg --files test/conformance/fixtures | rg '(^|[\\/])attachment-'
-```
-
-Use `rg` when searching by concept inside paths or XML content:
-
-```bash
-rg -n "xs:anyAttribute|wildcard-attribute" test\conformance\fixtures
-```
-
-## Agent Retrieval Playbook
-
-Agents should prefer a small number of focused file-system checks before adding or renaming fixtures. These commands are intentionally simple and use portable `rg` patterns.
-
-Check the current taxonomy shape:
-
-```bash
-rg --files test/conformance/fixtures | sort
-```
-
-Check whether a domain branch already exists:
-
-```bash
-rg --files test/conformance/fixtures | rg '(^|[\\/])xsd[\\/]types[\\/]'
-```
-
-Find fixtures by filename classifier:
-
-```bash
-rg --files test/conformance/fixtures | rg '(^|[\\/])type-'
-```
-
-Find fixtures by XML feature content:
-
-```bash
-rg -n "xs:union|xs:anyAttribute|substitutionGroup|PolicyReference" test\conformance\fixtures
-```
-
-Check whether old filler names are still present:
-
-```bash
-rg --files test/conformance/fixtures | rg '(^|[\\/])service\.wsdl'
-```
-
-Find the registry row that owns a fixture path:
-
-```bash
-rg -n "wildcard-attribute-any|type-union-simple|attachment-mtom-xop" test\conformance\registry.ts
-```
-
-Use these commands as discovery checks, not as validation gates. Repository validation still runs through `npm run docs:validate`, `npm run test:conformance`, and `npm test`.
-
-## Candidate Fixture Paths
-
-Use these paths as the target direction for the current conformance corpus:
-
-```text
-test/conformance/fixtures/xsd/compositors/choice-union-simple.wsdl
-test/conformance/fixtures/xsd/types/type-union-simple.wsdl
-test/conformance/fixtures/xsd/types/type-complex-abstract-extension.wsdl
-test/conformance/fixtures/xsd/elements/element-substitution-group.wsdl
-test/conformance/fixtures/wsdl/bindings/binding-soap-first-multi.wsdl
-test/conformance/fixtures/ws-policy/references/policy-reference-external.wsdl
-test/conformance/fixtures/xsd/sequences/sequence-composition-deep.wsdl
-test/conformance/fixtures/xsd/wildcards/wildcard-attribute-any.wsdl
-test/conformance/fixtures/soap/attachments/attachment-mtom-xop.wsdl
-```
-
-## References
-
-- [Google AIP-122 Resource Names](https://google.aip.dev/122)
-- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/)
-- [Microsoft Azure API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
-- [REST API URI Naming Conventions](https://restfulapi.net/resource-naming/)

package/docs/releases/README.md

@@ -1,94 +0,0 @@
-# Release Notes
-
-Add one Markdown file per release tag. The draft release workflow requires this file before it creates or updates a GitHub draft release.
-
-## File Naming
-
-Use the Git tag as the filename:
-
-```text
-vX.Y.Z.md
-```
-
-For example, release `0.20.1` uses tag `v0.20.1` and release notes file `docs/releases/v0.20.1.md`.
-
-## File Structure
-
-Each release notes file must use this structure:
-
-```markdown
-# TypeScript WSDL Client vX.Y.Z
-
-## Short agent-generated subtitle
-
-A concise summary paragraph.
-
-## What This Improves
-
-Explain the practical developer impact of the release. Focus on what becomes easier, safer, clearer, more reliable, or more complete for developers using or maintaining this package.
-
-## Highlights
-
-- User-facing release highlight.
-
-## 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: `vX.Y.Z`.
-```
-
-Keep the H1 in the repository file so each release note remains a complete source document. The draft release workflow strips only that H1 when generating the GitHub release body, so the GitHub page uses `TypeScript WSDL Client vX.Y.Z` as the release title and starts the body with the H2 subtitle.
-
-Write validation as consumer-facing outcomes, not as maintainer command transcripts. Keep exact release operator commands in `.github/copilot-instructions.md` and workflow logs.
-
-Write release notes for users and maintainers, not as a file-by-file change log. Use `CHANGELOG.md` for the canonical version history.
-
-When an abandoned major or minor candidate contains the complete launch narrative, carry that narrative into the next published corrective release. The corrective release notes must stand alone for users who never saw the abandoned draft.
-
-## Candidate Publication
-
-The supported release path keeps final-form tags immutable:
-
-1. Prepare versions, changelog, release notes, and the documentation index before pushing the release PR.
-2. Run release preflight on the final uncommitted tree and commit that exact validated tree.
-3. Push the PR and require Node 24 and Node 26 checks on its final head before merging.
-4. Verify the merged main tree matches the validated tree and require CI on the merged commit.
-5. Tag the validated merged main commit and push the tag to start the draft workflow.
-6. Verify the draft, release notes, uploaded skill ZIP, checksum manifest, and artifact verification results.
-7. Clean up task-owned merged branches and temporary outputs, then hand the draft to the maintainer.
-8. The maintainer reviews the draft in their own browser and clicks Publish.
-9. The guarded package workflow publishes to npmjs with provenance.
-
-The agent stops after draft verification and cleanup. Agents must never access GitHub through a browser, publish a release, or dispatch package publication. Use authenticated git and GitHub CLI commands for preparation and verification. Preserve unrelated work, contributor-owned branches, immutable release tags, and abandonment markers during cleanup.
-
-If the merged tree differs from the preflight-validated tree, stop before tagging and prepare a newly validated candidate. Do not rerun preflight for an unchanged validated tree.
-
-Manual package dispatch is a recovery path after the GitHub Release is published. It enforces the same tag, marker, reachability, draft, and prerelease checks.
-
-The normal path uses GitHub UI publication because a workflow publishing with its standard `GITHUB_TOKEN` does not trigger another workflow from the resulting event. Do not rely on recursive workflow delivery for package publication.
-
-## Abandoned Candidates
-
-Run the `Abandon Release Candidate` workflow before publishing a rejected draft. Supply the final-form tag, a permanent reason, and optional failed-validation evidence.
-
-The workflow creates annotated marker `abandoned/vX.Y.Z` on the same commit as `vX.Y.Z`, verifies the remote marker, and then deletes only the draft release and its candidate assets. The marker preserves the durable reason and release identity. The operation is idempotent when the marker already matches and the draft is absent. A marker on another commit fails for maintainer review.
-
-Drafting, abandonment, and package publication are serialized per release tag so abandonment cannot race package delivery.
-
-Never move, delete for reuse, or force-update either tag. The rejected version is consumed, and the correction uses the next version.
-
-The marker cannot disable GitHub's Publish button before draft retirement. Draft and package automation enforce the marker, and abandonment removes the rejected draft after verifying the marker. Never use release deletion with tag cleanup.
-
-## Tag Ruleset Proposal
-
-Protect `v*` and `abandoned/v*` against updates and deletions. Consider restricted creation after testing the intended maintainer or GitHub App bypass identity. Repository settings remain a maintainer decision and are not changed by release automation.