@techspokes/typescript-wsdl-client 1.4.0 → 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/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;
+}