@techspokes/typescript-wsdl-client 1.1.5 → 1.1.8

package/dist/generation/componentShape.js

@@ -0,0 +1,269 @@
+/** Documentation/static shape lowering only; source, scalar facets and particle languages remain native duties. */
+import { inspectDirectOperation } from '../compiler/directOperation.js';
+import { inspectComponentValueMapping } from '../compiler/directValues.js';
+import { projectionScalarRepresentation, inspectOrderedProjectionWildcards, inspectUnassessedProjectionWildcards } from '../compiler/directStructurePlan.js';
+import { createHash } from 'node:crypto';
+import { isComponentRecordProjection, inspectComponentRecordProjection } from '../compiler/componentRecordProjection.js';
+import { applicationRecordName } from '../compiler/applicationGroups.js';
+const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+/** Lower an authenticated mapping to recursive TypeScript and JSON shape descriptions.
+ * @remarks Scalar restrictions, fixed/default semantics, ordered occurrence correlation and strict wildcard
+ *   declaration membership require native validation. These descriptions never grant source/runtime authority.
+ * @returns Role-scoped definitions and root descriptions; no native handles or retrieval paths are emitted.
+ * @throws TypeError For foreign mappings or unsupported scalar representation. Caller cancellation propagates.
+ */
+export function lowerComponentShape(contract, supplied, role, check) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(role))
+        throw new TypeError('TypeScript role identifier required');
+    if (isComponentRecordProjection(supplied)) {
+        const owned = inspectComponentRecordProjection(supplied, contract);
+        return lowerComponentShape(owned.companion, owned.mapping, role, check);
+    }
+    const { projection, applicationGroups } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    const names = new Map(projection.records.map((record, index) => [record.type.id, applicationGroups
+            ? applicationRecordName(record.type.id) : `${role}_Record_${index}`]));
+    const definitions = Object.create(null);
+    const declarations = [];
+    const lexicalAttribute = { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { anyOf: [
+                { type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }] } },
+                { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                        $namespace: { type: 'string', minLength: 1 }, $value: {}
+                    } }
+            ] } };
+    const lexicalAttributeType = 'Readonly<Record<string, string | number | boolean | readonly (string | number | boolean)[] | {readonly "$namespace": string; readonly "$value": unknown}>>';
+    const openName = applicationGroups ? 'ApplicationOpenValue' : `${role}_OpenValue`;
+    let openDeclared = false;
+    const openShape = () => {
+        if (!openDeclared) {
+            openDeclared = true;
+            const attribute = { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { anyOf: [{ type: 'string' },
+                        { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: { $namespace: { type: 'string', minLength: 1 }, $value: { type: 'string' } } }] } };
+            definitions[openName] = { type: 'object', additionalProperties: false, required: ['$namespace', '$content'], properties: {
+                    $namespace: { type: 'string' }, $namespaces: { type: 'object', additionalProperties: { type: 'string' } }, $attributes: { type: 'array', items: attribute },
+                    $content: { type: 'array', items: { anyOf: [
+                                { type: 'object', additionalProperties: false, required: ['$value'], properties: { $value: { type: 'string' } } },
+                                { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { $ref: '#/definitions/' + openName } },
+                            ] } },
+                } };
+            declarations.push(`export type ${openName} = {readonly "$namespace": string; readonly "$namespaces"?: Readonly<Record<string, string>>; `
+                + 'readonly "$attributes"?: readonly Readonly<Record<string, string | {readonly "$namespace": string; readonly "$value": string}>>[]; '
+                + `readonly "$content": readonly ({readonly "$value": string} | Readonly<Record<string, ${openName}>>)[]};`);
+        }
+        return { type: `Readonly<Record<string, ${openName}>>`, schema: { type: 'object', minProperties: 1, maxProperties: 1,
+                additionalProperties: { $ref: '#/definitions/' + openName } } };
+    };
+    const scalar = (value) => {
+        check();
+        // @why A list-level pattern retains one lexical witness; its HTTP value is a string rather than an item array.
+        const item = value.retainLexical ? value : value.list ?? value;
+        const type = item.retainLexical ? 'string' : projectionScalarRepresentation(item.builtin);
+        if (!type)
+            throw new TypeError('Unsupported native scalar representation');
+        const schema = type === 'number' ? { type: 'integer', minimum: -2147483648, maximum: 2147483647 }
+            : type === 'string' ? { type, pattern: '^[\\u0009\\u000A\\u000D\\u0020-\\uD7FF\\uE000-\\uFFFD\\u{10000}-\\u{10FFFF}]*$' } : { type };
+        return value.list && !value.retainLexical ? { type: `readonly ${type}[]`, schema: { type: 'array', items: schema } } : { type, schema };
+    };
+    const shape = (value) => {
+        check();
+        const ordinary = (() => {
+            if (value.kind === 'scalar')
+                return scalar(value);
+            const name = names.get(value.type);
+            if (!name)
+                throw new TypeError('Missing native projection record');
+            return { type: name, schema: { $ref: '#/definitions/' + name } };
+        })();
+        if (!value.nillable || value.constraint?.kind === 'fixed')
+            return ordinary;
+        const record = value.kind === 'record' ? projection.records.find(record => record.type.id === value.type) : undefined;
+        const attributes = record?.attributes ?? [];
+        const properties = Object.create(null);
+        properties.$nil = { const: true };
+        const required = ['$nil'], members = ['readonly "$nil": true'];
+        for (const attribute of attributes) {
+            if (attribute.bag)
+                continue;
+            check();
+            const key = attribute.declaration.name.local, description = scalar(attribute);
+            properties[key] = description.schema;
+            if (attribute.required)
+                required.push(key);
+            members.push(`readonly ${literal(key)}${attribute.required ? '' : '?'}: ${description.type}`);
+        }
+        const bag = attributeBag(attributes, !!record?.attributeWildcard);
+        if (bag) {
+            properties.$attributes = bag.schema;
+            members.push(`readonly "$attributes"${bag.required ? '' : '?'}: ${bag.type}`);
+            if (bag.required)
+                required.push('$attributes');
+        }
+        if (record?.contextual) {
+            properties.$namespaces = { type: 'object', additionalProperties: { type: 'string' } };
+            members.push('readonly "$namespaces"?: Readonly<Record<string, string>>');
+        }
+        // @why Nil and ordinary values are disjoint: source data cannot use reserved $nil, and nil has no content fields.
+        return { type: `(${ordinary.type} | {${members.join('; ')}})`, schema: { anyOf: [ordinary.schema,
+                    { type: 'object', additionalProperties: false, properties, required }] } };
+    };
+    const attributeBag = (attributes, open = false) => {
+        const entries = attributes.filter(attribute => attribute.bag).map(attribute => {
+            const key = attribute.declaration.name.local, description = scalar(attribute);
+            const ambiguous = !!attribute.declaration.name.namespace && (open || attributes.some(other => other !== attribute && other.declaration.name.local === key));
+            const value = ambiguous ? { type: `{readonly "$namespace": ${literal(attribute.declaration.name.namespace)}; readonly "$value": ${description.type}}`,
+                schema: { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                        $namespace: { const: attribute.declaration.name.namespace }, $value: description.schema
+                    } } } : description;
+            return { type: `{readonly ${literal(key)}: ${value.type}}`, schema: { type: 'object', additionalProperties: false,
+                    required: [key], properties: { [key]: value.schema } } };
+        });
+        if (open)
+            entries.push({ type: lexicalAttributeType, schema: lexicalAttribute });
+        return entries.length ? { type: `readonly (${entries.map(entry => entry.type).join(' | ')})[]`,
+            schema: { type: 'array', items: { anyOf: entries.map(entry => entry.schema) } }, required: attributes.some(attribute => attribute.bag && attribute.required) } : undefined;
+    };
+    const groupObject = (nodes) => {
+        const properties = Object.create(null);
+        const required = [], members = [];
+        const visit = (node) => {
+            check();
+            if (!node.slot && !node.target) {
+                for (const child of node.children)
+                    visit(child);
+                return;
+            }
+            const key = node.slot?.element.name.local ?? node.target.resolved.propertyName;
+            let description;
+            if (node.slot)
+                description = shape(node.slot.value);
+            else {
+                const name = node.target.resolved.typeName;
+                if (node.alternatives) {
+                    const alternatives = node.children.map((child, index) => {
+                        const alternative = node.alternatives[index].resolved.typeName, body = groupObject(child.children);
+                        definitions[alternative] = body.schema;
+                        declarations.push(`export type ${alternative} = ${body.type};`);
+                        return { type: alternative, schema: { $ref: '#/definitions/' + alternative } };
+                    });
+                    definitions[name] = { anyOf: alternatives.map(a => a.schema) };
+                    declarations.push(`export type ${name} = ${alternatives.map(a => a.type).join(' | ')};`);
+                }
+                else {
+                    const body = groupObject(node.children);
+                    definitions[name] = body.schema;
+                    declarations.push(`export type ${name} = ${body.type};`);
+                }
+                description = { type: name, schema: { $ref: '#/definitions/' + name } };
+            }
+            const repeated = node.particle.occurs.max !== '1', mandatory = node.particle.occurs.min !== '0';
+            if (repeated)
+                description = { type: `readonly (${description.type})[]`, schema: { type: 'array', items: description.schema,
+                        minItems: Number(node.particle.occurs.min), ...(node.particle.occurs.max === 'unbounded' ? {} : { maxItems: Number(node.particle.occurs.max) }) } };
+            properties[key] = description.schema;
+            if (mandatory)
+                required.push(key);
+            members.push(`readonly ${literal(key)}${mandatory ? '' : '?'}: ${description.type}`);
+        };
+        for (const node of nodes)
+            visit(node);
+        return { type: `{${members.join('; ')}}`, schema: { type: 'object', properties, required, additionalProperties: false } };
+    };
+    for (const record of projection.records) {
+        check();
+        const name = names.get(record.type.id);
+        const properties = Object.create(null);
+        const required = [], members = [];
+        const member = (key, value, mandatory) => {
+            check();
+            properties[key] = value.schema;
+            if (mandatory)
+                required.push(key);
+            members.push(`  readonly ${literal(key)}${mandatory ? '' : '?'}: ${value.type};`);
+        };
+        for (const attribute of record.attributes)
+            if (!attribute.bag)
+                member(attribute.declaration.name.local, scalar(attribute), attribute.required);
+        const bag = attributeBag(record.attributes, !!record.attributeWildcard);
+        if (bag)
+            member('$attributes', bag, bag.required);
+        if (record.contextual)
+            member('$namespaces', { type: 'Readonly<Record<string, string>>', schema: { type: 'object', additionalProperties: { type: 'string' } } }, false);
+        if (record.text)
+            member('$value', scalar(record.text), true);
+        const group = applicationGroups?.records[record.type.id];
+        if (group) {
+            const description = groupObject(group.children);
+            const schema = description.schema;
+            Object.assign(properties, schema.properties);
+            required.push(...schema.required);
+            members.push(description.type.slice(1, -1));
+        }
+        else if (record.ordered) {
+            const variants = new Map();
+            for (const slot of record.slots) {
+                check();
+                const value = shape(slot.value), expanded = slot.element.name, key = literal(expanded);
+                if (record.keyed) {
+                    const ambiguous = !record.fixedOrder && record.slots.some(other => other !== slot && other.element.name.local === expanded.local);
+                    const scalarValue = slot.value.kind === 'scalar' ? scalar(slot.value) : value;
+                    const holder = ambiguous ? { type: slot.value.kind === 'scalar'
+                            ? `{readonly "$namespace": ${literal(expanded.namespace)}; readonly "$value": ${scalarValue.type}}`
+                            : `(${value.type} & {readonly "$namespace": ${literal(expanded.namespace)}})`,
+                        schema: slot.value.kind === 'scalar' ? { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                                $namespace: { const: expanded.namespace }, $value: scalarValue.schema
+                            } }
+                            // @why Native validation owns the record's fixed fields; this structural superset must preserve the identity holder.
+                            : { type: 'object', required: ['$namespace'], properties: { $namespace: { const: expanded.namespace } }, additionalProperties: true } } : value;
+                    if (ambiguous && slot.value.kind === 'scalar' && slot.value.nillable && slot.value.constraint?.kind !== 'fixed') {
+                        holder.type = `(${holder.type} | {readonly "$namespace": ${literal(expanded.namespace)}; readonly "$nil": true})`;
+                        holder.schema = { anyOf: [holder.schema, { type: 'object', additionalProperties: false, required: ['$namespace', '$nil'], properties: {
+                                        $namespace: { const: expanded.namespace }, $nil: { const: true }
+                                    } }] };
+                    }
+                    variants.set(key, { type: `{readonly ${literal(expanded.local)}: ${holder.type}}`, schema: {
+                            type: 'object', additionalProperties: false, required: [expanded.local], properties: { [expanded.local]: holder.schema }
+                        } });
+                    continue;
+                }
+                variants.set(key, { type: `{readonly name: {readonly namespace: ${literal(expanded.namespace)}; readonly local: ${literal(expanded.local)}}; readonly value: ${value.type}}`,
+                    schema: { type: 'object', additionalProperties: false, required: ['name', 'value'], properties: {
+                            name: { type: 'object', additionalProperties: false, required: ['namespace', 'local'], properties: { namespace: { const: expanded.namespace }, local: { const: expanded.local } } }, value: value.schema
+                        } } });
+            }
+            if (record.content === 'mixed')
+                variants.set('$value', { type: '{readonly "$value": string}', schema: {
+                        type: 'object', additionalProperties: false, required: ['$value'], properties: { $value: { type: 'string' } }
+                    } });
+            if (inspectOrderedProjectionWildcards(context, record))
+                variants.set('*', record.keyed ? {
+                    type: 'Readonly<Record<string, Readonly<{"$namespace": string; [key: string]: unknown}>>>',
+                    schema: { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { type: 'object',
+                            required: ['$namespace'], properties: { $namespace: { type: 'string' }, $namespaces: { type: 'object', additionalProperties: { type: 'string' } },
+                                $attributes: { type: 'array', items: lexicalAttribute }, $content: { type: 'array', items: { type: 'object' } }, $value: {} }, additionalProperties: true } },
+                } : {
+                    type: '{readonly name: {readonly namespace: string; readonly local: string}; readonly value: unknown}',
+                    schema: { type: 'object', additionalProperties: false, required: ['name', 'value'], properties: { name: { type: 'object', additionalProperties: false,
+                                required: ['namespace', 'local'], properties: { namespace: { type: 'string' }, local: { type: 'string' } } }, value: {} } },
+                });
+            if (record.keyed && inspectUnassessedProjectionWildcards(context, record))
+                variants.set('*', openShape());
+            const entries = [...variants.values()];
+            member('$content', { type: `readonly (${entries.map(entry => entry.type).join(' | ') || 'never'})[]`,
+                schema: { type: 'array', items: entries.length ? { anyOf: entries.map(entry => entry.schema) } : { not: {} } } }, true);
+        }
+        else
+            for (const slot of record.slots) {
+                check();
+                const value = shape(slot.value), repeated = slot.particle.occurs.max !== '1';
+                member(slot.element.name.local, repeated ? { type: slot.particle.occurs.min === '1'
+                        ? `readonly [${value.type}, ...(${value.type})[]]` : `readonly (${value.type})[]`, schema: { type: 'array', items: value.schema,
+                        minItems: Number(slot.particle.occurs.min) } } : value, repeated || slot.particle.occurs.min === '1');
+            }
+        declarations.push(`export type ${name} = ${members.length ? '{\n' + members.join('\n') + '\n}' : 'Readonly<Record<string, never>>'};`);
+        definitions[name] = { type: 'object', properties, required, additionalProperties: false };
+    }
+    const root = shape(projection.root);
+    const id = 'urn:checked-component:shape:' + createHash('sha256').update(JSON.stringify({ selector: contract.selector, role })).digest('hex');
+    // @why Nested identified fault schemas must not expose a root-only $ref that recurses during Ajv resource resolution.
+    const rootSchema = root.schema.$ref ? { allOf: [root.schema] } : root.schema;
+    return { type: root.type, declarations, schema: { $id: id, ...rootSchema, definitions } };
+}

