@techspokes/typescript-wsdl-client 1.1.5 → 1.1.8

package/dist/compiler/directSourceCapsule.js

@@ -4,13 +4,20 @@ import { checkSemanticBudget } from './semanticBudget.js';
 import { DataOwnershipLimitError } from './dataOwnership.js';
 import { createHash } from 'node:crypto';
 import { types } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { canonicalJson, parseCatalogJson, CatalogError } from './catalogErrors.js';
 import { createApplicationBudget } from './semanticBudget.js';
-import { inspectDirectOperation, selectDirectOperationInRequest } from './directOperation.js';
-import { createDirectValueMapping, DIRECT_VALUE_VERSION, DIRECT_SCALAR_POLICY } from './directValues.js';
-import { prepareDirectSoapSource, DirectSoapSourceError, DIRECT_SOAP_SOURCE_MAX_BYTES } from './directSoapSource.js';
+import { inspectDirectOperation, selectDirectOperationInRequest, selectComponentOperationInRequest } from './directOperation.js';
+import { createDirectValueMapping, createComponentValueMapping, inspectComponentValueMapping, DIRECT_VALUE_VERSION, DIRECT_SCALAR_POLICY } from './directValues.js';
+import { prepareDirectSoapSource, prepareComponentSoapWsdl, DirectSoapSourceError, DIRECT_SOAP_SOURCE_MAX_BYTES } from './directSoapSource.js';
+import { ComponentSoapPreparation } from './componentSoapPreparation.js';
+import { copyOriginalSchemaResource } from '../loader/schemaInput.js';
 import { SchemaResourceLoader, resolveResourceUri } from '../loader/schemaResources.js';
 import { parseOrderedSyntax, syntaxElements, isXmlNCName, SchemaLoadingError } from '../loader/orderedSyntax.js';
+import { createComponentRecordProjection, inspectComponentRecordProjection } from './componentRecordProjection.js';
+import { acquireStandardSchemaLibrary, SCHEMA_ELEMENT_LIBRARY } from './standardSchemaComponents.js';
+import { parseApplicationGroups } from './applicationGroups.js';
 export const DIRECT_CAPSULE_LIMITS = Object.freeze({ maxBytes: 256 * 1024, sourceBytes: DIRECT_SOAP_SOURCE_MAX_BYTES });
 const versions = Object.freeze({ capsuleFormat: 1, model: 'xsd10-faithful-v1', scope: 'direct-soap11-single-utf8-v1',
     mapping: DIRECT_VALUE_VERSION, scalarPolicy: DIRECT_SCALAR_POLICY, runtimePolicy: 'owned-loopback-http-no-extensions-v1' });
@@ -52,7 +59,7 @@ function failure(error, budget) {
     }
     else
         throw error;
-    return Object.freeze({ kind, rule, repair: 'Regenerate matched internal direct artifacts from explicitly authorized original WSDL; public generation remains unavailable.', usage: Object.freeze({ ...budget.usage() }) });
+    return Object.freeze({ kind, rule, repair: 'Regenerate matched checked direct artifacts from explicitly authorized original WSDL using the checked-direct-v1 pipeline.', usage: Object.freeze({ ...budget.usage() }) });
 }
 function check(budget, signal) {
     checkSemanticBudget(budget);
@@ -111,7 +118,7 @@ export function readDirectSourceCapsule(bytes, budget, signal) {
         return failure(error, budget);
     }
 }
