@techspokes/typescript-wsdl-client 1.1.8 → 1.3.0

package/README.md

@@ -9,13 +9,25 @@ Turn legacy WSDL/SOAP services into typed TypeScript clients and optional REST A
 
 Created from production integration work at [TechSpokes](https://www.techspokes.com); built for teams modernizing real enterprise SOAP integrations.
 
+## Upgrading to 1.3.0
+
+Version 1.3.0 adds opt-in checked SOAP 1.2 document/literal execution through the existing adapter. Existing SOAP 1.1 and direct-runtime bindings retain their contracts. SOAP 1.2 clients use an additive runtime handshake; regenerate matched artifacts when adopting that binding. Read the [1.2.x migration guidance](docs/migration.md#from-12x-to-130) for adoption and evidence limits.
+
+## Upgrading to 1.2.0
+
+Existing projects keep legacy generation unless they explicitly choose another profile. Regeneration can change affected DTO names, stream records and corrected scalar/simple-content results; 1.2.0 is not an unconditional drop-in regeneration upgrade. Read the [1.1.x migration guide](docs/migration.md#from-11x-to-120) before updating, including matched artifact regeneration, scaffold preservation, consumer checks and rollback.
+
+Published npm starting points include 1.1.5 and 1.1.8; 1.1.6 and 1.1.7 were unpublished candidates. Native multi-service composition and checked generation are optional capabilities with separate adoption instructions, not automatic migrations of an existing gateway.
+
 ## Pick Your Path
 
 | Goal | Command | What you get |
 |------|---------|-------------|
 | Typed SOAP client | `npx wsdl-tsc client` | TypeScript types, typed operations, mockable interface |
 | OpenAPI 3.1 spec | `npx wsdl-tsc openapi` | OpenAPI JSON/YAML generated from WSDL |
-| Full SOAP-to-REST bridge | `npx wsdl-tsc pipeline` | Client + OpenAPI + Fastify gateway + runnable app |
+| Full SOAP-to-REST bridge | `npx wsdl-tsc pipeline --init-app` | Client + OpenAPI + Fastify gateway + runnable app |
+| Several SOAP sources behind one API | `npx wsdl-tsc pipeline --services-config services.json` | Separate legacy clients, one gateway plugin and combined OpenAPI |
+| Checked document/literal or bounded RPC | `npx wsdl-tsc pipeline --model checked-components-v1` | Source-backed validation and buffered checked values |
 
 See [Start Here](docs/start-here.md) for detailed guidance on choosing a path.
 
@@ -31,7 +43,7 @@ Checked generation can opt into [application groups and configured names](docs/c
 
 ## Why Choose This
 
-Most tools in this space stop at one layer: a SOAP runtime, type generation, or spec conversion. This package generates the full stack from a single WSDL source.
+Most tools in this space stop at one layer: a SOAP runtime, type generation, or spec conversion. This package generates the full stack from a WSDL source and can compose independent legacy sources into one REST gateway.
 
 - Typed client, OpenAPI spec, REST gateway, and runnable app from one command
 - Deterministic output safe for CI regeneration and version control
@@ -101,6 +113,10 @@ curl -X POST http://localhost:3000/get-weather-information \
   -H "Content-Type: application/json" -d '{}'
 ```
 
+### Compose several SOAP services
+
+Use `pipeline --services-config ./services.json` to generate each source into separate client, catalog, OpenAPI and gateway paths, then emit one aggregate plugin and API document. The [multi-service guide](docs/gateway-guide.md#multi-service-setup) shows the configuration and generated `createClients` helper; each runtime client keeps its own WSDL source, endpoint and security settings. Native composition currently supports legacy generation; checked composition remains deferred.
+
 ## What Gets Generated
 
 | Output | Files | Purpose |
@@ -229,6 +245,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Configuration](docs/configuration.md) | Gateway security, upstream SOAP security, tags, operation overrides |
 | [Migration Playbook](docs/migration-playbook.md) | End-to-end SOAP modernization guide |
 | [Gateway Guide](docs/gateway-guide.md) | Fastify integration, inbound enforcement, and error handling |
+| [Multi-Service Gateway Status](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/roadmap/multi-service-gateway.md) | Implemented legacy composition, mapping boundaries, and deferred checked composition |
 | [Testing Guide](docs/testing.md) | Consumer tests and separate maintainer verification guidance |
 | [Production Guide](docs/production.md) | CI/CD, validation, logging |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and debugging |
@@ -236,6 +253,8 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
 | [Agent Skill Artifact](docs/agent-skill.md) | Release ZIP for consumer-project AI agents |
 | [Version Migration](docs/migration.md) | Upgrading between package versions |
+| [1.2.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.2.0.md) | Composition, consumer compatibility and bounded RPC qualification |
+| [1.3.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.3.0.md) | Checked SOAP 1.2 execution and preserved SOAP 1.1 compatibility |
 | [XML/JSON Mapping Contract](docs/mapping-contract.md) | Checked keyed, namespace, nil and group representations |
 | [Product Corpus](docs/corpus.md) | Representative public inputs and their executable evidence |
 
@@ -259,7 +278,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Direct Structural Matching](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/content-model-matching.md) | Internal structure-only matcher, evidence and scalar handoff |
 | [Architecture](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/architecture.md) | Internal pipeline for contributors |
 | [Reference Validation](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/reference-validation.md) | Internal evidence contract and Node tooling migration inventory |
-| [NOAA NDFD Qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) | Authentic source provenance and one-operation native refusal |
+| [NOAA NDFD Qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) | All-12 owned RPC execution, ten live successes and two live GML refusals |
 | [File Naming And Path Organization](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/file-naming-and-path-organization.md) | Contributor convention for taxonomy paths and fixture retrieval |
 
 ### Decisions and research

package/dist/checkedPlanning.js

@@ -166,10 +166,8 @@ export async function prepareCheckedComponentPlan(source, choices = {}, outputs)
                         && namespace !== XSD_NAMESPACE)
                         missing.set(namespace, child.source);
                 }
-            for (const [namespace, at] of missing)
-                add('missing-dependency', 'loading', `locationless-import:${namespace}`, 'Supply an authorized schema path for this namespace.', `checkedComponents.namespaceLocations[${JSON.stringify(namespace)}].location`, selectors.length ? selectors : operations.flatMap(o => o.binding ? [{ portType: o.portType, binding: o.binding, operation: o.operation }] : []), at);
-            if (missing.size)
-                unresolved = [...(intake.namespaceLocations ?? []), ...[...missing.keys()].sort().map(namespace => ({ namespace, location: 'REQUIRED_SCHEMA_LOCATION' }))];
+            // @why XSD 1.0 section 4.2.3 permits locationless imports. Native construction
+            //   decides whether their components are needed; namespace URIs are never fetch locations.
             if (!blockers.length && config) {
                 if (!Object.hasOwn(explicit, 'standardLibraries') && input.schemas.some(s => syntaxElements(s.syntax, XSD_NAMESPACE, 'import')
                     .some(n => syntaxAttribute(n, 'namespace') === XSD_NAMESPACE && syntaxAttribute(n, 'schemaLocation') === undefined))) {
@@ -188,6 +186,31 @@ export async function prepareCheckedComponentPlan(source, choices = {}, outputs)
                     }
                 }
                 for (const refusal of native.refusals) {
+                    if (['whole-source-qualification', 'source-preparation'].includes(refusal.rule) && missing.size) {
+                        const referenced = new Set();
+                        const pending = documents.map(document => document.root);
+                        while (pending.length) {
+                            const node = pending.pop();
+                            for (const attribute of node.attributes)
+                                if (attribute.name.namespace === ''
+                                    && ['type', 'ref', 'base', 'itemType', 'memberTypes', 'substitutionGroup', 'element'].includes(attribute.name.local)) {
+                                    for (const token of attribute.value.trim().split(/[\t\r\n ]+/)) {
+                                        try {
+                                            referenced.add(resolveLexicalQName(token, node).namespace);
+                                        }
+                                        catch { /* Native diagnostics retain malformed references. */ }
+                                    }
+                                }
+                            pending.push(...syntaxElements(node));
+                        }
+                        const needed = [...missing].filter(([namespace]) => referenced.has(namespace));
+                        for (const [namespace, at] of needed)
+                            add('missing-dependency', 'native-preparation', `locationless-import:${namespace}`, 'Supply an authorized schema path for required components in this namespace.', `checkedComponents.namespaceLocations[${JSON.stringify(namespace)}].location`, [refusal.selector], at);
+                        if (needed.length) {
+                            unresolved = [...(intake.namespaceLocations ?? []), ...needed.map(([namespace]) => namespace).sort().map(namespace => ({ namespace, location: 'REQUIRED_SCHEMA_LOCATION' }))];
+                            continue;
+                        }
+                    }
                     if (refusal.rule.startsWith('ambiguous-record-path:')) {
                         add('ambiguous-selection', 'native-preparation', refusal.rule, 'Supply recordPath using expanded names to select one declared repeated complex record in this companion source.', 'checkedComponents.recordProjections[].recordPath', [refusal.selector], undefined, 'mapping-and-artifact');
                         continue;

package/dist/cli.js

@@ -50,6 +50,7 @@ function loadStreamConfigOrExit(filePath) {
 }
 // Process command line arguments, removing the first two elements (node executable and script path)
 const rawArgs = hideBin(process.argv);
+const hasServicesConfig = rawArgs.some(argument => argument === "--services-config" || argument.startsWith("--services-config="));
 // Available commands
 const COMMANDS = ["compile", "client", "openapi", "gateway", "app", "pipeline", "assess"];
 // ---------------------------------------------------------------------------
@@ -613,10 +614,25 @@ if (rawArgs[0] === "app") {
     });
     process.exit(0);
 }
-if (rawArgs[0] === "pipeline") {
+if (rawArgs[0] === "pipeline" && hasServicesConfig) {
+    const argv = await yargs(rawArgs.slice(1)).version(false).scriptName("wsdl-tsc pipeline")
+        .option("services-config", { type: "string", demandOption: true, desc: "Multi-service generation configuration; exclusive with single-source pipeline flags" })
+        .strict().help().parse();
+    try {
+        const { loadMultiServiceConfig, runMultiServicePipeline } = await import("./multiServicePipeline.js");
+        const result = await runMultiServicePipeline(await loadMultiServiceConfig(argv["services-config"]));
+        success(`Composed gateway written to ${result.pluginFile}`);
+        success(`Combined OpenAPI specification written to ${result.openapiFile}`);
+    }
+    catch (error) {
+        handleCLIError(error);
+    }
+}
+if (rawArgs[0] === "pipeline" && !hasServicesConfig) {
     const pipelineArgv = await yargs(rawArgs.slice(1))
         .version(false)
         .scriptName("wsdl-tsc pipeline")
+        .option("services-config", { type: "string", desc: "Compose independent service pipelines from JSON; exclusive with single-source flags" })
         .usage("$0 --wsdl-source <file|url> [--client-dir <dir>] [--openapi-file <path>] [--gateway-dir <dir> --gateway-service-name <slug> --gateway-version-prefix <slug>] [--catalog-file <path>] [options]")
         .option("wsdl-source", { type: "string", demandOption: true, desc: "Path or URL to the WSDL" })
         .option("model", { type: "string", choices: ["legacy", "checked-components-v1"], default: "legacy", desc: "Generation model; components derive unambiguous WSDL selections" })

package/dist/client/checkedDirectRuntime.d.ts

@@ -1,4 +1,5 @@
-import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
+import type { ComponentClientResult } from './directClientRuntime.js';
+import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
 interface Name {
     readonly namespace: string;
     readonly local: string;
@@ -93,4 +94,13 @@ export declare const checkedComponentRuntimeV1: Readonly<{
     version: typeof COMPONENT_CLIENT_RUNTIME_VERSION;
     execute(expectedBase64: string, input: unknown, options: ComponentOptions, version: typeof COMPONENT_CLIENT_RUNTIME_VERSION): Promise<Failure | Success>;
 }>;
+/** Additive SOAP 1.2 binding permits protocol faults without declared application detail.
+ * @since 1.3.0
+ * @remarks Source reconstruction, endpoint restrictions and native validation use the shared component runtime.
+ * @returns Native component values, SOAP 1.2 protocol faults or explicit refusal; no full-profile admission.
+ */
+export declare const checkedComponentRuntimeV2: Readonly<{
+    version: typeof COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION;
+    execute(expectedBase64: string, input: unknown, options: ComponentOptions, version: typeof COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION): Promise<ComponentClientResult>;
+}>;
 export {};

package/dist/client/checkedDirectRuntime.js

@@ -1,6 +1,6 @@
 import { types } from 'node:util';
-import { directClientRuntime, componentClientRuntime } from './directClientRuntime.js';
-import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR } from './directClientVersion.js';
+import { directClientRuntime, componentClientRuntime, componentSoap12ClientRuntime } from './directClientRuntime.js';
+import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR, COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
 function dataOptions(options, allowed) {
     return !!options && typeof options === 'object' && !types.isProxy(options)
         && [null, Object.prototype].includes(Object.getPrototypeOf(options))
@@ -41,3 +41,20 @@ export const checkedComponentRuntimeV1 = Object.freeze({
         return componentClientRuntime.execute(expectedBase64, input, options);
     },
 });
+/** Additive SOAP 1.2 binding permits protocol faults without declared application detail.
+ * @since 1.3.0
+ * @remarks Source reconstruction, endpoint restrictions and native validation use the shared component runtime.
+ * @returns Native component values, SOAP 1.2 protocol faults or explicit refusal; no full-profile admission.
+ */
+export const checkedComponentRuntimeV2 = Object.freeze({
+    version: COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION,
+    async execute(expectedBase64, input, options, version) {
+        if (version !== COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION)
+            return Object.freeze({ kind: 'incompatible-artifact',
+                rule: 'generated-runtime-version', repair: COMPONENT_CLIENT_RUNTIME_REPAIR, usage: Object.freeze({ nodes: 0, work: 0 }) });
+        if (!dataOptions(options, ['localSource', 'fileRoots', 'capsule', 'soap', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'standardLibraries', 'recordSources'])) {
+            return Object.freeze({ kind: 'unsupported', rule: 'data-only checked component options required', usage: Object.freeze({ nodes: 0, work: 0 }) });
+        }
+        return componentSoap12ClientRuntime.execute(expectedBase64, input, options);
+    },
+});

package/dist/client/directClientRuntime.d.ts

@@ -1,6 +1,6 @@
 import type { SemanticBudgetLimits, ResolverUsage } from '../compiler/semanticBudget.js';
 import type { DirectCapsuleFailure } from '../compiler/directSourceCapsule.js';
-import type { DirectSoapOptions, ComponentSoapOptions, DirectSoapFailure } from '../compiler/directSoap.js';
+import type { DirectSoapOptions, ComponentSoapOptions, DirectSoapFailure, ComponentProtocolFault, DeclaredSoapFault } from '../compiler/directSoap.js';
 import type { DirectOperationSelector } from '../compiler/directOperation.js';
 import type { DirectApplicationValue } from '../compiler/directValues.js';
 import { DIRECT_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
@@ -65,6 +65,16 @@ export interface DirectClientRuntime {
     readonly version: typeof DIRECT_CLIENT_RUNTIME_VERSION;
     execute(expectedBase64: string, input: unknown, options: DirectClientOptions): Promise<DirectClientResult>;
 }
+/** Component-only protocol faults retain raw bytes without claiming an application value.
+ * @since 1.3.0
+ */
+export type ComponentClientResult = Exclude<DirectClientResult, {
+    kind: 'soap-fault';
+}> | ComponentProtocolFault | Readonly<Omit<Extract<DirectClientResult, {
+    kind: 'soap-fault';
+}>, 'fault'> & {
+    fault: Omit<DeclaredSoapFault, 'codeNode'>;
+}>;
 /** The generated literal is the expected artifact; caller bytes never choose its static contract. */
 export declare const directClientRuntime: DirectClientRuntime;
 /** Same artifact/execution chain, with explicit physical dependency snapshots and component-profile reconstruction. */
@@ -72,3 +82,10 @@ export declare const componentClientRuntime: Readonly<{
     version: "checked-component-runtime-v2";
     execute: (expectedBase64: string, input: unknown, options: ComponentClientOptions) => Promise<DirectClientResult>;
 }>;
+/** Additive SOAP 1.2 injection shares reconstruction and transport with SOAP 1.1.
+ * @since 1.3.0
+ */
+export declare const componentSoap12ClientRuntime: Readonly<{
+    version: "checked-component-soap12-runtime-v1";
+    execute: (expectedBase64: string, input: unknown, options: ComponentClientOptions) => Promise<ComponentClientResult>;
+}>;

package/dist/client/directClientRuntime.js

@@ -6,7 +6,7 @@ import { types } from 'node:util';
 import { createApplicationBudget } from '../compiler/semanticBudget.js';
 import { reconstructDirectSourceCapsuleInRequest, reconstructComponentSourceCapsuleInRequest, checkDirectSourceCompatibility, DIRECT_CAPSULE_LIMITS } from '../compiler/directSourceCapsule.js';
 import { exchangeDirectSoap, exchangeComponentSoap, directSoapOptionsShape } from '../compiler/directSoap.js';
-import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
+import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
 import { prepareSchemaSnapshotFiles } from '../loader/schemaInput.js';
 import { SchemaLoadingError } from '../loader/orderedSyntax.js';
 /** The generated literal is the expected artifact; caller bytes never choose its static contract. */
@@ -19,7 +19,14 @@ export const componentClientRuntime = Object.freeze({
     version: COMPONENT_CLIENT_RUNTIME_VERSION,
     execute: (expectedBase64, input, options) => executeClient(expectedBase64, input, options, true),
 });
-async function executeClient(expectedBase64, input, options, component) {
+/** Additive SOAP 1.2 injection shares reconstruction and transport with SOAP 1.1.
+ * @since 1.3.0
+ */
+export const componentSoap12ClientRuntime = Object.freeze({
+    version: COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION,
+    execute: (expectedBase64, input, options) => executeClient(expectedBase64, input, options, true, true),
+});
+async function executeClient(expectedBase64, input, options, component, allowSoap12 = false) {
     // Constant-sized entry introspection precedes budget configuration and all reads.
     const entryFailure = () => ({ kind: 'unsupported', rule: 'data-only client options required', usage: { nodes: 0, work: 0 } });
     if (!options || typeof options !== 'object' || types.isProxy(options)
@@ -121,6 +128,8 @@ async function executeClient(expectedBase64, input, options, component) {
                 standardLibraries: sources.standards, recordSources: sources.records }, budget);
             if (fresh.kind !== 'reconstructed-component')
                 return fresh;
+            if (fresh.contract.binding.version === '1.2' && !allowSoap12)
+                return fail('incompatible-artifact', 'SOAP 1.2 runtime binding required');
             if (fresh.selection.port !== options.soap.port || fresh.selection.service.namespace !== options.soap.service.namespace
                 || fresh.selection.service.local !== options.soap.service.local)
                 return fail('incompatible-artifact', 'explicit source selection mismatch');
@@ -138,8 +147,11 @@ async function executeClient(expectedBase64, input, options, component) {
             // by the original adapter; no catch-and-cast turns a failure into typed success.
             result = await exchangeDirectSoap(fresh.contract, fresh.mappings[0], input, options.soap);
         }
-        if (!('decoded' in result))
+        if (!('decoded' in result)) {
+            if (result.kind === 'soap-fault' && !allowSoap12)
+                return fail('incompatible-artifact', 'SOAP 1.2 runtime binding required');
             return result;
+        }
         if (options.soap.signal?.aborted)
             return fail('cancelled', 'cooperative-cancellation');
         const common = { value: result.decoded.validated.value, status: result.status, admitted: false,

package/dist/client/directClientVersion.d.ts

@@ -3,4 +3,6 @@ export declare const DIRECT_CLIENT_RUNTIME_VERSION: "checked-direct-runtime-v1";
 export declare const DIRECT_CLIENT_RUNTIME_REPAIR = "Regenerate matched direct client and capsule with the installed runtime.";
 /** Component profile never impersonates the supported direct preview protocol. */
 export declare const COMPONENT_CLIENT_RUNTIME_VERSION: "checked-component-runtime-v2";
+/** SOAP 1.2 can return protocol faults without declared application values. */
+export declare const COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION: "checked-component-soap12-runtime-v1";
 export declare const COMPONENT_CLIENT_RUNTIME_REPAIR = "Regenerate matched component client and source artifacts with the installed runtime.";

package/dist/client/directClientVersion.js

@@ -3,4 +3,6 @@ export const DIRECT_CLIENT_RUNTIME_VERSION = 'checked-direct-runtime-v1';
 export const DIRECT_CLIENT_RUNTIME_REPAIR = 'Regenerate matched direct client and capsule with the installed runtime.';
 /** Component profile never impersonates the supported direct preview protocol. */
 export const COMPONENT_CLIENT_RUNTIME_VERSION = 'checked-component-runtime-v2';
+/** SOAP 1.2 can return protocol faults without declared application values. */
+export const COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION = 'checked-component-soap12-runtime-v1';
 export const COMPONENT_CLIENT_RUNTIME_REPAIR = 'Regenerate matched component client and source artifacts with the installed runtime.';

package/dist/client/generateClient.js

@@ -66,6 +66,18 @@ export function generateClient(outFile, compiled) {
     const soapOptions = soapImport("IOptions");
     const soapSecurity = soapImport("ISecurity");
     const soapFactory = soapImport("createClientAsync");
+    const soapHttpClient = soapImport("HttpClient");
+    const soapExOptions = soapImport("IExOptions");
+    const aliases = new Map(compiled.aliases.map(alias => [alias.name, alias.tsType]));
+    const scalarTypes = Object.fromEntries(compiled.aliases.flatMap(alias => {
+        let type = alias.tsType;
+        const visited = new Set([alias.name]);
+        while (aliases.has(type) && !visited.has(type)) {
+            visited.add(type);
+            type = aliases.get(type);
+        }
+        return ["string", "number", "boolean", "bigint"].includes(type) || type.endsWith("[]") ? [[alias.name, type]] : [];
+    }));
     // Track whether any operation opts into streaming, so we can emit the
     // supporting runtime helpers only when they're actually used.
     let anyStream = false;
@@ -97,12 +109,14 @@ export function generateClient(outFile, compiled) {
    * Streams records from the ${m} operation of the ${clientName}.${opDocStr}${secHintsStr}
    *
    * @param args - The request arguments for the ${m} operation.
+   * @param options - Optional cancellation signal and total stream deadline in milliseconds.
    * @returns A promise resolving to a streaming response whose \`records\` is an
    *          async iterable of ${recordTs} objects parsed from the SOAP body as
    *          chunks arrive. Iteration pulls bytes on demand.
    */
   async ${m}<HeadersType = Record<string, string>>(
-    args: ${inTs}
+    args: ${inTs},
+    options?: StreamCallOptions
   ): Promise<StreamOperationResponse<T.${recordTs}, HeadersType>> {
     return this.callStream<${inTs}, T.${recordTs}, HeadersType>(
       args,
@@ -112,7 +126,8 @@ export function generateClient(outFile, compiled) {
       ${JSON.stringify(inputElementLocal)},
       ${JSON.stringify(inputElementNs)},
       ${JSON.stringify(op.soapAction ?? "")},
-      ${JSON.stringify(op.stream.recordPath)}
+      ${JSON.stringify(op.stream.recordPath)},
+      options
     );
   }`;
             methods.push(methodTemplate);
@@ -144,7 +159,11 @@ export function generateClient(outFile, compiled) {
     // inside this template literal (which would flag `this`, `await`, `yield`
     // outside-of-function false positives).
     const streamMethodsBlock = anyStream
-        ? "\n" + loadRuntimeSource("clientStreamMethods.tpl.txt").replace("__SOAP_CLIENT_TYPE__", soapClient.local)
+        ? "\n" + loadRuntimeSource("clientStreamMethods.tpl.txt")
+            .replaceAll("__SOAP_CLIENT_TYPE__", soapClient.local)
+            .replaceAll("__SOAP_HTTP_CLIENT__", soapHttpClient.local)
+            .replaceAll("__SOAP_EX_OPTIONS__", soapExOptions.local)
+            .replaceAll("__SOAP_SECURITY__", soapSecurity.local)
         : "";
     // noinspection JSFileReferences,JSUnresolvedReference,CommaExpressionJS,JSDuplicatedDeclaration,ReservedWordAsName,JSCommentMatchesSignature,JSValidateTypes,JSIgnoredPromiseFromCall,BadExpressionStatementJS,ES6UnusedImports,JSUnnecessarySemicolon,UnreachableCodeJS,JSUnusedLocalSymbols
     const classTemplate = `// noinspection JSAnnotator
@@ -153,13 +172,14 @@ export function generateClient(outFile, compiled) {
  * Generated ${clientName} client class.
  * This class wraps the node-soap client and provides strongly-typed methods for each operation.
  */
-import {${soapFactory.specifier}} from "soap";
-import type {${soapClient.specifier}, ${soapOptions.specifier}, ${soapSecurity.specifier}} from "soap";
+import {${soapFactory.specifier}${anyStream ? `, ${soapHttpClient.specifier}` : ""}} from "soap";
+import type {${soapClient.specifier}, ${soapOptions.specifier}, ${soapSecurity.specifier}${anyStream ? `, ${soapExOptions.specifier}` : ""}} from "soap";
 import type * as T from "./types${suffix}";
 import type {${clientName}DataTypes} from "./utils${suffix}";
 import {${clientConstant}_DATA_TYPES} from "./utils${suffix}";${anyStream ? `
 import {parseRecords, type RecordParseSpec} from "./streamXml${suffix}";
-import type {StreamOperationResponse} from "./operations${suffix}";` : ""}
+import type {StreamOperationResponse, StreamCallOptions} from "./operations${suffix}";
+export type {StreamCallOptions} from "./operations${suffix}";` : ""}
 
 /**
  * Represents the response structure for ${clientName} operations.
@@ -214,6 +234,8 @@ export class ${clientName} {
   protected attributesKeyOut: string;
   protected client?: ${soapClient.local};
   protected dataTypes: ${clientName}DataTypes = ${clientConstant}_DATA_TYPES;
+  protected scalarTypes: Readonly<Record<string, string>> = ${JSON.stringify(scalarTypes)};
+${anyStream ? `  protected streamRequestOptions: ${soapExOptions.local};\n` : ""}
 
   /**
    * Creates a new ${clientName} instance.
@@ -224,17 +246,20 @@ export class ${clientName} {
    * @param [options.security] - Optional SOAP security settings to apply.
    * @param [options.attributesKeyIn] - Key name for input attribute bags (default: "$attributes").
    * @param [options.attributesKeyOut] - Key name for output attribute bags (default: "attributes").
-   */
+${anyStream ? `   * @param [options.streamRequestOptions] - Stream HTTP options such as verified HTTPS agents, separate from WSDL options.\n` : ""}   */
   constructor(options: {
     source: string,
     options?: ${soapOptions.local},
     security?: ${soapSecurity.local},
     attributesKeyIn?: string,
-    attributesKeyOut?: string
+    attributesKeyOut?: string${anyStream ? `,
+    /** HTTP request options for stream calls, including HTTPS agents and timeouts; WSDL options stay separate. */
+    streamRequestOptions?: ${soapExOptions.local}` : ""}
   }) {
     this.source = options.source;
     this.attributesKeyIn = options.attributesKeyIn ?? "$attributes";
     this.attributesKeyOut = options.attributesKeyOut ?? "attributes";
+${anyStream ? `    this.streamRequestOptions = options.streamRequestOptions ?? {};\n` : ""}
     if (options.options) {
       this.options = options.options;
     }
@@ -402,13 +427,28 @@ ${methodsBody}
    *
    * @param node - The raw SOAP response node.
    * @param typeName - Optional metadata key to guide deserialization.
+   * @param nonNillable - Whether parent schema metadata rules out a nil child, permitting empty-object recovery.
    * @returns The deserialized object matching your DTO shape.
+   * @throws TypeError for invalid boolean, numeric, or bigint lexical values.
    */
-  protected fromSoapResult(node: any, typeName?: string): any {
-    // Pass through null/undefined unchanged
+  protected fromSoapResult(node: any, typeName?: string, nonNillable = false): any {
+    // @why node-soap collapses empty complex elements to null; only a declared non-nillable child permits recovering its object DTO.
+    // @constraints Nullable children and unknown/custom metadata retain null, including explicit xsi:nil responses.
+    if (node === null && nonNillable && typeName && Object.hasOwn(this.dataTypes.Attributes, typeName)
+      && Object.keys(this.dataTypes.ChildrenTypes[typeName] ?? {}).length === 0) return {};
     if (node == null) {
       return node;
     }
+    if (typeName && Object.hasOwn(this.scalarTypes, typeName)) typeName = this.scalarTypes[typeName];
+    if (typeName?.endsWith("[]")) {
+      let itemType = typeName.slice(0, -2);
+      if (itemType.startsWith("(") && itemType.endsWith(")")) itemType = itemType.slice(1, -1);
+      if (typeof node === "string") {
+        const lexical = node.replace(/^[\\t\\r\\n ]+|[\\t\\r\\n ]+$/g, "");
+        return lexical === "" ? [] : lexical.split(/[\\t\\r\\n ]+/).map(item => this.fromSoapResult(item, itemType));
+      }
+      if (Array.isArray(node)) return node.map(item => this.fromSoapResult(item, itemType));
+    }
     const childrenTypes: Readonly<Record<string, string>> = (typeName && this.dataTypes?.ChildrenTypes?.[typeName]) || {};
     const attributeTypes: Readonly<Record<string, string>> = (typeName && this.dataTypes?.AttributeTypes?.[typeName]) || {};
     // XML boolean attributes arrive as lexical strings even when element booleans are parsed by node-soap.
@@ -418,8 +458,22 @@ ${methodsBody}
       if (lexical === "false" || lexical === "0") return false;
       throw new TypeError("Invalid XML boolean response value");
     }
+    if (typeof node === "string" && (typeName === "number" || typeName === "bigint")) {
+      const lexical = node.replace(/^[\\t\\r\\n ]+|[\\t\\r\\n ]+$/g, "");
+      if (typeName === "bigint") {
+        if (!/^[+-]?\\d+$/.test(lexical)) throw new TypeError("Invalid XML bigint response value");
+        return BigInt(lexical);
+      }
+      if (!/^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$/.test(lexical)) {
+        throw new TypeError("Invalid XML numeric response value");
+      }
+      const number = Number(lexical);
+      if (!Number.isFinite(number)) throw new TypeError("Non-finite XML numeric response value");
+      return number;
+    }
     // A simple-content complex type retains its object shape when no attributes are present on the wire.
     if (typeof node !== "object") {
+      if (node === "" && typeName && Object.hasOwn(this.dataTypes.Attributes, typeName) && Object.keys(childrenTypes).length === 0) return {};
       return childrenTypes.$value ? {$value: this.fromSoapResult(node, childrenTypes.$value)} : node;
     }
     // Recursively process array elements
@@ -429,11 +483,12 @@ ${methodsBody}
 
     // Get child type mapping for recursive processing with correct types
     const repeatedElements: readonly string[] = (typeName && this.dataTypes?.RepeatedElements?.[typeName]) || [];
+    const nonNillableElements: readonly string[] = (typeName && this.dataTypes?.NonNillableElements?.[typeName]) || [];
     const result: any = {};
 
     // Preserve text content for mixed XML elements
-    if ("$value" in node) {
-      result.$value = (node as any).$value;
+    if ("$value" in node && (childrenTypes.$value || node.$value !== "")) {
+      result.$value = this.fromSoapResult(node.$value, childrenTypes.$value);
     }
 
     // Extract attributes from various node-soap attribute containers
@@ -455,10 +510,11 @@ ${methodsBody}
       // Recursively convert child elements with their specific type info
       const childType: string | undefined = childrenTypes[k];
       // node-soap can return a scalar when repetition is declared on a wrapping sequence (#141).
-      const value = v != null && !Array.isArray(v) && repeatedElements.includes(k) ? [v] : v;
-      result[k] = Array.isArray(value)
-        ? value.map(node => this.fromSoapResult(node, childType))
-        : this.fromSoapResult(value, childType);
+      const repeated = repeatedElements.includes(k);
+      const value = v != null && !Array.isArray(v) && repeated ? [v] : v;
+      result[k] = repeated && Array.isArray(value)
+        ? value.map(node => this.fromSoapResult(node, childType, nonNillableElements.includes(k)))
+        : this.fromSoapResult(value, childType, nonNillableElements.includes(k));
     }
 
     return result;

package/dist/client/generateDirectClient.js

@@ -1,5 +1,5 @@
 import { directLimit } from '../compiler/directExecutionPolicy.js';
-import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR } from './directClientVersion.js';
+import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR, COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
 /** Native-plan generator consumed by the opt-in checked pipeline. */
 import { checkSemanticBudget } from '../compiler/semanticBudget.js';
 import { writeFileSync, mkdirSync } from 'node:fs';
@@ -170,12 +170,15 @@ export async function generateComponentClient(expected, signal) {
             ...response.declarations, `export type Response = ${response.type};`,
             ...faults.flatMap(({ shape }, index) => [...shape.declarations, `export type Fault_${index} = ${shape.type};`])
         ];
+        const soap12 = expected.contract.binding.version === '1.2';
+        const runtimeVersion = soap12 ? COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION : COMPONENT_CLIENT_RUNTIME_VERSION;
         const lines = [
-            '// Checked component client; inject checkedComponentRuntimeV1 from the package root.',
+            `// Checked component client; inject ${soap12 ? 'checkedComponentRuntimeV2' : 'checkedComponentRuntimeV1'} from the package root.`,
             '// Scalar facets, ordered occurrence correlation and wildcard membership remain native runtime duties.',
             ...declarations,
             'export interface Usage {readonly nodes: number; readonly work: number}',
             'export interface Name {readonly namespace: string; readonly local: string}',
+            ...(soap12 ? ['export interface Soap12Fault {readonly version: "1.2"; readonly code: Name; readonly subcodes: readonly Name[]; readonly reasons: readonly {readonly lang: string; readonly text: string}[]; readonly string: string; readonly node?: string; readonly role?: string}'] : []),
             'export interface Options {',
             '  readonly localSource: string; readonly fileRoots: readonly string[]; readonly capsule: Uint8Array;',
             '  readonly sourceResources: readonly {readonly uri: string; readonly file: string; readonly canonicalUri?: string}[]; readonly sourceOrigins: readonly string[];',
@@ -190,26 +193,28 @@ export async function generateComponentClient(expected, signal) {
             '}',
             'export interface Failure {readonly kind: "incompatible-artifact" | "unsupported" | "missing-authority" | "resource-limit" | "cancelled" | "inconclusive" | "invalid-schema" | "scalar-invalid" | "value-invalid" | "xml-invalid" | "mismatch" | "transport" | "protocol";',
             '  readonly rule: string; readonly repair?: string; readonly phase?: "input" | "response"; readonly usage: Usage}',
-            'export interface NativeSuccess {readonly kind: "soap-response" | "soap-fault"; readonly value: unknown; readonly admitted: false;',
+            `export interface NativeSuccess {readonly kind: "soap-response" | "soap-fault"; readonly value${soap12 ? '?' : ''}: unknown; readonly admitted: false;`,
             '  readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array;',
-            '  readonly fault?: {readonly name: string; readonly code: Name; readonly string: string; readonly actor?: string}}',
-            `export interface Runtime {readonly version: ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}; execute(expectedBase64: string, input: unknown, options: Options, version: ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}): Promise<Failure | NativeSuccess>}`,
+            `  readonly fault?: {readonly name${soap12 ? '?' : ''}: string; readonly code: Name; readonly string: string; readonly actor?: string}}`,
+            `export interface Runtime {readonly version: ${literal(runtimeVersion)}; execute(expectedBase64: string, input: unknown, options: Options, version: ${literal(runtimeVersion)}): Promise<Failure | NativeSuccess>}`,
             'type Common = {readonly admitted: false; readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array};',
             'export type Result = Failure | (Common & {readonly kind: "soap-response"; readonly value: Response})',
             ...faults.map(({ mapping }, index) => {
                 if (mapping.direction.kind !== 'fault')
                     throw new TypeError('Native fault mapping required');
-                return `  | (Common & {readonly kind: "soap-fault"; readonly value: Fault_${index}; readonly fault: {readonly name: ${literal(mapping.direction.name)}; readonly code: Name; readonly string: string; readonly actor?: string}})`;
+                return soap12 ? `  | (Common & {readonly kind: "soap-fault"; readonly value: Fault_${index}; readonly fault: Soap12Fault & {readonly name: ${literal(mapping.direction.name)}}})`
+                    : `  | (Common & {readonly kind: "soap-fault"; readonly value: Fault_${index}; readonly fault: {readonly name: ${literal(mapping.direction.name)}; readonly code: Name; readonly string: string; readonly actor?: string}})`;
             }),
-            ...(faults.length ? [] : ['  | (Common & {readonly kind: "soap-fault"; readonly value: never; readonly fault: {readonly name: never; readonly code: Name; readonly string: string; readonly actor?: string}})']),
+            ...(soap12 ? ['  | (Common & {readonly kind: "soap-fault"; readonly value?: never; readonly fault: Soap12Fault & {readonly name?: never}})']
+                : faults.length ? [] : ['  | (Common & {readonly kind: "soap-fault"; readonly value: never; readonly fault: {readonly name: never; readonly code: Name; readonly string: string; readonly actor?: string}})']),
             ';',
             `export const expectedCapsuleBase64 = ${literal(Buffer.from(capsule.bytes).toString('base64'))};`,
             `export const selection = ${literal(JSON.stringify({ selector: expected.contract.selector, ...expected.selection }))};`,
             'export function createClient(runtime: Runtime) {',
             '  return Object.freeze({',
             `    [${literal(expected.contract.selector.operation)}]: async (input: Request, options: Options): Promise<Result> => {`,
-            `      if (runtime.version !== ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}) return {kind: "incompatible-artifact", rule: "generated-runtime-version", repair: ${literal(COMPONENT_CLIENT_RUNTIME_REPAIR)}, usage: {nodes: 0, work: 0}};`,
-            `      return await runtime.execute(expectedCapsuleBase64, input, options, ${literal(COMPONENT_CLIENT_RUNTIME_VERSION)}) as Result;`,
+            `      if (runtime.version !== ${literal(runtimeVersion)}) return {kind: "incompatible-artifact", rule: "generated-runtime-version", repair: ${literal(COMPONENT_CLIENT_RUNTIME_REPAIR)}, usage: {nodes: 0, work: 0}};`,
+            `      return await runtime.execute(expectedCapsuleBase64, input, options, ${literal(runtimeVersion)}) as Result;`,
             '    },', '  });', '}', '',
         ];
         const source = composeGeneratedSource(lines.join('\n'), resolvePreamble('direct-client'));