@techspokes/typescript-wsdl-client 1.4.0 → 1.5.0

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';
@@ -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,48 +78,32 @@ async function generateGatewayFromReconstruction(expected, options) {
             },
         },
     }));
-    faultVariants.push({ type: 'object', additionalProperties: false, required: ['fault'], properties: {
+    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 };
+        } };
+    const fault = { oneOf: [...faultVariants(false), protocolFault] };
+    const documentedFault = { oneOf: [...faultVariants(true), protocolFault] };
+    const diagnosticNameSchema = { type: 'object', additionalProperties: false, required: ['namespace', 'local'],
+        properties: { namespace: { type: 'string', maxLength: 256 }, local: { type: 'string', maxLength: 256 } } };
+    const diagnosticSchema = { type: 'object', additionalProperties: false,
+        required: ['version', 'universe', 'resource', 'digest', 'declaration', 'location'], properties: {
+            version: { const: 'checked-payload-diagnostic-v1' }, universe: { type: 'string', pattern: '^universe-[a-f0-9]{64}$' },
+            resource: { type: 'string', pattern: '^resource-[a-f0-9]{64}$' }, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+            declaration: { type: 'object', additionalProperties: false, required: ['kind', 'name'],
+                properties: { kind: { enum: ['element', 'attribute'] }, name: diagnosticNameSchema } },
+            owner: { type: 'object', additionalProperties: false, required: ['kind'],
+                properties: { kind: { type: 'string' }, name: diagnosticNameSchema } },
+            datatype: diagnosticNameSchema, builtin: diagnosticNameSchema, location: { type: 'string', maxLength: 2048 },
+            unknownField: { const: true }, truncated: { const: true },
+        } };
+    const failureSchema = { type: 'object', additionalProperties: false, required: ['kind', 'rule'],
+        properties: { kind: { type: 'string' }, rule: { type: 'string' }, diagnostic: diagnosticSchema } };
     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' } } : {}),
@@ -123,9 +116,10 @@ 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: 'SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentation.fault,
-                                            { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
-                        '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
+                        '502': { description: 'SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentedFault,
+                                            failureSchema] } } } },
+                        '499': { description: 'Cancelled request', content: { 'application/json': { schema: failureSchema } } },
+                        '500': { description: 'Incompatible artifacts or gateway configuration', content: { 'application/json': { schema: failureSchema } } } } } } },
     };
     let clientImport = path.relative(options.gatewayDir, path.join(options.clientDir, 'client.js')).replace(/\\/g, '/');
     if (!clientImport.startsWith('.'))
@@ -198,7 +192,7 @@ const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, option
       }
       const status = result.kind === 'incompatible-artifact' || result.kind === 'missing-authority' ? 500
         : result.kind === 'cancelled' ? 499 : result.phase === 'input' ? 400 : 502;
