@techspokes/typescript-wsdl-client 1.3.0 → 1.4.1

package/dist/gateway/checkedDocumentation.d.ts

@@ -0,0 +1,14 @@
+import type { DirectOperationSelector } from '../compiler/directOperation.js';
+type Schema = Readonly<Record<string, unknown>>;
+/** Lower one issued shape while its original reference scope is still available.
+ * @param root Generator-owned shape, with at most one root resource and definition dictionary.
+ * @param selector Outer operation selector, independent of companion projection contracts.
+ * @param role Direction or declared-fault role owning the shape.
+ * @param grouped Whether published configured definition names must be preserved.
+ * @param components Destination dictionary shared by the operation document.
+ * @param check Generation cancellation and semantic resource-accounting checkpoint.
+ * @returns A new documentation schema; runtime schemas and literal annotations remain unchanged.
+ * @throws TypeError For unexpected resources, references, missing descendants or component collisions.
+ */
+export declare function lowerCheckedDocumentation(root: Schema, selector: DirectOperationSelector, role: string, grouped: boolean, components: Record<string, Schema>, check: () => void): Schema;
+export {};

package/dist/gateway/checkedDocumentation.js

@@ -0,0 +1,106 @@
+/**
+ * Relocates generator-owned shape resources into OpenAPI documentation components.
+ * @since 1.4.1
+ * @constraints This is not a general JSON Schema resource bundler.
+ */
+import { createHash } from 'node:crypto';
+const maps = new Set(['properties', 'patternProperties', 'dependentSchemas']);
+const singles = new Set(['additionalProperties', 'additionalItems', 'contains', 'not', 'if', 'then', 'else', 'propertyNames', 'unevaluatedProperties', 'unevaluatedItems']);
+const arrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const escape = (value) => encodeURIComponent(value.replace(/~/g, '~0').replace(/\//g, '~1'));
+/** Lower one issued shape while its original reference scope is still available.
+ * @param root Generator-owned shape, with at most one root resource and definition dictionary.
+ * @param selector Outer operation selector, independent of companion projection contracts.
+ * @param role Direction or declared-fault role owning the shape.
+ * @param grouped Whether published configured definition names must be preserved.
+ * @param components Destination dictionary shared by the operation document.
+ * @param check Generation cancellation and semantic resource-accounting checkpoint.
+ * @returns A new documentation schema; runtime schemas and literal annotations remain unchanged.
+ * @throws TypeError For unexpected resources, references, missing descendants or component collisions.
+ */
+export function lowerCheckedDocumentation(root, selector, role, grouped, components, check) {
+    check();
+    if (root.$id !== undefined && (typeof root.$id !== 'string' || !/^urn:checked-component:shape:[a-f0-9]{64}$/.test(root.$id))) {
+        throw new TypeError('Unexpected checked documentation resource');
+    }
+    const definitions = (root.definitions ?? {});
+    // @why #467 Original resource IDs encode selection, not contract equivalence or component ownership.
+    const owner = createHash('sha256').update(JSON.stringify([selector.portType.namespace, selector.portType.local,
+        selector.binding.namespace, selector.binding.local, selector.operation, role])).digest('hex');
+    const names = new Map(Object.keys(definitions).sort().map(name => [name, grouped ? name : `Checked_${owner}_${name}`]));
+    const reference = (value) => {
+        if (typeof value !== 'string' || !value.startsWith('#/definitions/'))
+            throw new TypeError('Unexpected checked documentation reference');
+        let pointer;
+        try {
+            pointer = decodeURIComponent(value.slice(1));
+        }
+        catch {
+            throw new TypeError('Invalid checked documentation pointer');
+        }
+        const parts = pointer.slice(1).split('/').map(part => {
+            if (/~(?![01])/.test(part))
+                throw new TypeError('Invalid checked documentation pointer');
+            return part.replace(/~1/g, '/').replace(/~0/g, '~');
+        });
+        const name = names.get(parts[1]);
+        if (!name)
+            throw new TypeError('Unresolved checked documentation definition');
+        let target = root;
+        for (const part of parts) {
+            check();
+            if (!target || typeof target !== 'object' || !Object.hasOwn(target, part))
+                throw new TypeError('Unresolved checked documentation descendant');
+            target = target[part];
+        }
+        if (typeof target !== 'boolean' && (!target || typeof target !== 'object' || Array.isArray(target))) {
+            throw new TypeError('Checked documentation reference must target a schema');
+        }
+        return '#/components/schemas/' + escape(name) + parts.slice(2).map(part => '/' + escape(part)).join('');
+    };
+    const visit = (value, isRoot = false) => {
+        check();
+        if (typeof value === 'boolean')
+            return value;
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new TypeError('Unexpected checked documentation schema');
+        const record = value, result = Object.create(null);
+        for (const [key, item] of Object.entries(record)) {
+            check();
+            if (key === '$id' && isRoot)
+                continue;
+            if (key === 'definitions' && isRoot)
+                continue;
+            if (['$id', '$anchor', '$dynamicAnchor', '$dynamicRef', '$recursiveRef', '$recursiveAnchor', '$defs', 'definitions'].includes(key)) {
+                throw new TypeError('Unexpected checked documentation resource');
+            }
+            if (key === '$ref')
+                result[key] = reference(item);
+            else if (maps.has(key) || key === 'dependencies') {
+                const dictionary = Object.create(null);
+                for (const [name, child] of Object.entries(item)) {
+                    check();
+                    dictionary[name] = key === 'dependencies' && Array.isArray(child) ? child : visit(child);
+                }
+                result[key] = dictionary;
+            }
+            else if (arrays.has(key) || key === 'items' && Array.isArray(item))
+                result[key] = item.map(child => visit(child));
+            else if (singles.has(key) || key === 'items')
+                result[key] = visit(item);
+            // @constraints Unknown annotations are literal data, including keyword-shaped application examples.
+            else
+                result[key] = item;
+        }
+        return result;
+    };
+    const lowered = visit(root, true);
+    for (const [original, name] of names) {
+        const resolved = visit(definitions[original]);
+        if (Object.hasOwn(components, name) && JSON.stringify(components[name]) !== JSON.stringify(resolved)) {
+            throw new TypeError(`applicationGroups OpenAPI component collision ${name}`);
+        }
+        components[name] = resolved;
+    }
+    return lowered;
+}

package/dist/gateway/generateCheckedGateway.js

@@ -7,6 +7,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { componentSourceCapsuleBytes, inspectReconstructedComponentSource, inspectComponentSourceService } from '../compiler/directSourceCapsule.js';
 import { lowerComponentShape } from '../generation/componentShape.js';
+import { lowerCheckedDocumentation } from './checkedDocumentation.js';
 import { checkSemanticBudget } from '../compiler/semanticBudget.js';
 import { inspectDirectOperation } from '../compiler/directOperation.js';
 import { inspectComponentValueMapping } from '../compiler/directValues.js';
@@ -22,7 +23,7 @@ async function generateGatewayFromReconstruction(expected, options) {
         throw new Error('Checked gateway generation cancelled');
     inspectReconstructedComponentSource(expected);
     const capsule = { bytes: componentSourceCapsuleBytes(expected, options.signal) };
-    const runtime = expected.contract.binding.version === '1.2' ? 'checkedComponentRuntimeV2' : 'checkedComponentRuntimeV1';
+    const runtime = expected.contract.binding.version === '1.2' ? 'checkedComponentRuntimeV2' : 'checkedComponentRuntimeV3';
     if (!options.routePath.startsWith('/') || options.routePath.split('/').slice(1)
         .some(segment => !segment || !/^(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+$/.test(segment))) {
         throw new TypeError('Checked routePath requires literal nonempty path segments');
@@ -31,15 +32,21 @@ async function generateGatewayFromReconstruction(expected, options) {
     const output = expected.mappings.find(mapping => mapping.direction.kind === 'output');
     if (!input || !output)
         throw new TypeError('Issued input and output mappings required');
-    const schema = (mapping, role) => {
-        const { budget } = inspectDirectOperation(expected.contract).context;
-        return lowerComponentShape(expected.contract, mapping, role, () => {
-            checkSemanticBudget(budget);
-            if (options.signal?.aborted)
-                throw new Error('Checked gateway generation cancelled');
-        }).schema;
+    const { budget } = inspectDirectOperation(expected.contract).context;
+    const check = () => {
+        checkSemanticBudget(budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
     };
+    const schema = (mapping, role) => lowerComponentShape(expected.contract, mapping, role, check).schema;
+    const components = Object.create(null);
+    const documented = (value, mapping, role) => lowerCheckedDocumentation(value, expected.contract.selector, role, mapping.kind === 'component-mapping'
+        && !!inspectComponentValueMapping(mapping, expected.contract).applicationGroups, components, () => {
+        budget.chargeWork();
+        check();
+    });
     const request = schema(input, 'Request'), response = schema(output, 'Response');
+    const documentation = { request: documented(request, input, 'Request'), response: documented(response, output, 'Response') };
     const soap12 = expected.contract.binding.version === '1.2';
     const nameSchema = { type: 'object', additionalProperties: false, required: ['namespace', 'local'],
         properties: { namespace: { type: 'string' }, local: { type: 'string' } } };
@@ -53,12 +60,14 @@ async function generateGatewayFromReconstruction(expected, options) {
     const faults = expected.mappings.filter(mapping => mapping.direction.kind === 'fault').map(mapping => {
         if (mapping.direction.kind !== 'fault')
             throw new TypeError('Declared fault mapping required');
-        return { name: mapping.direction.name, value: schema(mapping, `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`) };
+        const role = `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`;
+        const value = schema(mapping, role);
+        return { name: mapping.direction.name, value, documented: documented(value, mapping, role) };
     });
-    const faultVariants = faults.map(fault => ({
+    const faultVariants = (documentationOnly) => faults.map(fault => ({
         type: 'object', additionalProperties: false, required: ['fault', 'value'],
         properties: {
-            value: fault.value,
+            value: documentationOnly ? fault.documented : fault.value,
             fault: {
                 type: 'object', additionalProperties: false, required: ['name', 'code', 'string', ...(soap12 ? ['version', 'subcodes', 'reasons'] : [])],
                 properties: soap12 ? { ...protocolFaultProperties, name: { const: fault.name } } : {
@@ -69,49 +78,17 @@ async function generateGatewayFromReconstruction(expected, options) {
             },
         },
     }));
-    if (soap12)
-        faultVariants.push({ type: 'object', additionalProperties: false, required: ['fault'], properties: {
-                fault: { type: 'object', additionalProperties: false, required: ['version', 'code', 'string', 'subcodes', 'reasons'],
-                    properties: protocolFaultProperties },
-            } });
-    const fault = faultVariants.length ? { oneOf: faultVariants } : { not: {} };
+    const protocolFault = { type: 'object', additionalProperties: false, required: ['fault'], properties: {
+            fault: { type: 'object', additionalProperties: false, required: ['version', 'code', 'string', ...(soap12 ? ['subcodes', 'reasons'] : [])],
+                properties: soap12 ? protocolFaultProperties : { version: { const: '1.1' }, code: nameSchema, string: { type: 'string' }, actor: { type: 'string' } } },
+        } };
+    const fault = { oneOf: [...faultVariants(false), protocolFault] };
+    const documentedFault = { oneOf: [...faultVariants(true), protocolFault] };
     const schemas = { request: { $schema: draft07, ...request }, response: { $schema: draft07, ...response }, fault: { $schema: draft07, ...fault } };
-    const grouped = expected.mappings.some(mapping => mapping.kind === 'component-mapping'
-        && inspectComponentValueMapping(mapping, expected.contract).applicationGroups);
-    const components = Object.create(null);
-    const documented = (value, dictionary = false) => {
-        if (Array.isArray(value))
-            return value.map(item => documented(item));
-        if (!value || typeof value !== 'object')
-            return value;
-        const record = value, result = Object.create(null);
-        // @why Property names belong to the application; definitions and $id are keywords only at schema nodes.
-        if (dictionary) {
-            for (const [key, item] of Object.entries(record))
-                result[key] = documented(item);
-            return result;
-        }
-        if (Object.hasOwn(record, 'definitions'))
-            for (const [key, definition] of Object.entries(record.definitions)) {
-                const resolved = documented(definition);
-                if (components[key] && JSON.stringify(components[key]) !== JSON.stringify(resolved))
-                    throw new TypeError(`applicationGroups OpenAPI component collision ${key}`);
-                components[key] = resolved;
-            }
-        for (const [key, item] of Object.entries(record)) {
-            if (key === 'definitions' || key === '$id')
-                continue;
-            result[key] = ['const', 'enum', 'default', 'examples'].includes(key) ? item
-                : key === '$ref' && typeof item === 'string' && item.startsWith('#/definitions/') ? item.replace('#/definitions/', '#/components/schemas/')
-                    : documented(item, ['properties', 'patternProperties', 'dependencies', 'dependentSchemas'].includes(key));
-        }
-        return result;
-    };
-    const documentation = grouped ? { request: documented(request), response: documented(response), fault: documented(fault) } : { request, response, fault };
     const doc = {
         openapi: '3.1.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
         info: { title: expected.selection.service.local, version: '1.0.0' },
-        ...(grouped ? { components: { schemas: components } } : {}),
+        ...(Object.keys(components).length ? { components: { schemas: components } } : {}),
         'x-checked-model': { model: 'checked-components-v1', scope: soap12 ? 'native-component-structured-soap12' : 'native-component-structured-soap11',
             ...(expected.responseProjection
                 ? { responseProjection: { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
@@ -124,7 +101,7 @@ async function generateGatewayFromReconstruction(expected, options) {
                     requestBody: { required: true, content: { 'application/json': { schema: documentation.request } } },
                     responses: { '200': { description: 'Independently validated SOAP response', content: { 'application/json': { schema: documentation.response } } },
                         '400': { description: 'Invalid HTTP request; no SOAP request is dispatched' },
-                        '502': { description: 'Declared SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentation.fault,
+                        '502': { description: 'SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentedFault,
                                             { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
                         '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
     };
@@ -191,9 +168,9 @@ const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, option
           ...(result.fault.name === undefined ? {} : {name: result.fault.name}),
           ...(result.fault.node === undefined ? {} : {node: result.fault.node}),
           ...(result.fault.role === undefined ? {} : {role: result.fault.role})};
-        const value = result.fault.name === undefined ? {fault} : {fault, value: result.value};` : `const fault = {name: result.fault.name, code: {namespace: result.fault.code.namespace, local: result.fault.code.local},
+        const value = result.fault.name === undefined ? {fault} : {fault, value: result.value};` : `const fault = {...(result.fault.name === undefined ? {version: result.fault.version} : {name: result.fault.name}), code: {namespace: result.fault.code.namespace, local: result.fault.code.local},
           string: result.fault.string, ...(result.fault.actor === undefined ? {} : {actor: result.fault.actor})};
-        const value = {fault, value: result.value};`}
+        const value = 'value' in result ? {fault, value: result.value} : {fault};`}
         if (!validateFault(value)) return reply.code(502).send({kind: 'value-invalid', rule: 'http-fault-shape'});
         return reply.code(502).type('application/json').serializer(value => JSON.stringify(value)).send(value);
       }

package/dist/index.d.ts

@@ -12,10 +12,12 @@ export type { ComposedOpenApiDocument, OpenApiCompositionEntry, OpenApiCompositi
 export type { CheckedComponentOptions, CheckedInventory } from './checkedPipeline.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export type { CheckedComponentPlan, ComponentPlanBlocker } from './checkedPlanning.js';
+export { inspectCheckedResponse } from './checkedResponseInspection.js';
+export type { CheckedResponseInspectionOptions, CheckedResponseInspectionReport } from './checkedResponseInspection.js';
 export type { ComponentRecordProjectionSpec, ComponentRecordProjectionAssociation } from './compiler/componentRecordProjection.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, type OperationStreamMetadata, type ShapeCatalogRef, type StreamConfig, } from "./util/streamConfig.js";
 export { applyShapeCatalogs, type ApplyShapeCatalogsOptions } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2, checkedComponentRuntimeV3 } from './client/checkedDirectRuntime.js';
 /**
  * Compiles a WSDL file to TypeScript client code
  *

package/dist/index.js

@@ -30,9 +30,10 @@ export { runGenerationPipeline } from "./pipeline.js";
 export { runMultiServicePipeline, loadMultiServiceConfig } from './multiServicePipeline.js';
 export { composeOpenApiDocuments } from './openapi/composeOpenAPI.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
+export { inspectCheckedResponse } from './checkedResponseInspection.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, } from "./util/streamConfig.js";
 export { applyShapeCatalogs } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2, checkedComponentRuntimeV3 } from './client/checkedDirectRuntime.js';
 // noinspection JSUnusedGlobalSymbols
 /**
  * Compiles a WSDL file to TypeScript client code

package/dist/util/readBoundedFile.d.ts

@@ -0,0 +1,9 @@
+/** Acquire a regular file through one descriptor under a caller-specified byte limit.
+ * @since 1.4.0
+ * @param file Local input path.
+ * @param maxBytes Maximum accepted file size, leaving room for a one-byte growth probe.
+ * @returns The bytes read from the opened file.
+ * @throws RangeError For an invalid limit or an input exceeding it.
+ * @throws Error For filesystem errors, a nonregular input, or a size change observed during the read.
+ */
+export declare function readBoundedFile(file: string, maxBytes: number): Buffer;

package/dist/util/readBoundedFile.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import { constants } from 'node:buffer';
+/** Acquire a regular file through one descriptor under a caller-specified byte limit.
+ * @since 1.4.0
+ * @param file Local input path.
+ * @param maxBytes Maximum accepted file size, leaving room for a one-byte growth probe.
+ * @returns The bytes read from the opened file.
+ * @throws RangeError For an invalid limit or an input exceeding it.
+ * @throws Error For filesystem errors, a nonregular input, or a size change observed during the read.
+ */
+export function readBoundedFile(file, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes >= constants.MAX_LENGTH)
+        throw new RangeError('Invalid file byte limit');
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new TypeError('Expected a regular file');
+        if (stat.size > maxBytes)
+            throw new RangeError('File byte limit exceeded');
+        const buffer = Buffer.alloc(stat.size + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const count = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        if (offset !== stat.size)
+            throw new Error('File size changed during the read');
+        return buffer.subarray(0, offset);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/util/xmlBytes.d.ts

@@ -0,0 +1,9 @@
+/** Inspect genuine XML bytes without evaluating caller-owned length, backing-store or iterator properties.
+ * @throws TypeError For non-byte views, proxies or shared backing stores.
+ * @constraints Callers must enforce their capacity before requesting a snapshot.
+ */
+export declare function xmlByteLength(value: unknown): number;
+/** Copy XML bytes through native slots so hashing and decoding share one private observation.
+ * @constraints Callers must first bound xmlByteLength; no user iterator or property getter is consulted.
+ */
+export declare function snapshotXmlBytes(value: Uint8Array): Uint8Array;

package/dist/util/xmlBytes.js

@@ -0,0 +1,24 @@
+import { types } from 'node:util';
+const typed = Object.getPrototypeOf(Uint8Array.prototype);
+const lengthGetter = Object.getOwnPropertyDescriptor(typed, 'byteLength').get;
+const bufferGetter = Object.getOwnPropertyDescriptor(typed, 'buffer').get;
+const setBytes = Uint8Array.prototype.set;
+/** Inspect genuine XML bytes without evaluating caller-owned length, backing-store or iterator properties.
+ * @throws TypeError For non-byte views, proxies or shared backing stores.
+ * @constraints Callers must enforce their capacity before requesting a snapshot.
+ */
+export function xmlByteLength(value) {
+    if (!types.isUint8Array(value) || types.isProxy(value))
+        throw new TypeError('XML requires Uint8Array bytes');
+    if (types.isSharedArrayBuffer(bufferGetter.call(value)))
+        throw new TypeError('Shared XML bytes are unsupported');
+    return lengthGetter.call(value);
+}
+/** Copy XML bytes through native slots so hashing and decoding share one private observation.
+ * @constraints Callers must first bound xmlByteLength; no user iterator or property getter is consulted.
+ */
+export function snapshotXmlBytes(value) {
+    const copy = new Uint8Array(xmlByteLength(value));
+    setBytes.call(copy, value);
+    return copy;
+}

package/docs/api-reference.md

@@ -4,9 +4,36 @@ This reference covers public generation, composition, stream and security APIs.
 
 See the main [README](../README.md) for installation, CLI usage, and project overview.
 
+## Captured checked SOAP responses
+
+`inspectCheckedResponse(source, options)` returns versioned diagnostic data without generating files or dispatching SOAP. Supply an authorized local WSDL, closed snapshots in `checkedComponents`, a full operation selector, and `responseBytes`. Optional `responseMetadata` supplies the actual HTTP `status`, `contentType` and `contentEncoding`. Omission leaves HTTP duties unassessed. `signal` and `limits` retain cancellation and XML capacity controls.
+
+```typescript
+import {inspectCheckedResponse} from '@techspokes/typescript-wsdl-client';
+
+const report = await inspectCheckedResponse('./sources/service.wsdl', {
+  checkedComponents: configuration,
+  selector: configuration.selectors[0],
+  responseBytes: capturedBytes,
+});
+console.log(report.kind);
+```
+
+The report separates wrapper and companion outcomes and excludes raw XML and decoded values. Configuration can select a consumer-owned `sourceCorrectionsFile`; the same effective contract is used for planning, inspection and generation. A correction draft does not authorize execution until its semantic choices are completed. See [source corrections and offline inspection](checked-gateway.md#consumer-owned-source-corrections).
+
+Set `includeCorrectionDraft: true` to request an available correction draft. Its exact resource pins can contain local source URIs; default reports retain only diagnostic resource labels.
+
+Pass the complete multi-operation checked configuration unchanged. Inspection authenticates the complete correction-source closure before selecting the requested operation and its projection; inactive companions retain their freshness checks.
+
+## Checked runtime bindings
+
+New SOAP 1.1 component clients inject package-root `checkedComponentRuntimeV3` with handshake `checked-component-soap11-runtime-v1`. SOAP 1.2 keeps `checkedComponentRuntimeV2`, and existing SOAP 1.1 artifacts keep their V1 binding. These injection contracts are separate from package and capsule versions.
+
+A V3 protocol `soap-fault` exposes version `1.1`, expanded `code`, `string`, optional `actor`, response bytes and transport status without a declared application `value` or fault `name`. A uniquely declared fault detail retains native decoding; malformed declared content is refused. See [runtime compatibility](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/005-checked-protocol-fault-compatibility.md) and [migration](migration.md#from-13x-to-140).
+
 All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Adding a preamble does not change an API signature or option; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
 
-Generated-output compatibility is versioned separately from those preambles. Read the [migration guide for the intended version](migration.md), including [1.2.x-to-1.3.0 SOAP binding adoption](migration.md#from-12x-to-130), before regenerating existing clients or changing their selected profile.
+Generated-output compatibility is versioned separately from those preambles. Read the [migration guide for the intended version](migration.md), including [1.3.x-to-1.4.0 runtime adoption](migration.md#from-13x-to-140), before regenerating existing clients or changing their selected profile.
 
 ## compileWsdlToProject
 
@@ -335,6 +362,8 @@ The generated aggregate plugin exports `createClients`, `MultiServiceClientOptio
 
 Compose existing OpenAPI 3.1 documents without generating clients or routers:
 
+Checked documents regenerated with 1.4.1 or later support this API. Regeneration relocates generator-owned local schema resources while preserving configured names and native supplemental-validation metadata. Archived resource-bearing documents remain unsupported; composition does not replace native XML validation.
+
 ```typescript
 interface OpenApiCompositionEntry {key: string; document: unknown}
 interface OpenApiCompositionOptions {

package/docs/checked-gateway.md

@@ -8,6 +8,8 @@ SOAP 1.2 document/literal operations use the selected binding's envelope namespa
 
 Generated SOAP 1.2 clients use the additive `checkedComponentRuntimeV2` package-root binding with protocol `checked-component-soap12-runtime-v1`. Existing SOAP 1.1 clients keep `checkedComponentRuntimeV1` and `checked-component-runtime-v2`, including their TypeScript injection contract. The older binding refuses SOAP 1.2 artifacts before SOAP dispatch.
 
+Regenerated SOAP 1.1 clients use `checkedComponentRuntimeV3` and `checked-component-soap11-runtime-v1`. Valid SOAP 1.1 faults without declared application detail retain protocol metadata and original response bytes without inventing a typed value. Declared application detail still requires native validation; mixed or ambiguous declared detail refuses. Gateways expose protocol faults as HTTP 502 without a `value` member. Existing V1/V2 injection contracts remain available; see [ADR-005](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/005-checked-protocol-fault-compatibility.md).
+
 SOAP 1.2 faults retain code, nested subcodes, language-tagged reasons and optional Node/Role metadata. Declared application detail uses the existing native mapping and gateway fault validation. A valid protocol fault without declared application detail carries fault metadata without a typed application value; the client retains original response bytes. Gateways return HTTP 502 for upstream faults, including SOAP Sender faults received on HTTP 400. SOAP 1.2 protocol rules follow [the messaging framework](https://www.w3.org/TR/soap12-part1/#soapfault) and [HTTP binding](https://www.w3.org/TR/soap12-part2/#soapinhttp).
 
 SOAP 1.2 header processing uses the default ultimate receiver and next roles. Unknown mandatory blocks targeted at this receiver refuse; other-role and optional blocks may be ignored. The `mustUnderstand` and `relay` attributes accept SOAP 1.2 Boolean lexical forms. This does not enable outgoing application headers, WS-Security, streaming or RPC/encoded SOAP 1.2.
@@ -96,6 +98,48 @@ Previously, ordinary setup authored `sourceResources`, selectors, `endpoint` and
 
 This component injection change uses `checked-component-runtime-v2`; regenerate clients, capsules, gateways and server scaffolds together when upgrading. The exported binding name remains `checkedComponentRuntimeV1` for existing imports, and existing explicit endpoint callbacks remain valid after regeneration. Consumer server/config/test files retain skip/force ownership rules; use existing force options deliberately to refresh those scaffolds. The v1.1.5 direct runtime protocol and legacy defaults are unchanged.
 
+### Consumer-owned source corrections
+
+Set `sourceCorrectionsFile` in checked generation configuration to apply a versioned JSON correction file to the project's outer and companion sources. Paths follow the existing generation convention: resolve them from the invocation working directory. Corrections are generation inputs; do not put them in HTTP request bodies or runtime endpoint configuration.
+
+Maintain upstream snapshots unchanged and keep the correction file under version control. The correction file pins the complete original resource set by logical URI and digest. Refreshing upstream metadata requires regenerating and reviewing the correction draft. Scoped targets identify original declarations and particles, not generated TypeScript names. All edits resolve against the original inventory before application.
+
+The bounded operations change particle occurrence bounds, narrow element wildcard namespaces, or insert a typed element into an existing sequence. Insertions require an existing named type or global element reference. Corrections do not define new complex types, rewrite imports, or change incoming SOAP XML. Use replacement snapshots for unsupported restructuring or sources that cannot construct a canonical inventory.
+
+The correction document has `version: 1`, `resources: [{uri, digest}]`, and `corrections`. Retain every original resource pin supplied by the tool. A target is `{id, uri, digest}` copied from the inventory or draft; do not replace it with a generated DTO name. Complete unresolved draft values before passing the file to generation.
+
+| Correction kind | Required settings |
+| --- | --- |
+| `set-occurs` | `target`, `min`, and `max`; bounds are canonical decimal strings, with `"unbounded"` also permitted for `max` |
+| `set-wildcard-namespaces` | `target` and `namespaces`; use explicit namespace strings and `""` for the no-namespace case; the original `processContents` is preserved |
+| `insert-element` | Sequence `target`, `position`, and `element`; position is `"append"` or `{kind: "before" or "after", target: originalChildTarget}` |
+
+For a local inserted declaration, `element` contains `{kind: "declaration", name, type: {namespace, local}, min, max}`. The type must be a built-in XSD type or an existing named type. A global element reference instead uses `{kind: "reference", target: globalElementTarget, min, max}`. For example, a reviewed new scalar can use `type: {namespace: "http://www.w3.org/2001/XMLSchema", local: "string"}`; selecting that type is a contract decision, not an inference from one text value. Local declarations follow the containing schema's element-form rules.
+
+Inserting a no-namespace type or reference beneath a nonempty default namespace currently refuses rather than changing QName meaning. Use a replacement snapshot for that case. Two insertions at the same original source position also refuse; choose distinct original anchors or supply a replacement snapshot for a larger restructuring.
+
+Making metadata optional can make a following unrestricted wildcard ambiguous. Review both declarations: an explicit payload namespace constraint may be necessary to preserve native XSD 1.0 qualification. Narrowing changes the accepted contract, so confirm every intended payload namespace rather than copying the wrapper namespace by assumption.
+
+Effective metadata is freshly parsed and checked before generation. Native decoding, SOAP bootstrap, generated types, OpenAPI, and runtime source reconstruction use those same effective bytes. Generated provenance distinguishes upstream and effective digests; successful validation establishes conformance to the consumer's effective contract, not upstream approval. Runtime needs the generated effective snapshots, not the correction file or upstream network access. Regenerate clients, contracts and gateways together after changes, and refresh source-derived presentation targets when necessary.
+
+One generated project retains one effective byte sequence per logical URI. Shared declarations change for all their uses in that project. Conflicting URI contents and interpretation-specific edits to shared chameleon declarations refuse; separate replacement snapshots are required for those cases. This feature does not extend checked multi-service composition or legacy generation.
+
+### Offline response inspection
+
+Use `inspect-response` with a local WSDL, closed snapshot configuration, one configured operation and a saved SOAP response. It does not acquire missing remote metadata, dispatch SOAP, or read credentials. Create the output directory first; existing report or draft files are not overwritten.
+
+```bash
+npx wsdl-tsc inspect-response --wsdl-source ./sources/service.wsdl --checked-config ./checked.json --operation Fetch --response-file ./captures/fetch.xml --report .generated/inspection.json --corrections-draft .generated/corrections-draft.json
+```
+
+XML-only inspection leaves HTTP status and media checks unassessed. To assess an actual full response, add `--response-metadata ./captures/fetch-metadata.json` containing `status`, `contentType`, and optional `contentEncoding`. Do not invent metadata for a capture that did not retain it.
+
+Reports separate wrapper and companion assessment. A valid inner payload cannot rescue an invalid wrapper. Reports omit decoded values and raw XML. Correction drafts provide pinned targets and existing values, but leave type, occurrence and namespace decisions unresolved until a developer reviews and completes them. Drafts may be unavailable when source loading or target inventory construction fails.
+
+Drafts retain exact logical source URIs, which can include local filesystem paths, because those identities are needed to apply corrections. The CLI writes them only to the explicitly requested draft file. Programmatic callers must select `includeCorrectionDraft: true` to receive those additional local identities; ordinary diagnostic reports use resource labels.
+
+Exit codes are 0 for conformance within the reported scope, 1 for mismatch/refusal, and 2 for invocation/file errors. A conforming SOAP fault remains identified as a fault. The package-root `inspectCheckedResponse` API accepts the same checked choices, a full operation selector, response bytes, optional actual response metadata, cancellation and XML limits; it returns diagnostic data without writing files.
+
 ### Planning and missing-schema recovery
 
 `--checked-report` writes versioned `checked-component-plan-v1` JSON on native success or refusal. Human refusals identify the native reason, stage, dimension, affected full operation identities and configuration pointer. Source legality, correspondence, mapping/artifact readiness and runtime remain separate dimensions. Unsupported or inconclusive qualification does not establish invalid vendor schemas. Loading interruptions retain discovered counts plus explicit incomplete inventory; independent operation refusals are collected before generation writes project artifacts.
@@ -211,6 +255,10 @@ Generated `buildServer` accepts runtime cancellation, timeout and XML limits. Or
 
 ## Validation and coverage evidence
 
+Regenerate with 1.4.1 or later to compose checked OpenAPI documents through `composeOpenApiDocuments`. Documentation definitions are relocated into operation- and role-scoped components for ungrouped shapes; configured grouped names remain unchanged. Runtime draft-07 schemas, capsules and native supplemental validation retain their existing contracts.
+
+Composition preserves structural JSON documentation, not complete native XML equivalence. Archived 1.4.0 documents with embedded schema resources still refuse composition; updating the runtime package alone does not repair those documents.
+
 OpenAPI documentation uses 3.1.1 with separate draft-07 HTTP runtime plans. Route-local Ajv disables coercion, default insertion and property removal, and preserves unrelated host policy. The native runtime explicitly converts validated HTTP values through the issued mapping, performs actual SOAP execution and independently validates response/fault XML. HTTP response validation also runs independently of serializer selection; JSON serialization preserves the validated values.
 
 `client/inventory.json` and the API result's `checked` field list every discovered portType operation, selected service/port/binding, requested/generated operation and unselected operations. Generation records `executed:false`; it does not claim a SOAP call occurred. Refused selection diagnostics name the requested operation and zero generated/executed operations. Unselected operations remain unassessed.

package/docs/cli-reference.md

@@ -10,7 +10,7 @@ Generation paths are explicit. Examples use the git-ignored `.generated/` direct
 
 ## Commands Overview
 
-The tool provides six generation commands and the assessment-only `assess` command.
+The tool provides six generation commands and the diagnostic commands `assess` and `inspect-response`.
 
 TypeScript outputs automatically receive [generated preambles](generated-code.md#generated-preambles-and-eslint), including app/test scaffolds when actually written. Command syntax is unchanged and there is no preamble flag. `compile` and `openapi` data outputs remain unchanged.
 
@@ -23,6 +23,21 @@ TypeScript outputs automatically receive [generated preambles](generated-code.md
 | app | Runnable Fastify app from client + gateway + OpenAPI | Local testing, demos |
 | compile | Parse WSDL to catalog.json only | Debugging, multi-stage builds |
 | assess | Source schema diagnostic report | Checked evidence and unresolved duties |
+| inspect-response | Offline captured SOAP response inspection | Scoped mismatches and source correction drafts |
+
+## inspect-response
+
+Inspect saved SOAP XML using an authorized local checked source and closed snapshots. This command never dispatches SOAP or reads credentials.
+
+Required inputs are `--wsdl-source`, `--checked-config`, `--operation`, `--response-file` and `--report`.
+
+```bash
+npx wsdl-tsc inspect-response --wsdl-source ./sources/service.wsdl --checked-config ./checked.json --operation Fetch --response-file ./captures/fetch.xml --report .generated/inspection.json
+```
+
+The checked configuration must list exactly one matching selector for `--operation`. Narrow `selectors` when different bindings expose the same operation name. Optional `--response-metadata` points to JSON containing actual `status`, `contentType` and optional `contentEncoding`; omission selects XML-only scope with HTTP checks unassessed. Optional `--corrections-draft` writes a draft when the inspector can derive one. Reports and drafts use exclusive creation; create the destination directory and choose unused filenames. Input files have a 1 MiB CLI capacity.
+
+Exit 0 establishes conformance only within the report's assessment scope; 1 reports mismatch/refusal and 2 identifies invocation/file errors. SOAP faults remain faults even when their declared shape conforms. See [checked source corrections](checked-gateway.md#consumer-owned-source-corrections) for draft completion and regeneration.
 
 ## pipeline
 

package/docs/migration.md

@@ -6,6 +6,12 @@ Versions are listed newest first. Find your current version and follow the steps
 
 See the root [README](../README.md). Historical version sections below describe their original releases; 1.2.0 compatibility guidance supersedes earlier unchanged-output statements for this upgrade.
 
+## From 1.4.0 to 1.4.1
+
+Regenerate checked specifications to compose them with `composeOpenApiDocuments`. Ungrouped documentation uses operation- and role-scoped components; configured grouped names remain stable. Archived 1.4.0 specifications containing embedded resources remain explicitly refused by composition.
+
+Existing runtime artifacts remain usable. Runtime draft-07 validation, capsules and native supplemental validation are unchanged; structural documentation parity does not establish complete native XML equivalence.
+
 ## General Upgrade Steps
 
 These steps apply to every version upgrade:
@@ -16,6 +22,16 @@ These steps apply to every version upgrade:
 4. Regenerate matched generator-owned artifacts using the existing generation script and options.
 5. Review the generated diff and run the consumer project's TypeScript build and tests.
 
+## From 1.3.x to 1.4.0
+
+Package updates preserve existing SOAP 1.1 V1 and SOAP 1.2 V2 runtime contracts. Newly generated checked SOAP 1.1 clients use `checkedComponentRuntimeV3` and `checked-component-soap11-runtime-v1`; regenerate matched clients, capsules, OpenAPI and gateways together to adopt that binding. Legacy generation and direct preview remain unchanged.
+
+A V3 `soap-fault` can carry protocol metadata without a declared application `value` or fault `name`. Check whether a typed value exists before accessing it. Declared details still undergo native validation, and protocol faults remain gateway HTTP 502 responses.
+
+Checked projects can opt into `sourceCorrectionsFile` for digest-pinned consumer corrections. Preserve upstream originals, review source changes, and regenerate effective snapshots and dependent artifacts together. Runtime deployments need effective snapshots and capsules, not the correction recipe; see [contract correction maintenance](checked-gateway.md).
+
+Offline inspection accepts the complete multi-operation checked configuration and a full operation selector. Correction pins cover every project companion even when only one operation is inspected. XML-only reports do not establish HTTP status or media conformance without supplied response metadata.
+
 ## From 1.2.x to 1.3.0
 
 Version 1.3.0 adds checked SOAP 1.2 document/literal execution. Legacy generation remains the default. Existing SOAP 1.1 component clients keep `checkedComponentRuntimeV1` and `checked-component-runtime-v2`; the shipped direct runtime is unchanged. Updating the package alone does not adopt SOAP 1.2 or require regeneration of existing SOAP 1.1 clients.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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",