@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/dist/compiler/componentRecordProjection.js

@@ -0,0 +1,329 @@
+/** Explicit buffered companion-record projection; wrapper and record source contexts never merge. */
+import { inspectDirectOperation } from './directOperation.js';
+import { createComponentValueMapping, inspectComponentValueMapping, expandProjectionValue } from './directValues.js';
+import { observeComponentXml, assertComponentObservedPayload, assessObservedComponentPayload } from './directCodec.js';
+import { deriveActualComplexContent } from './complexTypeContent.js';
+import { prepareSemanticParticleView } from './particleSemanticView.js';
+import { checkDeclaredParticleLegality } from './particleLocalAssessment.js';
+import { assessSourceAttributeUses } from './schemaAttributeUses.js';
+import { assessStandardSchemaElement } from './standardSchemaComponents.js';
+import { namespaceAllows } from './wildcardAlgebra.js';
+import { directDataOwnership } from './directExecutionPolicy.js';
+import { DataOwnershipLimitError } from './dataOwnership.js';
+import { isXmlNCName, syntaxElements } from '../loader/orderedSyntax.js';
+const issued = new WeakMap();
+const values = new WeakMap();
+/** Identity-only dispatch; inspecting an unowned object's fields cannot select this mapping profile. */
+export function isComponentRecordProjection(value) {
+    return !!value && typeof value === 'object' && issued.has(value);
+}
+class ScopeStop extends Error {
+    kind;
+    rule;
+    constructor(kind, rule) {
+        super(rule);
+        this.kind = kind;
+        this.rule = rule;
+    }
+}
+const same = (a, b) => a.namespace === b.namespace && a.local === b.local;
+const ownKeys = (value, keys) => Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+/** Build an explicit mapping from independently qualified native contracts.
+ * @remarks The current wrapper family is a unit sequence of fixed standard metadata elements and one strict
+ *   wildcard. Native occurrence/EDC/UPA checks remain authoritative. The complete companion payload is retained;
+ *   record paths establish intended record declarations, not permission to discard other payload fields.
+ *   This is a buffered projection, not full-response XSD validation in a merged declaration universe or streaming.
+ * @returns An exact native projection or a specific unsupported/value/resource/cancellation result.
+ */
+export function createComponentRecordProjection(outer, companion, supplied, options = {}) {
+    const { context } = inspectDirectOperation(outer);
+    inspectDirectOperation(companion);
+    const { budget } = context;
+    const check = () => { budget.chargeWork(); if (options.signal?.aborted)
+        throw new ScopeStop('cancelled', 'cooperative-cancellation'); };
+    const stop = rule => { throw new ScopeStop('unsupported', rule); };
+    const failure = (kind, rule) => Object.freeze({ kind, rule, usage: Object.freeze({ ...budget.usage() }) });
+    try {
+        const result = budget.guard(() => {
+            check();
+            if ('parts' in outer.output || 'parts' in companion.output)
+                return failure('unsupported', 'record-projection-requires-document-output');
+            if (outer.basis !== 'native-component-premises-v1' || companion.basis !== 'native-component-premises-v1'
+                || outer.correspondence !== 'dated-XSD-2004-components-v1' || companion.correspondence !== 'dated-XSD-2004-components-v1')
+                stop('component-record-source-authority');
+            const requested = directDataOwnership(budget).freeze(directDataOwnership(budget).snapshot(supplied, check));
+            const association = requested && typeof requested === 'object' && !Object.hasOwn(requested, 'version');
+            if (association && (requested.scope !== 'records-with-declared-wrapper-scope'
+                || !ownKeys(requested, Object.hasOwn(requested, 'recordPath') ? ['scope', 'recordPath'] : ['scope'])))
+                throw new ScopeStop('value-invalid', 'explicit-component-record-scope');
+            let spec = association ? { version: 'component-record-scope-v1', scope: requested.scope,
+                payloadPath: [companion.output.element.name], recordPath: requested.recordPath ?? [], opaqueExclusions: [] } : requested;
+            const validName = (name) => name && typeof name === 'object' && ownKeys(name, ['namespace', 'local'])
+                && typeof name.namespace === 'string' && typeof name.local === 'string' && isXmlNCName(name.local);
+            const path = (names) => Array.isArray(names) && names.length > 0 && names.every(validName);
+            if (!spec || typeof spec !== 'object' || !ownKeys(spec, ['version', 'scope', 'payloadPath', 'recordPath', 'opaqueExclusions'])
+                || spec.version !== 'component-record-scope-v1' || spec.scope !== 'records-with-declared-wrapper-scope'
+                || !path(spec.payloadPath) || spec.payloadPath.length !== 1 || !(association && !Object.hasOwn(requested, 'recordPath') || path(spec.recordPath))
+                || !Array.isArray(spec.opaqueExclusions) || !spec.opaqueExclusions.every(item => item && typeof item === 'object'
+                && ownKeys(item, ['path', 'reason']) && path(item.path) && item.path.length === 1
+                && ['standard-schema-metadata', 'wrapper-declaration-universe'].includes(item.reason)))
+                throw new ScopeStop('value-invalid', 'explicit-component-record-scope');
+            if (!same(spec.payloadPath[0], companion.output.element.name))
+                stop('companion-output-payload-path');
+            const parser = createComponentValueMapping(outer, { kind: 'input' }, options);
+            if (parser.kind !== 'component-mapping')
+                return parser;
+            const mapping = createComponentValueMapping(companion, { kind: 'output' }, options);
+            if (mapping.kind !== 'component-mapping')
+                return mapping;
+            const projection = inspectComponentValueMapping(mapping, companion).projection;
+            if (!projection)
+                return failure('unsupported', 'record-projection-requires-document-mapping');
+            const records = new Map(projection.records.map(record => [record.type.id, record]));
+            if (association && !Object.hasOwn(requested, 'recordPath')) {
+                const candidates = [];
+                let recursive = false;
+                const pending = [
+                    { value: projection.root, prefix: [], ancestors: new Set() },
+                ];
+                while (pending.length) {
+                    check();
+                    const { value, prefix, ancestors } = pending.pop();
+                    if (value.kind !== 'record')
+                        continue;
+                    if (ancestors.has(value.type)) {
+                        recursive = true;
+                        continue;
+                    }
+                    const record = records.get(value.type);
+                    if (!record)
+                        stop('record-path-native-record');
+                    const next = new Set(ancestors);
+                    next.add(value.type);
+                    for (const slot of record.slots) {
+                        check();
+                        const path = [...prefix, slot.element.name];
+                        if (slot.value.kind === 'record' && slot.particle.occurs.max !== '1')
+                            candidates.push(path);
+                        pending.push({ value: slot.value, prefix: path, ancestors: next });
+                    }
+                }
+                if (!recursive && !candidates.length)
+                    stop('record-path-complex-repeated-declaration');
+                if (recursive || candidates.length !== 1)
+                    stop(`ambiguous-record-path: supply recordPath selecting one repeated complex declaration; candidates=${JSON.stringify(candidates)}; recursive=${recursive}`);
+                spec = { ...spec, recordPath: candidates[0] };
+            }
+            let value = projection.root;
+            for (let index = 0; index < spec.recordPath.length; index++) {
+                check();
+                if (value.kind !== 'record')
+                    stop('record-path-record-parent');
+                const record = records.get(value.type);
+                if (!record)
+                    stop('record-path-native-record');
+                const slots = record.slots.filter(slot => { check(); return same(slot.element.name, spec.recordPath[index]); });
+                if (slots.length !== 1)
+                    stop('record-path-unique-declaration');
+                value = slots[0].value;
+                if (index === spec.recordPath.length - 1 && (value.kind !== 'record' || slots[0].particle.occurs.max === '1'))
+                    stop('record-path-complex-repeated-declaration');
+            }
+            const root = outer.output.element;
+            if (root.nillable || root.abstract || root.value || root.substitutionGroup)
+                stop('record-wrapper-declaration');
+            const type = context.resolve(root.type);
+            if (type.kind !== 'found' || type.node.kind !== 'complexType' || type.node.abstract || type.node.mixed)
+                stop('record-wrapper-complex-type');
+            const attributes = assessSourceAttributeUses(context, type.node.id);
+            if (attributes.kind === 'resource-limit')
+                return failure('resource-limit', 'record-wrapper-attributes');
+            if (attributes.kind !== 'checked' || attributes.value.wildcard || attributes.value.attributes.length)
+                stop('record-wrapper-attribute-scope');
+            const content = deriveActualComplexContent(context, type.node.id);
+            if (content.kind === 'resource-limit')
+                return failure('resource-limit', 'record-wrapper-content');
+            if (content.kind !== 'checked' || content.view.content.kind !== 'element-only')
+                stop('record-wrapper-content');
+            const prepared = prepareSemanticParticleView(context, content.view, 'declared');
+            if (prepared.kind === 'resource-limit')
+                return failure('resource-limit', 'record-wrapper-particle');
+            if (prepared.kind !== 'checked')
+                stop('record-wrapper-particle');
+            const legal = checkDeclaredParticleLegality(context, prepared.view);
+            if (legal.kind === 'resource-limit')
+                return failure('resource-limit', 'record-wrapper-particle-legality');
+            if (legal.kind !== 'checked' || !legal.value)
+                stop('record-wrapper-particle-legality');
+            const leaves = [], pending = [prepared.view.root];
+            let boundaries = 0;
+            while (pending.length) {
+                check();
+                const particle = pending.pop();
+                if (particle.occurs.min !== '1' || particle.occurs.max !== '1')
+                    stop('record-wrapper-unit-occurrence');
+                if (particle.kind === 'sequence')
+                    for (let index = particle.children.length - 1; index >= 0; index--) {
+                        check();
+                        pending.push(particle.children[index]);
+                    }
+                else if (particle.standardElement)
+                    leaves.push(Object.freeze({ kind: 'standard', declaration: particle.standardElement }));
+                else if (particle.kind === 'any' && particle.wildcard?.processContents === 'strict') {
+                    if (++boundaries > 1 || !namespaceAllows(particle.wildcard.namespace, spec.payloadPath[0].namespace, budget.chargeWork))
+                        stop('record-wrapper-wildcard-boundary');
+                    leaves.push(Object.freeze({ kind: 'boundary', namespace: particle.wildcard.namespace }));
+                }
+                else
+                    stop('record-wrapper-terminal-scope');
+            }
+            if (boundaries !== 1)
+                stop('record-wrapper-one-boundary');
+            const metadata = leaves.filter((leaf) => leaf.kind === 'standard');
+            if (association)
+                spec = { ...spec, opaqueExclusions: [
+                        ...metadata.map(leaf => ({ path: [leaf.declaration.name], reason: 'standard-schema-metadata' })),
+                        { path: spec.payloadPath, reason: 'wrapper-declaration-universe' },
+                    ] };
+            const exclusions = spec.opaqueExclusions.filter(item => item.reason === 'standard-schema-metadata');
+            const universes = spec.opaqueExclusions.filter(item => item.reason === 'wrapper-declaration-universe');
+            if (metadata.length !== exclusions.length || metadata.some(leaf => exclusions.filter(item => same(item.path[0], leaf.declaration.name)).length !== 1)
+                || universes.length !== 1 || !same(universes[0].path[0], spec.payloadPath[0]))
+                stop('record-wrapper-explicit-exclusions');
+            check();
+            const result = Object.freeze({ kind: 'component-record-projection', version: 'component-record-scope-v1',
+                direction: Object.freeze({ kind: 'output' }), root: outer.output, contextId: outer.contextId, admitted: false, spec: directDataOwnership(budget).freeze(spec),
+                usage: Object.freeze({ ...budget.usage() }) });
+            issued.set(result, Object.freeze({ outer, companion, parser, mapping, leaves: Object.freeze(leaves) }));
+            return result;
+        });
+        return result.kind === 'resource-limit' && !('rule' in result) ? failure('resource-limit', 'record-projection-budget') : result;
+    }
+    catch (error) {
+        if (budget.exhausted())
+            return failure('resource-limit', 'record-projection-budget');
+        if (error instanceof DataOwnershipLimitError)
+            return failure('resource-limit', error.message);
+        if (error instanceof ScopeStop)
+            return failure(error.kind, error.rule);
+        throw error;
+    }
+}
+/** Native projection identity and exact outer contract are checked before reading projection fields. */
+export function inspectComponentRecordProjection(projection, outer) {
+    const owned = issued.get(projection);
+    if (!owned || outer !== undefined && owned.outer !== outer)
+        throw new TypeError('Native matching component record projection required');
+    inspectDirectOperation(owned.outer);
+    inspectDirectOperation(owned.companion);
+    return owned;
+}
+export function inspectComponentRecordValue(value, projection) {
+    inspectComponentRecordProjection(projection);
+    if (values.get(value) !== projection)
+        throw new TypeError('Native matching component record value required');
+    return value;
+}
+/** Revalidate the projected application value, including after JSON serialization.
+ * @remarks This uses the exact companion's existing inverse and scalar/structure owners. It establishes only
+ *   projected-value validity; it cannot reconstruct or certify omitted wrapper metadata or SOAP protocol state.
+ */
+export function validateComponentRecordApplication(projection, application, options = {}) {
+    const owned = inspectComponentRecordProjection(projection), { context } = inspectDirectOperation(owned.companion);
+    if ('parts' in owned.mapping.root)
+        throw new TypeError('Record projection requires a document mapping');
+    return expandProjectionValue(context, owned.mapping.root.element, application, options);
+}
+/** Decode once and validate the declared wrapper plus its explicitly selected companion payload.
+ * @remarks The complete companion value survives; only declared standard metadata is omitted. This function
+ *   does not validate SOAP protocol grammar itself. Its protocol selector can choose only this projection or
+ *   an actual declared fault mapping of the outer contract, always on nodes from the same parse.
+ */
+export function decodeComponentRecordXml(outer, projection, bytes, options = {}) {
+    const owned = inspectComponentRecordProjection(projection, outer), { context } = inspectDirectOperation(outer), { budget } = context;
+    const check = () => { budget.chargeWork(); if (options.signal?.aborted)
+        throw new ScopeStop('cancelled', 'cooperative-cancellation'); };
+    const failure = (kind, rule) => Object.freeze({ kind, rule, usage: Object.freeze({ ...budget.usage() }) });
+    try {
+        const result = budget.guard(() => {
+            check();
+            const observation = observeComponentXml(outer, owned.parser, bytes, options);
+            if (observation.kind !== 'observed-component-xml')
+                return observation;
+            const selected = options.selectPayload?.(observation.root) ?? { payload: observation.root, mapping: projection };
+            assertComponentObservedPayload(observation, selected.payload, check);
+            if (selected.mapping !== projection) {
+                const { mapping } = inspectComponentValueMapping(selected.mapping, outer);
+                if (mapping.direction.kind !== 'fault')
+                    throw new TypeError('Record projection selection requires this output or a declared fault');
+                return assessObservedComponentPayload(outer, mapping, observation, selected.payload, options);
+            }
+            const wrapper = selected.payload;
+            if ('parts' in outer.output)
+                throw new ScopeStop('unsupported', 'record-projection-requires-document-output');
+            if (!same(wrapper.name, outer.output.element.name))
+                throw new ScopeStop('mismatch', 'record-wrapper-root');
+            if (wrapper.attributes.length || wrapper.children.some(node => node.kind === 'text' && /[^\t\r\n ]/.test(node.value)))
+                throw new ScopeStop('mismatch', 'record-wrapper-attributes-or-text');
+            const children = syntaxElements(wrapper);
+            if (children.length !== owned.leaves.length)
+                throw new ScopeStop('mismatch', 'record-wrapper-child-count');
+            let payload;
+            for (let index = 0; index < owned.leaves.length; index++) {
+                check();
+                const leaf = owned.leaves[index], child = children[index];
+                if (leaf.kind === 'standard') {
+                    if (!same(child.name, leaf.declaration.name))
+                        throw new ScopeStop('mismatch', 'record-wrapper-standard-order');
+                    const assessed = assessStandardSchemaElement(leaf.declaration, child, budget, { signal: options.signal, check });
+                    if (assessed.kind !== 'schema-element-instance')
+                        return failure(assessed.kind, assessed.kind === 'resource-limit' ? 'record-standard-budget' : assessed.rule);
+                    if (assessed.remaining.length)
+                        throw new ScopeStop('unsupported', 'record-standard-instance-obligations');
+                }
+                else {
+                    if (!same(child.name, projection.spec.payloadPath[0]) || !namespaceAllows(leaf.namespace, child.name.namespace, budget.chargeWork))
+                        throw new ScopeStop('mismatch', 'record-wrapper-companion-boundary');
+                    payload = child;
+                }
+            }
+            if (!payload)
+                throw new TypeError('Native record boundary unavailable');
+            const decoded = assessObservedComponentPayload(owned.companion, owned.mapping, observation, payload, options);
+            if (decoded.kind !== 'component-decoded')
+                return decoded;
+            if (decoded.validated.kind !== 'projection-value')
+                throw new TypeError('Record projection requires a document value receipt');
+            const recordCount = countRecords(observation, payload, projection.spec.recordPath, check);
+            const validated = Object.freeze({ kind: 'component-record-value', scope: 'records-with-declared-wrapper-scope',
+                admitted: false, value: decoded.validated.value, recordCount, companion: decoded.validated });
+            values.set(validated, projection);
+            check();
+            return Object.freeze({ kind: 'component-record-decoded', admitted: false, payload: wrapper, mapping: projection,
+                validated, usage: Object.freeze({ ...budget.usage() }) });
+        });
+        return result.kind === 'resource-limit' && !('rule' in result) ? failure('resource-limit', 'record-projection-budget') : result;
+    }
+    catch (error) {
+        if (budget.exhausted())
+            return failure('resource-limit', 'record-projection-budget');
+        if (error instanceof ScopeStop)
+            return failure(error.kind, error.rule);
+        throw error;
+    }
+}
+function countRecords(observation, payload, path, check) {
+    assertComponentObservedPayload(observation, payload, check);
+    let current = [payload];
+    for (const name of path) {
+        const next = [];
+        for (const parent of current)
+            for (const child of syntaxElements(parent)) {
+                check();
+                if (same(child.name, name))
+                    next.push(child);
+            }
+        current = next;
+    }
+    return current.length;
+}

