@techspokes/typescript-wsdl-client 1.4.1 → 1.5.0

package/dist/compiler/payloadDiagnostics.d.ts

@@ -0,0 +1,60 @@
+import type { AttributeNode, ElementNode } from './canonicalGraph.js';
+import type { SemanticContext } from './semanticContext.js';
+import type { ExpandedName } from '../loader/orderedSyntax.js';
+/** Optional additive metadata shared by inspection, direct runtimes and generated HTTP failures.
+ * @since 1.5.0
+ * @constraints Resource and universe identifiers are opaque; source locators remain trusted local data.
+ */
+export interface CheckedPayloadDiagnostic {
+    readonly version: 'checked-payload-diagnostic-v1';
+    readonly universe: string;
+    readonly resource: string;
+    readonly digest: string;
+    readonly declaration: {
+        readonly kind: 'element' | 'attribute';
+        readonly name: ExpandedName;
+    };
+    readonly owner?: {
+        readonly kind: string;
+        readonly name?: ExpandedName;
+    };
+    readonly datatype?: ExpandedName;
+    readonly builtin?: ExpandedName;
+    readonly location: string;
+    readonly unknownField?: true;
+    readonly truncated?: true;
+}
+type Evidence = Readonly<{
+    context: SemanticContext;
+    declaration: ElementNode | AttributeNode;
+}>;
+/** Format only a schema-established expanded name, with a bounded occurrence index.
+ * @param name Name supplied by the native schema owner, never an unknown payload name.
+ * @param index One-based occurrence index.
+ * @returns A bounded readable location segment.
+ */
+export declare function diagnosticName(name: ExpandedName, index?: number): string;
+/** Append a known-field segment while retaining an explicit marker for omitted ancestor information.
+ * @param parent Bounded location already built from native schema fields.
+ * @param segment Native known-field segment or fixed diagnostic marker.
+ * @returns At most 2048 characters, including an explicit truncation marker when necessary.
+ */
+export declare function appendDiagnosticLocation(parent: string, segment: string): string;
+/** Publish safe diagnostic facts while retaining native source ownership privately.
+ * @param context Actual semantic owner of the failed declaration.
+ * @param declaration Actual declaration selected by native matching.
+ * @param location Location built from matched schema fields.
+ * @param options Optional scalar builtin and unknown-field marker.
+ * @returns Bounded, immutable, value-redacted metadata with no native handles or source URI.
+ */
+export declare function createPayloadDiagnostic(context: SemanticContext, declaration: ElementNode | AttributeNode, location: string, options?: Readonly<{
+    builtin?: ExpandedName;
+    unknownField?: boolean;
+}>): CheckedPayloadDiagnostic;
+/** Read native provenance only for a diagnostic emitted in this process.
+ * @param diagnostic Exact issued diagnostic object.
+ * @returns Native declaration ownership or undefined for copied/public data.
+ * @constraints This trusted internal seam is not a public HTTP or JSON authority surface.
+ */
+export declare function inspectPayloadDiagnostic(diagnostic: CheckedPayloadDiagnostic): Evidence | undefined;
+export {};

package/dist/compiler/payloadDiagnostics.js

