@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/docs/testing.md

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

package/docs/troubleshooting.md

@@ -30,7 +30,7 @@ A missing, empty, or unreadable packaged preamble fails generation with the reso
 | Structural collision between main and companion catalog | Two types share a name but differ structurally; rename in the companion source or point `recordType` at a distinct subtree |
 | Stream response ends abruptly or JSON array parse fails | Mid-stream upstream error per the terminal-error policy; check gateway logs for the classified error |
 | Stream recordPath does not match | SAX matching is positional and case-sensitive; verify duplicate local-name segments are spelled exactly |
-| Stream client throws "stream request failed" | The upstream SOAP endpoint rejected the hand-built envelope; check `requestRaw` on the response and verify SOAP action and namespaces match the WSDL binding |
+| Stream request fails | Check endpoint/action/binding, media type/encoding, shape config, DTO conversion and cancellation evidence |
 
 ## SOAP Wire Logging
 
@@ -85,6 +85,8 @@ cat ./src/services/hotel/catalog.json | jq '.types'
 
 ## Streaming Debug
 
+Requests use node-soap's WSDL serializer and `requestStream`. Check the [supported transport settings](gateway-guide.md#streaming-transport-settings) before changing serialization. Pre-header failures can use the gateway error handler; once output is committed, failure truncates the stream and cannot become a recoverable JSON error envelope. Scoped diagnostics and explicit companion sources help configuration; a universal live-response mismatch doctor or wizard is not provided.
+
 Inspect stream metadata on the compiled catalog to confirm the config was parsed and applied:
 
 ```bash

package/llms.txt

@@ -6,7 +6,7 @@
 ## Quick Facts
 
 - CLI binary: wsdl-tsc
-- Node.js >= 20.0.0
+- Node.js >= 24.0.0
 - Runtime dependency: soap
 - Output: TypeScript client + OpenAPI 3.1 + Fastify gateway
 - All output is deterministic and diff-friendly
@@ -26,7 +26,15 @@ npx wsdl-tsc pipeline \
   --gateway-service-name <slug> \
   --gateway-version-prefix <version>
 
-## Generated Files
+## Profile selection
+
+Before upgrading a 1.1.x consumer, read [migration](docs/migration.md#from-11x-to-120). Legacy remains the default, but regeneration can change colliding DTO names, mapped stream records and corrected scalar/simple-content values. Preserve matched artifacts, lockfiles and app/test customizations; adopt a new profile separately. npm published 1.1.5 and 1.1.8, while 1.1.6/1.1.7 were unpublished candidates.
+
+Use legacy pipeline for one source, or pipeline --services-config services.json for independent legacy sources. The aggregate typed createClients binds each runtime WSDL, endpoint and security separately; no checked/app/test aggregate mode is available. See [composition](docs/gateway-guide.md#multi-service-setup).
+
+Use pipeline --model checked-components-v1 for the bounded document/literal or SOAP 1.1 RPC/encoded string profile. Checked replies remain buffered checked values. Legacy buffered success uses envelopes; opt-in legacy NDJSON/JSON-array streams deliver generated DTO records directly through node-soap requestStream. See [migration](docs/migration.md#from-11x-to-120).
+
+## Output inventory
 
 - client/client.ts: typed SOAP client class
 - client/types.ts: TypeScript interfaces from XSD
@@ -43,11 +51,11 @@ npx wsdl-tsc pipeline \
 
 ## Documentation
 
-- AGENTS.md: agent instructions (universal, tool-agnostic)
-- README.md: project overview and quick start
-- CONTRIBUTING.md: development setup, project structure, testing strategy
-- docs/migration.md: upgrade paths between versions
-- .github/copilot-instructions.md: authoritative detailed agent instructions (referenced by AGENTS.md)
-- docs/README.md: documentation directory index and conventions
+- [README.md](README.md): project overview and quick start
+- [Checked generation](docs/checked-generation.md): opt-in checked client and gateway workflow
+- [Migration](docs/migration.md): upgrade paths between versions
+- [Agent skill](docs/agent-skill.md): consumer-project generation guidance
+- [Contributor guide](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/CONTRIBUTING.md): repository setup and tests
+- [Agent instructions](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/AGENTS.md): repository working rules
 - npm: https://www.npmjs.com/package/@techspokes/typescript-wsdl-client
 - GitHub: https://github.com/TechSpokes/typescript-wsdl-client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.1.5",
+  "version": "1.2.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",
@@ -51,12 +51,32 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "dist/**/*.d.ts.map",
-    "docs",
+    "!dist/runtime/**",
+    "docs/start-here.md",
+    "docs/cli-reference.md",
+    "docs/configuration.md",
+    "docs/concepts.md",
+    "docs/generated-code.md",
+    "docs/output-anatomy.md",
+    "docs/gateway-guide.md",
+    "docs/checked-generation.md",
+    "docs/checked-gateway.md",
+    "docs/supported-patterns.md",
+    "docs/troubleshooting.md",
+    "docs/migration.md",
+    "docs/migration-playbook.md",
+    "docs/production.md",
+    "docs/testing.md",
+    "docs/api-reference.md",
+    "docs/agent-skill.md",
+    "docs/direct-values.md",
+    "docs/mapping-contract.md",
+    "docs/corpus.md",
+    "docs/examples/**",
     "README.md",
     "LICENSE",
     "llms.txt",
-    "src/runtime/*.ts",
+    "src/runtime/streamXml.ts",
     "src/runtime/*.tpl.txt",
     "src/generation/preambles/**/*.preamble"
   ],
@@ -68,13 +88,20 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",
     "typecheck:integration": "tsc -p test/integration/tsconfig.json",
-    "test": "vitest run",
-    "test:unit": "vitest run test/unit",
+    "test": "tsx scripts/run-verification.ts test:run",
+    "test:run": "vitest run",
+    "test:unit": "tsx scripts/run-verification.ts test:unit:run",
+    "test:unit:run": "vitest run test/unit",
     "test:snap": "vitest run test/snapshot",
-    "test:integration": "vitest run test/integration",
+    "test:integration": "tsx scripts/run-verification.ts test:integration:run",
+    "test:integration:run": "vitest run test/integration",
     "test:feasibility": "vitest run test/integration/content-model-soap-feasibility.test.ts test/integration/content-model-gateway-feasibility.test.ts",
-    "test:github": "vitest run test/unit test/snapshot test/integration",
-    "test:conformance": "vitest run test/conformance --reporter=verbose",
+    "test:github": "vitest run test/unit test/snapshot test/integration test/tooling --exclude \"**/*installed.test.ts\"",
+    "test:installed": "tsx scripts/run-verification.ts test:installed:run",
+    "test:installed:run": "vitest run test/integration/checked-direct-installed.test.ts test/integration/checked-gateway-installed.test.ts test/integration/checked-intake-installed.test.ts test/integration/component-transferred-installed.test.ts test/integration/generated-direct-installed.test.ts test/integration/portable-installed.test.ts",
+    "test:platform": "vitest run test/unit/checked-assessment.test.ts test/unit/direct-operation.test.ts test/unit/direct-structure.test.ts test/unit/direct-structure-evidence.test.ts test/unit/direct-values.test.ts test/unit/direct-codec.test.ts test/unit/direct-codec-independent.test.ts test/unit/direct-source-capsule.test.ts test/unit/direct-capsule-independent.test.ts test/unit/generated-direct-independent.test.ts test/unit/direct-resource-limits.test.ts test/unit/direct-resource-limits-independent.test.ts test/unit/checked-direct-runtime.test.ts test/integration/direct-normal-execution.test.ts test/integration/noaa-ndfd-qualification.test.ts test/tooling/readiness-inventory.test.ts test/integration/owned-node-process.test.ts test/unit/schema-resource-cancellation.test.ts",
+    "test:conformance": "tsx scripts/run-verification.ts test:conformance:run",
+    "test:conformance:run": "vitest run test/conformance --reporter=verbose",
     "test:conformance:contracts": "vitest run --config vitest.conformance.config.ts test/conformance/stages/contracts.stage.ts --reporter=verbose",
     "test:conformance:compile": "vitest run --config vitest.conformance.config.ts test/conformance/stages/compile.stage.ts --reporter=verbose",
     "test:conformance:client": "vitest run --config vitest.conformance.config.ts test/conformance/stages/client.stage.ts --reporter=verbose",
@@ -94,27 +121,35 @@
     "maint:deps": "node scripts/maint-deps.mjs",
     "docs:support-matrix": "tsx scripts/generate-support-matrix.ts",
     "docs:support-matrix:check": "tsx scripts/generate-support-matrix.ts --check",
-    "docs:validate": "node scripts/validate-docs.mjs && npm run docs:support-matrix:check",
+    "docs:corpus": "tsx scripts/product-corpus.ts",
+    "docs:corpus:check": "tsx scripts/product-corpus.ts --check",
+    "test:corpus": "tsx scripts/run-verification.ts test:corpus:run",
+    "test:corpus:run": "npm run build && tsx scripts/product-corpus.ts --test",
+    "docs:validate": "node scripts/validate-docs.mjs && npm run docs:support-matrix:check && npm run docs:corpus:check",
     "skill:validate": "node scripts/validate-agent-skill.mjs",
     "skill:package": "node scripts/build-agent-skill.mjs",
-    "package:validate": "node scripts/validate-npm-package.mjs",
+    "package:validate": "tsx scripts/validate-npm-package.ts",
     "package:smoke": "node scripts/smoke-npm-package.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:publish-check": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate",
-    "ci": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:research && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run && npm run smoke:pipeline && npm run package:smoke",
-    "ci:github": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:research && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && npm run test:github && npm run smoke:pipeline",
-    "ci:github:node26": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:research && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run test:unit && vitest run test/integration/client-imports.test.ts && npm run smoke:pipeline",
+    "ci": "tsx scripts/run-verification.ts ci:run",
+    "ci:run": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run --exclude \"test/conformance/reference/**\" --reporter=default --reporter=json --outputFile=tmp/conformance/product-tests.json && npm run smoke:pipeline && npm run package:smoke",
+    "ci:github": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run skill:validate && npm run package:validate && npm run docs:validate && npm run test:github && npm run smoke:pipeline",
+    "ci:github:node26": "npm run check:toolchain && npm run typecheck:tooling && npm run typecheck:reference && npm run clean && npm run build && npm run typecheck && npm run test:reference && npm run typecheck:integration && npm run test:unit && vitest run test/tooling test/integration/client-imports.test.ts && npm run smoke:pipeline",
     "examples:regenerate": "tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir examples/generated-output/client --openapi-file examples/generated-output/openapi.json --gateway-dir examples/generated-output/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json",
     "reference:setup": "tsx scripts/semantic-reference.ts --setup",
     "test:reference": "tsx scripts/semantic-reference.ts",
     "test:reference:full": "tsx scripts/semantic-reference.ts --full",
     "check:toolchain": "tsx scripts/check-toolchain.ts",
     "typecheck:tooling": "tsc -p test/tooling/tsconfig.json",
-    "typecheck:research": "tsc -p test/research/s06-au01/tsconfig.json && tsc -p test/research/re01/tsconfig.json && tsc -p test/research/s06-pw01/tsconfig.json && tsc -p test/research/dt01/tsconfig.json",
+    "research:typecheck": "tsc -p research/tsconfig.json",
     "typecheck:reference": "tsc -p test/conformance/reference/tsconfig.json",
-    "test:research:ports": "vitest run test/research/s06-au01 test/research/re01 test/research/s06-pw01 test/research/dt01",
-    "research:re01:measure": "tsx test/research/re01/measure.ts",
-    "research:re01:compare": "tsx test/research/re01/cli.ts",
+    "research:test": "tsx research/reference/run.ts",
+    "research:reference": "tsx research/reference/run.ts --reference-only",
+    "research:docs": "tsx research/validate-docs.ts",
+    "research:ci": "npm run check:toolchain && npm run research:typecheck && npm run research:docs && npm run research:test",
+    "research:re01:measure": "tsx research/tests/re01/measure.ts",
+    "research:re01:compare": "tsx research/tests/re01/cli.ts",
     "assess:inventory": "tsx scripts/readiness-inventory.ts"
   },
   "devDependencies": {
@@ -123,23 +158,29 @@
     "@types/node": "^26.6.6",
     "@types/yargs": "^17.0.35",
     "eslint": "^10.14.0",
-    "fastify": "^5.12.7",
+    "fastify": "^5.12.8",
     "fastify-plugin": "^6.0.1",
     "libxml2-wasm": "^0.7.2",
-    "rimraf": "^6.1.3",
+    "rimraf": "^6.1.4",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.72.1",
-    "vitest": "^5.0.5"
+    "typescript-eslint": "^8.72.2",
+    "vitest": "^5.1.0"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^13.1.0",
-    "fast-xml-parser": "^5.11.2",
+    "fast-xml-parser": "^5.12.0",
     "js-yaml": "^5.5.0",
     "saxes": "^6.0.0",
     "soap": "^1.14.0",
     "yargs": "^18.2.0"
   },
+  "overrides": {
+    "minimatch": "^11.0.3",
+    "rimraf": {
+      "glob": "^14.0.3"
+    }
+  },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/TechSpokes"