package/dist/compiler/componentSoapPreparation.d.ts

@@ -0,0 +1,20 @@
+import type { DirectOperationContract } from './directOperation.js';
+import type { ExpandedName } from '../loader/orderedSyntax.js';
+/** Own closed metadata for one invocation; runtime reconstruction never consumes this object.
+ * @since 1.1.7
+ * @constraints Every action and selection is checked against authentic native source before reuse.
+ */
+export declare class ComponentSoapPreparation {
+    #private;
+    /** Prepare one source/service/binding within this invocation.
+     * @param contract Fresh native operation identity.
+     * @param selection Service/port choice checked before reuse.
+     * @param check Cancellation and resource checks owned by this invocation.
+     * @returns Resolves after closed metadata preparation; dependency objects remain private.
+     * @throws For foreign handles, unsupported selection, cancellation or bootstrap failures.
+     */
+    prepare(contract: DirectOperationContract, selection: {
+        service: ExpandedName;
+        port: string;
+    }, check: () => void): Promise<void>;
+}

package/dist/compiler/componentSoapPreparation.js

@@ -0,0 +1,36 @@
+/** Invocation-local SOAP preparation ownership without exposing dependency metadata types.
+ * @since 1.1.7
+ */
+import { inspectDirectOperation } from './directOperation.js';
+import { prepareComponentSoapWsdl, validateComponentSoapSelection } from './directSoapSource.js';
+/** Own closed metadata for one invocation; runtime reconstruction never consumes this object.
+ * @since 1.1.7
+ * @constraints Every action and selection is checked against authentic native source before reuse.
+ */
+export class ComponentSoapPreparation {
+    #sources = new WeakMap();
+    /** Prepare one source/service/binding within this invocation.
+     * @param contract Fresh native operation identity.
+     * @param selection Service/port choice checked before reuse.
+     * @param check Cancellation and resource checks owned by this invocation.
+     * @returns Resolves after closed metadata preparation; dependency objects remain private.
+     * @throws For foreign handles, unsupported selection, cancellation or bootstrap failures.
+     */
+    async prepare(contract, selection, check) {
+        const { source } = inspectDirectOperation(contract);
+        validateComponentSoapSelection(contract, selection, check);
+        const key = JSON.stringify([selection.service, selection.port, contract.selector.binding]);
+        let entries = this.#sources.get(source);
+        if (!entries) {
+            entries = new Map();
+            this.#sources.set(source, entries);
+        }
+        let prepared = entries.get(key);
+        if (!prepared) {
+            prepared = prepareComponentSoapWsdl(contract, selection, check);
+            entries.set(key, prepared);
+        }
+        await prepared;
+        check();
+    }
+}