@@ -0,0 +1,73 @@
+/** Bounded value-redacted facts emitted by the native declaration owner.
+ * @since 1.5.0
+ * @constraints Display metadata never establishes validation or correction authority.
+ */
+import { createHash } from 'node:crypto';
+const evidence = new WeakMap();
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+/** Format only a schema-established expanded name, with a bounded occurrence index.
+ * @param name Name supplied by the native schema owner, never an unknown payload name.
+ * @param index One-based occurrence index.
+ * @returns A bounded readable location segment.
+ */
+export function diagnosticName(name, index = 1) {
+    return `{${name.namespace.slice(0, 256)}}${name.local.slice(0, 256)}[${index > 100_000 ? '>100000' : index}]`
+        + (name.namespace.length > 256 || name.local.length > 256 ? '[truncated]' : '');
+}
+/** Append a known-field segment while retaining an explicit marker for omitted ancestor information.
+ * @param parent Bounded location already built from native schema fields.
+ * @param segment Native known-field segment or fixed diagnostic marker.
+ * @returns At most 2048 characters, including an explicit truncation marker when necessary.
+ */
+export function appendDiagnosticLocation(parent, segment) {
+    if (parent.endsWith('/[truncated]'))
+        return parent;
+    const location = parent + '/' + segment;
+    return location.length > 2048 ? location.slice(0, 2036) + '/[truncated]' : location;
+}
+/** Publish safe diagnostic facts while retaining native source ownership privately.
+ * @param context Actual semantic owner of the failed declaration.
+ * @param declaration Actual declaration selected by native matching.
+ * @param location Location built from matched schema fields.
+ * @param options Optional scalar builtin and unknown-field marker.
+ * @returns Bounded, immutable, value-redacted metadata with no native handles or source URI.
+ */
+export function createPayloadDiagnostic(context, declaration, location, options = {}) {
+    let truncated = location.length > 2048 || location.includes('[truncated]') || location.includes('[>100000]');
+    const name = (value) => {
+        if (value.namespace.length > 256 || value.local.length > 256)
+            truncated = true;
+        return Object.freeze({ namespace: value.namespace.slice(0, 256), local: value.local.slice(0, 256) });
+    };
+    let ownerId = context.owner(declaration.id), owner;
+    for (let depth = 0; ownerId && depth < 32; depth++) {
+        const found = context.lookup(ownerId);
+        if (found.kind !== 'found')
+            break;
+        if (found.node.identity.kind === 'global') {
+            owner = Object.freeze({ kind: found.node.kind, name: name(found.node.identity.name) });
+            break;
+        }
+        ownerId = context.owner(ownerId);
+    }
+    const resolved = context.resolve(declaration.type);
+    const datatype = resolved.kind === 'builtin' ? resolved.name : resolved.kind === 'found'
+        && resolved.node.identity.kind === 'global' ? resolved.node.identity.name : undefined;
+    const source = declaration.context.source;
+    const result = Object.freeze({ version: 'checked-payload-diagnostic-v1',
+        universe: `universe-${hash(context.contextId)}`, resource: `resource-${hash(source.uri)}`, digest: source.digest,
+        declaration: Object.freeze({ kind: declaration.kind, name: name(declaration.name) }),
+        ...(owner ? { owner } : {}), ...(datatype ? { datatype: name(datatype) } : {}),
+        ...(options.builtin ? { builtin: name(options.builtin) } : {}), location: location.slice(0, 2048),
+        ...(options.unknownField ? { unknownField: true } : {}), ...(truncated ? { truncated: true } : {}) });
+    evidence.set(result, { context, declaration });
+    return result;
+}
+/** Read native provenance only for a diagnostic emitted in this process.
+ * @param diagnostic Exact issued diagnostic object.
+ * @returns Native declaration ownership or undefined for copied/public data.
+ * @constraints This trusted internal seam is not a public HTTP or JSON authority surface.
+ */
+export function inspectPayloadDiagnostic(diagnostic) {
+    return evidence.get(diagnostic);
+}

package/dist/compiler/sourceCorrections.d.ts

@@ -1,4 +1,5 @@
 import type { SchemaInput } from "../loader/schemaInput.js";