-function read(bytes, budget, signal) {
+function capsuleJson(bytes, budget, signal) {
     check(budget, signal);
     if (!types.isUint8Array(bytes) || types.isProxy(bytes))
         return reject('byte-input-required');
@@ -132,7 +139,10 @@ function read(bytes, budget, signal) {
     catch {
         return reject('capsule-utf8');
     }
-    const parsed = record(parseCatalogJson(decoded, { maxBytes: directLimit(budget, DIRECT_CAPSULE_LIMITS.maxBytes), maxDepth: 16 }), ['versions', 'source', 'compatibility', 'fingerprint']);
+    return parseCatalogJson(decoded, { maxBytes: directLimit(budget, DIRECT_CAPSULE_LIMITS.maxBytes), maxDepth: 16 });
+}
+function read(bytes, budget, signal) {
+    const parsed = record(capsuleJson(bytes, budget, signal), ['versions', 'source', 'compatibility', 'fingerprint']);
     const actual = record(parsed.versions, Object.keys(versions));
     for (const key of Object.keys(versions))
         if (actual[key] !== versions[key])
@@ -303,3 +313,415 @@ export function checkDirectSourceCompatibility(expected, contract, selection, si
         return failure(error, budget);
     }
 }
+const componentVersions = Object.freeze({ ...versions, scope: 'component-soap11-utf8-graph-v1', mapping: 'component-values-v1',
+    runtimePolicy: 'explicit-http-verified-https-transport-v1' });
+const scopedComponentVersions = Object.freeze({ ...componentVersions, scope: 'component-soap11-utf8-graph-v2', mapping: 'component-values-and-record-scope-v1' });
+const componentReconstructions = new WeakMap();
+function componentFailure(error, budget) {
+    return Object.freeze({ ...failure(error, budget), repair: 'Regenerate matched component artifacts from explicitly authorized original WSDL and dependencies.' });
+}
+// @constraints Retrieval keys are compared only; artifact paths never initiate I/O. Local relative imports can relocate together.
+function componentResourceKey(source, uri) {
+    if (uri === source.root.uri)
+        return 'root';
+    if (new URL(uri).protocol !== 'file:')
+        return 'uri:' + uri;
+    return 'file:' + path.relative(path.dirname(fileURLToPath(source.root.uri)), fileURLToPath(uri)).replaceAll('\\', '/');
+}
+function componentResources(contract, signal) {
+    const { source, context: { budget } } = inspectDirectOperation(contract);
+    const resources = source.resources.map(resource => {
+        check(budget, signal);
+        const bytes = copyOriginalSchemaResource(source, resource.uri, amount => { check(budget, signal); budget.chargeWork(amount); });
+        return { key: componentResourceKey(source, resource.uri), base64: Buffer.from(bytes).toString('base64'), digest: resource.digest };
+    }).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+    if (new Set(resources.map(resource => resource.key)).size !== resources.length)
+        throw new Stop('unsupported', 'ambiguous-resource-key');
+    return resources;
+}
+async function componentDescriptor(contract, selection, signal, responseProjection, preparation, applicationGroups) {
+    const { context: { budget }, source } = inspectDirectOperation(contract);
+    const tick = () => check(budget, signal);
+    tick();
+    if (contract.basis !== 'native-component-premises-v1' || contract.correspondence !== 'dated-XSD-2004-components-v1')
+        throw new Stop('unsupported', 'component-capsule-version');
+    const owned = directDataOwnership(budget).snapshot(selection, tick);
+    record(owned, ['service', 'port']);
+    name(owned.service);
+    ncname(owned.port);
+    if (preparation)
+        await ComponentSoapPreparation.prototype.prepare.call(preparation, contract, owned, tick);
+    else
+        await prepareComponentSoapWsdl(contract, owned, tick);
+    if (responseProjection)
+        inspectComponentRecordProjection(responseProjection, contract);
+    const mappings = [];
+    const make = (direction) => {
+        tick();
+        const mapping = direction.kind === 'output' && responseProjection ? responseProjection : createComponentValueMapping(contract, direction, { signal }, applicationGroups);
+        if (mapping.kind !== 'component-mapping' && mapping.kind !== 'component-record-projection')
+            throw new Stop(mapping.kind === 'resource-limit' || mapping.kind === 'cancelled' ? mapping.kind : 'unsupported', mapping.rule);
+        mappings.push(mapping);
+        return { element: mapping.root.element.name, message: mapping.root.message, part: mapping.root.part };
+    };
+    const input = make({ kind: 'input' }), output = make({ kind: 'output' });
+    const faults = contract.faults.map(fault => ({ name: fault.name, root: make({ kind: 'fault', name: fault.name }) }));
+    const compatibility = { selector: contract.selector, service: owned.service, port: owned.port,
+        action: contract.binding.action, input, output, faults };
+    let projection = null;
+    if (responseProjection) {
+        const { companion } = inspectComponentRecordProjection(responseProjection, contract);
+        const { context } = inspectDirectOperation(companion);
+        projection = { spec: responseProjection.spec, source: { selector: companion.selector, action: companion.binding.action,
+                output: { element: companion.output.element.name, message: companion.output.message, part: companion.output.part },
+                libraries: context.standardLibraryIds(), resources: componentResources(companion, signal) } };
+    }
+    const targets = new Set(mappings.flatMap(mapping => mapping.kind === 'component-mapping'
+        ? (inspectComponentValueMapping(mapping, contract).applicationGroups?.targets ?? []).map(target => target.target) : []));
+    const groups = applicationGroups ? parseApplicationGroups(applicationGroups) : undefined;
+    const groupPlans = mappings.flatMap(mapping => mapping.kind === 'component-mapping'
+        ? [inspectComponentValueMapping(mapping, contract).applicationGroups] : []);
+    const applicationGroupIdentity = groups ? hash(json({ version: 'application-groups-v1',
+        targets: [...new Map(groupPlans.flatMap(plan => plan.targets.map(target => [target.target, target]))).values()].sort((a, b) => a.target.localeCompare(b.target, 'en')),
+        records: [...new Map(groupPlans.flatMap(plan => plan.dispositions.map(record => [record.source, record]))).values()].sort((a, b) => a.source.localeCompare(b.source, 'en')) }, budget)) : undefined;
+    tick();
+    return { compatibility, resources: componentResources(contract, signal), mappings, libraries: inspectDirectOperation(contract).context.standardLibraryIds(), projection,
+        ...(groups ? { applicationGroups: groups.names === undefined ? {} : { names: groups.names.filter(item => targets.has(item.target)) }, applicationGroupIdentity } : {}) };
+}
+/** Serialize native component provenance as data; no source, mapping or execution authority is serialized.
+ * @returns Deterministic original resource bytes and compatibility description, or explicit refusal.
+ * @throws TypeError For foreign operation handles. Caller cancellation is returned as a refusal.
+ */
+export async function createComponentSourceCapsule(contract, selection, signal, responseProjection) {
+    const { budget } = inspectDirectOperation(contract).context;
+    try {
+        const { compatibility, resources, libraries, projection } = await componentDescriptor(contract, selection, signal, responseProjection);
+        const capsule = componentCapsule({ compatibility, resources, libraries, projection }, budget);
+        const serialized = json(capsule, budget) + '\n';
+        if (Buffer.byteLength(serialized) > directLimit(budget, DIRECT_CAPSULE_LIMITS.maxBytes))
+            throw new Stop('resource-limit', 'capsule-byte-limit');
+        check(budget, signal);
+        return Object.freeze({ kind: 'component-capsule', bytes: Buffer.from(serialized), admitted: false, usage: Object.freeze({ ...budget.usage() }) });
+    }
+    catch (error) {
+        if (!budget.exhausted() && signal?.aborted)
+            return componentFailure(new Stop('cancelled', 'cooperative-cancellation'), budget);
+        return componentFailure(error, budget);
+    }
+}
+function componentCapsule(derived, budget) {
+    const { compatibility, resources, libraries, projection } = derived;
+    const extended = libraries.length > 0 || projection !== null;
+    const value = { versions: extended ? scopedComponentVersions : componentVersions, resources, compatibility,
+        ...(extended ? { libraries, projection } : {}), ...(derived.applicationGroups ? { applicationGroups: derived.applicationGroups, applicationGroupIdentity: derived.applicationGroupIdentity } : {}) };
+    return { ...value, fingerprint: hash(json(value, budget)) };
+}
+/** Prepare a generator-owned operation once through the same native descriptor used by runtime reconstruction.
+ * @param contract Fresh source-owned operation, never a report or copied handle.
+ * @param selection Explicit resolved service and port.
+ * @param preparation Invocation-owned SOAP metadata reuse.
+ * @param signal Caller cancellation.
+ * @param responseProjection Optional native companion projection.
+ * @returns An authentic reconstruction retaining its exact issued capsule and mappings, or native refusal.
+ * @throws TypeError For foreign native operation identities.
+ * @constraints Runtime physical-source reconstruction is independent and unchanged.
+ */
+export async function prepareComponentSourceForOperation(contract, selection, preparation, signal, responseProjection, applicationGroups) {
+    const { budget } = inspectDirectOperation(contract).context;
+    try {
+        const derived = await componentDescriptor(contract, selection, signal, responseProjection, preparation, applicationGroups);
+        const capsule = componentCapsule(derived, budget);
+        if (Buffer.byteLength(json(capsule, budget) + '\n') > directLimit(budget, DIRECT_CAPSULE_LIMITS.maxBytes))
+            throw new Stop('resource-limit', 'capsule-byte-limit');
+        return issueComponentReconstruction(capsule, contract, derived, signal, responseProjection);
+    }
+    catch (error) {
+        if (!budget.exhausted() && signal?.aborted)
+            return componentFailure(new Stop('cancelled', 'cooperative-cancellation'), budget);
+        return componentFailure(error, budget);
+    }
+}
+/** Copy capsule data retained by an authentic reconstruction without repeating preparation.
+ * @param expected Fresh owned reconstruction.
+ * @param signal Caller cancellation.
+ * @returns Deterministic capsule bytes; the data grants no runtime authority.
+ * @throws TypeError For copied or foreign reconstruction identities; cancellation/resource failures propagate.
+ */
+export function componentSourceCapsuleBytes(expected, signal) {
+    inspectReconstructedComponentSource(expected);
+    const { budget } = inspectDirectOperation(expected.contract).context;
+    check(budget, signal);
+    return Buffer.from(json(componentReconstructions.get(expected), budget) + '\n');
+}
+function readComponent(bytes, budget, signal) {
+    const value = capsuleJson(bytes, budget, signal);
+    const extended = !!value && typeof value === 'object' && (Object.hasOwn(value, 'libraries') || Object.hasOwn(value, 'projection'));
+    const grouped = !!value && typeof value === 'object' && Object.hasOwn(value, 'applicationGroups');
+    const parsed = record(value, [...(extended ? ['versions', 'resources', 'compatibility', 'libraries', 'projection', 'fingerprint']
+            : ['versions', 'resources', 'compatibility', 'fingerprint']), ...(grouped ? ['applicationGroups', 'applicationGroupIdentity'] : [])]);
+    if (grouped) {
+        try {
+            parseApplicationGroups(parsed.applicationGroups);
+        }
+        catch {
+            reject('application-group-configuration');
+        }
+        text(parsed.applicationGroupIdentity);
+        if (!/^[a-f0-9]{64}$/.test(parsed.applicationGroupIdentity))
+            reject('application-group-identity');
+    }
+    const expectedVersions = extended ? scopedComponentVersions : componentVersions;
+    const actual = record(parsed.versions, Object.keys(expectedVersions));
+    for (const key of Object.keys(expectedVersions))
+        if (actual[key] !== expectedVersions[key])
+            reject('unsupported-version-mode-or-policy');
+    validateComponentResources(parsed.resources, budget, signal);
+    const root = (value) => { const r = record(value, ['element', 'message', 'part']); name(r.element); name(r.message); ncname(r.part); };
+    const selector = (value) => { const s = record(value, ['portType', 'binding', 'operation']); name(s.portType); name(s.binding); ncname(s.operation); };
+    if (extended) {
+        validateComponentLibraries(parsed.libraries);
+        if (parsed.projection !== null) {
+            const projection = record(parsed.projection, ['spec', 'source']);
+            const spec = record(projection.spec, ['version', 'scope', 'payloadPath', 'recordPath', 'opaqueExclusions']);
+            if (spec.version !== 'component-record-scope-v1' || spec.scope !== 'records-with-declared-wrapper-scope')
+                reject('unsupported-record-projection');
+            const path = (value) => { if (!Array.isArray(value) || !value.length)
+                reject('record-projection-path');
+            else
+                for (const entry of value) {
+                    check(budget, signal);
+                    name(entry);
+                } };
+            path(spec.payloadPath);
+            path(spec.recordPath);
+            if (!Array.isArray(spec.opaqueExclusions))
+                return reject('record-projection-exclusions');
+            for (const item of spec.opaqueExclusions) {
+                check(budget, signal);
+                const exclusion = record(item, ['path', 'reason']);
+                path(exclusion.path);
+                if (!['standard-schema-metadata', 'wrapper-declaration-universe'].includes(exclusion.reason))
+                    reject('record-projection-exclusion');
+            }
+            const source = record(projection.source, ['selector', 'action', 'output', 'libraries', 'resources']);
+            selector(source.selector);
+            text(source.action);
+            root(source.output);
+            validateComponentLibraries(source.libraries);
+            validateComponentResources(source.resources, budget, signal);
+        }
+        if (!parsed.libraries.length && parsed.projection === null)
+            reject('empty-component-extension');
+    }
+    const c = record(parsed.compatibility, ['selector', 'service', 'port', 'action', 'input', 'output', 'faults']);
+    selector(c.selector);
+    name(c.service);
+    ncname(c.port);
+    text(c.action);
+    root(c.input);
+    root(c.output);
+    if (!Array.isArray(c.faults))
+        return reject('faults-required');
+    const names = new Set();
+    for (const entry of c.faults) {
+        check(budget, signal);
+        const fault = record(entry, ['name', 'root']);
+        ncname(fault.name);
+        root(fault.root);
+        if (names.has(fault.name))
+            reject('duplicate-fault');
+        names.add(fault.name);
+    }
+    text(parsed.fingerprint);
+    if (hash(json({ versions: actual, resources: parsed.resources, compatibility: c,
+        ...(extended ? { libraries: parsed.libraries, projection: parsed.projection } : {}),
+        ...(grouped ? { applicationGroups: parsed.applicationGroups, applicationGroupIdentity: parsed.applicationGroupIdentity } : {}) }, budget)) !== parsed.fingerprint)
+        reject('compatibility-fingerprint');
+    check(budget, signal);
+    return directDataOwnership(budget).freeze(parsed);
+}
+function validateComponentLibraries(value) {
+    if (!Array.isArray(value))
+        return reject('component-libraries-required');
+    let previous = '';
+    for (const id of value) {
+        if (typeof id !== 'string' || id !== SCHEMA_ELEMENT_LIBRARY || id <= previous)
+            reject('supported-sorted-unique-libraries-required');
+        previous = id;
+    }
+}
+function validateComponentResources(value, budget, signal) {
+    if (!Array.isArray(value) || !value.length)
+        return reject('resources-required');
+    let previous = '';
+    for (const entry of value) {
+        check(budget, signal);
+        const resource = record(entry, ['key', 'base64', 'digest']);
+        text(resource.key);
+        text(resource.base64);
+        text(resource.digest);
+        if (resource.key <= previous)
+            reject('sorted-unique-resources-required');
+        previous = resource.key;
+        const original = Buffer.from(resource.base64, 'base64');
+        if (original.toString('base64') !== resource.base64 || hash(original) !== resource.digest)
+            reject('corrupt-source');
+    }
+    if (!value.some(resource => resource.key === 'root'))
+        reject('root-resource-required');
+}
+export async function reconstructComponentSourceCapsule(bytes, localSource, options) {
+    return reconstructComponentSourceCapsuleInRequest(bytes, localSource, options, createApplicationBudget(options.limits));
+}
+/** Private runtime seam retaining one sticky request for artifact reading, source qualification and exchange. */
+export async function reconstructComponentSourceCapsuleInRequest(bytes, localSource, options, budget) {
+    try {
+        const capsule = readComponent(bytes, budget, options.signal);
+        const allowed = directDataOwnership(budget).snapshot(options.standardLibraries ?? [], () => check(budget, options.signal));
+        if (!Array.isArray(allowed) || allowed.some(id => id !== SCHEMA_ELEMENT_LIBRARY) || new Set(allowed).size !== allowed.length)
+            throw new Stop('unsupported', 'explicit-standard-library-permissions');
+        const sources = directDataOwnership(budget).snapshot(options.recordSources ?? [], () => check(budget, options.signal));
+        if (!Array.isArray(sources))
+            throw new Stop('unsupported', 'explicit-record-source-permissions');
+        let recordSource;
+        const sourceKeys = new Set();
+        for (const entry of sources) {
+            check(budget, options.signal);
+            const supplied = record(entry, ['selector', 'source']);
+            text(supplied.source);
+            const selector = record(supplied.selector, ['portType', 'binding', 'operation']);
+            name(selector.portType);
+            name(selector.binding);
+            ncname(selector.operation);
+            const key = json(selector, budget);
+            if (sourceKeys.has(key))
+                throw new Stop('unsupported', 'duplicate-record-source-permission');
+            sourceKeys.add(key);
+            if (key === json(capsule.compatibility.selector, budget))
+                recordSource = supplied.source;
+        }
+        if (capsule.projection && !recordSource)
+            throw new Stop('missing-authority', 'explicit-companion-source-required');
+        const contract = await selectPinnedComponentSource(capsule.resources, capsule.compatibility.selector, capsule.libraries ?? [], localSource, options, budget, allowed);
+        let responseProjection;
+        if (capsule.projection) {
+            const source = capsule.projection.source;
+            const companion = await selectPinnedComponentSource(source.resources, source.selector, source.libraries, recordSource, { ...options, loading: { ...options.loading, sourceUri: undefined } }, budget, allowed);
+            const projection = createComponentRecordProjection(contract, companion, capsule.projection.spec, { signal: options.signal });
+            if (projection.kind !== 'component-record-projection')
+                throw new Stop(projection.kind === 'resource-limit' || projection.kind === 'cancelled'
+                    ? projection.kind : 'incompatible-artifact', projection.rule);
+            responseProjection = projection;
+        }
+        return await reconstructComponentAgainst(capsule, contract, { service: capsule.compatibility.service, port: capsule.compatibility.port }, options.signal, responseProjection);
+    }
+    catch (error) {
+        if (!budget.exhausted() && options.signal?.aborted)
+            return componentFailure(new Stop('cancelled', 'cooperative-cancellation'), budget);
+        return componentFailure(error, budget);
+    }
+}
+async function selectPinnedComponentSource(resources, selector, libraries, localSource, options, budget, allowed) {
+    if (typeof localSource !== 'string' || new URL(resolveResourceUri(localSource)).protocol !== 'file:')
+        throw new Stop('missing-authority', 'new-local-file-required');
+    if (libraries.some(id => !allowed.includes(id)))
+        throw new Stop('missing-authority', 'explicit-standard-component-permission');
+    const loader = await SchemaResourceLoader.create({ fileRoots: options.loading.policy.fileRoots }, directLoadingLimits(budget, options.loading.limits), undefined, amount => { check(budget, options.signal); budget.chargeWork(amount); }, options.signal);
+    const physical = await loader.fetchResource(localSource), expectedRoot = resources.find(resource => resource.key === 'root');
+    if (physical.digest !== expectedRoot.digest || Buffer.from(physical.bytes).toString('base64') !== expectedRoot.base64)
+        reject('local-source-changed');
+    const offline = options.loading.offlineResources ? new Map(options.loading.offlineResources) : undefined;
+    offline?.set(physical.uri, physical);
+    const loading = { ...options.loading, ...(offline ? { offlineResources: offline } : {}) };
+    const selected = await selectComponentOperationInRequest(loading.sourceUri ?? physical.uri, selector, { loading, signal: options.signal,
+        standardLibraries: libraries.map(acquireStandardSchemaLibrary) }, budget);
+    if (selected.kind !== 'selected')
+        throw new Stop(selected.kind === 'loading-refused' ? 'missing-authority'
+            : selected.kind === 'selection-refused' ? 'incompatible-artifact' : selected.kind, selected.rule);
+    return selected.contract;
+}
+/** Generator seam: expected bytes are checked against an already fresh, source-owned native operation.
+ * @remarks This accepts transient native authority only. Runtime consumers still reconstruct from independently
+ *   authorized physical files. It permits service-wide generation to reuse one native whole-source qualification.
+ */
+export async function reconstructComponentSourceCapsuleForOperation(bytes, contract, selection, signal, responseProjection) {
+    const { budget } = inspectDirectOperation(contract).context;
+    try {
+        return await reconstructComponentAgainst(readComponent(bytes, budget, signal), contract, selection, signal, responseProjection);
+    }
+    catch (error) {
+        if (!budget.exhausted() && signal?.aborted)
+            return componentFailure(new Stop('cancelled', 'cooperative-cancellation'), budget);
+        return componentFailure(error, budget);
+    }
+}
+async function reconstructComponentAgainst(capsule, contract, selection, signal, responseProjection) {
+    const { budget } = inspectDirectOperation(contract).context;
+    let derived;
+    try {
+        derived = await componentDescriptor(contract, selection, signal, responseProjection, undefined, capsule.applicationGroups);
+    }
+    catch (error) {
+        if (error instanceof TypeError && error.message.startsWith('applicationGroups'))
+            return reject('source-application-groups-changed');
+        throw error;
+    }
+    if (json(derived.applicationGroups ?? null, budget) !== json(capsule.applicationGroups ?? null, budget))
+        reject('source-application-groups-changed');
+    if (derived.applicationGroupIdentity !== capsule.applicationGroupIdentity)
+        reject('source-application-groups-changed');
+    if (json(derived.resources, budget) !== json(capsule.resources, budget))
+        reject('local-source-changed');
+    if (json(derived.compatibility, budget) !== json(capsule.compatibility, budget))
+        reject('source-contract-changed');
+    if (json(derived.libraries, budget) !== json(capsule.libraries ?? [], budget) || json(derived.projection, budget) !== json(capsule.projection ?? null, budget))
+        reject('source-projection-changed');
+    return issueComponentReconstruction(capsule, contract, derived, signal, responseProjection);
+}
+function issueComponentReconstruction(capsule, contract, derived, signal, responseProjection) {
+    const { budget } = inspectDirectOperation(contract).context;
+    check(budget, signal);
+    const result = Object.freeze({ kind: 'reconstructed-component', contract,
+        mappings: Object.freeze(derived.mappings), selection: Object.freeze({ service: derived.compatibility.service, port: derived.compatibility.port }),
+        ...(responseProjection ? { responseProjection } : {}),
+        admitted: false, usage: Object.freeze({ ...budget.usage() }) });
+    componentReconstructions.set(result, capsule);
+    return result;
+}
+/** Authenticate transient reconstruction identity; saved/copy-shaped reports cannot be consumed by generators. */
+export function inspectReconstructedComponentSource(value) {
+    if (!componentReconstructions.has(value))
+        throw new TypeError('Freshly reconstructed component source required');
+    inspectDirectOperation(value.contract);
+    return value;
+}
+/** Group fresh operations for one service without merging source contexts or binding identities.
+ * @returns A deterministic operation order over the original native handles.
+ * @throws TypeError For foreign handles, duplicate operations, accessors or mixed sources/services/bindings.
+ */
+export function inspectComponentSourceService(values) {
+    if (!Array.isArray(values) || types.isProxy(values) || !values.length)
+        throw new TypeError('Nonempty native component operations required');
+    const keys = Reflect.ownKeys(values);
+    if (keys.length !== values.length + 1)
+        throw new TypeError('Dense native operation array required');
+    const operations = [];
+    for (let index = 0; index < values.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(values, String(index));
+        if (!descriptor || !('value' in descriptor))
+            throw new TypeError('Data-only native operation array required');
+        operations.push(inspectReconstructedComponentSource(descriptor.value));
+    }
+    const first = operations[0], { source, context: { budget } } = inspectDirectOperation(first.contract), names = new Set();
+    for (const operation of operations) {
+        check(budget);
+        const inspection = inspectDirectOperation(operation.contract);
+        if (inspection.source !== source || inspection.context.budget !== budget
+            || json(operation.selection, budget) !== json(first.selection, budget)
+            || json(operation.contract.selector.binding, budget) !== json(first.contract.selector.binding, budget)
+            || names.has(operation.contract.selector.operation))
+            throw new TypeError('One source/service/binding and unique operations required');
+        names.add(operation.contract.selector.operation);
+    }
+    return Object.freeze(operations.sort((a, b) => budget.compareText(a.contract.selector.operation, b.contract.selector.operation)));
+}

package/dist/compiler/directStructure.d.ts

@@ -1,7 +1,10 @@
 import type { DirectMessageRoot, DirectOperationContract } from './directOperation.js';
-import type { ElementNode, Reference } from './canonicalGraph.js';
+import type { AttributeNode, ElementNode, Reference } from './canonicalGraph.js';
 import type { ExpandedName, SyntaxElement, SyntaxSource } from '../loader/orderedSyntax.js';
+import type { DirectProjectionSlot } from './directStructurePlan.js';
+import type { SemanticContext } from './semanticContext.js';
 import type { ResolverUsage } from './semanticBudget.js';
+import type { ProjectionScalarList } from './projectionScalar.js';
 export type DirectDirection = Readonly<{
     kind: 'input' | 'output';
 } | {
@@ -9,7 +12,7 @@ export type DirectDirection = Readonly<{
     name: string;
 }>;
 export interface DirectScalarDuty {
-    readonly declaration: ElementNode;
+    readonly declaration: ElementNode | AttributeNode;
     readonly type: Reference;
     readonly builtin: ExpandedName;
     readonly lexical: string;
@@ -17,7 +20,74 @@ export interface DirectScalarDuty {
     readonly payloadSource: SyntaxSource;
     readonly payloadPath: string;
     readonly schemaPath: string;
+    readonly fixedCanonical?: string;
+    readonly retainLexical?: true;
+    readonly list?: ProjectionScalarList;
 }
+export type DirectMatchedNode = Readonly<{
+    kind: 'unassessed';
+    declaration: ElementNode;
+    payloadPath: string;
+    payload: SyntaxElement;
+} | {
+    kind: 'mixed-text';
+    declaration: ElementNode;
+    payloadPath: string;
+    value: string;
+} | {
+    kind: 'scalar';
+    declaration: ElementNode;
+    payloadPath: string;
+    operand: number;
+} | {
+    kind: 'record';
+    declaration: ElementNode;
+    payloadPath: string;
+    nil?: true;
+    keyed?: true;
+    namespaceChoices?: readonly string[];
+    dynamicDeclarations?: readonly ElementNode[];
+    namespaces?: Readonly<Record<string, string>>;
+    openAttributes?: readonly import('../loader/orderedSyntax.js').SyntaxAttribute[];
+    attributes: readonly Readonly<{
+        declaration: AttributeNode;
+        operand: number;
+        payloadPath: string;
+        bag?: true;
+        namespaceChoice?: true;
+        origin: 'present' | 'schema-default' | 'schema-fixed';
+    }>[];
+    text?: Extract<DirectMatchedNode, {
+        kind: 'scalar';
+    }>;
+    content?: readonly DirectMatchedNode[];
+    slots: readonly Readonly<{
+        slot: DirectProjectionSlot;
+        items: readonly DirectMatchedNode[];
+    }>[];
+}>;
+export type ProjectionStructuralResult = Readonly<{
+    kind: 'projection-match';
+    scope: 'structure-only';
+    scalarValidity: 'unassessed';
+    admitted: false;
+    root: ElementNode;
+    contextId: string;
+    tree: DirectMatchedNode;
+    occurrences: readonly DirectScalarDuty[];
+    usage: ResolverUsage;
+}> | Readonly<{
+    kind: 'mismatch' | 'unsupported' | 'cancelled' | 'resource-limit';
+    rule: string;
+    schemaPath?: string;
+    payloadPath?: string;
+    usage: ResolverUsage;
+}>;
+export type ProjectionStructuralMatch = Extract<ProjectionStructuralResult, {
+    kind: 'projection-match';
+}>;
+/** Native context identity authenticates structure only, never source validity or operation admission. */
+export declare function inspectProjectionStructuralMatch(match: unknown, context: SemanticContext): ProjectionStructuralMatch;
 export type DirectStructuralResult = Readonly<{
     kind: 'structural-match';
     scope: 'structure-only';
@@ -27,6 +97,7 @@ export type DirectStructuralResult = Readonly<{
     contextId: string;
     direction: DirectDirection;
     occurrences: readonly DirectScalarDuty[];
+    tree: DirectMatchedNode;
     usage: ResolverUsage;
 }> | Readonly<{
     kind: 'mismatch' | 'unsupported' | 'cancelled' | 'resource-limit';
@@ -41,11 +112,17 @@ export type DirectStructuralMatch = Extract<DirectStructuralResult, {
 /** Identity is checked before any receipt fields; no retrospective authentication. */
 export declare function inspectDirectStructuralMatch(match: unknown, expectedContract: DirectOperationContract): DirectStructuralMatch;
 /**
- * Data-only SyntaxElement input (plain records/arrays, no proxies/accessors). Malformed
- * input throws TypeError; XML structure differences return mismatch. No caller is frozen.
- * Cancellation is synchronous/cooperative, checked at visits and before publication.
+ * Match a data-only ordered XML tree against an actual native projection.
+ * @remarks The issued receipt establishes structure only, not source validity, scalar validity or operation admission.
+ * @constraints Plain records/arrays only; proxies and accessors are unsupported. No caller payload is frozen.
+ * @throws TypeError For malformed data-only trees or unauthenticated contexts.
+ * @returns A context-owned structural match or a mismatch, unsupported, cancellation or resource failure.
  */
+export declare function matchDirectProjection(context: SemanticContext, root: ElementNode, payload: SyntaxElement, options?: Readonly<{
+    signal?: AbortSignal;
+    flatOnly?: boolean;
+}>): ProjectionStructuralResult;
+/** Operation-owned flat preview wrapper; structured projection matches cannot bypass this gate. */
 export declare function matchDirectOperation(contract: DirectOperationContract, direction: DirectDirection, payload: SyntaxElement, options?: Readonly<{
     signal?: AbortSignal;
 }>): DirectStructuralResult;
-//# sourceMappingURL=directStructure.d.ts.map