package/dist/generation/preamble.d.ts

@@ -14,4 +14,3 @@ export declare const resolvePreamble: (artifact: string) => string;
  * @constraints Embedded fragments must not pass through this composer separately.
  */
 export declare function composeGeneratedSource(body: string, preamble: string): string;
-//# sourceMappingURL=preamble.d.ts.map

package/dist/generation/sourceLayout.d.ts

@@ -0,0 +1,13 @@
+/** Physical layout checks only; source interpretation and eligibility remain native responsibilities. */
+import path from 'node:path';
+import type { SchemaInput } from '../loader/schemaInput.js';
+/** Find a finite common directory using complete parent segments, including valid names beginning with two dots.
+ * @throws Error For cross-volume inputs, cancellation or an impossible ancestor search.
+ */
+export declare function commonSourceDirectory(root: string, files: readonly string[], check: () => void, paths?: Pick<typeof path, 'dirname' | 'parse' | 'relative' | 'isAbsolute' | 'sep'>): string;
+/** Refuse local retrieval aliases that cannot be copied as a relocatable physical tree.
+ * @remarks HTTP aliases use generated offline URI records. Local symlink aliases remain unsupported;
+ *   this scaffold does not invent filesystem links or rewrite original source bytes.
+ * @throws TypeError For unowned source input. Error For a nonrelocatable authenticated dependency or cancellation.
+ */
+export declare function assertCanonicalSourceLayout(input: SchemaInput, check: () => void): void;