+import type { SyntaxSource } from "../loader/orderedSyntax.js";
 import type { OfflineSchemaResource } from "../loader/schemaResources.js";
 import type { GraphNode, NodeId } from "./canonicalGraph.js";
 export type SourceCorrectionSelector = Readonly<{
@@ -42,6 +43,10 @@ export type SourceCorrectionInventoryNode = Readonly<{
     parent?: NodeId;
     chameleon: boolean;
     ambiguousContext: boolean;
+    declaredType?: Readonly<{
+        namespace: string;
+        local: string;
+    }>;
 }>;
 export type SourceCorrectionInventory = Readonly<{
     version: 1;
@@ -88,7 +93,19 @@ type InsertCorrection = Readonly<{
     position: InsertPosition;
     element: InsertElement;
 }>;
-type Correction = OccursCorrection | WildcardCorrection | InsertCorrection;
+type DeclaredTypeCorrection = Readonly<{
+    kind: "set-declared-type";
+    target: SourceCorrectionSelector;
+    expectedType: Readonly<{
+        namespace: string;
+        local: string;
+    }>;
+    type: Readonly<{
+        namespace: string;
+        local: string;
+    }>;
+}>;
+type Correction = OccursCorrection | WildcardCorrection | InsertCorrection | DeclaredTypeCorrection;
 export type SourceCorrectionProvenance = Readonly<{
     version: 1;
     canonicalRecipeDigest: string;
@@ -107,6 +124,38 @@ export type PreparedCorrectedSourceInputs = Readonly<{
     inventory: SourceCorrectionInventory;
     resources: ReadonlyMap<string, OfflineSchemaResource>;
     provenance: SourceCorrectionProvenance;
+    originalTargets: readonly Readonly<{
+        uri: string;
+        effectiveDigest: string;
+        effectiveStart: number;
+        namespace: string;
+        kind: GraphNode['kind'];
+        ambiguous: boolean;
+        target: SourceCorrectionSelector;
+        declaredType?: Readonly<{
+            namespace: string;
+            local: string;
+        }>;
+    }>[];
+}>;
+/** Recover an original target from the actual edit spans, never an effective ordinal path.
+ * @param prepared Native correction result retaining the original pinned inventory and edit correspondence.
+ * @param source Effective declaration source obtained from its native semantic owner.
+ * @param namespace Effective schema interpretation namespace.
+ * @param kind Actual declaration kind.
+ * @returns A pinned original selector, or an explicit reason when correspondence is unavailable or ambiguous.
+ * @constraints This trusted local authoring result contains source locators and must not enter HTTP diagnostics.
+ */
+export declare function recoverOriginalSourceCorrectionTarget(prepared: PreparedCorrectedSourceInputs, source: SyntaxSource, namespace: string, kind: GraphNode['kind']): Readonly<{
+    kind: 'available';
+    target: SourceCorrectionSelector;
+    declaredType?: Readonly<{
+        namespace: string;
+        local: string;
+    }>;
+} | {
+    kind: 'unavailable';
+    reason: 'original-target-not-established' | 'ambiguous-original-target';
 }>;
 export declare class SourceCorrectionError extends Error {
     readonly category: "invalid-recipe" | "stale-source" | "ambiguous-target" | "unsupported-target" | "resource-limit" | "cancelled";

package/dist/compiler/sourceCorrections.js

@@ -1,10 +1,11 @@
 /** Explicit, source-pinned XML corrections for loaded schema inputs. */
 import { createHash } from "node:crypto";
 import { copyOriginalSchemaResource } from "../loader/schemaInput.js";
-import { decodeMetadataXml, isXmlNCName, syntaxElements, XSD_NAMESPACE } from "../loader/orderedSyntax.js";
+import { decodeMetadataXml, isXmlNCName, syntaxAttribute, syntaxElements, XSD_NAMESPACE } from "../loader/orderedSyntax.js";
 import { DEFAULT_GRAPH_NODES, GraphError, isBuiltinType } from "./canonicalGraph.js";
 import { buildCanonicalGraph } from "./buildCanonicalGraph.js";
 import { namespaceAllows, wildcardNamespaces } from './wildcardAlgebra.js';
+import { normalizeWhitespace } from '../util/xmlWhitespace.js';
 const RECIPE_VERSION = 1;
 const MAX_RECIPE_BYTES = 256 * 1024;
 const MAX_RECIPE_DEPTH = 32;
@@ -13,6 +14,22 @@ const MAX_OUTPUT_GROWTH = 2 * 1024 * 1024;
 const MAX_SYNTAX_INDEX_NODES = DEFAULT_GRAPH_NODES;
 const MAX_LEXICAL_SCAN = 64 * 1024 * 1024;
 const HASH = /^[a-f0-9]{64}$/;
+/** Recover an original target from the actual edit spans, never an effective ordinal path.
+ * @param prepared Native correction result retaining the original pinned inventory and edit correspondence.
+ * @param source Effective declaration source obtained from its native semantic owner.
+ * @param namespace Effective schema interpretation namespace.
+ * @param kind Actual declaration kind.
+ * @returns A pinned original selector, or an explicit reason when correspondence is unavailable or ambiguous.
+ * @constraints This trusted local authoring result contains source locators and must not enter HTTP diagnostics.
+ */
+export function recoverOriginalSourceCorrectionTarget(prepared, source, namespace, kind) {
+    const matches = prepared.originalTargets.filter(item => item.uri === source.uri && item.effectiveDigest === source.digest
+        && item.effectiveStart === source.start.offset && item.namespace === namespace && item.kind === kind);
+    if (matches.length !== 1 || matches[0].ambiguous)
+        return { kind: 'unavailable',
+            reason: matches.length > 1 || matches[0]?.ambiguous ? 'ambiguous-original-target' : 'original-target-not-established' };
+    return { kind: 'available', target: matches[0].target, ...(matches[0].declaredType ? { declaredType: matches[0].declaredType } : {}) };
+}
 export class SourceCorrectionError extends Error {
     category;
     constructor(category, message) {
@@ -127,6 +144,13 @@ function checkOccurs(min, max, label) {
     if (max !== "unbounded" && (min.length > max.length || (min.length === max.length && min > max)))
         fail("invalid-recipe", `${label} minimum exceeds maximum`);
 }
+function expandedType(value, label) {
+    const item = record(value, ["namespace", "local"], label);
+    const namespace = text(item.namespace, `${label}.namespace`, true), local = text(item.local, `${label}.local`);
+    if (!isXmlNCName(local))
+        fail("invalid-recipe", `${label}.local must be an XML NCName`);
+    return Object.freeze({ namespace, local });
+}
 function parseRecipe(value, signal) {
     boundedJsonSize(value, signal);
     const root = record(value, ["version", "resources", "corrections"], "recipe");
@@ -145,6 +169,12 @@ function parseRecipe(value, signal) {
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
             fail("invalid-recipe", `corrections[${index}] must be an object`);
         const kind = raw.kind;
+        if (kind === "set-declared-type") {
+            const item = record(raw, ["kind", "target", "expectedType", "type"], `corrections[${index}]`);
+            return Object.freeze({ kind, target: selector(item.target, `corrections[${index}].target`),
+                expectedType: expandedType(item.expectedType, `corrections[${index}].expectedType`),
+                type: expandedType(item.type, `corrections[${index}].type`) });
+        }
         if (kind === "set-occurs") {
             const item = record(raw, ["kind", "target", "min", "max"], `corrections[${index}]`);
             const min = occurrence(item.min, `corrections[${index}].min`, false), max = occurrence(item.max, `corrections[${index}].max`, true);
@@ -312,9 +342,10 @@ function targetMap(inputs, signal) {
                 if (old.node.context.effectiveNamespace !== node.context.effectiveNamespace || old.node.context.source.path !== source.path) {
                     fail("ambiguous-target", "One canonical identity has conflicting schema contexts");
                 }
+                old.universes.push(graph);
                 continue;
             }
-            targets.set(key, { node, syntax, ambiguousContext: false });
+            targets.set(key, { node, syntax, ambiguousContext: false, universes: [graph] });
         }
     }
     for (const target of targets.values()) {
@@ -350,7 +381,9 @@ function targetMap(inputs, signal) {
             ...(nodeName(node) ? { name: nodeName(node) } : {}), syntaxName: syntax.name, uri: source.uri, digest: source.digest, path: source.path,
             start: source.start.offset, end: source.end.offset, attributes: rawAttributes, ...(node.kind === "particle" ? { occurs: node.occurs } : {}),
             ...(wildcard ? { wildcard } : {}), ...(children ? { children } : {}), ...(parents.has(node.id) ? { parent: parents.get(node.id) } : {}),
-            chameleon: Boolean(node.context.chameleon || contextChameleon.get(sourceKey(source.uri, source.digest, source.path))), ambiguousContext });
+            chameleon: Boolean(node.context.chameleon || contextChameleon.get(sourceKey(source.uri, source.digest, source.path))), ambiguousContext,
+            ...((node.kind === 'element' || node.kind === 'attribute') && syntaxAttribute(syntax, 'type') !== undefined && node.type.kind !== 'local'
+                ? { declaredType: node.type.name } : {}) });
         nodes.push(entry);
     }
     nodes.sort((a, b) => compareText(a.uri, b.uri) || compareText(a.path, b.path) || compareText(a.id, b.id));
@@ -588,6 +621,73 @@ function validateTargetType(qnameValue, targets) {
     if (!exists)
         fail("unsupported-target", "Inserted element type must refer to an existing named type or XML Schema builtin");
 }
+/** Check a replacement in each declaring source universe and schema interpretation.
+ * @param target Original authored declaration and its independent acquired universes.
+ * @param replacement Expanded replacement type, never a payload-derived guess.
+ * @param signal Cooperative cancellation signal.
+ * @param budget Shared bounded correction work allowance.
+ * @returns Nothing when every origin permits the existing type reference.
+ * @throws SourceCorrectionError For unavailable, illegal, unimported or ambiguous types, cancellation or exhausted work.
+ * @constraints An independent companion cannot lend its types or import permissions to this declaration.
+ */
+function validateDeclaredType(target, replacement, signal, budget) {
+    const charge = () => {
+        checkAbort(signal);
+        if (--budget.remaining < 0)
+            fail('resource-limit', 'Declared-type correction exceeds its work limit');
+    };
+    if (replacement.namespace === XSD_NAMESPACE && isBuiltinType(replacement.local)) {
+        if (target.node.kind === 'attribute' && replacement.local === 'anyType')
+            fail('unsupported-target', 'Attribute declared type must be simple');
+        return;
+    }
+    for (const graph of target.universes) {
+        charge();
+        const matches = graph.nodes.filter(node => {
+            charge();
+            return (node.kind === 'simpleType' || node.kind === 'complexType') && node.identity.kind === 'global'
+                && node.identity.name.namespace === replacement.namespace && node.identity.name.local === replacement.local;
+        });
+        if (matches.length !== 1)
+            fail(matches.length > 1 ? 'ambiguous-target' : 'unsupported-target', 'Replacement type must be an existing named type in the target source universe');
+        if (target.node.kind === 'attribute' && matches[0].kind !== 'simpleType')
+            fail('unsupported-target', 'Attribute declared type must be simple');
+        const imports = new Map();
+        const importSyntax = new Map();
+        for (const retained of graph.schemaRetained) {
+            charge();
+            if (retained.syntax.name.namespace === XSD_NAMESPACE && retained.syntax.name.local === 'import') {
+                const source = retained.syntax.source;
+                importSyntax.set(sourceKey(source.uri, source.digest, source.path), retained.syntax);
+            }
+        }
+        for (const edge of graph.loading.edges) {
+            charge();
+            if (edge.kind !== 'import')
+                continue;
+            const syntax = importSyntax.get(sourceKey(edge.source.uri, edge.source.digest, edge.source.path));
+            if (!syntax)
+                fail('unsupported-target', 'Replacement type import prerequisite is unavailable');
+            const namespaces = imports.get(edge.from) ?? new Set();
+            namespaces.add(normalizeWhitespace(syntaxAttribute(syntax, 'namespace') ?? '', 'collapse'));
+            imports.set(edge.from, namespaces);
+        }
+        const source = target.node.context.source;
+        const origins = (graph.origins[target.node.id] ?? []).filter(origin => {
+            charge();
+            const actual = origin.context.source;
+            return sourceKey(actual.uri, actual.digest, actual.path) === sourceKey(source.uri, source.digest, source.path);
+        });
+        if (!origins.length)
+            fail('unsupported-target', 'Replacement type declaring interpretation is unavailable');
+        for (const origin of origins) {
+            charge();
+            if (replacement.namespace !== origin.context.effectiveNamespace && !imports.get(origin.interpretation)?.has(replacement.namespace)) {
+                fail('unsupported-target', 'Replacement type namespace is not imported by the declaring schema');
+            }
+        }
+    }
+}
 function decodedResource(source, cache) {
     const prior = cache.get(source.uri);
     if (prior !== undefined)
@@ -599,6 +699,30 @@ function decodedResource(source, cache) {
 function validateCorrection(correction, targets, sources, decoded, claimed, insertSlots, signal, scanBudget = { remaining: MAX_LEXICAL_SCAN }) {
     const target = targetFor(correction.target, targets), source = checkSelectorResource(correction.target, sources), node = target.node;
     checkAbort(signal);
+    if (correction.kind === 'set-declared-type') {
+        if ((node.kind !== 'element' && node.kind !== 'attribute') || syntaxAttribute(target.syntax, 'ref') !== undefined
+            || syntaxAttribute(target.syntax, 'type') === undefined || node.type.kind === 'local'
+            || syntaxElements(target.syntax, XSD_NAMESPACE).some(child => child.name.local === 'simpleType' || child.name.local === 'complexType')) {
+            fail('unsupported-target', 'set-declared-type requires an authored element or attribute declaration with an existing @type; inline and ref forms refuse');
+        }
+        if (node.type.name.namespace !== correction.expectedType.namespace || node.type.name.local !== correction.expectedType.local) {
+            fail('stale-source', 'Declared type does not match expectedType in the original schema context');
+        }
+        validateDeclaredType(target, correction.type, signal, scanBudget);
+        if (node.context.chameleon && correction.type.namespace === '')
+            fail('unsupported-target', 'A no-namespace replacement would be reinterpreted by chameleon adoption');
+        const claim = `${sourceKey(source.uri, source.digest, node.context.source.path)}:type`;
+        if (claimed.has(claim))
+            fail('invalid-recipe', 'Conflicting correction for declared type');
+        claimed.add(claim);
+        const xml = decodedResource(source, decoded), replacement = qname(correction.type.namespace, correction.type.local, node.context.namespaces, new Set());
+        const edits = updateStartTag(xml, target, { type: replacement.lexical }, signal, scanBudget);
+        if (replacement.declaration) {
+            const tag = startTag(xml, node.context.source.start.offset, signal, scanBudget);
+            edits.push({ start: tag.close, end: tag.close, text: ` ${replacement.declaration}`, label: `${node.id}:attributes` });
+        }
+        return { patches: new Map([[source.uri, edits]]), provenance: { kind: correction.kind, target: correction.target } };
+    }
     if (correction.kind === "set-occurs") {
         if (node.kind !== "particle")
             fail("unsupported-target", "set-occurs target must be an XSD particle");
@@ -692,9 +816,10 @@ function validateCorrection(correction, targets, sources, decoded, claimed, inse
     insertSlots.add(slot);
     return { patches: new Map([[source.uri, [{ start: position, end: replacementEnd ?? position, text, label: `${node.id}:insert` }]]]), provenance: { kind: correction.kind, target: correction.target } };
 }
-function applyPatches(original, patches, signal) {
+function normalizedPatches(patches, signal) {
     const combined = new Map();
     for (const patch of patches) {
+        checkAbort(signal);
         const key = `${patch.start}:${patch.end}`;
         const prior = combined.get(key);
         if (!prior) {
@@ -706,10 +831,12 @@ function applyPatches(original, patches, signal) {
         }
         combined.set(key, { ...prior, text: prior.text + patch.text.replace(/^\s+/, " ") });
     }
-    const sorted = [...combined.values()].sort((a, b) => a.start - b.start || a.end - b.end || compareText(a.label, b.label));
+    return [...combined.values()].sort((a, b) => a.start - b.start || a.end - b.end || compareText(a.label, b.label));
+}
+function applyPatches(original, patches, signal) {
     let previousEnd = 0;
     const chunks = [];
-    for (const patch of sorted) {
+    for (const patch of patches) {
         checkAbort(signal);
         if (patch.start < previousEnd || patch.end < patch.start || patch.end > original.length)
             fail("invalid-recipe", "Correction source spans overlap or exceed the original resource");
@@ -755,12 +882,14 @@ export function prepareCorrectedSourceInputs(inputs, recipeValue, signal) {
         provenanceCorrections.push(result.provenance);
     }
     const resources = new Map(), provenanceResources = [];
+    const originalTargets = [];
     let effectiveBytesTotal = 0;
     let outputGrowth = 0;
     const outputLimit = Math.min(...inputs.map(input => input.limits.totalBytes)), singleLimit = Math.min(...inputs.map(input => input.limits.resourceBytes));
     for (const source of [...sources.values()].sort((a, b) => compareText(a.uri, b.uri))) {
         checkAbort(signal);
-        const edits = patches.get(source.uri) ?? [];
+        // @constraints Application and original-target correspondence consume exactly the same combined edits.
+        const edits = normalizedPatches(patches.get(source.uri) ?? [], signal);
         const originalText = edits.length ? decodedResource(source, decoded) : "";
         const updated = edits.length ? applyPatches(originalText, edits, signal) : "";
         const bytes = edits.length && updated !== originalText ? utf8Output(updated, source.bytes) : source.bytes;
@@ -773,6 +902,26 @@ export function prepareCorrectedSourceInputs(inputs, recipeValue, signal) {
         if (outputGrowth > MAX_OUTPUT_GROWTH)
             fail("resource-limit", "Correction output growth exceeds the limit");
         const effectiveDigest = sha256(bytes), changed = effectiveDigest !== source.digest;
+        // @constraints Encoding-declaration rewriting is outside edit-span correspondence; refuse rather than guess.
+        if (!edits.length || decodeMetadataXml(bytes) === updated)
+            for (const node of inventory.nodes) {
+                checkAbort(signal);
+                if (node.uri !== source.uri || node.digest !== source.digest)
+                    continue;
+                let effectiveStart = node.start, established = true;
+                for (const edit of edits) {
+                    if (edit.end <= node.start)
+                        effectiveStart += edit.text.length - (edit.end - edit.start);
+                    else if (edit.start <= node.start)
+                        established = false;
+                }
+                const native = targets.get(selectorKey({ id: node.id, uri: node.uri, digest: node.digest }))?.node;
+                const declaredType = native && (native.kind === 'element' || native.kind === 'attribute') && native.type.kind !== 'local' ? native.type.name : undefined;
+                if (established)
+                    originalTargets.push(Object.freeze({ uri: source.uri, effectiveDigest, effectiveStart,
+                        namespace: node.namespace, kind: node.kind, ambiguous: node.ambiguousContext,
+                        target: Object.freeze({ id: node.id, uri: node.uri, digest: node.digest }), ...(declaredType ? { declaredType } : {}) }));
+            }
         const resource = Object.freeze({ bytes: new Uint8Array(bytes), digest: effectiveDigest });
         resources.set(source.uri, resource);
         for (const alias of source.aliases)
@@ -790,5 +939,5 @@ export function prepareCorrectedSourceInputs(inputs, recipeValue, signal) {
     }
     const provenance = Object.freeze({ version: 1, canonicalRecipeDigest: canonicalRecipeDigest(recipe),
         resources: Object.freeze(provenanceResources), corrections: Object.freeze(provenanceCorrections.map(item => Object.freeze(item))) });
-    return Object.freeze({ inventory, resources, provenance });
+    return Object.freeze({ inventory, resources, provenance, originalTargets: Object.freeze(originalTargets) });
 }

package/dist/gateway/generateCheckedGateway.js

@@ -84,6 +84,21 @@ async function generateGatewayFromReconstruction(expected, options) {
         } };
     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 doc = {
         openapi: '3.1.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
@@ -102,8 +117,9 @@ async function generateGatewayFromReconstruction(expected, options) {
                     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: [documentedFault,
-                                            { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
-                        '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
+                                            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('.'))
@@ -176,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.

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.