@techspokes/typescript-wsdl-client 0.27.0 → 0.29.0

package/docs/output-anatomy.md

@@ -75,7 +75,7 @@ CLI OpenAPI generation always validates the generated spec using `@apidevtools/s
 
 ### Stream Schema Extension
 
-Stream operations do not use the standard success envelope for `200` responses. The response content declares the configured stream media type (default `application/x-ndjson`) with `schema: { "type": "string" }` and an `x-wsdl-tsc-stream` extension that carries the record schema reference:
+Stream operations do not use the standard success envelope for `200` responses. NDJSON streams declare the configured stream media type (default `application/x-ndjson`) with `schema: { "type": "string" }` and an `x-wsdl-tsc-stream` extension that carries the record schema reference:
 
 ```json
 {
@@ -94,7 +94,29 @@ Stream operations do not use the standard success envelope for `200` responses.
 }
 ```
 
-OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document, so the extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators. Error responses (400, 502, and the rest) still use the normal envelope.
+JSON array streams default to `application/json` and declare the record schema as the array item schema while keeping the same extension:
+
+```json
+{
+  "200": {
+    "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" }
+        }
+      }
+    }
+  }
+}
+```
+
+OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document, so the extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators. JSON array streams use a normal array schema and keep the extension for downstream tooling. Error responses (400, 502, and the rest) still use the normal envelope.
 
 ## Gateway Output
 
@@ -117,11 +139,11 @@ Each route file in `routes/` follows the same pattern: validate the JSON request
 
 ### Stream Routes
 
-Stream-configured operations generate a different route shape. The Fastify response serialization schema is omitted because Fastify cannot serialize an unbounded stream with a normal JSON response schema. The handler sets `reply.type("application/x-ndjson")` and returns `reply.send(toNdjson(result.records))`. `runtime.ts` gains a `toNdjson<T>(records: AsyncIterable<T>): Readable` helper that wraps the async iterable in a backpressure-aware Node `Readable`. See the [Gateway Guide](gateway-guide.md#streaming-handlers) for the full handler example and terminal-error policy.
+Stream-configured operations generate a different route shape. The Fastify response serialization schema is omitted because the handler sends a `Readable` directly. NDJSON handlers set `reply.type("application/x-ndjson")` and return `reply.send(toNdjson(result.records))`; JSON array handlers set `reply.type("application/json")` and return `reply.send(toJsonArray(result.records))`. `runtime.ts` gains `toNdjson<T>(records: AsyncIterable<T>): Readable` and `toJsonArray<T>(records: AsyncIterable<T>): Readable` helpers. See the [Gateway Guide](gateway-guide.md#streaming-handlers) for the full handler example and terminal-error policy.
 
 ### Generated Test Surface
 
-When `--test-dir` is combined with `--stream-config`, the generated happy-path tests for stream operations assert on the `application/x-ndjson` content-type and parse each line as a separate JSON record. Mock clients use async-generator overrides that yield records to drive those tests; see the [Testing Guide](testing.md) for the pattern.
+When `--test-dir` is combined with `--stream-config`, the generated happy-path tests for stream operations assert on the configured content type. NDJSON tests parse each line as a separate JSON record, and JSON array tests parse the response body once as an array. Mock clients use async-generator overrides that yield records to drive those tests; see the [Testing Guide](testing.md) for the pattern.
 
 ### Plugin registration
 

package/docs/production.md

@@ -83,7 +83,7 @@ Log the time to first record, not just the time to response completion. First-re
 
 ### Terminal-Error Policy
 
-Errors raised before the first record use the normal gateway error envelope (client sees a standard JSON error). Errors raised mid-stream truncate the chunked response without a terminating zero-chunk. Consumers detect this as an incomplete HTTP response. Document this behavior for downstream API consumers so they distinguish truncation from a legitimate empty stream.
+Errors raised before the first record use the normal gateway error envelope because the JSON array helper prefetches the first record before emitting `[`. Errors raised mid-stream truncate the response. NDJSON consumers detect this as an incomplete HTTP response, and JSON array consumers must treat an incomplete or invalid JSON document as a failed stream. Document this behavior for downstream API consumers so they distinguish truncation from a legitimate empty stream.
 
 ## Known Limitations
 
@@ -105,7 +105,7 @@ Single-child sequences with maxOccurs>1 become array schemas. Sequences with mul
 
 ### Stream Format Coverage
 
-Only `ndjson` is emitted today. `json-array` is reserved in the config schema but not yet implemented; opting in with `format: "json-array"` parses successfully but generates no routes for that operation.
+`ndjson` is the default stream format. `json-array` is supported for operations that need a single JSON document response; it streams records incrementally as a JSON array and does not buffer the full SOAP response.
 
 ### Stream Transport Bypasses node-soap
 

package/docs/releases/v0.28.0.md

@@ -0,0 +1,32 @@
+# TypeScript WSDL Client v0.28.0
+
+## JSON Array Streaming
+
+This release implements `format: "json-array"` for operations opted into streaming with `--stream-config`.
+
+## What This Improves
+
+Teams can now serve large SOAP response records as one streamed `application/json` array without buffering the full upstream response. NDJSON remains the default stream format, and JSON array operations keep the same generated client return shape: `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`.
+
+## Highlights
+
+- Adds `toJsonArray()` runtime streaming alongside the existing NDJSON helper.
+- Emits OpenAPI `application/json` array schemas for JSON array stream operations.
+- Generates Fastify routes that call `toJsonArray(result.records)` for `format: "json-array"`.
+- Generates route tests that parse JSON array stream responses as one array document.
+- Documents the terminal-error behavior for JSON array streams.
+
+## Upgrade Notes
+
+No special upgrade steps. Existing stream operations keep `ndjson` unless the stream config opts an operation into `format: "json-array"`.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Documentation links and TypeScript fenced snippets were validated.
+- Agent skill artifact was validated and packaged.
+
+## Notes
+
+Release tag: `v0.28.0`.

package/docs/releases/v0.29.0.md

@@ -0,0 +1,32 @@
+# TypeScript WSDL Client v0.29.0
+
+## Dependency And Roadmap Maintenance
+
+This release brings the project dependency floor and generated app scaffold pins up to date after Dependabot and security review updates. It also carries forward the latest 1.0 readiness documentation so maintainers and adopters can track the remaining capability conformance work.
+
+## What This Improves
+
+Developers get current dependency minimums in both the published package and newly scaffolded Fastify gateway apps. The refreshed lockfile includes transitive security maintenance for build and request-related packages, while the roadmap documentation now reflects the JSON array streaming release and the 1.0 conformance planning model.
+
+## Highlights
+
+- Updates root dependency minimums for `fast-xml-parser`, `fastify-plugin`, `@types/node`, and `vitest`.
+- Refreshes lockfile security updates for `esbuild`, `form-data`, and `hasown`.
+- Updates generated app scaffold pins for `fastify-plugin` and `@types/node`.
+- Refreshes 1.0 roadmap documentation after the JSON array streaming release.
+- Adds the 1.0 capability conformance framework documentation.
+
+## Upgrade Notes
+
+No special upgrade steps. Regenerate generated Fastify app scaffolds when you want new app projects to start with the updated dependency pins.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Documentation links and TypeScript fenced snippets were validated.
+- Agent skill artifact was validated and packaged.
+
+## Notes
+
+Release tag: `v0.29.0`.

package/docs/roadmap/README.md

@@ -1,6 +1,6 @@
 # Version 1.0 Roadmap Plan
 
-Detailed plan for moving `@techspokes/typescript-wsdl-client` from `0.26.x` to a stable `1.0.0` release.
+Detailed plan for moving `@techspokes/typescript-wsdl-client` from the released `0.28.x` line to a stable `1.0.0` release.
 
 See the root [README.md](../../README.md) for project overview and the root [ROADMAP.md](../../ROADMAP.md) for the public roadmap summary.
 
@@ -8,28 +8,29 @@ See the root [README.md](../../README.md) for project overview and the root [ROA
 
 This plan turns the 1.0 roadmap into implementation slices that can be picked up independently. Each slice has its own plan document with scope, testing strategy, acceptance gates, and release implications.
 
-The plan is optimized for preserving quality. Contract mismatches are resolved before new capability work, compatibility research constrains schema changes, and WSDL coverage work turns unsupported behavior into explicit diagnostics.
+The plan is optimized for preserving quality. The contract and compatibility baselines now exist, choice union mode is shipped, and JSON array streaming is shipped. The remaining readiness work is WSDL coverage evidence and the final release candidate gate pass.
 
 ## Route Summary
 
-| Slice | Document | Outcome |
-|-------|----------|---------|
-| Contract audit | [Contract Audit](v1.0-contract-audit.md) | Public surfaces match behavior |
-| OpenAPI compatibility | [OpenAPI Fastify Compatibility](v1.0-openapi-fastify-compatibility.md) | Schema strategy is proven |
-| Choice union mode | [Choice Union Mode](v1.0-choice-union-mode.md) | Implemented in `0.26.0` |
-| JSON array streaming | [JSON Array Streaming](v1.0-json-array-streaming.md) | `format: "json-array"` works |
-| WSDL coverage matrix | [WSDL Coverage Matrix](v1.0-wsdl-coverage-matrix.md) | Feature support is test-backed |
-| Release candidate | [Release Candidate Gates](v1.0-release-candidate-gates.md) | 1.0 release is repeatable |
+| Slice                 | Document                                                                     | Status            | Outcome                         |
+|-----------------------|------------------------------------------------------------------------------|-------------------|---------------------------------|
+| Contract audit        | [Contract Audit](v1.0-contract-audit.md)                                     | baseline complete | Public surfaces match behavior  |
+| OpenAPI compatibility | [OpenAPI Fastify Compatibility](v1.0-openapi-fastify-compatibility.md)       | baseline complete | Schema strategy is proven       |
+| Choice union mode     | [Choice Union Mode](v1.0-choice-union-mode.md)                               | complete          | Implemented in `0.26.0`         |
+| JSON array streaming  | [JSON Array Streaming](v1.0-json-array-streaming.md)                         | complete          | Implemented in `0.28.0`         |
+| Conformance framework | [Capability Conformance Framework](v1.0-capability-conformance-framework.md) | planned           | Pipeline claims are test-backed |
+| WSDL coverage matrix  | [WSDL Coverage Matrix](v1.0-wsdl-coverage-matrix.md)                         | remaining         | Feature support is test-backed  |
+| Release candidate     | [Release Candidate Gates](v1.0-release-candidate-gates.md)                   | remaining         | 1.0 release is repeatable       |
 
 ## Execution Order
 
 ### Slice 1: Contract Audit
 
-Start with contract audit because it defines the exact public promises that later slices must satisfy. This slice updates docs, identifies mismatched flags and options, and creates failing tests for the behavior that must become true.
+The baseline contract audit is complete. Keep it active as release hygiene so CLI docs, API docs, configuration docs, examples, roadmap statements, and generated behavior stay aligned.
 
 ### Slice 2: OpenAPI Fastify Compatibility
 
-Run compatibility research before changing union schemas or streaming JSON schemas. This keeps schema design constrained by Fastify validation, Fastify serialization, and generated gateway behavior.
+Compatibility research is complete for choice union mode and JSON array streaming. Run the same local Fastify probes before any future schema output changes.
 
 ### Slice 3: Choice Union Mode
 
@@ -37,16 +38,28 @@ Choice union mode is complete in `0.26.0`. The default `all-optional` mode remai
 
 ### Slice 4: JSON Array Streaming
 
-Implement streaming JSON array output after stream error behavior is researched. This is the next implementation slice after `0.26.0`, and the result must stream records incrementally without buffering the full SOAP response.
+JSON array streaming is complete in `0.28.0`. The default `ndjson` format remains unchanged, and `format: "json-array"` streams records incrementally without buffering the full SOAP response.
 
-### Slice 5: WSDL Coverage Matrix
+### Slice 5: Capability Conformance Framework
 
-Build the automated WSDL feature matrix once the two existing public contract gaps are handled. The matrix should then drive the remaining WSDL support and diagnostic decisions.
+Build the conformance registry, fixture strategy, stage runners, and issue-triage model. This slice turns feature claims into testable pipeline-wide capability cases.
 
-### Slice 6: Release Candidate Gates
+### Slice 6: WSDL Coverage Matrix
+
+Build the automated WSDL feature matrix next. The matrix should drive the remaining WSDL support, diagnostic, and deferral decisions.
+
+### Slice 7: Release Candidate Gates
 
 Run the release candidate gates after feature work and documentation have converged. This slice validates docs, tests, generated examples, package contents, skill artifact, release notes, and provenance workflow readiness.
 
+## Remaining Before 1.0
+
+- Build the capability conformance registry and runner.
+- Build and run the WSDL feature matrix as the first conformance domain.
+- Turn unsupported or partial matrix rows into diagnostics, documentation, or scoped fixes.
+- Confirm `docs/supported-patterns.md` matches the matrix.
+- Run the release-candidate gates.
+
 ## Quality Principles
 
 - Keep default generated output stable unless a slice explicitly changes it.
@@ -72,8 +85,8 @@ Run the release candidate gates after feature work and documentation have conver
 
 ### Coverage Gate
 
-- A WSDL feature matrix runs under test automation.
-- Each matrix entry has a fixture and expected behavior.
+- A capability conformance matrix runs under test automation.
+- Each matrix entry has a fixture, status, and stage expectations.
 - Unsupported features fail loudly or are documented as deliberately unsupported.
 
 ### Release Gate

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

@@ -0,0 +1,219 @@
+# Version 1.0 Capability Conformance Framework
+
+Status: planned before `1.0.0`.
+
+Plan for turning SOAP, WSDL, OpenAPI, gateway, app, generated-test, and documentation support claims into fixture-backed conformance evidence.
+
+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.
+
+## 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;
+  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.
+
+## 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
+
+Create the capability registry, fixture directory, and a Vitest runner for compile-stage expectations. Include the existing roadmap priority rows and keep unsupported rows diagnostic or research-only until behavior is proven.
+
+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.
+
+## Phase 2: 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.
+
+## Phase 3: Gateway Runtime Evidence
+
+Extend relevant rows to generate gateways and test Fastify runtime behavior through `fastify.inject`. Add mock operations clients and request/response fixtures as part of the registry.
+
+Acceptance criteria:
+
+- Supported gateway rows register generated plugins successfully.
+- Valid request fixtures return expected envelopes or streams.
+- Invalid request fixtures fail with expected status codes.
+- Stream rows prove NDJSON and JSON array behavior separately.
+
+## Phase 4: Generated Test And App Evidence
+
+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.
+
+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`.
+
+## Phase 5: Documentation And Release Gates
+
+Wire the conformance framework into docs validation, CI, or release preflight once runtime cost is acceptable. Keep a focused command for maintainers who want only conformance checks.
+
+Acceptance criteria:
+
+- `docs/supported-patterns.md` cannot drift from the registry.
+- CI or release preflight runs the selected conformance subset.
+- Full conformance can run locally before `1.0.0`.
+- Release notes can cite capability IDs for behavior changes.
+
+## Phase 6: WSDL Inspector
+
+Build the inspector after the registry has enough stable coverage to be useful. Start 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.
+
+## Open Decisions
+
+- Decide whether the first registry lives under `test/fixtures` or `test/conformance`.
+- Decide whether conformance should be a normal `npm test` suite or a separate script at first.
+- Decide how much generated output type-checking is acceptable in CI runtime.
+- Decide which inspector output format becomes public before `1.0.0`.
+- Decide whether docs should remain manually maintained or eventually generated from the registry.
+
+## Release Implications
+
+This framework is 1.0 readiness infrastructure. It can ship incrementally in `0.28.x` or later patch releases as tests, docs, and diagnostics improve.
+
+Do not block the first conformance slice on the WSDL inspector. The registry and runner create the durable foundation; the inspector should reuse that foundation after it proves useful.

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

@@ -1,6 +1,8 @@
 # Version 1.0 Contract Audit
 
-Plan for aligning public flags, programmatic options, docs, and generated behavior before implementing the remaining 1.0 features.
+Status: baseline completed in `0.25.2`; ongoing as release hygiene.
+
+Plan for keeping public flags, programmatic options, docs, generated behavior, and roadmap statements aligned through `1.0.0`.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
@@ -8,39 +10,38 @@ See the root [README.md](../../README.md) for project overview and [Version 1.0
 
 The contract audit makes every public promise explicit before 1.0. A public promise includes CLI flags, programmatic options, configuration files, generated file shapes, documentation examples, release workflow claims, and roadmap statements.
 
-## Why This Slice Comes First
+## Why This Slice Remains Active
 
-This slice prevents later work from building on ambiguous behavior. It also gives contributors a reliable target when they implement choice union mode, JSON array streaming, and WSDL feature coverage.
+This slice prevents later work from building on ambiguous behavior. Choice union mode and JSON array streaming are shipped, so the audit now protects those contracts while WSDL coverage and release-candidate work proceed.
 
-## Scope
+## Ongoing Scope
 
 - Audit CLI flags in `src/cli.ts` against `docs/cli-reference.md`.
 - Audit programmatic options in exported types against `docs/api-reference.md`.
 - Audit configuration file formats against `docs/configuration.md`.
 - Audit generated output claims against snapshots and `examples/generated-output`.
 - Refresh `ROADMAP.md` so shipped work is not listed as future work.
-- Add failing tests for public behavior that must be implemented in later slices.
+- Add focused tests for public behavior when the audit finds a real drift risk.
 
 ## Out Of Scope
 
-- Do not implement choice union mode in this slice.
-- Do not implement JSON array streaming in this slice.
 - Do not expand WSDL feature support in this slice.
 - Do not change default generated output unless a contract is already wrong.
+- Do not treat release metadata gaps as feature support.
 
 ## Required Findings
 
 ### Choice Mode
 
-`--client-choice-mode union` must stay public because 1.0 requires full union support. The audit should identify every code path and doc section that must change when union mode is implemented.
+`--client-choice-mode union` is implemented in `0.26.0`. Audit passes should keep CLI docs, API docs, generated-code docs, supported-pattern docs, tests, and examples aligned with the released opt-in behavior.
 
 ### JSON Array Streaming
 
-`format: "json-array"` must stay in the 1.0 roadmap because 1.0 requires the format. The audit should identify every parser, client, OpenAPI, gateway, runtime, and docs surface that currently assumes NDJSON.
+`format: "json-array"` is implemented in `0.28.0`. The audit should keep every parser, client, OpenAPI, gateway, runtime, and docs surface aligned across both stream formats.
 
 ### Roadmap State
 
-`ROADMAP.md` must reflect `0.25.x` as current. Release preflight and security hardening must be treated as shipped work.
+`ROADMAP.md` must reflect the released `0.28.x` line. Choice union mode and JSON array streaming must be treated as shipped work, while WSDL coverage and release-candidate gates remain the active 1.0 work.
 
 ### Release Metadata
 
@@ -58,15 +59,15 @@ Add or update focused tests that inspect CLI option availability and generated m
 
 ### Negative Tests
 
-Add tests that document the current failing behavior for union mode and JSON array streaming only if the next slice can consume them. These tests should be skipped or marked as expected failures only if the repository already has an accepted pattern for that.
+Add negative tests only for newly identified contract gaps that a follow-up slice can consume. These tests should be skipped or marked as expected failures only if the repository already has an accepted pattern for that.
 
 ## Acceptance Criteria
 
-- `ROADMAP.md` names `0.25.x` as current.
+- `ROADMAP.md` names released `0.28.x` work accurately.
 - `docs/roadmap/README.md` links every 1.0 slice.
 - CLI, API, and configuration docs agree on required 1.0 behavior.
 - Known contract gaps are linked to implementation slices.
-- `CHANGELOG.md` has one `docs(roadmap):` entry for the audit docs.
+- `CHANGELOG.md` has one `docs(roadmap):` entry when audit docs change.
 - `npm run docs:validate` passes.
 
 ## Release Implications

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

@@ -1,29 +1,29 @@
 # Version 1.0 JSON Array Streaming
 
-Plan for implementing `format: "json-array"` streaming for SOAP operations that already use the stream configuration model.
+Status: implemented for `0.28.0`.
 
-This is the next planned feature slice after the `0.26.0` choice union mode release.
+This document records the implementation slice for `format: "json-array"` streaming for SOAP operations that already use the stream configuration model.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
 ## Goal
 
-`format: "json-array"` must stream records incrementally as a valid JSON array without buffering the full SOAP response. The implementation must be compatible with generated clients, OpenAPI output, Fastify routes, generated tests, and production docs.
+`0.28.0` completes `format: "json-array"` streaming as a valid JSON array without buffering the full SOAP response. The implementation is compatible with generated clients, OpenAPI output, Fastify routes, generated tests, and production docs.
 
 ## Design Direction
 
-JSON array streaming should write an opening bracket, stream comma-separated JSON records, and write a closing bracket after the async iterable completes. The implementation must preserve backpressure by converting the async iterable into a Node `Readable` stream.
+JSON array streaming writes an opening bracket with the first record, streams comma-separated JSON records, and writes a closing bracket after the async iterable completes. The implementation preserves backpressure by converting the async iterable into a Node `Readable` stream.
 
-The key research question is error timing. If the route can observe an upstream error before sending the first byte, it should still return the normal error envelope. Once the JSON array response has started, a later error must truncate the response and clients must treat the JSON parse failure as a failed stream.
+The key researched constraint is error timing. The helper prefetches the first record before sending the first byte, so an upstream error before the first record still returns the normal error envelope. Once the JSON array response has started, a later error truncates the response and clients must treat the JSON parse failure as a failed stream.
 
-## Scope
+## Completed Scope
 
-- Implement a runtime helper for JSON array streaming.
-- Preserve existing NDJSON behavior.
-- Emit JSON array route handlers when stream metadata says `format: "json-array"`.
-- Emit `application/json` OpenAPI content with an array item schema.
-- Generate stream-aware mock clients and tests for JSON array operations.
-- Document terminal-error behavior for JSON array clients.
+- Implemented a runtime helper for JSON array streaming.
+- Preserved existing NDJSON behavior.
+- Emitted JSON array route handlers when stream metadata says `format: "json-array"`.
+- Emitted `application/json` OpenAPI content with an array item schema.
+- Generated stream-aware mock clients and tests for JSON array operations.
+- Documented terminal-error behavior for JSON array clients.
 
 ## Out Of Scope
 
@@ -31,29 +31,29 @@ The key research question is error timing. If the route can observe an upstream
 - Do not change buffered SOAP operations.
 - Do not make JSON array the default stream format.
 
-## Research Tasks
+## Research Findings
 
 ### First-Byte Timing
 
-Research whether generated routes should prefetch the first record before calling `reply.send`. Prefetching can preserve normal error envelopes for errors that happen before any record is available, but it may delay response headers for slow upstream services.
+Generated routes prefetch the first record before emitting the first JSON array byte. This preserves normal error envelopes for errors that happen before any record is available, with the tradeoff that response headers wait for the first upstream record.
 
 ### Empty Stream Handling
 
-Confirm that an empty stream returns `[]` with `application/json`. The helper must emit a syntactically valid empty array without special route code where possible.
+An empty stream returns `[]` with `application/json`. The helper emits a syntactically valid empty array without special route code.
 
 ### Backpressure Handling
 
-Confirm that the helper does not pull from the async iterable faster than the HTTP stream can write. Use tests modeled after existing NDJSON backpressure tests.
+Tests confirm that the helper does not pull from the async iterable faster than the HTTP stream can write. The coverage mirrors the existing NDJSON backpressure tests.
 
 ### Terminal Error Handling
 
-Confirm how Fastify and Node surface stream errors after the JSON array has begun. Document the client-visible behavior in production docs and troubleshooting docs.
+Fastify surfaces stream errors after the JSON array has begun as a destroyed or reset response under inject and as a truncated response to real clients. Production docs and troubleshooting docs describe this as a failed stream.
 
 ## Implementation Units
 
 ### Runtime Helper
 
-Add `toJsonArray<T>(records: AsyncIterable<T>): Readable` beside `toNdjson`. The helper should serialize records with `JSON.stringify`, insert commas between records, and close the array when iteration completes.
+Added `toJsonArray<T>(records: AsyncIterable<T>): Readable` beside `toNdjson`. The helper serializes records with `JSON.stringify`, inserts commas between records, and closes the array when iteration completes.
 
 ### Gateway Emitter
 
@@ -87,6 +87,8 @@ Test errors before the first emitted record separately from errors after at leas
 
 ## Acceptance Criteria
 
+Satisfied by `0.28.0`:
+
 - `format: "json-array"` generates working client, OpenAPI, gateway, and tests.
 - JSON array output is parseable when the source completes normally.
 - Output is streamed incrementally and does not buffer the full response.
@@ -96,4 +98,4 @@ Test errors before the first emitted record separately from errors after at leas
 
 ## Release Implications
 
-This slice is a user-facing feature release. The release notes must state that `json-array` is no longer reserved and can be selected per operation with `stream-config`.
+This slice shipped as the `0.28.0` user-facing feature release. The release notes state that `json-array` can be selected per operation with `stream-config`, while NDJSON remains the default stream format.