@techspokes/typescript-wsdl-client 1.4.1 → 1.5.0

package/README.md

@@ -9,6 +9,10 @@ Turn legacy WSDL/SOAP services into typed TypeScript clients and optional REST A
 
 Created from production integration work at [TechSpokes](https://www.techspokes.com); built for teams modernizing real enterprise SOAP integrations.
 
+## Upgrading to 1.5.0
+
+Version 1.5.0 adds scoped, value-redacted checked payload diagnostics and explicit digest-pinned declared-type corrections. Trusted local inspection can supply original correction targets; changed effective contracts need fresh qualification and matched artifact regeneration. Read the [1.4.x migration guidance](docs/migration.md#from-14x-to-150).
+
 ## Upgrading to 1.4.0
 
 Version 1.4.0 adds explicit JSON source corrections, offline SOAP response inspection, and checked SOAP 1.1 protocol faults without invented application values. Existing runtime bindings remain available; regenerate matched SOAP 1.1 artifacts to adopt the additive V3 binding. Read the [1.3.x migration guidance](docs/migration.md#from-13x-to-140).
@@ -257,6 +261,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
 | [Agent Skill Artifact](docs/agent-skill.md) | Release ZIP for consumer-project AI agents |
 | [Version Migration](docs/migration.md) | Upgrading between package versions |
+| [1.5.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.5.0.md) | Scoped diagnostics and explicit declared-type corrections |
 | [1.2.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.2.0.md) | Composition, consumer compatibility and bounded RPC qualification |
 | [1.4.1 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.4.1.md) | Composable checked OpenAPI documentation |
 | [1.4.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.4.0.md) | Contract corrections, offline inspection and SOAP 1.1 protocol faults |

package/dist/checkedPipeline.d.ts

@@ -90,6 +90,7 @@ export declare function parseCheckedComponentChoices(value: unknown): Partial<Ch
 export interface PreparedCheckedSourceInputs {
     readonly main: SchemaInput;
     readonly companions: ReadonlyMap<string, SchemaInput>;
+    readonly correctionPreparation: ReturnType<typeof prepareCorrectedSourceInputs>;
     readonly provenance: Awaited<ReturnType<typeof prepareCorrectedSourceInputs>>['provenance'] & {
         readonly recipeFile: {
             readonly digest: string;
@@ -168,7 +169,7 @@ export declare function prepareComponentStages(wsdl: string, config: CheckedComp
             changed: boolean;
         }>[];
         corrections: readonly Readonly<{
-            kind: "set-occurs" | "set-wildcard-namespaces" | "insert-element";
+            kind: "set-occurs" | "set-wildcard-namespaces" | "insert-element" | "set-declared-type";
             target: import("./compiler/sourceCorrections.js").SourceCorrectionSelector;
         }>[];
     }> & {

package/dist/checkedPipeline.js

@@ -241,7 +241,7 @@ export async function prepareCheckedSourceInputs(source, config, acquiredMain) {
     const effectiveCompanions = new Map();
     for (const [key, input] of companions)
         effectiveCompanions.set(key, await reload(input));
-    return { main: effectiveMain, companions: effectiveCompanions, provenance: { ...corrected.provenance,
+    return { main: effectiveMain, companions: effectiveCompanions, correctionPreparation: corrected, provenance: { ...corrected.provenance,
             recipeFile: { digest: createHash('sha256').update(bytes).digest('hex') } } };
 }
 /**

package/dist/checkedResponseInspection.d.ts

@@ -2,6 +2,8 @@ import type { CheckedComponentOptions } from './checkedPipeline.js';
 import type { DirectOperationSelector } from './compiler/directOperation.js';
 import type { ObservedSoapResponseMetadata } from './compiler/directSoap.js';
 import type { DirectXmlLimits } from './compiler/directCodec.js';
+import type { SourceCorrectionSelector } from './compiler/sourceCorrections.js';
+import type { CheckedPayloadDiagnostic } from './compiler/payloadDiagnostics.js';
 export interface CheckedResponseInspectionOptions {
     readonly checkedComponents?: Partial<CheckedComponentOptions>;
     readonly selector: DirectOperationSelector;
@@ -10,6 +12,7 @@ export interface CheckedResponseInspectionOptions {
     readonly signal?: AbortSignal;
     readonly limits?: DirectXmlLimits;
     readonly includeCorrectionDraft?: boolean;
+    readonly includeCorrectionTargets?: boolean;
 }
 type Assessment = 'conforming' | 'mismatch' | 'refused' | 'unassessed';
 interface ScopedOutcome {
@@ -31,7 +34,25 @@ interface InspectionDiagnostic {
     readonly source?: InspectionLocation;
     readonly schemaPath?: string;
     readonly payloadPath?: string;
+    readonly diagnostic?: CheckedPayloadDiagnostic;
 }
+/** Explicit trusted authoring data; available selectors retain original locators and digest pins.
+ * @since 1.5.0
+ * @constraints Only requested local authoring output may contain these locators; HTTP diagnostics never do.
+ */
+export type CheckedResponseCorrectionTarget = Readonly<{
+    diagnostic: number;
+} & ({
+    kind: 'available';
+    target: SourceCorrectionSelector;
+    declaredType?: {
+        namespace: string;
+        local: string;
+    };
+} | {
+    kind: 'unavailable';
+    reason: string;
+})>;
 /** A non-applicable recipe draft; null fields require an explicit consumer decision.
  * @since Unreleased
  */
@@ -78,6 +99,7 @@ export interface CheckedResponseInspectionReport {
     };
     readonly diagnostics: readonly InspectionDiagnostic[];
     readonly correctionDraft?: CheckedResponseCorrectionDraft;
+    readonly correctionTargets?: readonly CheckedResponseCorrectionTarget[];
     readonly sourceCorrections?: {
         readonly recipeDigest: string;
         readonly resources: readonly {

package/dist/checkedResponseInspection.js

@@ -16,7 +16,8 @@ import { createComponentValueMapping } from './compiler/directValues.js';
 import { observeComponentXml, assessObservedComponentPayload, DIRECT_XML_LIMITS } from './compiler/directCodec.js';
 import { inspectComponentRecordProjection } from './compiler/componentRecordProjection.js';
 import { acquireStandardSchemaLibrary } from './compiler/standardSchemaComponents.js';
-import { inspectSourceCorrectionInventory, SourceCorrectionError } from './compiler/sourceCorrections.js';
+import { inspectSourceCorrectionInventory, recoverOriginalSourceCorrectionTarget, SourceCorrectionError } from './compiler/sourceCorrections.js';
+import { inspectPayloadDiagnostic } from './compiler/payloadDiagnostics.js';
 import { loadSemanticSchemaInput, prepareSchemaSnapshotFiles, copyOriginalSchemaResource } from './loader/schemaInput.js';
 import { resolveResourceUri } from './loader/schemaResources.js';
 import { syntaxElements, syntaxAttribute, resolveLexicalQName, XSD_NAMESPACE, WSDL_NAMESPACE, SchemaLoadingError } from './loader/orderedSyntax.js';
@@ -59,9 +60,11 @@ function failureAssessment(kind) {
 export async function inspectCheckedResponse(source, options) {
     if (typeof source !== 'string' || !source)
         throw new TypeError('Local WSDL source string required');
-    const supplied = record(options, ['checkedComponents', 'selector', 'responseBytes', 'responseMetadata', 'signal', 'limits', 'includeCorrectionDraft']);
+    const supplied = record(options, ['checkedComponents', 'selector', 'responseBytes', 'responseMetadata', 'signal', 'limits', 'includeCorrectionDraft', 'includeCorrectionTargets']);
     if (supplied.includeCorrectionDraft !== undefined && typeof supplied.includeCorrectionDraft !== 'boolean')
         throw new TypeError('includeCorrectionDraft must be boolean');
+    if (supplied.includeCorrectionTargets !== undefined && typeof supplied.includeCorrectionTargets !== 'boolean')
+        throw new TypeError('includeCorrectionTargets must be boolean');
     const selector = parseCheckedComponentChoices({ selectors: [supplied.selector] }).selectors[0];
     const choices = parseCheckedComponentChoices(supplied.checkedComponents ?? {});
     const responseByteLength = xmlByteLength(supplied.responseBytes);
@@ -90,6 +93,8 @@ export async function inspectCheckedResponse(source, options) {
     const displaySelector = { portType: { namespace: bounded(selector.portType.namespace), local: bounded(selector.portType.local) },
         binding: { namespace: bounded(selector.binding.namespace), local: bounded(selector.binding.local) }, operation: bounded(selector.operation) };
     const diagnostics = [];
+    let sourcePreparation;
+    let correctionTargets = supplied.includeCorrectionTargets ? [] : undefined;
     const inputs = [];
     const locations = new Map();
     const resources = [];
@@ -115,14 +120,53 @@ export async function inspectCheckedResponse(source, options) {
     const location = (at) => ({ resource: at.uri === 'urn:typescript-wsdl-client:inspected-response' ? 'response' : locations.get(at.uri)?.resource ?? 'unlocated-source',
         digest: at.uri === 'urn:typescript-wsdl-client:inspected-response' ? responseIdentity.digest : locations.get(at.uri)?.digest ?? at.digest,
         path: bounded(at.path), line: at.start.line, column: at.start.column });
+    let authoringInventory;
+    const inventoryForAuthoring = () => {
+        if (authoringInventory?.inputCount === inputs.length)
+            return authoringInventory;
+        try {
+            authoringInventory = { inputCount: inputs.length, value: inspectSourceCorrectionInventory(inputs, signal) };
+        }
+        catch (error) {
+            if (!(error instanceof SourceCorrectionError) && !(error instanceof SchemaLoadingError))
+                throw error;
+            authoringInventory = { inputCount: inputs.length, reason: `original-target-inventory-${error.category}` };
+        }
+        return authoringInventory;
+    };
     const add = (scope, result) => {
         if (diagnostics.length === 32) {
             truncated = true;
             return;
         }
+        if (result.diagnostic?.truncated)
+            truncated = true;
         diagnostics.push({ scope, kind: bounded(result.kind, 80), rule: result.kind === 'xml-invalid' ? 'observed-XML-invalid' : bounded(result.rule), guidance,
             ...(result.source ? { source: location(result.source) } : {}), ...(result.schemaPath ? { schemaPath: bounded(result.schemaPath) } : {}),
-            ...(result.payloadPath ? { payloadPath: bounded(result.payloadPath) } : {}) });
+            ...(result.payloadPath ? { payloadPath: bounded(result.payloadPath) } : {}), ...(result.diagnostic ? { diagnostic: result.diagnostic } : {}) });
+        if (correctionTargets) {
+            const diagnostic = diagnostics.length - 1;
+            const native = result.diagnostic && inspectPayloadDiagnostic(result.diagnostic);
+            if (!native)
+                correctionTargets.push({ diagnostic, kind: 'unavailable', reason: 'native-declaration-unavailable' });
+            else if (sourcePreparation)
+                correctionTargets.push({ diagnostic, ...recoverOriginalSourceCorrectionTarget(sourcePreparation.correctionPreparation, native.declaration.context.source, native.declaration.context.effectiveNamespace, native.declaration.kind) });
+            else {
+                const declaration = native.declaration;
+                const inventory = inventoryForAuthoring();
+                if (!inventory.value) {
+                    correctionTargets.push({ diagnostic, kind: 'unavailable', reason: inventory.reason });
+                    return;
+                }
+                const matches = inventory.value.nodes.filter(node => node.id === declaration.id && node.uri === declaration.context.source.uri
+                    && node.digest === declaration.context.source.digest && node.kind === declaration.kind
+                    && node.namespace === declaration.context.effectiveNamespace);
+                correctionTargets.push(matches.length === 1 && !matches[0].ambiguousContext
+                    ? { diagnostic, kind: 'available', target: { id: matches[0].id, uri: matches[0].uri, digest: matches[0].digest },
+                        ...(declaration.type.kind !== 'local' ? { declaredType: declaration.type.name } : {}) }
+                    : { diagnostic, kind: 'unavailable', reason: matches.length > 1 || matches[0]?.ambiguousContext ? 'ambiguous-original-target' : 'original-target-not-established' });
+            }
+        }
     };
     let responseOutcome = { assessment: 'unassessed' };
     let wrapper, companion;
@@ -138,12 +182,17 @@ export async function inspectCheckedResponse(source, options) {
         const report = { version: 'checked-response-inspection-v1', kind, scope: metadata ? 'full-response' : 'xml-only',
             admitted: false, executed: false, selector: displaySelector, response: responseIdentity, http, fault, resources,
             outcomes: { response: scoped(responseOutcome), ...(wrapper ? { wrapper: scoped(wrapper) } : {}), ...(companion ? { companion: scoped(companion) } : {}) }, diagnostics,
-            ...(correctionDraft ? { correctionDraft } : {}), ...(correctionEvidence ? { sourceCorrections: correctionEvidence } : {}), truncated };
+            ...(correctionDraft ? { correctionDraft } : {}), ...(correctionTargets ? { correctionTargets } : {}), ...(correctionEvidence ? { sourceCorrections: correctionEvidence } : {}), truncated };
         if (Buffer.byteLength(JSON.stringify(report)) > 128 * 1024 && correctionDraft) {
             correctionDraft = undefined;
             truncated = true;
             return finish();
         }
+        if (Buffer.byteLength(JSON.stringify(report)) > 128 * 1024 && correctionTargets?.some(target => target.kind === 'available')) {
+            correctionTargets = correctionTargets.map(target => ({ diagnostic: target.diagnostic, kind: 'unavailable', reason: 'authoring-target-exceeds-report-capacity' }));
+            truncated = true;
+            return finish();
+        }
         return report;
     };
     if (signal?.aborted || !withinByteLimit || metadataOverLimit) {
@@ -161,6 +210,7 @@ export async function inspectCheckedResponse(source, options) {
         await fs.access(localFile(choices.sourceCorrectionsFile));
     const selectedChoices = { ...choices, sourceResources: choices.sourceResources ?? [], signal };
     const prepared = await prepareCheckedComponentPlan(rootFile, selectedChoices, undefined, selector);
+    sourcePreparation = prepared.sources;
     if (prepared.sourceInput)
         retain(prepared.sourceInput);
     if (prepared.sources) {

package/dist/client/checkedDirectRuntime.d.ts

@@ -1,3 +1,4 @@
+import type { CheckedPayloadDiagnostic } from '../compiler/payloadDiagnostics.js';
 import type { ComponentClientResult } from './directClientRuntime.js';
 import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_SOAP12_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
 interface Name {
@@ -34,6 +35,7 @@ interface Failure {
     readonly usage: Usage;
     readonly repair?: string;
     readonly phase?: 'input' | 'response';
+    readonly diagnostic?: CheckedPayloadDiagnostic;
 }
 type Success = {
     readonly value: unknown;

package/dist/client/directClientRuntime.d.ts

@@ -1,3 +1,4 @@
+import type { CheckedPayloadDiagnostic } from '../compiler/payloadDiagnostics.js';
 import type { SemanticBudgetLimits, ResolverUsage } from '../compiler/semanticBudget.js';
 import type { DirectCapsuleFailure } from '../compiler/directSourceCapsule.js';
 import type { DirectSoapOptions, ComponentSoapOptions, DirectSoapFailure, ComponentProtocolFault, DeclaredSoapFault, Soap11FaultMetadata, Soap12FaultMetadata } from '../compiler/directSoap.js';
@@ -36,6 +37,7 @@ export interface DirectClientFailure {
     readonly usage: ResolverUsage;
     readonly repair?: string;
     readonly phase?: 'input' | 'response';
+    readonly diagnostic?: CheckedPayloadDiagnostic;
 }
 export type DirectClientResult = DirectClientFailure | Readonly<{
     kind: 'soap-response';

package/dist/client/directClientRuntime.js

@@ -156,7 +156,11 @@ async function executeClient(expectedBase64, input, options, component, protocol
         if (!('decoded' in result)) {
             if (result.kind === 'soap-fault' && result.fault.version !== protocol)
                 throw new TypeError('Protocol fault requires its generated runtime binding');
-            return result;
+            if (result.kind === 'soap-fault')
+                return result;
+            // @constraints Native source provenance can contain endpoint secrets; only the safe diagnostic crosses the runtime boundary.
+            return Object.freeze({ kind: result.kind, rule: result.rule, usage: result.usage,
+                ...(result.phase ? { phase: result.phase } : {}), ...(result.diagnostic ? { diagnostic: result.diagnostic } : {}) });
         }
         if (options.soap.signal?.aborted)
             return fail('cancelled', 'cooperative-cancellation');

package/dist/client/generateDirectClient.js

@@ -86,7 +86,7 @@ export function generateDirectClient(expected, signal) {
             '}',
             'export interface Failure {',
             '  readonly kind: "incompatible-artifact" | "unsupported" | "missing-authority" | "resource-limit" | "cancelled" | "inconclusive" | "invalid-schema" | "scalar-invalid" | "value-invalid" | "xml-invalid" | "mismatch" | "transport" | "protocol";',
-            '  readonly rule: string; readonly repair?: string; readonly usage: Usage;',
+            '  readonly rule: string; readonly repair?: string; readonly usage: Usage; readonly diagnostic?: import("@techspokes/typescript-wsdl-client").CheckedPayloadDiagnostic;',
             '}',
             'export interface NativeSuccess { readonly kind: "soap-response" | "soap-fault"; readonly value: unknown;',
             '  readonly admitted: false; readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array;',
@@ -192,7 +192,7 @@ export async function generateComponentClient(expected, signal) {
             '    readonly limits?: {readonly maxBytes?: number; readonly maxDepth?: number; readonly maxNodes?: number; readonly maxText?: number}};',
             '}',
             'export interface Failure {readonly kind: "incompatible-artifact" | "unsupported" | "missing-authority" | "resource-limit" | "cancelled" | "inconclusive" | "invalid-schema" | "scalar-invalid" | "value-invalid" | "xml-invalid" | "mismatch" | "transport" | "protocol";',
-            '  readonly rule: string; readonly repair?: string; readonly phase?: "input" | "response"; readonly usage: Usage}',
+            '  readonly rule: string; readonly repair?: string; readonly phase?: "input" | "response"; readonly usage: Usage; readonly diagnostic?: import("@techspokes/typescript-wsdl-client").CheckedPayloadDiagnostic}',
             'export interface NativeSuccess {readonly kind: "soap-response" | "soap-fault"; readonly value?: unknown; readonly admitted: false;',
             '  readonly status: number; readonly usage: Usage; readonly responseBytes: Uint8Array;',
             '  readonly fault?: {readonly name?: string; readonly code: Name; readonly string: string; readonly actor?: string}}',

package/dist/compiler/componentRecordProjection.js

@@ -9,6 +9,7 @@ import { assessSourceAttributeUses } from './schemaAttributeUses.js';
 import { assessStandardSchemaElement } from './standardSchemaComponents.js';
 import { namespaceAllows } from './wildcardAlgebra.js';
 import { directDataOwnership } from './directExecutionPolicy.js';
+import { createPayloadDiagnostic, diagnosticName } from './payloadDiagnostics.js';
 import { DataOwnershipLimitError } from './dataOwnership.js';
 import { isXmlNCName, syntaxElements } from '../loader/orderedSyntax.js';
 const issued = new WeakMap();
@@ -318,8 +319,18 @@ export function decodeComponentRecordXml(outer, projection, bytes, options = {})
     catch (error) {
         if (budget.exhausted())
             return failure('resource-limit', 'record-projection-budget');
-        if (error instanceof ScopeStop)
-            return failure(error.kind, error.rule);
+        if (error instanceof ScopeStop) {
+            if (error.kind !== 'mismatch' || 'parts' in outer.output)
+                return failure(error.kind, error.rule);
+            const declaration = outer.output.element;
+            // @constraints Native metadata lookups consume the same budget and retain its terminal resource result.
+            const diagnosed = budget.guard(() => {
+                const diagnostic = createPayloadDiagnostic(context, declaration, '/' + diagnosticName(declaration.name) + '/[unknown-field]', { unknownField: true });
+                return Object.freeze({ ...failure(error.kind, error.rule), diagnostic });
+            });
+            return diagnosed.kind === 'resource-limit' && !('rule' in diagnosed)
+                ? failure('resource-limit', 'record-projection-budget') : diagnosed;
+        }
         throw error;
     }
 }

package/dist/compiler/directCodec.d.ts

@@ -1,3 +1,4 @@
+import type { CheckedPayloadDiagnostic } from './payloadDiagnostics.js';
 import type { DirectOperationContract } from './directOperation.js';
 import type { DirectValueMapping, DirectValueReceipt, DirectValueFailure, DirectExpandedValue, ComponentValueMapping, ProjectionExpandedValue, ProjectionValueReceipt } from './directValues.js';
 import type { SyntaxElement, SyntaxSource } from '../loader/orderedSyntax.js';
@@ -31,6 +32,7 @@ export interface DirectCodecFailure {
     readonly source?: SyntaxSource;
     readonly schemaPath?: string;
     readonly payloadPath?: string;
+    readonly diagnostic?: CheckedPayloadDiagnostic;
     readonly usage: ResolverUsage;
 }
 export interface DirectEncodedXml {

package/dist/compiler/directSoap.d.ts

@@ -1,3 +1,4 @@
+import type { CheckedPayloadDiagnostic } from './payloadDiagnostics.js';
 import type { DirectOperationContract } from './directOperation.js';
 import type { DirectCodecFailure, DirectDecodedXml, ComponentDecodedXml, DirectXmlLimits } from './directCodec.js';
 import type { ExpandedName, SyntaxElement, SyntaxSource } from '../loader/orderedSyntax.js';
@@ -23,6 +24,7 @@ export interface DirectSoapFailure {
     readonly source?: SyntaxSource;
     readonly schemaPath?: string;
     readonly payloadPath?: string;
+    readonly diagnostic?: CheckedPayloadDiagnostic;
 }
 /** Version-specific protocol metadata; application detail remains owned by native mappings.
  * @since 1.3.0

package/dist/compiler/directSoap.js

@@ -560,7 +560,8 @@ function assessSoapResponse(contract, output, faults, bytes, profile, options) {
         if (!decoded)
             throw new TypeError('Missing decoded SOAP response');
         if (!('validated' in decoded))
-            return profile.component ? Object.freeze({ ...decoded, phase: 'response' }) : fail(decoded.kind, decoded.rule);
+            return profile.component ? Object.freeze({ ...decoded, phase: 'response' })
+                : Object.freeze({ ...fail(decoded.kind, decoded.rule), ...(decoded.diagnostic ? { diagnostic: decoded.diagnostic } : {}) });
         check();
         check();
         return Object.freeze({ kind: faultInfo ? 'soap-fault' : 'soap-response', admitted: false, decoded,

package/dist/compiler/directStructure.d.ts

@@ -5,6 +5,7 @@ import type { DirectProjectionSlot } from './directStructurePlan.js';
 import type { SemanticContext } from './semanticContext.js';
 import type { ResolverUsage } from './semanticBudget.js';
 import type { ProjectionScalarList } from './projectionScalar.js';
+import type { CheckedPayloadDiagnostic } from './payloadDiagnostics.js';
 export type DirectDirection = Readonly<{
     kind: 'input' | 'output';
 } | {
@@ -20,6 +21,7 @@ export interface DirectScalarDuty {
     readonly payloadSource: SyntaxSource;
     readonly payloadPath: string;
     readonly schemaPath: string;
+    readonly knownLocation?: string;
     readonly fixedCanonical?: string;
     readonly retainLexical?: true;
     readonly list?: ProjectionScalarList;
@@ -81,6 +83,7 @@ export type ProjectionStructuralResult = Readonly<{
     rule: string;
     schemaPath?: string;
     payloadPath?: string;
+    diagnostic?: CheckedPayloadDiagnostic;
     usage: ResolverUsage;
 }>;
 export type ProjectionStructuralMatch = Extract<ProjectionStructuralResult, {
@@ -104,6 +107,7 @@ export type DirectStructuralResult = Readonly<{
     rule: string;
     schemaPath?: string;
     payloadPath?: string;
+    diagnostic?: CheckedPayloadDiagnostic;
     usage: ResolverUsage;
 }>;
 export type DirectStructuralMatch = Extract<DirectStructuralResult, {

package/dist/compiler/directStructure.js

@@ -3,6 +3,7 @@ import { inspectDirectOperation } from './directOperation.js';
 import { planDirectProjection, flatDirectProjection, matchOrderedProjection, selectProjectionAttribute, isXmlCharacters, isXmlNamespaceBinding } from './directStructurePlan.js';
 import { assertSemanticContext } from './semanticContext.js';
 import { isXmlNCName } from '../loader/orderedSyntax.js';
+import { createPayloadDiagnostic, diagnosticName, appendDiagnosticLocation } from './payloadDiagnostics.js';
 const projectionIssued = new WeakMap();
 /** Native context identity authenticates structure only, never source validity or operation admission. */
 export function inspectProjectionStructuralMatch(match, context) {
@@ -24,12 +25,14 @@ class Stop extends Error {
     rule;
     schemaPath;
     payloadPath;
-    constructor(kind, rule, schemaPath, payloadPath) {
+    diagnostic;
+    constructor(kind, rule, schemaPath, payloadPath, diagnostic) {
         super(rule);
         this.kind = kind;
         this.rule = rule;
         this.schemaPath = schemaPath;
         this.payloadPath = payloadPath;
+        this.diagnostic = diagnostic;
     }
 }
 /**
@@ -160,7 +163,11 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                 }
             }
             const same = (a, b) => budget.compareText(a.namespace, b.namespace) === 0 && budget.compareText(a.local, b.local) === 0;
-            const mismatch = (rule, declaration, path) => fail('mismatch', rule, declaration.context.source.path, path);
+            let currentLocation = '/' + diagnosticName(root.name);
+            const mismatch = (rule, declaration, path) => {
+                const unknownField = ['unexpected-child', 'unknown-attribute', 'root-name', 'scalar-child', 'ordered-particle-language'].includes(rule);
+                throw new Stop('mismatch', rule, declaration.context.source.path, path, createPayloadDiagnostic(context, declaration, unknownField ? appendDiagnosticLocation(currentLocation, '[unknown-field]') : currentLocation, { unknownField }));
+            };
             const attributes = (node, declaration, path) => {
                 check();
                 if (node.attributes.length)
@@ -188,6 +195,7 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                     end: { offset: s.end.offset, line: s.end.line, column: s.end.column } });
                 occurrences.push({ declaration, type: declaration.type, builtin, lexical, namespaces,
                     payloadSource, payloadPath: path, schemaPath: declaration.context.source.path,
+                    knownLocation: declaration.kind === 'attribute' ? appendDiagnosticLocation(currentLocation, '@' + diagnosticName(declaration.name)) : currentLocation,
                     ...(fixedCanonical === undefined ? {} : { fixedCanonical }), ...(retainLexical ? { retainLexical } : {}), ...(list ? { list } : {}) });
             };
             const text = (node, declaration, path) => {
@@ -216,6 +224,7 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                 check();
                 const frame = frames.pop();
                 const { declaration, path: parentPath } = frame;
+                currentLocation = frame.location ?? '/' + diagnosticName(declaration.name);
                 let node = frame.node;
                 budget.chargeWork(128 + parentPath.length * 4);
                 if (node.kind === 'text') {
@@ -407,6 +416,15 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                         dynamicDeclarations: selected.filter(slot => !('value' in slot) && slot.element).map(slot => slot.element),
                         ...(record.keyed ? { keyed: true } : {}) });
                     let selectedIndex = elements.length - 1;
+                    const occurrenceIndexes = new Map();
+                    const locations = selected.map(slot => {
+                        check();
+                        if (!slot.element)
+                            return currentLocation;
+                        const key = slot.element.id, index = (occurrenceIndexes.get(key) ?? 0) + 1;
+                        occurrenceIndexes.set(key, index);
+                        return appendDiagnosticLocation(currentLocation, diagnosticName(slot.element.name, index));
+                    });
                     for (let index = node.children.length - 1; index >= 0; index--) {
                         check();
                         const child = node.children[index];
@@ -415,13 +433,13 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                                 frames.push({ node: child, path: `${parentPath}/children/${index}`, declaration, value: frame.value, into: content });
                             continue;
                         }
-                        const item = elements[selectedIndex], slot = selected[selectedIndex--];
+                        const item = elements[selectedIndex], childLocation = locations[selectedIndex], slot = selected[selectedIndex--];
                         if (!slot.element) {
                             frames.push({ node: item.node, path: item.path, declaration, value: frame.value, unassessed: true, into: content });
                             continue;
                         }
                         frames.push({ node: item.node, path: item.path, declaration: slot.element,
-                            value: 'value' in slot ? slot.value : wildcardValue(slot.element), into: content });
+                            value: 'value' in slot ? slot.value : wildcardValue(slot.element), into: content, location: childLocation });
                     }
                     continue;
                 }
@@ -456,7 +474,8 @@ export function matchDirectProjection(context, root, payload, options = {}) {
                         return mismatch('unexpected-child', declaration, path);
                     if (slot.particle.occurs.max === '1' && count === 1)
                         return mismatch('duplicate-singleton', slot.element, path);
-                    children.push({ node: child, declaration: slot.element, value: slot.value, path, into: matchedSlots[cursor].items });
+                    children.push({ node: child, declaration: slot.element, value: slot.value, path, into: matchedSlots[cursor].items,
+                        location: appendDiagnosticLocation(currentLocation, diagnosticName(slot.element.name, count + 1)) });
                     count++;
                 }
                 for (; cursor < slots.length; cursor++, count = 0) {
@@ -488,7 +507,8 @@ export function matchDirectProjection(context, root, payload, options = {}) {
         if (budget.exhausted())
             return Object.freeze({ kind: 'resource-limit', rule: 'request-budget', usage: budget.usage() });
         if (error instanceof Stop)
-            return Object.freeze({ kind: error.kind, rule: error.rule, schemaPath: error.schemaPath, payloadPath: error.payloadPath, usage: Object.freeze({ ...budget.usage() }) });
+            return Object.freeze({ kind: error.kind, rule: error.rule, schemaPath: error.schemaPath, payloadPath: error.payloadPath,
+                ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), usage: Object.freeze({ ...budget.usage() }) });
         throw error;
     }
 }

package/dist/compiler/directValues.d.ts

@@ -1,3 +1,4 @@
+import type { CheckedPayloadDiagnostic } from './payloadDiagnostics.js';
 import type { DirectOperationContract, DirectMessageRoot, RpcMessageRoot } from './directOperation.js';
 import type { DirectDirection, DirectScalarDuty, DirectStructuralMatch } from './directStructure.js';
 import type { DirectRootPlan, DirectProjectionPlan } from './directStructurePlan.js';
@@ -96,6 +97,7 @@ export interface DirectValueFailure {
     readonly schemaPath?: string;
     readonly payloadPath?: string;
     readonly usage: ResolverUsage;
+    readonly diagnostic?: CheckedPayloadDiagnostic;
 }
 type Options = Readonly<{
     signal?: AbortSignal;

package/dist/compiler/directValues.js

@@ -1,4 +1,5 @@
 import { directDataOwnership, directLimit } from './directExecutionPolicy.js';
+import { createPayloadDiagnostic, diagnosticName } from './payloadDiagnostics.js';
 import { types } from 'node:util';
 /** Internal direct value chain. No XML encoding, transport or runtime admission. */
 import { checkSemanticBudget } from './semanticBudget.js';
@@ -60,12 +61,14 @@ class Stop extends Error {
     rule;
     schemaPath;
     payloadPath;
-    constructor(kind, rule, schemaPath, payloadPath) {
+    diagnostic;
+    constructor(kind, rule, schemaPath, payloadPath, diagnostic) {
         super(rule);
         this.kind = kind;
         this.rule = rule;
         this.schemaPath = schemaPath;
         this.payloadPath = payloadPath;
+        this.diagnostic = diagnostic;
     }
 }
 function run(contract, options, work) {
@@ -96,7 +99,7 @@ function runContext(context, options, work) {
             return { kind: 'resource-limit', rule: error.message, usage: budget.usage() };
         if (error instanceof Stop)
             return Object.freeze({ kind: error.kind, rule: error.rule, schemaPath: error.schemaPath,
-                payloadPath: error.payloadPath, usage: Object.freeze({ ...budget.usage() }) });
+                payloadPath: error.payloadPath, ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), usage: Object.freeze({ ...budget.usage() }) });
         if (error instanceof ApplicationGroupValueError)
             return Object.freeze({ kind: 'value-invalid', rule: error.message, usage: Object.freeze({ ...budget.usage() }) });
         throw error;
@@ -192,8 +195,9 @@ export function inspectComponentValueMapping(value, contract) {
 }
 function scalar(duty, s, context) {
     const { budget, check } = s;
-    const fail = (_owner, rule) => { throw new Stop('scalar-invalid', rule, duty.schemaPath, duty.payloadPath); };
-    const unavailable = () => { throw new Stop('unsupported', 'direct-datatype-prerequisite', duty.schemaPath, duty.payloadPath); };
+    const diagnostic = () => createPayloadDiagnostic(context, duty.declaration, duty.knownLocation ?? '/' + diagnosticName(duty.declaration.name), { builtin: duty.builtin });
+    const fail = (_owner, rule) => { throw new Stop('scalar-invalid', rule, duty.schemaPath, duty.payloadPath, diagnostic()); };
+    const unavailable = () => { throw new Stop('unsupported', 'direct-datatype-prerequisite', duty.schemaPath, duty.payloadPath, diagnostic()); };
     // This is a neutral lexical operand, not a schema LexicalValue or checked receipt.
     const core = datatypeValues({
         step: (_owner, count = 1) => { check(); budget.chargeWork(count); },
@@ -208,11 +212,11 @@ function scalar(duty, s, context) {
         const assessed = assessProjectionScalarOperand(context, duty.declaration, lexical, check);
         check();
         if (assessed.kind !== 'projection-scalar-operand')
-            throw new Stop(assessed.kind === 'scalar-invalid' ? 'scalar-invalid' : assessed.kind === 'resource-limit' ? 'resource-limit' : 'unsupported', 'rule' in assessed ? assessed.rule : 'request-budget', duty.schemaPath, duty.payloadPath);
+            throw new Stop(assessed.kind === 'scalar-invalid' ? 'scalar-invalid' : assessed.kind === 'resource-limit' ? 'resource-limit' : 'unsupported', 'rule' in assessed ? assessed.rule : 'request-budget', duty.schemaPath, duty.payloadPath, diagnostic());
         result = assessed.operand;
     }
     if (duty.fixedCanonical !== undefined && budget.compareText(result.canonical, duty.fixedCanonical) !== 0)
-        throw new Stop('scalar-invalid', duty.declaration.kind === 'attribute' ? 'fixed-attribute-value' : 'fixed-element-value', duty.schemaPath, duty.payloadPath);
+        throw new Stop('scalar-invalid', duty.declaration.kind === 'attribute' ? 'fixed-attribute-value' : 'fixed-element-value', duty.schemaPath, duty.payloadPath, diagnostic());
     const normalized = result.normalized ?? normalizeWhitespace(duty.lexical, whitespaceFor(duty.builtin.local));
     const present = (operand, builtin, lexical, retainLexical) => {
         check();
@@ -1097,14 +1101,14 @@ export function expandProjectionValue(context, root, application, options = {},
         if (structural.kind !== 'projection-match') {
             if (structural.kind === 'mismatch') {
                 if (structural.rule === 'ordered-particle-language')
-                    throw new Stop('value-invalid', structural.rule, structural.schemaPath, structural.payloadPath);
+                    throw new Stop('value-invalid', structural.rule, structural.schemaPath, structural.payloadPath, structural.diagnostic);
                 throw new Error('Internal projection expansion violated its source mapping');
             }
-            throw new Stop(structural.kind, structural.rule, structural.schemaPath, structural.payloadPath);
+            throw new Stop(structural.kind, structural.rule, structural.schemaPath, structural.payloadPath, structural.diagnostic);
         }
         const validated = assessProjectionScalars(context, structural, options, mapping);
         if (validated.kind !== 'projection-value')
-            throw new Stop(validated.kind, validated.rule, validated.schemaPath, validated.payloadPath);
+            throw new Stop(validated.kind, validated.rule, validated.schemaPath, validated.payloadPath, validated.diagnostic);
         const expanded = s.publish({ kind: 'projection-expanded', provenance: 'generated-direct-value', admitted: false, payload, validated });
         projectionExpansions.set(expanded, context);
         return expanded;
@@ -1122,7 +1126,7 @@ export function expandDirectValue(contract, suppliedMapping, application, option
         if (structural.kind !== 'structural-match') {
             if (structural.kind === 'mismatch')
                 throw new Error('Internal direct expansion violated its source mapping');
-            throw new Stop(structural.kind, structural.rule, structural.schemaPath, structural.payloadPath);
+            throw new Stop(structural.kind, structural.rule, structural.schemaPath, structural.payloadPath, structural.diagnostic);
         }
         const validated = assessed(contract, structural, mapping, s);
         const expanded = s.publish({ kind: 'direct-expanded', provenance: 'generated-direct-value', admitted: false, payload, validated });