@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

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

package/dist/loader/schemaResources.js

@@ -90,7 +90,7 @@ export class SchemaResourceLoader {
         if (offline)
             for (const [uri, value] of offline) {
                 charge?.(256 + uri.length * 32);
-                snapshots.set(resolveResourceUri(uri), { bytes: value.bytes, digest: value.digest });
+                snapshots.set(resolveResourceUri(uri), { bytes: value.bytes, digest: value.digest, canonicalUri: value.canonicalUri });
             }
         return new SchemaResourceLoader(roots, [...configuredRoots, ...roots], origins, loadingLimits(overrides), snapshots, charge, signal);
     }
@@ -101,6 +101,7 @@ export class SchemaResourceLoader {
     get metrics() {
         return Object.freeze({ resources: this.resources.size, totalBytes: this.totalBytes, ioMs: this.ioMs });
     }
+    get resourceAliases() { return new Map(this.aliases); }
     async authorize(uri) {
         this.charge?.(1024 + uri.length * 32 + this.roots.length * 256);
         const url = new URL(resolveResourceUri(uri));
@@ -170,10 +171,46 @@ export class SchemaResourceLoader {
                     chunks.push(Uint8Array.from(chunk));
                 };
                 if (this.offline) {
-                    checkResourceCount();
                     const snapshot = this.offline.get(uri);
                     if (!snapshot)
                         throw new SchemaLoadingError("transport", "Schema resource is absent from the offline snapshot");
+                    if (snapshot.bytes.byteLength > this.limits.resourceBytes)
+                        throw new SchemaLoadingError('resource-limit', 'Decompressed schema byte budget exceeded');
+                    const snapshotDigest = (value) => {
+                        if (controller.signal.aborted || performance.now() - started > budget)
+                            throw new SchemaLoadingError('transport', 'Schema I/O deadline exceeded');
+                        this.charge?.(64 + value.bytes.byteLength * 8);
+                        return createHash('sha256').update(value.bytes).digest('hex');
+                    };
+                    if (snapshot.canonicalUri) {
+                        if (new URL(uri).protocol !== 'file:' && new URL(resolveResourceUri(snapshot.canonicalUri)).protocol === 'file:')
+                            throw new SchemaLoadingError('unsupported-capability', 'Remote metadata cannot select local resources');
+                        const canonical = await this.authorize(snapshot.canonicalUri);
+                        const target = this.offline.get(canonical);
+                        if (target && (target.digest !== snapshot.digest || target.bytes.byteLength !== snapshot.bytes.byteLength)) {
+                            throw new SchemaLoadingError('invalid-schema', 'Conflicting offline alias bytes');
+                        }
+                        if (target) {
+                            if (target.bytes.byteLength > this.limits.resourceBytes)
+                                throw new SchemaLoadingError('resource-limit', 'Decompressed schema byte budget exceeded');
+                            if (snapshotDigest(target) !== target.digest)
+                                throw new SchemaLoadingError('invalid-schema', 'Offline schema digest mismatch');
+                            if (target.canonicalUri && resolveResourceUri(target.canonicalUri) !== canonical)
+                                throw new SchemaLoadingError('unsupported-capability', 'Offline aliases must name a canonical snapshot');
+                        }
+                        uri = canonical;
+                        redirectAliases.push(uri);
+                        const cached = this.resources.get(this.resourceKeys.get(uri) ?? '');
+                        if (cached) {
+                            if (snapshot.digest !== cached.digest || snapshotDigest(snapshot) !== snapshot.digest) {
+                                throw new SchemaLoadingError('invalid-schema', 'Conflicting offline alias bytes');
+                            }
+                            for (const alias of redirectAliases)
+                                this.aliases.set(alias, uri);
+                            return cached;
+                        }
+                    }
+                    checkResourceCount();
                     accept(snapshot.bytes);
                     const digest = createHash("sha256").update(snapshot.bytes).digest("hex");
                     if (digest !== snapshot.digest)
@@ -188,6 +225,9 @@ export class SchemaResourceLoader {
                     try {
                         if (!(await file.stat()).isFile())
                             throw new SchemaLoadingError("unsupported-capability", "Schema resource must be a regular file");
+                        // @why Cancellation during metadata I/O must not construct an already-aborted stream that can emit outside iterator handling.
+                        if (controller.signal.aborted)
+                            throw new SchemaLoadingError("transport", "Schema resource I/O cancelled");
                         const stream = file.createReadStream({ autoClose: false, signal: controller.signal });
                         try {
                             for await (const chunk of stream)
@@ -211,9 +251,10 @@ export class SchemaResourceLoader {
                             const location = response.headers.get("location");
                             if (!location)
                                 throw new SchemaLoadingError("transport", "Schema redirect has no location");
-                            uri = await this.authorize(resolveResourceUri(location, uri));
-                            if (new URL(uri).protocol === "file:")
+                            const redirected = resolveResourceUri(location, uri);
+                            if (new URL(redirected).protocol === "file:")
                                 throw new SchemaLoadingError("unsupported-capability", "HTTP redirects cannot select file resources");
+                            uri = await this.authorize(redirected);
                             redirectAliases.push(uri);
                             const redirectedCache = this.resources.get(this.resourceKeys.get(this.aliases.get(uri) ?? uri) ?? "");
                             if (redirectedCache) {

package/dist/loader/wsdlLoader.d.ts

@@ -43,4 +43,3 @@ export type WsdlCatalog = {
  * @throws {Error} - If the document is not a valid WSDL 1.1 file
  */
 export declare function loadWsdl(wsdlUrlOrPath: string): Promise<WsdlCatalog>;
-//# sourceMappingURL=wsdlLoader.d.ts.map

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>;

package/dist/multiServicePipeline.js

@@ -0,0 +1,287 @@
+import fs from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { types } from "node:util";
+import { fileURLToPath } from "node:url";
+import { runGenerationPipeline } from "./pipeline.js";
+import { composeOpenApiDocuments } from "./openapi/composeOpenAPI.js";
+import { buildComposedGatewaySource } from "./gateway/generateComposedGateway.js";
+import { deriveClientName } from "./util/tools.js";
+import { slugName } from "./gateway/helpers.js";
+const data = (value, label) => {
+    if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value)))
+        throw new TypeError(`${label} must be a data object`);
+    for (const property of Object.values(Object.getOwnPropertyDescriptors(value)))
+        if (!Object.hasOwn(property, "value"))
+            throw new TypeError(`${label} must not contain accessors`);
+    return value;
+};
+const text = (value, label) => {
+    if (typeof value !== "string" || !value.trim())
+        throw new TypeError(`${label} must be a nonempty string`);
+    return value;
+};
+const known = (value, allowed, label) => {
+    for (const key of Reflect.ownKeys(value))
+        if (typeof key !== "string" || !allowed.includes(key))
+            throw new TypeError(`Unknown ${label} option: ${String(key)}`);
+};
+const localPath = (value, label) => {
+    // @why Lexically different output paths can share a symlink/junction target; ownership checks must compare their filesystem destinations.
+    let ancestor = path.resolve(text(value, label));
+    const missing = [];
+    while (!existsSync(ancestor)) {
+        missing.unshift(path.basename(ancestor));
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw new TypeError(`Cannot resolve output filesystem root for ${label}`);
+        ancestor = parent;
+    }
+    return path.join(realpathSync(ancestor), ...missing);
+};
+const canonical = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+const within = (directory, file) => {
+    const relative = path.relative(canonical(directory), canonical(file));
+    return relative === "" || relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+};
+const prefix = (value) => {
+    const result = text(value, "generation.openapi.basePath");
+    if (!/^\/(?:[a-zA-Z0-9._~-]+\/)*[a-zA-Z0-9._~-]+$/.test(result) || result.split("/").some(segment => segment === "." || segment === ".."))
+        throw new TypeError("Each service needs an explicit static OpenAPI basePath without trailing slash");
+    return result;
+};
+function prepare(options) {
+    const input = data(options, "composition");
+    if (Object.keys(input).some(key => !["services", "openapi", "gateway"].includes(key)))
+        throw new TypeError("Unknown multi-service composition option");
+    if (!Array.isArray(options.services) || options.services.length === 0)
+        throw new TypeError("At least one independent service is required");
+    known(data(options.openapi, "aggregate OpenAPI"), ["outFile", "title", "version", "description", "servers"], "aggregate OpenAPI");
+    known(data(options.gateway, "aggregate gateway"), ["outDir", "imports", "openapiPath"], "aggregate gateway");
+    for (const name of ["title", "version", "description"])
+        if (options.openapi[name] !== undefined && typeof options.openapi[name] !== "string")
+            throw new TypeError(`openapi.${name} must be a string`);
+    if (options.openapi.servers !== undefined && (!Array.isArray(options.openapi.servers) || options.openapi.servers.some(server => typeof server !== "string" || !server)))
+        throw new TypeError("openapi.servers must contain server URL strings");
+    const outFile = localPath(options.openapi.outFile, "openapi.outFile");
+    if (path.extname(outFile).toLowerCase() !== ".json")
+        throw new TypeError("The aggregate OpenAPI output must be a JSON file");
+    const gatewayDir = localPath(options.gateway.outDir, "gateway.outDir");
+    if (options.gateway.imports !== undefined && !["js", "ts", "bare"].includes(options.gateway.imports))
+        throw new TypeError("Invalid aggregate import extension mode");
+    const openapiPath = options.gateway.openapiPath === false ? false : options.gateway.openapiPath ?? "/openapi.json";
+    if (openapiPath !== false && (!/^\/[^?#\\]*$/.test(openapiPath) || openapiPath.includes("//")))
+        throw new TypeError("Invalid OpenAPI discovery path");
+    const keys = new Set(), slugs = new Set(), decorators = new Set(), prefixes = new Set();
+    const outputs = [
+        { owner: "aggregate", role: "gateway", file: gatewayDir, directory: true },
+        { owner: "aggregate", role: "openapi", file: outFile, directory: false },
+    ];
+    const entries = options.services.map(entry => {
+        data(entry, "service entry");
+        if (Object.keys(entry).some(key => !["key", "generation"].includes(key)))
+            throw new TypeError("Unknown service entry option");
+        const key = text(entry.key, "service key");
+        if (!/^[a-z][a-z0-9-]*$/.test(key) || keys.has(key))
+            throw new TypeError("Unique lowercase service keys required");
+        keys.add(key);
+        const generation = data(entry.generation, `generation for ${key}`);
+        known(generation, ["model", "checkedComponents", "wsdl", "catalogOut", "clientOutDir", "compiler", "openapi", "gateway", "app", "test", "streamConfigFile", "streamConfig"], "service generation");
+        if (generation.model !== undefined && generation.model !== "legacy" || generation.checkedComponents !== undefined || generation.app !== undefined || generation.test !== undefined)
+            throw new TypeError("Multi-service generation currently composes legacy service routers; app/test/checked settings are not aggregate settings");
+        text(generation.wsdl, `${key}.wsdl`);
+        if (!generation.openapi || !generation.gateway)
+            throw new TypeError(`Service ${key} requires OpenAPI and gateway generation`);
+        data(generation.openapi, "service OpenAPI");
+        data(generation.gateway, "service gateway");
+        const basePath = prefix(generation.openapi.basePath);
+        if (prefixes.has(basePath))
+            throw new TypeError(`Duplicate service basePath ${basePath}`);
+        prefixes.add(basePath);
+        const clientDir = localPath(generation.clientOutDir, `${key}.clientOutDir`);
+        const catalogOut = localPath(generation.catalogOut, `${key}.catalogOut`);
+        const serviceOpenapi = localPath(generation.openapi.outFile, `${key}.openapi.outFile`);
+        const serviceGateway = localPath(generation.gateway.outDir, `${key}.gateway.outDir`);
+        if (!slugName(text(generation.gateway.versionSlug, `${key}.gateway.versionSlug`)))
+            throw new TypeError("A normalized gateway version slug is required");
+        const slug = slugName(text(generation.gateway.serviceSlug, `${key}.gateway.serviceSlug`));
+        if (!slug || slugs.has(slug))
+            throw new TypeError("Gateway service slugs must remain unique after normalization");
+        slugs.add(slug);
+        const decorator = generation.gateway.clientDecoratorName ?? `wsdl_${key.replaceAll("-", "_")}Client`;
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(decorator) || decorators.has(decorator))
+            throw new TypeError("Unique valid client decorators required");
+        decorators.add(decorator);
+        if (generation.gateway.emitPlugin === false || generation.gateway.stubHandlers === true || generation.gateway.emitRuntime === false)
+            throw new TypeError("Composition requires complete service plugins and runtime handlers");
+        for (const target of [clientDir, serviceGateway])
+            if (path.parse(target).root !== path.parse(gatewayDir).root)
+                throw new TypeError("Composed generated modules must share a filesystem root");
+        outputs.push({ owner: key, role: "client", file: clientDir, directory: true }, { owner: key, role: "gateway", file: serviceGateway, directory: true }, { owner: key, role: "catalog", file: catalogOut, directory: false }, { owner: key, role: "openapi", file: serviceOpenapi, directory: false });
+        return { key, generation: { ...generation, catalogOut, clientOutDir: clientDir,
+                openapi: { ...generation.openapi, basePath, outFile: serviceOpenapi },
+                gateway: { ...generation.gateway, outDir: serviceGateway, clientDecoratorName: decorator } } };
+    });
+    for (let a = 0; a < outputs.length; a++)
+        for (let b = a + 1; b < outputs.length; b++) {
+            const left = outputs[a], right = outputs[b];
+            if (canonical(left.file) === canonical(right.file))
+                throw new TypeError(`Conflicting output paths: ${left.role} and ${right.role}`);
+            const overlap = left.directory && within(left.file, right.file) || right.directory && within(right.file, left.file);
+            if (overlap && (left.owner !== right.owner || left.directory && right.directory))
+                throw new TypeError("Service output ownership must not overlap");
+            const file = left.directory ? right : left, directory = left.directory ? left : right;
+            if (overlap && !file.directory && directory.directory) {
+                const relative = path.relative(directory.file, file.file).replaceAll("\\", "/");
+                if (relative.endsWith(".ts") || /^(?:routes|schemas)(?:\/|$)/.test(relative))
+                    throw new TypeError("Output file conflicts with generated service modules");
+            }
+        }
+    for (const entry of entries) {
+        const source = entry.generation.wsdl;
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source) && !source.startsWith("file:"))
+            continue;
+        const sourceFile = localPath(source.startsWith("file:") ? fileURLToPath(source) : source, "source WSDL");
+        if (outputs.some(output => output.directory ? within(output.file, sourceFile) : canonical(output.file) === canonical(sourceFile)))
+            throw new TypeError("Source WSDLs must remain outside generated output ownership");
+    }
+    return { entries, outFile, gatewayDir, openapiPath };
+}
+/** Publish the matched spec/plugin after all service generation and composition checks succeed.
+ * @constraints Uses only individually owned staging files; never removes a consumer output tree.
+ */
+async function publish(files) {
+    const staged = [];
+    try {
+        for (const { file, content } of files) {
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            let previous;
+            try {
+                previous = await fs.readFile(file);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const temporary = file + ".stage-" + randomUUID();
+            staged.push({ file, temporary, previous, committed: false });
+            await fs.writeFile(temporary, content, { flag: "wx" });
+        }
+        for (const entry of staged) {
+            await fs.rename(entry.temporary, entry.file);
+            entry.committed = true;
+        }
+    }
+    catch (error) {
+        for (const entry of [...staged].reverse())
+            if (entry.committed) {
+                if (entry.previous === undefined)
+                    await fs.unlink(entry.file);
+                else
+                    await fs.writeFile(entry.file, entry.previous);
+            }
+        throw error;
+    }
+    finally {
+        for (const entry of staged)
+            await fs.unlink(entry.temporary).catch(error => { if (error.code !== "ENOENT")
+                throw error; });
+    }
+}
+/** 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 async function runMultiServicePipeline(options) {
+    const prepared = prepare(options);
+    const services = Object.create(null);
+    const documents = [];
+    const routers = [];
+    for (const { key, generation } of prepared.entries) {
+        const result = await runGenerationPipeline(generation);
+        const compiled = result.compiled;
+        const fileSlugs = new Set();
+        const expectedOperations = new Set(compiled.operations.map(operation => operation.name));
+        if (expectedOperations.size !== compiled.operations.length)
+            throw new TypeError(`Service ${key} has overloaded operation names that cannot own unique gateway routes`);
+        for (const operation of compiled.operations) {
+            const slug = slugName(operation.name);
+            if (!slug || fileSlugs.has(slug))
+                throw new TypeError(`Service ${key} has colliding generated operation filenames`);
+            fileSlugs.add(slug);
+        }
+        const described = [];
+        const document = data(result.openapiDoc, "generated OpenAPI");
+        for (const item of Object.values(data(document.paths, "generated paths"))) {
+            const pathItem = data(item, "generated path item");
+            for (const method of ["get", "put", "post", "delete", "options", "head", "patch", "trace"]) {
+                if (pathItem[method] !== undefined)
+                    described.push(text(data(pathItem[method], "generated operation").operationId, "operationId"));
+            }
+        }
+        if (described.length !== expectedOperations.size || described.some(name => !expectedOperations.has(name)))
+            throw new TypeError(`Service ${key} loses operations through generated route collisions`);
+        const className = deriveClientName(compiled);
+        if (generation.gateway.clientClassName && generation.gateway.clientClassName !== className)
+            throw new TypeError("Configure compiler.clientName to keep client and gateway classes matched");
+        services[key] = { compiled, clientDir: generation.clientOutDir, gatewayDir: generation.gateway.outDir };
+        documents.push({ key, document: result.openapiDoc });
+        routers.push({ key, clientDir: generation.clientOutDir, gatewayDir: generation.gateway.outDir, clientClassName: className });
+    }
+    const openapiDoc = composeOpenApiDocuments(documents, options.openapi);
+    const { default: SwaggerParser } = await import("@apidevtools/swagger-parser");
+    const validator = new SwaggerParser();
+    await validator.validate(structuredClone(openapiDoc), { resolve: { external: false } });
+    if (prepared.openapiPath !== false && Object.hasOwn(openapiDoc.paths, prepared.openapiPath))
+        throw new TypeError("OpenAPI discovery path conflicts with a service route");
+    const pluginFile = path.join(prepared.gatewayDir, "plugin.ts");
+    const source = buildComposedGatewaySource(routers, { outDir: prepared.gatewayDir, openapiFile: prepared.outFile,
+        imports: options.gateway.imports, openapiPath: prepared.openapiPath });
+    await publish([{ file: prepared.outFile, content: JSON.stringify(openapiDoc, null, 2) + "\n" }, { file: pluginFile, content: source }]);
+    return { openapiDoc, services, pluginFile, openapiFile: prepared.outFile };
+}
+/** 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 async function loadMultiServiceConfig(file) {
+    const absolute = path.resolve(file), base = path.dirname(absolute);
+    const options = JSON.parse(await fs.readFile(absolute, "utf8"));
+    data(options, "composition");
+    data(options.openapi, "aggregate OpenAPI");
+    data(options.gateway, "aggregate gateway");
+    if (!Array.isArray(options.services))
+        throw new TypeError("services must be an array");
+    const resolve = (value) => value === undefined ? undefined : path.resolve(base, text(value, "config path"));
+    const source = (value) => /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : resolve(value);
+    options.openapi.outFile = resolve(options.openapi.outFile);
+    options.gateway.outDir = resolve(options.gateway.outDir);
+    for (const entry of options.services) {
+        data(entry, "service");
+        const generation = data(entry.generation, "generation");
+        generation.wsdl = source(text(generation.wsdl, "wsdl"));
+        generation.catalogOut = resolve(generation.catalogOut);
+        generation.clientOutDir = resolve(generation.clientOutDir);
+        generation.streamConfigFile = resolve(generation.streamConfigFile);
+        if (generation.openapi) {
+            generation.openapi.outFile = resolve(generation.openapi.outFile);
+            generation.openapi.tagsFile = resolve(generation.openapi.tagsFile);
+            generation.openapi.opsFile = resolve(generation.openapi.opsFile);
+            generation.openapi.securityConfigFile = resolve(generation.openapi.securityConfigFile);
+        }
+        if (generation.gateway)
+            generation.gateway.outDir = resolve(generation.gateway.outDir);
+        if (generation.streamConfig)
+            for (const shape of Object.values(generation.streamConfig.shapeCatalogs)) {
+                if (shape.catalogFile)
+                    shape.catalogFile = resolve(shape.catalogFile);
+                if (shape.wsdlSource)
+                    shape.wsdlSource = source(shape.wsdlSource);
+            }
+    }
+    return options;
+}

package/dist/openapi/casing.d.ts

@@ -21,4 +21,3 @@ export type PathStyle = "kebab" | "asis" | "lower";
  * @returns {string} - Formatted path segment
  */
 export declare function toPathSegment(name: string, style: PathStyle): string;
-//# sourceMappingURL=casing.d.ts.map

package/dist/openapi/composeOpenAPI.d.ts

@@ -0,0 +1,29 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export interface ComposedOpenApiDocument extends JsonObject {
+    openapi: string;
+    info: JsonObject;
+    paths: Record<string, JsonObject>;
+    components: Record<string, Record<string, JsonValue>>;
+}
+export interface OpenApiCompositionOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: readonly string[];
+}
+export interface OpenApiCompositionEntry {
+    key: string;
+    document: unknown;
+}
+/** Compose service-scoped OpenAPI contracts without changing SOAP client ownership.
+ * @param entries Self-contained OpenAPI 3.1 documents whose HTTP paths already contain their service prefixes.
+ * @param options Combined API metadata and default gateway servers; custom source servers remain operation-local.
+ * @returns A fresh deterministic document with qualified component names and operation identifiers.
+ * @throws For invalid JSON, duplicate service keys/paths/operation IDs, unresolved local references or unsupported relative references/schema resources.
+ * @constraints Only reference-bearing OpenAPI/JSON Schema positions are rewritten; examples, literal values and extensions remain data.
+ * @see https://spec.openapis.org/oas/v3.1.0.html Reference, Link, Security Requirement and Schema objects govern distinct reference positions.
+ */
+export declare function composeOpenApiDocuments(entries: readonly OpenApiCompositionEntry[], options?: OpenApiCompositionOptions): ComposedOpenApiDocument;