package/dist/generation/sourceLayout.js

@@ -0,0 +1,40 @@
+/** Physical layout checks only; source interpretation and eligibility remain native responsibilities. */
+import path from 'node:path';
+import { assertLoadedSchemaInput } from '../loader/schemaInput.js';
+/** Find a finite common directory using complete parent segments, including valid names beginning with two dots.
+ * @throws Error For cross-volume inputs, cancellation or an impossible ancestor search.
+ */
+export function commonSourceDirectory(root, files, check, paths = path) {
+    let common = paths.dirname(root);
+    for (const file of files) {
+        check();
+        if (paths.parse(file).root.toLowerCase() !== paths.parse(common).root.toLowerCase())
+            throw new Error('Cross-volume source relocation requires explicit consumer source configuration');
+        for (;;) {
+            check();
+            const relative = paths.relative(common, file);
+            if (relative !== '..' && !relative.startsWith('..' + paths.sep) && !paths.isAbsolute(relative))
+                break;
+            const parent = paths.dirname(common);
+            if (parent === common)
+                throw new Error('Unable to find common source directory');
+            common = parent;
+        }
+    }
+    return common;
+}
+/** Refuse local retrieval aliases that cannot be copied as a relocatable physical tree.
+ * @remarks HTTP aliases use generated offline URI records. Local symlink aliases remain unsupported;
+ *   this scaffold does not invent filesystem links or rewrite original source bytes.
+ * @throws TypeError For unowned source input. Error For a nonrelocatable authenticated dependency or cancellation.
+ */
+export function assertCanonicalSourceLayout(input, check) {
+    assertLoadedSchemaInput(input);
+    const schemas = new Map(input.schemas.map(schema => [schema.key, schema.documentUri]));
+    for (const edge of input.edges) {
+        check();
+        if (edge.to && edge.referenceUri && new URL(edge.referenceUri).protocol === 'file:' && edge.referenceUri !== (schemas.get(edge.to) ?? edge.to)) {
+            throw new Error('Source relocation refuses import retrieval aliases; supply canonical source references or independently configured runtime inputs');
+        }
+    }
+}