package/dist/compiler/composeCanonicalGraph.d.ts

@@ -66,4 +66,3 @@ export declare function extendContent(base: readonly ContentContribution[], loca
 /** Restriction replaces child content, including the empty case. No removed base particle is appended. */
 export declare function restrictContent(local: NodeId | undefined): readonly ContentContribution[];
 export declare function composeCanonicalGraph(resolved: ResolvedGraph, limits?: SemanticLimits): ComposedGraph;
-//# sourceMappingURL=composeCanonicalGraph.d.ts.map

package/dist/compiler/dataOwnership.d.ts

@@ -19,4 +19,3 @@ export declare const dataOwnership: Readonly<{
     snapshot: <T>(value: T, check?: () => void) => T;
     freeze: <T>(value: T) => Readonly<T>;
 }>;
-//# sourceMappingURL=dataOwnership.d.ts.map

package/dist/compiler/dataOwnership.js

@@ -4,6 +4,8 @@ export class DataOwnershipLimitError extends RangeError {
 }
 export const DIRECT_METADATA_LIMITS = Object.freeze({ maxEntries: 100_000, maxText: 1024 * 1024, maxDepth: 256 });
 export function createDataOwnership(chargeWork, limits) {
+    // @why Canonical preparation revisits shared immutable source subtrees; only this owner's completed traversals are reusable.
+    const frozen = new WeakSet();
     function arrayIndex(index) {
         // Array positions are bounded by JavaScript's array length, so this is a
         // constant-size numeric decision, followed by a precharged text conversion.
@@ -119,6 +121,9 @@ export function createDataOwnership(chargeWork, limits) {
             chargeWork(); // Set read.
             if (seen.has(current))
                 continue;
+            chargeWork();
+            if (frozen.has(current))
+                continue;
             chargeWork(2); // Visit-state insertion and freeze traversal.
             seen.add(current);
             chargeWork(); // Array classification.
@@ -136,12 +141,11 @@ export function createDataOwnership(chargeWork, limits) {
             }
             else {
                 for (const key in current) {
-                    chargeWork(); // Own-field introspection.
-                    if (!Object.hasOwn(current, key))
-                        continue;
                     chargeWork(43 + key.length); // Descriptor, field access, name inspection and push.
                     const descriptor = Object.getOwnPropertyDescriptor(current, key);
-                    if (descriptor === undefined || !('value' in descriptor)) {
+                    if (descriptor === undefined)
+                        continue;
+                    if (!('value' in descriptor)) {
                         throw new TypeError('RE01 records require data fields');
                     }
                     stack.push(descriptor.value);
@@ -149,6 +153,12 @@ export function createDataOwnership(chargeWork, limits) {
             }
             Object.freeze(current);
         }
+        // @constraints A shallow external freeze or interrupted traversal supplies no reusable deep-freeze evidence.
+        for (const current of seen) {
+            chargeWork(2);
+            if (!types.isProxy(current))
+                frozen.add(current);
+        }
         return value;
     }
     return { snapshot, freeze };

package/dist/compiler/datatypeValues.d.ts

@@ -44,4 +44,3 @@ export declare function datatypeValues<Owner>(c: DatatypeValueContext<Owner>): {
     sameValue: (a: DatatypeOperand, b: DatatypeOperand, owner: Owner) => boolean;
     compare: (a: DatatypeOperand, b: DatatypeOperand, owner: Owner) => number | undefined;
 };
-//# sourceMappingURL=datatypeValues.d.ts.map

package/dist/compiler/declarationIdentity.d.ts

@@ -0,0 +1,22 @@
+export type NodeId = string;
+export type SymbolRole = "element" | "attribute" | "type" | "group" | "attributeGroup" | "message" | "portType" | "binding" | "service";
+export type Identity = Readonly<{
+    kind: "global";
+    role: SymbolRole;
+    name: Readonly<{
+        namespace: string;
+        local: string;
+    }>;
+} | {
+    kind: "scoped";
+    owner: NodeId;
+    path: string;
+    role: string;
+}>;
+/** Encode XML symbol identity independently of source location and emitted language names. */
+export declare function globalId(role: SymbolRole, name: Readonly<{
+    namespace: string;
+    local: string;
+}>): NodeId;
+/** Encode a declaration within its owner's scope using the caller's structural path convention. */
+export declare function scopedId(owner: NodeId, path: string, role: string): NodeId;

package/dist/compiler/declarationIdentity.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+/** Encode XML symbol identity independently of source location and emitted language names. */
+export function globalId(role, name) {
+    return JSON.stringify(["global", role, name.namespace, name.local]);
+}
+/** Encode a declaration within its owner's scope using the caller's structural path convention. */
+export function scopedId(owner, path, role) {
+    return "scoped:" + createHash("sha256").update(JSON.stringify([owner, path, role])).digest("hex");
+}

package/dist/compiler/directCodec.d.ts

@@ -1,7 +1,8 @@
 import type { DirectOperationContract } from './directOperation.js';
-import type { DirectValueMapping, DirectValueReceipt, DirectValueFailure, DirectExpandedValue } from './directValues.js';
+import type { DirectValueMapping, DirectValueReceipt, DirectValueFailure, DirectExpandedValue, ComponentValueMapping, ProjectionExpandedValue, ProjectionValueReceipt } from './directValues.js';
 import type { SyntaxElement, SyntaxSource } from '../loader/orderedSyntax.js';
 import type { ResolverUsage } from './semanticBudget.js';
+import type { RpcTypedValue } from './rpcTypedValues.js';
 export interface DirectXmlLimits {
     readonly maxBytes?: number;
     readonly maxDepth?: number;
@@ -48,12 +49,88 @@ export interface DirectDecodedXml {
     readonly validated: DirectValueReceipt;
     readonly usage: ResolverUsage;
 }
+export interface ComponentEncodedXml {
+    readonly kind: 'component-encoded';
+    readonly admitted: false;
+    readonly encoding: 'utf-8';
+    readonly bytes: Uint8Array;
+    readonly expanded: ProjectionExpandedValue | RpcExpandedValue;
+    readonly mapping: ComponentValueMapping;
+    readonly usage: ResolverUsage;
+}
+export interface ComponentDecodedXml {
+    readonly kind: 'component-decoded';
+    readonly admitted: false;
+    readonly payload: SyntaxElement;
+    readonly validated: ProjectionValueReceipt | RpcValueReceipt;
+    readonly mapping: ComponentValueMapping;
+    readonly usage: ResolverUsage;
+}
+export interface RpcValueReceipt {
+    readonly kind: 'rpc-string-value' | 'rpc-typed-value';
+    readonly admitted: false;
+    readonly value: RpcTypedValue;
+    readonly usage: ResolverUsage;
+}
+export interface RpcExpandedValue {
+    readonly kind: 'rpc-string-expanded' | 'rpc-typed-expanded';
+    readonly admitted: false;
+    readonly payload: SyntaxElement;
+    readonly validated: RpcValueReceipt;
+    readonly usage: ResolverUsage;
+}
+export interface ComponentPayloadSelection {
+    readonly payload: SyntaxElement;
+    readonly mapping: ComponentValueMapping;
+}
+/** Parser ownership only; neither the observation nor its displayed fields establish value or operation validity. */
+export interface ComponentXmlObservation {
+    readonly kind: 'observed-component-xml';
+    readonly root: SyntaxElement;
+    readonly usage: ResolverUsage;
+}
 /** Validate fresh values using the delivered inverse, then emit deterministic UTF-8. */
 export declare function encodeDirectXml(contract: DirectOperationContract, mapping: unknown, application: unknown, options?: Options): DirectEncodedXml | DirectCodecFailure;
+/** Encode a component-qualified structured operation direction through the same native inverse and XML writer.
+ * @remarks Mapping/source authority is checked before values. This supplies XML bytes only, not policy enforcement or dispatch.
+ * @returns Native-validated UTF-8 output or explicit scalar/value/unsupported/cancellation/resource failure.
+ */
+export declare function encodeComponentXml(contract: DirectOperationContract, mapping: unknown, application: unknown, options?: Options): ComponentEncodedXml | DirectCodecFailure;
+/** Observe once through the existing component parser and execution controls.
+ * @remarks Any exact operation-owned mapping can bind parsing to its execution context. Its value/root is not
+ *   assessed here. Source qualification, wrapper scope and selected payload validation remain separate owners.
+ */
+export declare function observeComponentXml(contract: DirectOperationContract, mapping: unknown, bytes: Uint8Array, options?: Options & Readonly<{
+    uri?: string;
+    componentResponseEncoding?: {
+        charset?: string;
+    };
+}>): ComponentXmlObservation | DirectCodecFailure;
+/** Validate a genuine observed subtree through an independently qualified component mapping.
+ * @remarks XML capacities belong to the observation episode. This entry assesses the selected mapping's
+ *   structure and scalar duties; it does not assert cross-contract wrapper, SOAP or runtime authority.
+ * @throws TypeError For copied observations, foreign mappings or a node outside the observed document.
+ */
+export declare function assessObservedComponentPayload(contract: DirectOperationContract, mapping: unknown, observation: ComponentXmlObservation, payload: SyntaxElement, options?: Readonly<{
+    signal?: AbortSignal;
+}>): ComponentDecodedXml | DirectCodecFailure;
+/** Verify membership without conferring a selected mapping or wrapper validity. */
+export declare function assertComponentObservedPayload(observation: ComponentXmlObservation, payload: SyntaxElement, check: () => void): void;
 /** Bounded observed bytes -> ordered syntax -> existing structural/scalar checks. */
 export declare function decodeDirectXml(contract: DirectOperationContract, mapping: unknown, bytes: Uint8Array, options?: Options & Readonly<{
     uri?: string;
     selectPayload?: (root: SyntaxElement) => DirectPayloadSelection;
 }>): DirectDecodedXml | DirectCodecFailure;
+/** Decode observed component-profile bytes through the same parser and native structured/scalar owners.
+ * @remarks Protocol selection may choose only an actual node from this parse and an exact operation-owned mapping.
+ *   It cannot relabel a copied syntax tree, switch operations or acquire runtime/policy enforcement authority.
+ * @returns A native-validated structured value or explicit XML/structure/scalar/unsupported/resource failure.
+ */
+export declare function decodeComponentXml(contract: DirectOperationContract, mapping: unknown, bytes: Uint8Array, options?: Options & Readonly<{
+    uri?: string;
+    componentResponseEncoding?: {
+        charset?: string;
+    };
+    selectPayload?: (root: SyntaxElement) => ComponentPayloadSelection;
+}>): ComponentDecodedXml | DirectCodecFailure;
 export {};
-//# sourceMappingURL=directCodec.d.ts.map