@techspokes/typescript-wsdl-client 1.1.8 → 1.2.0

package/dist/compiler/schemaCompiler.js

@@ -1,6 +1,7 @@
 import { getChildrenWithLocalName, getFirstWithLocalName, normalizeArray, pascal, resolveQName, } from "../util/tools.js";
 import { xsdToTsPrimitive } from "../xsd/primitives.js";
 import { WsdlCompilationError } from "../util/errors.js";
+import { LegacyDeclarations } from "./legacyDeclarations.js";
 // XML Schema namespace constant
 const XS = "http://www.w3.org/2001/XMLSchema";
 /**
@@ -13,25 +14,6 @@ const XS = "http://www.w3.org/2001/XMLSchema";
 function qkey(q) {
     return `{${q.ns}}${q.local}`;
 }
-/**
- * Generates a name for an inline complex type
- *
- * This function creates appropriate TypeScript names for anonymous types
- * that are defined inline within element declarations.
- *
- * @param {string} parentTypeName - Name of the parent type
- * @param {string} [propName] - Name of the property containing the inline type
- * @param {number|"unbounded"} [_max] - Maximum occurrence (unused but kept for API compatibility)
- * @returns {string} - Generated TypeScript name for the inline type
- */
-function makeInlineTypeName(parentTypeName, propName, _max) {
-    const base = pascal(parentTypeName || "AnonParent");
-    const prop = pascal(propName || "");
-    if (prop) {
-        return prop;
-    }
-    return `${base}Anon`;
-}
 // --- Minimal WS-Policy scanning (inline policies only; PolicyReference not resolved) ---
 /**
  * Extracts security requirements from WS-Policy nodes
@@ -255,9 +237,13 @@ export function compileCatalog(cat, options, streamConfig) {
             }
         }
     }
-    // outputs & state
-    const compiledMap = new Map(); // key: ns|name
-    const aliasMap = new Map(); // key: ns|name
+    const declarations = new LegacyDeclarations([
+        ...Array.from(complexTypes.values(), rec => ({ kind: "complex", name: String(rec.node["@_name"]), ns: rec.tns, node: rec.node, prefixes: rec.prefixes })),
+        ...Array.from(simpleTypes.values(), rec => ({ kind: "simple", name: String(rec.node["@_name"]), ns: rec.tns, node: rec.node, prefixes: rec.prefixes })),
+        ...Array.from(elements.values(), rec => ({ kind: "element", name: String(rec.node["@_name"]), ns: rec.tns, node: rec.node, prefixes: rec.prefixes })),
+    ]);
+    const compiledMap = new Map();
+    const aliasMap = new Map();
     const inProgress = new Set();
     // meta accumulators
     const attrSpec = {};
@@ -314,22 +300,23 @@ export function compileCatalog(cat, options, streamConfig) {
         const list = getFirstWithLocalName(simpleNode, "list");
         if (list?.["@_itemType"]) {
             const q = resolveQName(list["@_itemType"], schemaNS, prefixes);
-            const declared = q.ns === XS ? `xs:${q.local}` : `{${q.ns}}${q.local}`;
-            return { tsType: `${xsdToTsPrimitive(declared, options?.primitive)}[]`, declared };
+            const item = resolveTypeRef(q, schemaNS, prefixes);
+            const itemType = item.tsType.includes("|") ? `(${item.tsType})` : item.tsType;
+            return { tsType: `${itemType}[]`, declared: item.declared };
         }
         // fallback
         return { tsType: "string", declared: "xs:string" };
     }
     /** Compile and cache a named simpleType */
     function getOrCompileAlias(name, sNode, schemaNS, prefixes) {
-        const key = `${schemaNS}|${name}`;
+        const key = declarations.type(schemaNS, name);
         const present = aliasMap.get(key);
         if (present) {
             return present;
         }
         const { tsType, declared, jsdoc } = compileSimpleTypeNode(sNode, schemaNS, prefixes);
         const alias = {
-            name: pascal(name),
+            name: declarations.name(key),
             ns: schemaNS,
             tsType,
             declared,
@@ -373,19 +360,26 @@ export function compileCatalog(cat, options, streamConfig) {
         const k = qkey(q);
         return complexTypes.get(k);
     }
-    function getOrCompileComplex(name, cnode, schemaNS, prefixes) {
-        // Early cycle detection: check if we're already processing this raw name + namespace combo
-        // BEFORE calling pascal() to avoid stack overflow on circular references
-        const rawKey = `${schemaNS}|${name}`;
-        if (inProgress.has(rawKey)) {
-            // Return a minimal stub to break the cycle
-            const stubName = pascal(name);
-            return { name: stubName, ns: schemaNS, attrs: [], elems: [] };
+    function getOrCompileComplex(name, cnode, schemaNS, prefixes, declarationId = declarations.type(schemaNS, name)) {
+        const key = declarationId;
+        const outName = declarations.name(key);
+        const present = compiledMap.get(key);
+        if (present)
+            return present;
+        if (inProgress.has(key))
+            return { name: outName, ns: schemaNS, attrs: [], elems: [] };
+        inProgress.add(key);
+        try {
+            return compileComplexBody(cnode, schemaNS, prefixes, declarationId);
+        }
+        finally {
+            inProgress.delete(key);
         }
-        inProgress.add(rawKey);
-        const outName = pascal(name);
+    }
+    function compileComplexBody(cnode, schemaNS, prefixes, declarationId) {
+        const key = declarationId;
+        const outName = declarations.name(key);
         const typeDoc = extractAnnotationDocumentation(cnode);
-        const key = `${schemaNS}|${outName}`;
         // hoisted helpers for merging and collecting
         const mergeAttrs = (into, list) => {
             const idx = new Map();
@@ -415,40 +409,6 @@ export function compileCatalog(cat, options, streamConfig) {
                 }
             }
         };
-        const mergeChoiceGroups = (into, list) => {
-            if (list.length === 0)
-                return into;
-            const merged = into ? [...into] : [];
-            const idx = new Map();
-            merged.forEach((g, i) => idx.set(g.name, i));
-            for (const g of list) {
-                const pos = idx.get(g.name);
-                if (pos == null) {
-                    idx.set(g.name, merged.length);
-                    merged.push(g);
-                }
-                else {
-                    merged[pos] = g;
-                }
-            }
-            return merged;
-        };
-        const mergeJsonUnique = (into, list) => {
-            if (list.length === 0)
-                return into;
-            const merged = into ? [...into] : [];
-            const seen = new Set(merged.map((w) => JSON.stringify(w)));
-            for (const w of list) {
-                const key = JSON.stringify(w);
-                if (!seen.has(key)) {
-                    seen.add(key);
-                    merged.push(w);
-                }
-            }
-            return merged;
-        };
-        const mergeWildcards = (into, list) => mergeJsonUnique(into, list);
-        const mergeAttributeWildcards = (into, list) => mergeJsonUnique(into, list);
         const collectAttributes = (node) => {
             const out = [];
             const attrs = getChildrenWithLocalName(node, "attribute");
@@ -547,7 +507,7 @@ export function compileCatalog(cat, options, streamConfig) {
             }
             return out;
         };
-        const compileElementParticle = (ownerTypeName, e) => {
+        const compileElementParticle = (e) => {
             const nameOrRef = e["@_name"] || e["@_ref"];
             if (!nameOrRef)
                 return undefined;
@@ -557,8 +517,8 @@ export function compileCatalog(cat, options, streamConfig) {
             const inlineComplex = getFirstWithLocalName(e, "complexType");
             const inlineSimple = getFirstWithLocalName(e, "simpleType");
             if (inlineComplex) {
-                const inlineName = makeInlineTypeName(ownerTypeName, propName || nameOrRef, max);
-                const rec = getOrCompileComplex(inlineName, inlineComplex, schemaNS, prefixes);
+                const inlineId = declarations.inline(declarationId, e);
+                const rec = getOrCompileComplex(String(propName || nameOrRef), inlineComplex, schemaNS, prefixes, inlineId);
                 return {
                     name: propName || nameOrRef,
                     tsType: rec.name,
@@ -603,7 +563,7 @@ export function compileCatalog(cat, options, streamConfig) {
             });
             const recurse = (groupNode, inherited = one, inheritSequenceOccurs = true) => {
                 for (const e of getChildrenWithLocalName(groupNode, "element")) {
-                    const particle = compileElementParticle(ownerTypeName, e);
+                    const particle = compileElementParticle(e);
                     if (!particle)
                         continue;
                     // @constraints Preserve disabled particles until the content model can represent their absence (#145).
@@ -636,7 +596,7 @@ export function compileCatalog(cat, options, streamConfig) {
                         const branches = [];
                         let branchSourceOrder = 0;
                         for (const e of getChildrenWithLocalName(child.node, "element")) {
-                            const particle = compileElementParticle(ownerTypeName, e);
+                            const particle = compileElementParticle(e);
                             if (particle) {
                                 branches.push({
                                     name: particle.name,
@@ -672,29 +632,6 @@ export function compileCatalog(cat, options, streamConfig) {
             recurse(node);
             return out;
         };
-        const present = compiledMap.get(key);
-        if (present) {
-            // On duplicate definitions, merge new attributes and elements
-            const newAttrs = collectAttributes(cnode);
-            const newElems = collectParticles(outName, cnode);
-            const newWildcards = collectWildcards(cnode);
-            const newAttributeWildcards = collectAttributeWildcards(cnode);
-            const newChoiceGroups = collectChoiceGroups(outName, cnode);
-            mergeAttrs(present.attrs, newAttrs);
-            mergeElems(present.elems, newElems);
-            present.wildcards = mergeWildcards(present.wildcards, newWildcards);
-            present.attributeWildcards = mergeAttributeWildcards(present.attributeWildcards, newAttributeWildcards);
-            const mergedChoiceGroups = mergeChoiceGroups(present.choiceGroups, newChoiceGroups);
-            if (mergedChoiceGroups && mergedChoiceGroups.length > 0) {
-                present.choiceGroups = mergedChoiceGroups;
-            }
-            if (!present.doc && typeDoc) {
-                present.doc = typeDoc;
-            }
-            // Remove from inProgress since we're done with this cycle
-            inProgress.delete(rawKey);
-            return present;
-        }
         // result accumulators
         const attrs = [];
         const elems = [];
@@ -749,7 +686,6 @@ export function compileCatalog(cat, options, streamConfig) {
                     ...(localChoiceGroups.length > 0 ? { localChoiceGroups } : {}),
                 };
                 compiledMap.set(key, result);
-                inProgress.delete(key);
                 return result;
             }
         }
@@ -784,7 +720,6 @@ export function compileCatalog(cat, options, streamConfig) {
                     ...(attributeWildcards.length > 0 ? { attributeWildcards } : {}),
                 };
                 compiledMap.set(key, result);
-                inProgress.delete(rawKey);
                 return result;
             };
             if (ext) {
@@ -811,20 +746,19 @@ export function compileCatalog(cat, options, streamConfig) {
             ...(choiceGroups.length > 0 ? { choiceGroups } : {}),
         };
         compiledMap.set(key, result);
-        inProgress.delete(rawKey);
         return result;
     }
     // Helper: compile a global element into a surface type (wrapper)
     function compileElementAsType(name, enode, schemaNS, prefixes) {
-        const outName = pascal(name);
+        const key = declarations.surface(schemaNS, name);
+        const outName = declarations.name(key);
         const elementDoc = extractAnnotationDocumentation(enode);
-        const key = `${schemaNS}|${outName}`;
         const present = compiledMap.get(key);
         if (present)
             return present;
         const inlineComplex = getFirstWithLocalName(enode, "complexType");
         if (inlineComplex) {
-            return getOrCompileComplex(name, inlineComplex, schemaNS, prefixes);
+            return getOrCompileComplex(name, inlineComplex, schemaNS, prefixes, key);
         }
         const inlineSimple = getFirstWithLocalName(enode, "simpleType");
         if (inlineSimple) {
@@ -871,7 +805,7 @@ export function compileCatalog(cat, options, streamConfig) {
                     // record alias: ElementName -> BaseTypeName
                     const aliasKey = key;
                     const existingAlias = aliasMap.get(aliasKey);
-                    const declared = `{${base.ns}}${base.name}`;
+                    const declared = `{${base.ns}}${q.local}`;
                     if (!existingAlias) {
                         aliasMap.set(aliasKey, { name: outName, ns: schemaNS, tsType: base.name, declared, doc: elementDoc });
                     }
@@ -1138,9 +1072,10 @@ export function compileCatalog(cat, options, streamConfig) {
         const inputElement = elementOfMessage(inMsg);
         const outputElement = elementOfMessage(outMsg);
         const doc = extractDirectDocumentation(po);
-        // Derive TypeScript type names from element local names
-        const inputTypeName = inputElement ? pascal(inputElement.local) : undefined;
-        const outputTypeName = outputElement ? pascal(outputElement.local) : undefined;
+        const surfaceName = (element) => elements.has(qkey(element))
+            ? declarations.name(declarations.surface(element.ns, element.local)) : pascal(element.local);
+        const inputTypeName = inputElement ? surfaceName(inputElement) : undefined;
+        const outputTypeName = outputElement ? surfaceName(outputElement) : undefined;
         const op = {
             name,
             soapAction: bOps.get(name) || "",

package/dist/compiler/semanticCatalog.d.ts

@@ -58,8 +58,8 @@ export declare function deriveCompatibilityView(graph: CanonicalGraph): {
     model: "xsd10-faithful-v1";
     symbols: {
         id: string;
-        kind: "element" | "attribute" | "wsdl" | "complexType" | "simpleType" | "attributeWildcard" | "group" | "attributeGroup" | "particle" | "attributeUse" | "attributeGroupUse";
-        identity: import("./canonicalGraph.js").Identity;
+        kind: "element" | "attribute" | "wsdl" | "group" | "attributeGroup" | "complexType" | "simpleType" | "attributeWildcard" | "particle" | "attributeUse" | "attributeGroupUse";
+        identity: import("./declarationIdentity.js").Identity;
     }[];
 };
 /** Internal faithful companion dispatch. Regeneration never fabricates missing structure. */

package/dist/gateway/generateComposedGateway.d.ts

@@ -0,0 +1,16 @@
+export interface ComposedGatewayService {
+    key: string;
+    clientDir: string;
+    gatewayDir: string;
+    clientClassName: string;
+}
+/** Build a typed aggregate over independently generated service routers.
+ * @returns Complete generated source; the caller publishes it only after composition succeeds.
+ * @constraints Routes already carry generation-time prefixes. Runtime prefixing is refused to keep the served definition accurate.
+ */
+export declare function buildComposedGatewaySource(services: readonly ComposedGatewayService[], options: {
+    outDir: string;
+    openapiFile: string;
+    imports?: "js" | "ts" | "bare";
+    openapiPath?: string | false;
+}): string;

package/dist/gateway/generateComposedGateway.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { composeGeneratedSource, resolvePreamble } from "../generation/preamble.js";
+/** Build a typed aggregate over independently generated service routers.
+ * @returns Complete generated source; the caller publishes it only after composition succeeds.
+ * @constraints Routes already carry generation-time prefixes. Runtime prefixing is refused to keep the served definition accurate.
+ */
+export function buildComposedGatewaySource(services, options) {
+    const suffix = options.imports === "bare" ? "" : `.${options.imports ?? "js"}`;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+    const relative = (target) => {
+        const resolved = path.relative(options.outDir, target).replaceAll("\\", "/");
+        if (path.isAbsolute(resolved) || /^[a-z]:/i.test(resolved))
+            throw new Error("Composed outputs must share a filesystem root");
+        return resolved.startsWith(".") ? resolved : "./" + resolved;
+    };
+    const ordered = [...services].sort((a, b) => a.key.localeCompare(b.key));
+    const lines = [
+        'import type {FastifyPluginAsync} from "fastify";',
+        'import {types} from "node:util";',
+        `import definition from ${literal(relative(options.openapiFile))} with {type: "json"};`,
+        ...ordered.flatMap((service, index) => [
+            `import {${service.clientClassName} as Client${index}} from ${literal(relative(path.join(service.clientDir, "client" + suffix)))};`,
+            `import type {${service.clientClassName}Operations as Operations${index}} from ${literal(relative(path.join(service.clientDir, "operations" + suffix)))};`,
+            `import service${index} from ${literal(relative(path.join(service.gatewayDir, "plugin" + suffix)))};`,
+        ]),
+        "",
+        "export const openapi = definition;",
+        "export interface MultiServiceClients {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: Operations${index};`),
+        "}",
+        "export interface MultiServiceClientOptions {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: ConstructorParameters<typeof Client${index}>[0];`),
+        "}",
+        "export interface MultiServiceGatewayOptions {clients: MultiServiceClients}",
+        "function registry(value: unknown): void {",
+        '  if (!value || typeof value !== "object" || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError("Service registry must be a data object");',
+        `  const expected = ${literal(ordered.map(service => service.key))};`,
+        '  if (Reflect.ownKeys(value).length !== expected.length) throw new TypeError("Service registry must contain exactly the configured services");',
+        "  for (const key of expected) {",
+        "    const property = Object.getOwnPropertyDescriptor(value, key);",
+        '    if (!property || !Object.hasOwn(property, "value") || !property.value) throw new TypeError("Missing service registry value: " + key);',
+        "  }",
+        "}",
+        "",
+        "/** Bind each generated SOAP client to its own explicit runtime WSDL and options. */",
+        "export function createClients(options: MultiServiceClientOptions): {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: Client${index};`),
+        "} {",
+        "  registry(options);",
+        "  return {",
+        ...ordered.map((service, index) => `    ${literal(service.key)}: new Client${index}(options[${literal(service.key)}]),`),
+        "  };",
+        "}",
+        "",
+        "const plugin: FastifyPluginAsync<MultiServiceGatewayOptions> = async (fastify, options) => {",
+        '  if (fastify.prefix) throw new TypeError("Configure service OpenAPI basePath instead of a runtime aggregate prefix");',
+        "  registry(options.clients);",
+        ...ordered.map((service, index) => `  await fastify.register(async scope => {await scope.register(service${index}, {client: options.clients[${literal(service.key)}]});});`),
+        ...(options.openapiPath === false ? [] : [`  fastify.get(${literal(options.openapiPath ?? "/openapi.json")}, async () => openapi);`]),
+        "};",
+        "export default plugin;",
+        "",
+    ];
+    return composeGeneratedSource(lines.join("\n"), resolvePreamble("gateway"));
+}

package/dist/gateway/generateGateway.js

@@ -131,6 +131,7 @@ export async function generateGateway(opts) {
     }
     // Resolve client metadata for full handler generation
     const clientMeta = resolveClientMeta({
+        gatewayDir: opts.outDir,
         clientDir: opts.clientDir,
         catalogFile: opts.catalogFile,
         clientClassName: opts.clientClassName,

package/dist/gateway/generators.js

@@ -922,7 +922,7 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
             ? "toJsonArray"
             : "toNdjson";
         const runtimeImport = op.stream
-            ? `import { ${streamHelperName} } from "../runtime${suffix}";`
+            ? `import { ${streamHelperName}${hasUnwrap ? ", unwrapArrayWrappers" : ""} } from "../runtime${suffix}";`
             : hasUnwrap
                 ? `import { buildSuccessEnvelope, unwrapArrayWrappers } from "../runtime${suffix}";`
                 : `import { buildSuccessEnvelope } from "../runtime${suffix}";`;
@@ -942,9 +942,24 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
         const handlerBody = op.stream
             ? `    handler: async (request, reply) => {
       const client = fastify.${clientMeta.decoratorName};
-      const result = await client.${clientMethod}(${bodyArg});
-      reply.type(${JSON.stringify(op.stream.mediaType)});
-      return reply.send(${streamHelperName}(result.records));
+      const controller = new AbortController();
+      const disconnected = () => { if (!reply.raw.writableEnded) controller.abort(); };
+      request.raw.once("aborted", disconnected);
+      reply.raw.once("close", disconnected);
+      if (request.raw.aborted || reply.raw.destroyed) controller.abort();
+      try {
+        const result = await client.${clientMethod}(${bodyArg}, { signal: controller.signal });
+        reply.type(${JSON.stringify(op.stream.mediaType)});
+        ${hasUnwrap ? `async function* mappedRecords() {
+          for await (const record of result.records) yield unwrapArrayWrappers(record, ${JSON.stringify(op.stream.recordTypeName ?? "unknown")});
+        }
+        // @constraints Keep disconnect cancellation active until the response stream finishes.
+        return await reply.send(${streamHelperName}(mappedRecords()));` : `// @constraints Keep disconnect cancellation active until the response stream finishes.
+        return await reply.send(${streamHelperName}(result.records));`}
+      } finally {
+        request.raw.removeListener("aborted", disconnected);
+        reply.raw.removeListener("close", disconnected);
+      }
     },`
             : `    handler: async (request) => {
       const client = fastify.${clientMeta.decoratorName};

package/dist/gateway/helpers.d.ts

@@ -199,6 +199,7 @@ export interface ResolvedOperationMeta {
  * @property {"js"|"ts"|"bare"} importsMode - Import extension mode
  */
 export interface ResolveClientMetaOptions {
+    gatewayDir?: string;
     clientDir?: string;
     catalogFile?: string;
     clientClassName?: string;

package/dist/gateway/helpers.js

@@ -11,6 +11,7 @@
  * - Automatic version/service detection from OpenAPI paths
  */
 import { pascal, trimRepeatedEdgeChar } from "../util/tools.js";
+import path from "node:path";
 /**
  * Converts a name to a deterministic slug for use in file names and URN IDs
  *
@@ -393,6 +394,20 @@ export function resolveClientMeta(opts, catalog) {
     const operationsImportPath = opts.clientDir
         ? `../client/operations${suffix}`
         : `./client/operations${suffix}`;
+    const modulePath = (from, module) => {
+        const relative = path.relative(from, path.join(opts.clientDir, module + suffix)).replaceAll("\\", "/");
+        if (path.isAbsolute(relative) || /^[a-z]:/i.test(relative))
+            throw new Error("Generated client and gateway modules must share a filesystem root");
+        return relative.startsWith(".") ? relative : "./" + relative;
+    };
+    if (opts.clientDir && opts.gatewayDir)
+        return {
+            className, decoratorName,
+            importPath: modulePath(path.join(opts.gatewayDir, "routes"), "client"),
+            typesImportPath: modulePath(path.join(opts.gatewayDir, "routes"), "types"),
+            pluginImportPath: modulePath(opts.gatewayDir, "client"),
+            operationsImportPath: modulePath(opts.gatewayDir, "operations"),
+        };
     return {
         className,
         decoratorName,

package/dist/generation/componentShape.js

@@ -19,7 +19,31 @@ export function lowerComponentShape(contract, supplied, role, check) {
         const owned = inspectComponentRecordProjection(supplied, contract);
         return lowerComponentShape(owned.companion, owned.mapping, role, check);
     }
-    const { projection, applicationGroups } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    const { mapping, projection, applicationGroups, rpcParts } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    if ('parts' in mapping.root) {
+        const properties = Object.create(null);
+        const required = [], members = [];
+        for (const part of mapping.root.parts) {
+            check();
+            const plan = rpcParts?.find(plan => plan.name === part.name)?.projection;
+            let type = 'string';
+            if (plan?.root.kind === 'record') {
+                const record = plan.records[0];
+                const fields = Object.fromEntries(record.slots.map(slot => [slot.element.name.local, { type: 'boolean' }]));
+                properties[part.name] = { type: 'object', properties: fields, required: Object.keys(fields), additionalProperties: false };
+                type = `{${record.slots.map(slot => `readonly ${literal(slot.element.name.local)}: boolean`).join('; ')}}`;
+            }
+            else {
+                type = plan?.root.kind === 'scalar' && plan.root.builtin.local === 'boolean' ? 'boolean' : 'string';
+                properties[part.name] = { type };
+            }
+            required.push(part.name);
+            members.push(`readonly ${literal(part.name)}: ${type}`);
+        }
+        return { type: `{${members.join('; ')}}`, declarations: [], schema: { type: 'object', additionalProperties: false, properties, required } };
+    }
+    if (!projection)
+        throw new TypeError('Native document projection required');
     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);

package/dist/index.d.ts

@@ -5,6 +5,10 @@ export { buildSecurity, loadSecurityConfigFile, parseSecurityConfig, SecurityCon
 export { generateTests } from "./test/generateTests.js";
 export { runGenerationPipeline } from "./pipeline.js";
 export type { PipelineOptions } from './pipeline.js';
+export { runMultiServicePipeline, loadMultiServiceConfig } from './multiServicePipeline.js';
+export type { MultiServicePipelineOptions, MultiServicePipelineResult, MultiServiceEntry } from './multiServicePipeline.js';
+export { composeOpenApiDocuments } from './openapi/composeOpenAPI.js';
+export type { ComposedOpenApiDocument, OpenApiCompositionEntry, OpenApiCompositionOptions } from './openapi/composeOpenAPI.js';
 export type { CheckedComponentOptions, CheckedInventory } from './checkedPipeline.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export type { CheckedComponentPlan, ComponentPlanBlocker } from './checkedPlanning.js';

package/dist/index.js

@@ -27,6 +27,8 @@ 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 { runMultiServicePipeline, loadMultiServiceConfig } from './multiServicePipeline.js';
+export { composeOpenApiDocuments } from './openapi/composeOpenAPI.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, } from "./util/streamConfig.js";
 export { applyShapeCatalogs } from "./compiler/shapeResolver.js";

package/dist/loader/orderedSyntax.d.ts

@@ -70,6 +70,10 @@ export declare function resolveLexicalQName(lexical: string, node: SyntaxElement
 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 {
+    /** Explicit component SOAP response policy; source and shipped direct decoding remain separate. */
+    componentResponseEncoding?: {
+        charset?: string;
+    };
     /** Internal metadata boundary; payload/capsule callers retain the existing encoding policy. */
     metadataEncoding?: boolean;
     maxDepth?: number;

package/dist/loader/orderedSyntax.js

@@ -55,19 +55,33 @@ const xmlEncodingDeclaration = /^<\?xml\s[^?]*encoding\s*=\s*["']([^"']+)["']/i;
 export function decodeMetadataXml(bytes) {
     return decodeXml(bytes, true, true);
 }
-function decodeXml(bytes, strictBom = false, metadata = false) {
+function decodeXml(bytes, strictBom = false, metadata = false, response) {
     let encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
         : bytes[0] === 0xfe && bytes[1] === 0xff ? "utf-16be" : "utf-8";
     try {
         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 bom = encoding !== 'utf-8' || bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+        const canonical = (label) => label.toLowerCase() === 'utf8' ? 'utf-8' : label.toLowerCase();
+        const agrees = (label) => canonical(label) === encoding || canonical(label) === 'utf-16' && encoding.startsWith('utf-16');
+        if ((metadata || response) && !bom) {
             const end = buffer.indexOf('>');
             const declaration = xmlEncodingDeclaration.exec(buffer.toString('latin1', 0, end < 0 ? 0 : end + 1))?.[1].toLowerCase();
-            if (declaration === 'iso-8859-1')
+            if (response) {
+                const asserted = response.charset ?? declaration;
+                if (asserted) {
+                    const selected = canonical(asserted);
+                    if (!['utf-8', 'iso-8859-1'].includes(selected))
+                        throw new SchemaLoadingError('unsupported-capability', 'Unsupported XML byte encoding');
+                    encoding = selected;
+                }
+            }
+            else if (declaration === 'iso-8859-1')
                 encoding = 'iso-8859-1';
         }
+        if (response?.charset && !agrees(response.charset))
+            throw new SchemaLoadingError('unsupported-capability', 'HTTP charset disagrees with XML bytes');
         // 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'))
@@ -107,7 +121,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 = options.metadataEncoding ? decodeMetadataXml(bytes) : decodeXml(bytes, options.xml10Only);
+    const text = options.metadataEncoding ? decodeMetadataXml(bytes) : decodeXml(bytes, options.xml10Only, false, options.componentResponseEncoding);
     const lines = [0];
     for (let i = 0; i < text.length; i++) {
         if (text[i] === "\r") {

package/dist/multiServicePipeline.d.ts

@@ -0,0 +1,41 @@
+import { type PipelineOptions } from "./pipeline.js";
+import { type ComposedOpenApiDocument, type OpenApiCompositionOptions } from "./openapi/composeOpenAPI.js";
+import type { CompiledCatalog } from "./compiler/schemaCompiler.js";
+export interface MultiServiceEntry {
+    key: string;
+    generation: PipelineOptions;
+}
+export interface MultiServicePipelineOptions {
+    services: readonly MultiServiceEntry[];
+    openapi: OpenApiCompositionOptions & {
+        outFile: string;
+    };
+    gateway: {
+        outDir: string;
+        imports?: "js" | "ts" | "bare";
+        openapiPath?: string | false;
+    };
+}
+export interface MultiServicePipelineResult {
+    openapiDoc: ComposedOpenApiDocument;
+    services: Record<string, {
+        compiled: CompiledCatalog;
+        clientDir: string;
+        gatewayDir: string;
+    }>;
+    pluginFile: string;
+    openapiFile: string;
+}
+/** Generate independent WSDL clients behind one typed gateway and discoverable API definition.
+ * @param options Explicit per-service pipelines and disjoint aggregate output paths.
+ * @returns Matched aggregate artifacts and each service's unmerged compiled catalog.
+ * @throws For configuration/output conflicts, source generation failures or invalid API composition.
+ * @sideEffects Generates each selected legacy service in caller order, then publishes the aggregate spec/plugin pair.
+ * @constraints Failure preserves previous aggregate spec/plugin files; earlier generated service dependencies are not rolled back.
+ */
+export declare function runMultiServicePipeline(options: MultiServicePipelineOptions): Promise<MultiServicePipelineResult>;
+/** Load a composition config with paths resolved against its own directory.
+ * @throws For invalid JSON or missing required output/source paths when the pipeline validates it.
+ * @constraints Runtime client options and credentials are deliberately not generation configuration.
+ */
+export declare function loadMultiServiceConfig(file: string): Promise<MultiServicePipelineOptions>;