-      return reply.code(status).send({kind: result.kind, rule: result.rule});
+      return reply.code(status).send({kind: result.kind, rule: result.rule, ...(result.diagnostic ? {diagnostic: result.diagnostic} : {})});
     } finally {
       request.raw.removeListener('aborted', disconnected);
       reply.raw.removeListener('close', disconnected);

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export type { CheckedComponentOptions, CheckedInventory } from './checkedPipelin
 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 { CheckedResponseInspectionOptions, CheckedResponseInspectionReport, CheckedResponseCorrectionTarget } 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";
@@ -50,3 +50,4 @@ export declare function compileWsdlToProject(input: {
 export { assessSchemaSource, serializeAssessmentReport, parseAssessmentReport, assessmentExitCode, ASSESSMENT_VERSION, ASSESSMENT_BASIS } from './compiler/checkedAssessment.js';
 export type { ApplicationGroupsOptions, ApplicationGroupName } from './compiler/applicationGroups.js';
 export type { CheckedAssessmentReport, AssessmentObligation, AssessedOperation, AssessmentStatus } from './compiler/checkedAssessment.js';
+export type { CheckedPayloadDiagnostic } from './compiler/payloadDiagnostics.js';

package/docs/api-reference.md

@@ -21,6 +21,8 @@ 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).
 
+Optional `diagnostic` metadata uses `CheckedPayloadDiagnostic` and `checked-payload-diagnostic-v1` across inspection and newly generated runtime/gateway failures. It identifies native scoped declarations, effective types and bounded known-field locations without source locators or payload values. For explicit local authoring, `includeCorrectionTargets: true` adds `CheckedResponseCorrectionTarget` descriptors with original pinned selectors and original `declaredType`, or an unavailable reason; retain these trusted locators outside HTTP responses and logs. See [trusted original correction targets](checked-gateway.md#trusted-original-correction-targets) for compatibility and recovery rules.
+
 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.
@@ -362,6 +364,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

@@ -104,7 +104,7 @@ Set `sourceCorrectionsFile` in checked generation configuration to apply a versi
 
 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 bounded operations change particle occurrence bounds, narrow element wildcard namespaces, insert a typed element into an existing sequence, or change an authored element or attribute type reference. Insertions require an existing named type or global element reference. Corrections do not define new 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.
 
@@ -113,6 +113,7 @@ The correction document has `version: 1`, `resources: [{uri, digest}]`, and `cor
 | `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}` |
+| `set-declared-type` | Declaration `target`, original `expectedType`, and replacement `type`, both as `{namespace, local}` |
 
 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.
 
@@ -124,6 +125,27 @@ Effective metadata is freshly parsed and checked before generation. Native decod
 
 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.
 
+#### Changing an existing declared type
+
+Use `set-declared-type` for an existing authored element or attribute `@type`. Obtain the original declaration selector and `declaredType` through [trusted correction targets](#trusted-original-correction-targets), then copy `declaredType` into `expectedType`. Keep every original resource pin; an effective datatype or ordinal path alone does not establish an original target.
+
+```json
+{
+  "kind": "set-declared-type",
+  "target": {"id": "ORIGINAL_DECLARATION_ID", "uri": "ORIGINAL_RESOURCE_URI", "digest": "ORIGINAL_SHA256"},
+  "expectedType": {"namespace": "http://www.w3.org/2001/XMLSchema", "local": "anyURI"},
+  "type": {"namespace": "http://www.w3.org/2001/XMLSchema", "local": "string"}
+}
+```
+
+The original type guard compares expanded names resolved in the declaration's schema context. Replacements may select XML Schema builtins or existing named types from the declaration's authorized source universe. A foreign named type also requires an existing import in the declaring schema; another companion or including schema cannot lend its type declarations or import permissions. Namespace prefixes are emitted deterministically without changing expanded names.
+
+Inline anonymous types, implicit types, `ref` uses, new definitions and new imports refuse. Attribute replacements require simple types. Missing or stale selectors, mismatched old types, conflicting edits and ambiguous shared chameleon interpretations also refuse; pins are never refreshed automatically.
+
+Changing `anyURI` to `string` admits raw text and escaped embed content while removing the URI guarantee. Changing `dateTime` to `string` also admits nonsense. An existing constrained string type may check a timestamp layout while still accepting impossible calendar dates; it does not prove calendar validity or normalize timezones.
+
+Every use of the selected shared declaration adopts its new type in that project. Independent source universes with colliding names keep their own declarations. Original source and response bytes remain unchanged; regenerate and qualify matching client, native/runtime, capsule and OpenAPI artifacts against the new effective bytes before adoption.
+
 ### 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.
@@ -140,6 +162,40 @@ Drafts retain exact logical source URIs, which can include local filesystem path
 
 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.
 
+### Scoped payload diagnostics
+
+Native element and attribute failures can include an optional `diagnostic` object in inspection reports, direct runtime failures and newly generated gateway error responses. `checked-payload-diagnostic-v1` identifies the source universe and resource with opaque hashes, retains the effective source digest, and identifies the declared field, owning declaration and effective datatype when established by the native owner. A scalar diagnostic also identifies its builtin datatype.
+
+`location` uses schema-established expanded names and one-based occurrence indexes. An unknown child or wrapper is represented by `[unknown-field]` under the nearest known parent; its caller-controlled name is omitted. Diagnostics contain no XML values, source URI, absolute local path, raw exception or native handle.
+
+Names and locations are bounded, and `truncated: true` indicates shortened diagnostic metadata. An occurrence above 100000 is displayed as `[>100000]`; omitted ancestor information is marked `[truncated]`. Neither marker is an exact original location or a correction selector.
+
+This metadata is additive: the inspection report remains `checked-response-inspection-v1`, existing runtime bindings retain their versions, and consumers must continue branching on the existing failure `kind` and `rule`. Existing generated gateways keep their previous envelope until regenerated; regenerate the matching client, gateway and OpenAPI artifacts to obtain the documented optional `diagnostic`. HTTP status and native strict validation remain unchanged; a missing diagnostic never makes a failure acceptable.
+
+### Trusted original correction targets
+
+Pass `includeCorrectionTargets: true` to the public `inspectCheckedResponse()` API only for trusted local authoring. The optional `correctionTargets` array associates each descriptor with its zero-based `diagnostic` index. An available descriptor includes `target: {id, uri, digest}` for the original element or attribute declaration and its original expanded `declaredType` when named. Use that type as the explicit `expectedType` guard when authoring a declared-type correction.
+
+```typescript
+import {inspectCheckedResponse} from '@techspokes/typescript-wsdl-client';
+import type {CheckedComponentOptions} from '@techspokes/typescript-wsdl-client';
+declare const source: string;
+declare const selector: {portType: {namespace: string; local: string}; binding: {namespace: string; local: string}; operation: string};
+declare const responseBytes: Uint8Array;
+declare const checkedComponents: Partial<CheckedComponentOptions>;
+const report = await inspectCheckedResponse(source, {
+  selector,
+  responseBytes,
+  checkedComponents,
+  includeCorrectionTargets: true,
+});
+const available = report.correctionTargets?.filter(item => item.kind === 'available');
+```
+
+These descriptors intentionally contain original source locators and must stay out of public HTTP responses and logs. Default inspection reports and generated gateway diagnostics do not include them. Requesting `includeCorrectionDraft` is a separate authoring operation.
+
+Original target recovery uses native declaration ownership and retained edit-span correspondence when a recipe already exists. It never treats an effective ordinal path as an original target. A descriptor with `kind: 'unavailable'` states a reason, including absent native declaration evidence, an ambiguous original context, a newly inserted declaration without an original, or correspondence that cannot be established after encoding-declaration rewriting. Do not infer a selector or silently refresh pins from that result.
+
 ### 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.
@@ -255,6 +311,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/migration.md

@@ -6,6 +6,24 @@ 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.x to 1.5.0
+
+Checked payload failures gain optional `checked-payload-diagnostic-v1` metadata with opaque source/universe identities, source digests, declaration and datatype names, and bounded locations. Existing failure kinds, HTTP statuses and strict validation remain the same. Regenerate matched clients, capsules, gateways and OpenAPI to obtain the new generated diagnostic declarations and serialized fields; existing runtime bindings remain supported.
+
+Offline inspection retains `checked-response-inspection-v1` and adds optional metadata. Request `includeCorrectionTargets: true` only in a trusted local authoring workflow: its original selectors contain source locators that must not be forwarded to HTTP clients or logs. An unavailable target requires an explicit authoring decision; an effective ordinal path is not an original selector.
+
+Use `set-declared-type` in the existing pinned recipe only for a supported authored element or attribute `@type`. Preserve the original URI/digest and guard the expected original expanded type name, then qualify the changed effective sources and regenerate all matching artifacts. A shared declaration changes every use in its project, so review those uses before adoption.
+
+Changing `xs:anyURI` to `xs:string` admits embed text and removes URI validation. Changing `xs:dateTime` to string also accepts nonsense; an existing constrained string type can enforce a layout without proving calendar validity or normalizing timezones. No observed response weakens validation automatically or refreshes source pins.
+
+Alternate companion response branches remain a design investigation. This release does not add an application-error branch API or reinterpret an error payload as record data.
+
+## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",