package/dist/generation/writeGeneratedSource.d.ts

@@ -8,4 +8,3 @@
  * @constraints Call only after any scaffold skip/force guard.
  */
 export declare function writeGeneratedSource(filePath: string, content: string, artifact: string): void;
-//# sourceMappingURL=writeGeneratedSource.d.ts.map

package/dist/index.d.ts

@@ -4,9 +4,14 @@ export { generateGateway } from "./gateway/generateGateway.js";
 export { buildSecurity, loadSecurityConfigFile, parseSecurityConfig, SecurityConfigError, type SecurityConfig, } from "./util/securityConfig.js";
 export { generateTests } from "./test/generateTests.js";
 export { runGenerationPipeline } from "./pipeline.js";
+export type { PipelineOptions } from './pipeline.js';
+export type { CheckedComponentOptions, CheckedInventory } from './checkedPipeline.js';
+export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
+export type { CheckedComponentPlan, ComponentPlanBlocker } from './checkedPlanning.js';
+export type { ComponentRecordProjectionSpec, ComponentRecordProjectionAssociation } from './compiler/componentRecordProjection.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, type OperationStreamMetadata, type ShapeCatalogRef, type StreamConfig, } from "./util/streamConfig.js";
 export { applyShapeCatalogs, type ApplyShapeCatalogsOptions } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1 } from './client/checkedDirectRuntime.js';
 /**
  * Compiles a WSDL file to TypeScript client code
  *
@@ -37,5 +42,5 @@ export declare function compileWsdlToProject(input: {
     streamConfig?: import("./util/streamConfig.js").StreamConfig;
 }): Promise<void>;
 export { assessSchemaSource, serializeAssessmentReport, parseAssessmentReport, assessmentExitCode, ASSESSMENT_VERSION, ASSESSMENT_BASIS } from './compiler/checkedAssessment.js';
+export type { ApplicationGroupsOptions, ApplicationGroupName } from './compiler/applicationGroups.js';
 export type { CheckedAssessmentReport, AssessmentObligation, AssessedOperation, AssessmentStatus } from './compiler/checkedAssessment.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -27,9 +27,10 @@ export { generateGateway } from "./gateway/generateGateway.js";
 export { buildSecurity, loadSecurityConfigFile, parseSecurityConfig, SecurityConfigError, } from "./util/securityConfig.js";
 export { generateTests } from "./test/generateTests.js";
 export { runGenerationPipeline } from "./pipeline.js";
+export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, } from "./util/streamConfig.js";
 export { applyShapeCatalogs } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1 } from './client/checkedDirectRuntime.js';
 // noinspection JSUnusedGlobalSymbols
 /**
  * Compiles a WSDL file to TypeScript client code

package/dist/loader/fetch.d.ts

@@ -33,4 +33,3 @@ export declare function fetchText(urlOrPath: string, base?: string): Promise<{
     uri: string;
     text: string;
 }>;
-//# sourceMappingURL=fetch.d.ts.map

package/dist/loader/orderedSyntax.d.ts

@@ -62,8 +62,16 @@ export declare const isXmlNCName: (value: string) => boolean;
 export declare const isXmlName: (value: string) => boolean;
 export declare const isXmlNmtoken: (value: string) => boolean;
 export declare function resolveLexicalQName(lexical: string, node: SyntaxElement): ExpandedName;
+/** Decode private metadata text; original bytes remain the digest and snapshot authority.
+ * @remarks ISO-8859-1 maps every byte to the same code point, including C1 controls.
+ *   HTTP charset headers are not encoding authority here. Runtime XML uses its existing policy.
+ * @throws SchemaLoadingError For malformed bytes or incompatible/unsupported declarations.
+ */
+export declare function decodeMetadataXml(bytes: Uint8Array): string;
 /** Positions are one-based lines/columns and zero-based UTF-16 offsets in decoded XML. */
 export interface OrderedSyntaxOptions {
+    /** Internal metadata boundary; payload/capsule callers retain the existing encoding policy. */
+    metadataEncoding?: boolean;
     maxDepth?: number;
     /** Optional bounded runtime boundary; legacy schema callers retain their policy. */
     maxBytes?: number;
@@ -74,4 +82,3 @@ export interface OrderedSyntaxOptions {
     reserveNode?: () => void;
 }
 export declare function parseOrderedSyntax(bytes: Uint8Array, uri: string, options?: OrderedSyntaxOptions): SyntaxDocument;
-//# sourceMappingURL=orderedSyntax.d.ts.map

package/dist/loader/orderedSyntax.js

@@ -46,15 +46,35 @@ export function resolveLexicalQName(lexical, node) {
         throw new SchemaLoadingError("invalid-schema", "Unbound QName prefix", node.source);
     return Object.freeze({ namespace: namespace ?? "", local: parts.at(-1) });
 }
-function decodeXml(bytes, strictBom = false) {
-    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
+const xmlEncodingDeclaration = /^<\?xml\s[^?]*encoding\s*=\s*["']([^"']+)["']/i;
+/** Decode private metadata text; original bytes remain the digest and snapshot authority.
+ * @remarks ISO-8859-1 maps every byte to the same code point, including C1 controls.
+ *   HTTP charset headers are not encoding authority here. Runtime XML uses its existing policy.
+ * @throws SchemaLoadingError For malformed bytes or incompatible/unsupported declarations.
+ */
+export function decodeMetadataXml(bytes) {
+    return decodeXml(bytes, true, true);
+}
+function decodeXml(bytes, strictBom = false, metadata = false) {
+    let encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
         : bytes[0] === 0xfe && bytes[1] === 0xff ? "utf-16be" : "utf-8";
     try {
-        const text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+        const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        // @why Sniff only an ASCII declaration, never guess Latin1 after UTF-8 failure.
+        //   A BOM fixes the encoding and must agree with the decoded declaration.
+        if (metadata && encoding === 'utf-8' && !(bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)) {
+            const end = buffer.indexOf('>');
+            const declaration = xmlEncodingDeclaration.exec(buffer.toString('latin1', 0, end < 0 ? 0 : end + 1))?.[1].toLowerCase();
+            if (declaration === 'iso-8859-1')
+                encoding = 'iso-8859-1';
+        }
+        // TextDecoder's ISO label aliases Windows-1252; Buffer supplies actual ISO byte identity.
+        const text = encoding === 'iso-8859-1' ? buffer.toString('latin1') : new TextDecoder(encoding, { fatal: true }).decode(bytes);
         if (strictBom && text.startsWith('\ufeff'))
             throw new SchemaLoadingError('invalid-schema', 'Multiple XML byte order marks');
-        const declared = /^<\?xml\s[^?]*encoding\s*=\s*["']([^"']+)["']/i.exec(text)?.[1].toLowerCase();
-        if (declared && !(encoding === "utf-8" ? ["utf-8", "utf8"] : ["utf-16", encoding]).includes(declared)) {
+        const declared = xmlEncodingDeclaration.exec(text)?.[1].toLowerCase();
+        const allowed = encoding === 'iso-8859-1' ? [encoding] : encoding === 'utf-8' ? ['utf-8', 'utf8'] : ['utf-16', encoding];
+        if (declared && !allowed.includes(declared)) {
             throw new SchemaLoadingError("unsupported-capability", "Unsupported XML byte encoding");
         }
         return text;
@@ -87,7 +107,7 @@ export function parseOrderedSyntax(bytes, uri, options = {}) {
     const charge = (amount) => options.chargeWork?.(amount);
     charge(4096 + bytes.byteLength * 64);
     const digest = createHash("sha256").update(bytes).digest("hex");
-    const text = decodeXml(bytes, options.xml10Only);
+    const text = options.metadataEncoding ? decodeMetadataXml(bytes) : decodeXml(bytes, options.xml10Only);
     const lines = [0];
     for (let i = 0; i < text.length; i++) {
         if (text[i] === "\r") {

package/dist/loader/resolutionDepth.d.ts

@@ -4,4 +4,3 @@ export type ResolutionArc = Readonly<{
     cost: 0 | 1;
 }>;
 export declare function resolutionDepthBound(root: string, graph: ReadonlyMap<string, readonly ResolutionArc[]>, terminals: ReadonlySet<string>): number;
-//# sourceMappingURL=resolutionDepth.d.ts.map

package/dist/loader/schemaInput.d.ts

@@ -26,6 +26,7 @@ export type SchemaInput = Readonly<{
     documents: readonly SyntaxDocument[];
     schemas: readonly SchemaInterpretation[];
     resources: readonly ResourceMetadata[];
+    resourceAliases: ReadonlyMap<string, string>;
     edges: readonly ResolutionEdge[];
     limits: LoadingLimits;
     metrics: Readonly<{
@@ -39,15 +40,41 @@ export declare function copyOriginalSchemaResource(input: SchemaInput, uri: stri
 export declare function assertLoadedSchemaInput(input: SchemaInput): void;
 export declare function schemaInterpretationKey(node: SyntaxElement, targetNamespace: string, context: SchemaContext): string;
 export type SchemaInputOptions = {
+    /** Generated logical root for independently authorized physical snapshots; confers no I/O authority. */
+    sourceUri?: string;
+    /** Diagnostic observation only; partial documents never establish loading completeness or eligibility. */
+    onDocument?: (document: SyntaxDocument) => void;
     signal?: AbortSignal;
     /** Optional request accounting used by the additive assessment boundary. */
     chargeWork?: (amount: number) => void;
     policy: SchemaResourcePolicy;
     limits?: Partial<LoadingLimits>;
     offlineResources?: ReadonlyMap<string, OfflineSchemaResource>;
+    /**
+     * Explicit resource locations for XSD imports without schemaLocation.
+     * @remarks Keys are exact namespace names (including the empty namespace).
+     *   Locations resolve against the caller's working directory, never the importing
+     *   document. Explicit schemaLocation attributes take precedence. Resource policy,
+     *   digests, namespace matching and loading limits still apply; no namespace is fetched implicitly.
+     * @see https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#composition-schemaImport
+     */
+    namespaceLocations?: ReadonlyMap<string, string>;
 };
+/** Prepare a closed input set from independently authorized physical metadata snapshots.
+ * @remarks Logical import URIs never initiate I/O here. The later native loader still checks their explicit origin/root
+ *   permissions. Missing snapshots refuse rather than falling back to network or to artifact-embedded bytes.
+ * @returns The actual physical root URI and complete offline loading configuration.
+ * @throws SchemaLoadingError For non-file physical inputs, duplicates, denied roots or unavailable files.
+ */
+export declare function prepareSchemaSnapshotFiles(root: string, files: readonly {
+    readonly uri: string;
+    readonly file: string;
+    readonly canonicalUri?: string;
+}[], options: Omit<SchemaInputOptions, 'offlineResources'>): Promise<{
+    source: string;
+    loading: SchemaInputOptions;
+}>;
 /** A fresh compilation-scoped snapshot, with no implicit network or filesystem permission. */
 export declare function loadSchemaInput(source: string, options: SchemaInputOptions): Promise<SchemaInput>;
 /** Internal faithful source entry; preserves syntax and the legacy public entry. */
 export declare function loadSemanticSchemaInput(source: string, options: SchemaInputOptions): Promise<SchemaInput>;
-//# sourceMappingURL=schemaInput.d.ts.map

package/dist/loader/schemaInput.js

@@ -23,6 +23,29 @@ export function assertLoadedSchemaInput(input) {
 export function schemaInterpretationKey(node, targetNamespace, context) {
     return JSON.stringify([node.source.digest, node.source.uri, node.baseUri, targetNamespace, context.kind, context.namespace, node.source.path]);
 }
+/** Prepare a closed input set from independently authorized physical metadata snapshots.
+ * @remarks Logical import URIs never initiate I/O here. The later native loader still checks their explicit origin/root
+ *   permissions. Missing snapshots refuse rather than falling back to network or to artifact-embedded bytes.
+ * @returns The actual physical root URI and complete offline loading configuration.
+ * @throws SchemaLoadingError For non-file physical inputs, duplicates, denied roots or unavailable files.
+ */
+export async function prepareSchemaSnapshotFiles(root, files, options) {
+    const physical = async (reference) => {
+        if (new URL(resolveResourceUri(reference)).protocol !== 'file:')
+            throw new SchemaLoadingError('unsupported-capability', 'Physical schema snapshot file required');
+        return loader.fetchResource(reference);
+    };
+    const loader = await SchemaResourceLoader.create({ fileRoots: options.policy.fileRoots }, options.limits, undefined, options.chargeWork, options.signal);
+    const source = await physical(root), offlineResources = new Map([[source.uri, source]]);
+    for (const entry of files) {
+        options.chargeWork?.(1);
+        const uri = resolveResourceUri(entry.uri);
+        if (offlineResources.has(uri))
+            throw new SchemaLoadingError('invalid-schema', 'Duplicate logical schema snapshot');
+        offlineResources.set(uri, { ...await physical(entry.file), canonicalUri: entry.canonicalUri });
+    }
+    return { source: source.uri, loading: { ...options, offlineResources } };
+}
 /** A fresh compilation-scoped snapshot, with no implicit network or filesystem permission. */
 export function loadSchemaInput(source, options) {
     return loadSchemaInputWithValues(source, options, false);
@@ -32,6 +55,15 @@ export function loadSemanticSchemaInput(source, options) {
     return loadSchemaInputWithValues(source, options, true);
 }
 async function loadSchemaInputWithValues(source, options, semanticValues) {
+    // @why Snapshot caller configuration before the first asynchronous resource read.
+    const namespaceLocations = new Map();
+    if (options.namespaceLocations)
+        for (const [namespace, location] of options.namespaceLocations) {
+            if (typeof namespace !== 'string' || typeof location !== 'string' || !location)
+                throw new TypeError('Namespace locations require string namespace names and nonempty resource locations');
+            options.chargeWork?.(256 + (namespace.length + location.length) * 32);
+            namespaceLocations.set(namespace, resolveResourceUri(location));
+        }
     const loader = await SchemaResourceLoader.create(options.policy, options.limits, options.offlineResources, options.chargeWork, options.signal);
     const documents = new Map();
     const originalBytes = new Map();
@@ -67,12 +99,13 @@ async function loadSchemaInputWithValues(source, options, semanticValues) {
         const resource = await loader.fetchResource(uri);
         let doc = documents.get(resource.uri);
         if (!doc) {
-            doc = parseOrderedSyntax(resource.bytes, resource.uri, { maxDepth: loader.limits.syntaxDepth });
+            doc = parseOrderedSyntax(resource.bytes, resource.uri, { maxDepth: loader.limits.syntaxDepth, metadataEncoding: true });
             if (semanticValues) {
                 options.chargeWork?.(128);
                 originalBytes.set(resource.uri, resource.bytes);
             }
             documents.set(resource.uri, doc);
+            options.onDocument?.(doc);
         }
         return doc;
     };
@@ -94,6 +127,9 @@ async function loadSchemaInputWithValues(source, options, semanticValues) {
     const referencedDocument = async (reference, node) => {
         try {
             const referenceUri = resolveResourceUri(reference, node.baseUri);
+            if (new URL(node.source.uri).protocol !== 'file:' && new URL(referenceUri).protocol === 'file:') {
+                throw new SchemaLoadingError('unsupported-capability', 'Remote metadata cannot select local resources');
+            }
             return { referenceUri, doc: await getDocument(referenceUri) };
         }
         catch (error) {
@@ -136,7 +172,8 @@ async function loadSchemaInputWithValues(source, options, semanticValues) {
             const missingLocation = semanticValues ? location === undefined : !location;
             if (missingLocation && kind === "include")
                 throw new SchemaLoadingError("invalid-schema", "Schema include requires schemaLocation", child.source);
-            if (missingLocation) {
+            const suppliedLocation = missingLocation && kind === 'import' ? namespaceLocations.get(importedNamespace ?? '') : undefined;
+            if (missingLocation && suppliedLocation === undefined) {
                 recordEdge({ kind, from: key, source: child.source, cycle: false });
                 continue;
             }
@@ -144,7 +181,7 @@ async function loadSchemaInputWithValues(source, options, semanticValues) {
             const namespace = kind === "include" ? targetNamespace : importedNamespace ?? "";
             if (kind === "import" && namespace === targetNamespace)
                 throw new SchemaLoadingError("invalid-schema", "Schema import must name a different namespace", child.source);
-            const { referenceUri, doc } = await referencedDocument(location, child);
+            const { referenceUri, doc } = await referencedDocument(suppliedLocation ?? location, child);
             const childDeclaredNamespace = xsdUri(doc.root, "targetNamespace");
             // A successfully supplied import referent must match both presence and
             // value. An explicit empty import namespace without a referent is not
@@ -204,7 +241,7 @@ async function loadSchemaInputWithValues(source, options, semanticValues) {
     else
         throw new SchemaLoadingError("unsupported-capability", "Only WSDL 1.1 or XSD schema inputs are accepted; payload hints cannot resolve schemas", root.root.source);
     const input = Object.freeze({ root, documents: Object.freeze([...documents.values()]), schemas: Object.freeze([...schemas.values()]),
-        resources: loader.metadata, edges: Object.freeze(edges), limits: loader.limits, metrics: loader.metrics });
+        resources: loader.metadata, resourceAliases: loader.resourceAliases, edges: Object.freeze(edges), limits: loader.limits, metrics: loader.metrics });
     loadedInputs.add(input);
     if (semanticValues)
         originalSources.set(input, originalBytes);

package/dist/loader/schemaResources.d.ts

@@ -19,6 +19,7 @@ export type SchemaResourcePolicy = Readonly<{
 export type OfflineSchemaResource = Readonly<{
     bytes: Uint8Array;
     digest: string;
+    canonicalUri?: string;
 }>;
 export type ResourceMetadata = Readonly<{
     uri: string;
@@ -53,7 +54,7 @@ export declare class SchemaResourceLoader {
         totalBytes: number;
         ioMs: number;
     }>;
+    get resourceAliases(): ReadonlyMap<string, string>;
     private authorize;
     fetchResource(reference: string): Promise<FetchedSchemaResource>;
 }
-//# sourceMappingURL=schemaResources.d.ts.map