@techspokes/typescript-wsdl-client 1.1.8 → 1.3.0

package/dist/openapi/composeOpenAPI.js

@@ -0,0 +1,322 @@
+import { types } from "node:util";
+const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+const categories = {
+    schemas: "schema", responses: "response", parameters: "parameter", examples: "example",
+    requestBodies: "requestBody", headers: "header", securitySchemes: "securityScheme", links: "link",
+    callbacks: "callback", pathItems: "pathItem",
+};
+const dict = () => Object.create(null);
+const record = (value, context) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${context} must be an object`);
+    return value;
+};
+const items = (value, context) => {
+    if (!Array.isArray(value))
+        throw new TypeError(`${context} must be an array`);
+    return value;
+};
+const pointerToken = (value) => value.replaceAll("~", "~0").replaceAll("/", "~1");
+/** Copy JSON data without invoking accessors or sharing mutable source objects.
+ * @throws For non-JSON values, accessors, proxies, sparse arrays or cycles.
+ */
+function copyJson(value, active = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (!value || typeof value !== "object" || types.isProxy(value) || active.has(value))
+        throw new TypeError("Actual acyclic JSON data required");
+    if (!Array.isArray(value) && ![null, Object.prototype].includes(Object.getPrototypeOf(value)))
+        throw new TypeError("Plain JSON objects required");
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Reflect.ownKeys(value).length !== value.length + 1)
+                throw new TypeError("Dense JSON arrays required");
+            return Array.from({ length: value.length }, (_, index) => {
+                const property = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!property || !Object.hasOwn(property, "value"))
+                    throw new TypeError("JSON array data properties required");
+                return copyJson(property.value, active);
+            });
+        }
+        const result = dict();
+        for (const key of Reflect.ownKeys(value)) {
+            const property = Object.getOwnPropertyDescriptor(value, key);
+            if (typeof key !== "string" || !property.enumerable || !Object.hasOwn(property, "value"))
+                throw new TypeError("JSON object data properties required");
+            result[key] = copyJson(property.value, active);
+        }
+        return result;
+    }
+    finally {
+        active.delete(value);
+    }
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+}
+/** 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 function composeOpenApiDocuments(entries, options = {}) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        throw new TypeError("At least one service document is required");
+    const input = items(copyJson(entries), "services");
+    const keys = new Set();
+    const paths = dict();
+    const components = dict();
+    const webhooks = dict();
+    const tags = dict();
+    const services = dict();
+    const rootServers = options.servers?.map(url => ({ url })) ?? [{ url: "/" }];
+    let dialect;
+    for (const entry of input.map(value => record(value, "service")).sort((left, right) => String(left.key).localeCompare(String(right.key)))) {
+        const key = entry.key;
+        if (typeof key !== "string" || !/^[a-z][a-z0-9-]*$/.test(key) || keys.has(key))
+            throw new TypeError("Unique lowercase service keys required");
+        keys.add(key);
+        const source = record(entry.document, `service ${key}`);
+        if (typeof source.openapi !== "string" || !/^3\.1\.\d+$/.test(source.openapi))
+            throw new TypeError("OpenAPI 3.1 documents required");
+        record(source.info, "OpenAPI info");
+        const sourcePaths = record(source.paths, "OpenAPI paths");
+        const sourceComponents = source.components === undefined ? dict() : record(source.components, "OpenAPI components");
+        const sourceDialect = source.jsonSchemaDialect ?? "https://spec.openapis.org/oas/3.1/dialect/base";
+        if (typeof sourceDialect !== "string" || dialect !== undefined && dialect !== sourceDialect)
+            throw new TypeError("Source schema dialects must agree");
+        dialect = sourceDialect;
+        const qualified = (name) => `${key}__${name}`;
+        const operationIds = new Map();
+        const operationNodes = new Set();
+        const sourceRootServers = source.servers === undefined ? undefined : items(source.servers, "servers");
+        const defaultSourceServer = JSON.stringify(sourceRootServers) === '[{"url":"/"}]';
+        const effectiveServers = options.servers && defaultSourceServer ? undefined : sourceRootServers;
+        const defaultSecurity = source.security;
+        function resolve(tokens, reference) {
+            let target = source;
+            for (const token of tokens) {
+                if (!target || typeof target !== "object" || !Object.hasOwn(target, token))
+                    throw new TypeError(`Unresolved local reference ${reference} in ${key}`);
+                target = target[token];
+            }
+            return target;
+        }
+        function reference(value, operation = false) {
+            if (typeof value !== "string" || value.length === 0)
+                throw new TypeError("Reference must be a nonempty string");
+            if (!value.startsWith("#")) {
+                try {
+                    new URL(value);
+                }
+                catch {
+                    throw new TypeError(`Relative external references need resolution before composition: ${value}`);
+                }
+                return value;
+            }
+            let fragment;
+            try {
+                fragment = decodeURIComponent(value.slice(1));
+            }
+            catch {
+                throw new TypeError(`Invalid reference ${value}`);
+            }
+            if (!fragment.startsWith("/") || /~(?![01])/u.test(fragment))
+                throw new TypeError(`Unsupported local reference ${value}`);
+            const tokens = fragment.slice(1).split("/").map(token => token.replaceAll("~1", "/").replaceAll("~0", "~"));
+            const target = resolve(tokens, value);
+            if (operation && (!target || typeof target !== "object" || Array.isArray(target) || !operationNodes.has(target)))
+                throw new TypeError(`operationRef does not resolve to an operation: ${value}`);
+            if (tokens[0] === "components" && tokens.length >= 3)
+                tokens[2] = qualified(tokens[2]);
+            else if (tokens[0] === "webhooks" && tokens.length >= 2)
+                tokens[1] = qualified(tokens[1]);
+            else if (tokens[0] !== "paths")
+                throw new TypeError(`Reference target cannot be retained during composition: ${value}`);
+            return "#/" + tokens.map(token => encodeURIComponent(pointerToken(token))).join("/");
+        }
+        function security(value) {
+            return items(value, "security").map(requirement => Object.fromEntries(Object.entries(record(requirement, "security requirement")).map(([name, scopes]) => {
+                if (!Object.hasOwn(record(sourceComponents.securitySchemes, "securitySchemes"), name))
+                    throw new TypeError(`Missing security scheme ${name}`);
+                if (!items(scopes, "security scopes").every(scope => typeof scope === "string"))
+                    throw new TypeError("Security scopes must be strings");
+                return [qualified(name), scopes];
+            })));
+        }
+        function map(value, kind, scan, extensions = false) {
+            return Object.fromEntries(Object.entries(record(value, `${kind} map`)).map(([name, child]) => [name,
+                extensions && name.startsWith("x-") ? child : walk(child, kind, scan)]));
+        }
+        function walk(value, kind, scan, inheritedServers = effectiveServers) {
+            if (kind === "data")
+                return value;
+            if (kind === "schema" && typeof value === "boolean")
+                return value;
+            const node = record(value, kind);
+            const out = { ...node };
+            if (kind === "operation" && scan) {
+                operationNodes.add(node);
+                if (node.operationId !== undefined) {
+                    if (typeof node.operationId !== "string" || !node.operationId || operationIds.has(node.operationId))
+                        throw new TypeError(`Duplicate or invalid operationId in ${key}`);
+                    operationIds.set(node.operationId, node);
+                }
+            }
+            if (Object.hasOwn(node, "$ref") && !scan)
+                out.$ref = reference(node.$ref);
+            const array = (name, childKind) => { if (node[name] !== undefined)
+                out[name] = items(node[name], name).map(child => walk(child, childKind, scan)); };
+            const child = (name, childKind) => { if (node[name] !== undefined)
+                out[name] = walk(node[name], childKind, scan); };
+            const keyed = (name, childKind, extensions = false) => { if (node[name] !== undefined)
+                out[name] = map(node[name], childKind, scan, extensions); };
+            if (kind === "schema") {
+                if (["$id", "$anchor", "$dynamicAnchor", "$vocabulary"].some(name => Object.hasOwn(node, name)))
+                    throw new TypeError("Resolve schema resources/anchors before OpenAPI composition");
+                if (node.$dynamicRef !== undefined && !scan)
+                    out.$dynamicRef = reference(node.$dynamicRef);
+                for (const name of ["properties", "patternProperties", "dependentSchemas", "$defs", "definitions"])
+                    keyed(name, "schema");
+                for (const name of ["allOf", "anyOf", "oneOf", "prefixItems"])
+                    array(name, "schema");
+                for (const name of ["items", "contains", "additionalProperties", "unevaluatedProperties", "unevaluatedItems", "propertyNames", "not", "if", "then", "else", "additionalItems"])
+                    child(name, "schema");
+                if (node.discriminator !== undefined && !scan) {
+                    const discriminator = record(node.discriminator, "discriminator");
+                    const mapping = discriminator.mapping;
+                    if (mapping !== undefined)
+                        out.discriminator = { ...discriminator, mapping: Object.fromEntries(Object.entries(record(mapping, "discriminator mapping")).map(([name, target]) => {
+                                if (typeof target !== "string")
+                                    throw new TypeError("Discriminator targets must be strings");
+                                const schemas = record(sourceComponents.schemas, "schemas");
+                                return [name, Object.hasOwn(schemas, target) ? qualified(target) : reference(target)];
+                            })) };
+                }
+            }
+            else if (kind === "pathItem") {
+                array("parameters", "parameter");
+                const servers = node.servers === undefined ? inheritedServers : items(node.servers, "path servers");
+                for (const method of methods)
+                    if (node[method] !== undefined)
+                        out[method] = walk(node[method], "operation", scan, servers);
+            }
+            else if (kind === "operation") {
+                array("parameters", "parameter");
+                child("requestBody", "requestBody");
+                keyed("responses", "response", true);
+                keyed("callbacks", "callback");
+                if (!scan) {
+                    if (node.operationId !== undefined)
+                        out.operationId = `${key}.${node.operationId}`;
+                    if (node.security !== undefined || defaultSecurity !== undefined)
+                        out.security = security(node.security ?? defaultSecurity);
+                    if (node.servers === undefined && inheritedServers !== undefined && JSON.stringify(inheritedServers) !== JSON.stringify(rootServers))
+                        out.servers = inheritedServers;
+                    if (node.tags !== undefined)
+                        out.tags = items(node.tags, "tags").map(tag => { if (typeof tag !== "string")
+                            throw new TypeError("Tags must be strings"); return `${key}.${tag}`; });
+                }
+            }
+            else if (kind === "parameter" || kind === "header" || kind === "mediaType") {
+                child("schema", "schema");
+                keyed("examples", "example");
+                keyed("content", "mediaType");
+                keyed("encoding", "encoding");
+                if (kind === "mediaType" && node["x-wsdl-tsc-stream"] !== undefined) {
+                    // @why Generated stream consumers discover record schemas here; unrelated extension payloads may contain literal $ref data.
+                    const stream = record(node["x-wsdl-tsc-stream"], "stream metadata");
+                    out["x-wsdl-tsc-stream"] = { ...stream,
+                        ...(stream.itemSchema === undefined ? {} : { itemSchema: walk(stream.itemSchema, "schema", scan) }) };
+                }
+            }
+            else if (kind === "encoding")
+                keyed("headers", "header");
+            else if (kind === "requestBody")
+                keyed("content", "mediaType");
+            else if (kind === "response") {
+                keyed("headers", "header");
+                keyed("content", "mediaType");
+                keyed("links", "link");
+            }
+            else if (kind === "callback") {
+                for (const [expression, pathItem] of Object.entries(node))
+                    if (expression !== "$ref" && !expression.startsWith("x-"))
+                        out[expression] = walk(pathItem, "pathItem", scan);
+            }
+            else if (kind === "link" && !scan) {
+                if (node.operationId !== undefined && node.operationRef !== undefined)
+                    throw new TypeError("A link cannot set both operationId and operationRef");
+                if (node.operationId !== undefined) {
+                    if (typeof node.operationId !== "string" || !operationIds.has(node.operationId))
+                        throw new TypeError(`Unresolved link operationId ${String(node.operationId)}`);
+                    out.operationId = `${key}.${node.operationId}`;
+                }
+                if (node.operationRef !== undefined)
+                    out.operationRef = reference(node.operationRef, true);
+            }
+            return out;
+        }
+        for (const [route, value] of Object.entries(sourcePaths))
+            if (!route.startsWith("x-"))
+                walk(value, "pathItem", true);
+        if (source.webhooks !== undefined)
+            map(source.webhooks, "pathItem", true);
+        for (const [category, values] of Object.entries(sourceComponents)) {
+            if (category.startsWith("x-"))
+                continue;
+            if (!Object.hasOwn(categories, category))
+                throw new TypeError(`Unsupported OpenAPI component category ${category}`);
+            map(values, categories[category], true);
+        }
+        for (const [route, value] of Object.entries(sourcePaths)) {
+            if (route.startsWith("x-"))
+                continue;
+            if (!route.startsWith("/") || Object.hasOwn(paths, route))
+                throw new TypeError(`Duplicate or invalid final path ${route}`);
+            paths[route] = record(walk(value, "pathItem", false), "path item");
+        }
+        if (source.webhooks !== undefined)
+            for (const [name, value] of Object.entries(record(source.webhooks, "webhooks")))
+                webhooks[qualified(name)] = walk(value, "pathItem", false);
+        for (const [category, values] of Object.entries(sourceComponents)) {
+            if (category.startsWith("x-"))
+                continue;
+            const destination = components[category] ??= dict();
+            for (const [name, value] of Object.entries(record(values, "components")))
+                destination[qualified(name)] = walk(value, categories[category], false);
+        }
+        if (source.tags !== undefined)
+            for (const value of items(source.tags, "tags")) {
+                const tag = record(value, "tag");
+                if (typeof tag.name !== "string")
+                    throw new TypeError("Tag name must be a string");
+                tags[`${key}.${tag.name}`] = { ...tag, name: `${key}.${tag.name}` };
+            }
+        services[key] = { info: source.info,
+            extensions: Object.fromEntries(Object.entries(source).filter(([name]) => name.startsWith("x-"))),
+            componentExtensions: Object.fromEntries(Object.entries(sourceComponents).filter(([name]) => name.startsWith("x-"))),
+            pathExtensions: Object.fromEntries(Object.entries(sourcePaths).filter(([name]) => name.startsWith("x-"))) };
+    }
+    const info = { title: options.title ?? "Composed SOAP API", version: options.version ?? "0.0.0" };
+    if (options.description !== undefined)
+        info.description = options.description;
+    const result = { openapi: "3.1.0", info, servers: rootServers, paths, components, "x-wsdl-tsc-services": services };
+    if (Object.keys(webhooks).length)
+        result.webhooks = webhooks;
+    if (Object.keys(tags).length)
+        result.tags = Object.keys(tags).sort().map(name => tags[name]);
+    if (dialect !== "https://spec.openapis.org/oas/3.1/dialect/base")
+        result.jsonSchemaDialect = dialect;
+    return stable(result);
+}

package/dist/pipeline.d.ts

@@ -53,7 +53,7 @@ export interface PipelineOptions {
     /**
      * Path to a stream configuration JSON file. Loaded and parsed once before
      * compilation; the parsed value takes precedence over `streamConfig` when
-     * both are set. Leave undefined to preserve byte-for-byte buffered output.
+     * both are set. Unlisted operations retain their buffered API selection.
      */
     streamConfigFile?: string;
     /**

package/dist/pipeline.js

@@ -21,6 +21,7 @@ import { resolveCompilerOptions } from "./config.js";
 import { emitClientArtifacts, reportCompilationStats, reportOpenApiSuccess, success } from "./util/cli.js";
 import { loadStreamConfigFile } from "./util/streamConfig.js";
 import { applyShapeCatalogs } from "./compiler/shapeResolver.js";
+import { deriveClientName } from "./util/tools.js";
 /**
  * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI/Gateway/App
  *
@@ -129,6 +130,7 @@ export async function runGenerationPipeline(opts) {
             clientDir: opts.clientOutDir ? path.resolve(opts.clientOutDir) : undefined,
             // Reuse the same imports mode as the TypeScript client/types/utils emitters
             imports: finalCompiler.imports,
+            clientClassName: opts.gateway.clientClassName ?? deriveClientName(compiled),
             // Pass catalog for runtime unwrap generation
             catalogFile: path.resolve(opts.catalogOut),
             // Thread flatten flag from OpenAPI options

package/docs/agent-skill.md

@@ -4,6 +4,12 @@ Standalone agent skill artifact for consumer projects using `@techspokes/typescr
 
 ## Purpose
 
+The skill is a light router to canonical product documentation. Its manual instructions cover input discovery, document selection and generated-file ownership; generation profiles, constructors, mappings, compatibility and transport rules remain in the core guides.
+
+Agents prefer the installed package's documentation, which matches the code they are using. The ZIP also includes generated extracts of canonical docs for its recorded release version, including [migration](migration.md#from-11x-to-120), composition, checked generation and streaming. Those extracts are versioned snapshots, not separately authored sources of product truth.
+
+Use a matching repository tag when the installed guide is unavailable, and use target-version docs deliberately during upgrades. Live `main` may contain unreleased behavior; a skill for a newer release must not establish capabilities of an older installed package. `references/SOURCE-MAP.json` records the snapshot's version, tag and source sections.
+
 Release assets include `typescript-wsdl-client-agent-skill-vX.Y.Z.zip` and `SHA256SUMS`. GitHub artifact provenance attests the ZIP, which contains an installable `typescript-wsdl-client/` skill folder for consumer projects.
 
 The skill is for consumer-project agents. It tells agents how to choose `wsdl-tsc` commands, handle generated output boundaries, load reference material, and validate generated code without treating generated files as hand-maintained source.
@@ -18,8 +24,11 @@ typescript-wsdl-client/
   references/
     architecture.md
     consumer-workflows.md
+    checked-generation.md
     cli-reference.md
+    composition.md
     generated-code.md
+    migration.md
     testing.md
     troubleshooting.md
     streaming.md
@@ -28,7 +37,7 @@ typescript-wsdl-client/
 
 ## Evergreen Content
 
-Evergreen content lives under `agent-skill/` and is reviewed as source code. Update evergreen files only when stable agent workflow, architecture guidance, dependency rules, or generated-output safety rules change.
+Evergreen content lives under `agent-skill/` and supplies stable routing and ownership instructions. Update product contracts in the canonical docs and select their sections through the reference manifest; do not copy those details into hand-maintained skill summaries.
 
 The evergreen files are `agent-skill/SKILL.md`, `agent-skill/install.mjs`, `agent-skill/evergreen/architecture.md`, and `agent-skill/evergreen/consumer-workflows.md`.
 

package/docs/api-reference.md

@@ -1,10 +1,12 @@
 # Programmatic API
 
-All CLI commands are available as TypeScript functions. This document covers each exported function, its usage, and its type signatures.
+This reference covers public generation, composition, stream and security APIs. Assessment and checked planning are separate diagnostic surfaces; see [checked generation](checked-generation.md#programmatic-planning-and-generation).
 
 See the main [README](../README.md) for installation, CLI usage, and project overview.
 
-All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Signatures and options are unchanged; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
+All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Adding a preamble does not change an API signature or option; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
+
+Generated-output compatibility is versioned separately from those preambles. Read the [migration guide for the intended version](migration.md), including [1.2.x-to-1.3.0 SOAP binding adoption](migration.md#from-12x-to-130), before regenerating existing clients or changing their selected profile.
 
 ## compileWsdlToProject
 
@@ -17,6 +19,8 @@ await compileWsdlToProject({
   wsdl: "./wsdl/Hotel.wsdl",
   outDir: "./src/services/hotel",
   options: {
+    wsdl: "./wsdl/Hotel.wsdl",
+    out: "./src/services/hotel",
     imports: "js",
     catalog: true,
     primitive: {
@@ -38,13 +42,13 @@ await compileWsdlToProject({
 declare function compileWsdlToProject(input: {
   wsdl: string;
   outDir: string;
-  options?: Partial<CompilerOptions>;
+  options?: CompilerOptions;
   streamConfigFile?: string;
   streamConfig?: StreamConfig;
 }): Promise<void>;
 ```
 
-`streamConfigFile` points at a JSON file parsed by `loadStreamConfigFile`. `streamConfig` accepts an already-parsed value; `streamConfigFile` takes precedence when both are set. Buffered generation is unchanged when both are omitted. See [Stream Configuration](configuration.md#stream-configuration) for the file format and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale.
+`streamConfigFile` points at raw JSON parsed by `loadStreamConfigFile`; `streamConfig` accepts normalized metadata from `parseStreamConfig`. The file takes precedence when both are set. Omitting both retains buffered API selection, without a byte-for-byte output guarantee across upgrades. See [Stream Configuration](configuration.md#stream-configuration).
 
 ### CompilerOptions
 
@@ -120,6 +124,7 @@ interface GenerateOpenAPIOptions {
   pathStyle?: "kebab" | "asis" | "lower";
   defaultMethod?: string;
   closedSchemas?: boolean;
+  flattenArrayWrappers?: boolean;
   pruneUnusedSchemas?: boolean;
   tagStyle?: "default" | "first" | "service";
   tagsFile?: string;
@@ -169,10 +174,17 @@ interface GenerateGatewayOptions {
   openapiDocument?: any;
   outDir: string;
   clientDir?: string;
-  versionSlug?: string;
-  serviceSlug?: string;
+  versionSlug: string;
+  serviceSlug: string;
   defaultResponseStatusCodes?: number[];
   imports?: "js" | "ts" | "bare";
+  clientClassName?: string;
+  clientDecoratorName?: string;
+  catalogFile?: string;
+  emitPlugin?: boolean;
+  emitRuntime?: boolean;
+  stubHandlers?: boolean;
+  flattenArrayWrappers?: boolean;
 }
 ```
 
@@ -231,8 +243,10 @@ await runGenerationPipeline({
 
 ```typescript
 declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
-  compiled: CompiledCatalog;
+  compiled: any;
   openapiDoc?: any;
+  checked?: CheckedInventory;
+  planning?: CheckedComponentPlan;
 }>;
 ```
 
@@ -240,8 +254,10 @@ declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
 
 ```typescript
 interface PipelineOptions {
+  model?: "legacy" | "checked-components-v1";
+  checkedComponents?: Partial<CheckedComponentOptions>;
   wsdl: string;
-  catalogOut: string;
+  catalogOut?: string;
   clientOutDir?: string;
   compiler?: Partial<CompilerOptions>;
   openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
@@ -249,7 +265,19 @@ interface PipelineOptions {
   };
   gateway?: Omit<GenerateGatewayOptions, "openapiFile" | "openapiDocument"> & {
     outDir?: string;
+    versionSlug: string;
+    serviceSlug: string;
+  };
+  app?: {
+    appDir: string;
+    openapiMode?: "copy" | "reference";
+    force?: boolean;
+    host?: string;
+    port?: number;
+    prefix?: string;
+    securityConfigFile?: string;
   };
+  test?: {testDir: string; force?: boolean; flattenArrayWrappers?: boolean};
   streamConfigFile?: string;
   streamConfig?: StreamConfig;
 }
@@ -257,6 +285,75 @@ interface PipelineOptions {
 
 `streamConfigFile` and `streamConfig` are threaded through the compile step and into every downstream emitter via `catalog.json`. Relative paths in `shapeCatalogs` resolve against the stream-config file's directory when `streamConfigFile` is used, otherwise against the WSDL's directory.
 
+Legacy calls require `catalogOut` at runtime. Checked component calls use `model: "checked-components-v1"` and optional `checkedComponents`; they return checked inventory/planning instead of a legacy catalog contract. See [the complete programmatic checked example](checked-generation.md#programmatic-planning-and-generation) for source policy and planning before generation. Checked RPC outputs remain opaque strings and buffered checked values; legacy stream configuration does not activate checked streaming.
+
+## runMultiServicePipeline
+
+Generate independent legacy clients and service routers, then publish one aggregate gateway plugin and combined OpenAPI JSON document. The [multi-service guide](gateway-guide.md#multi-service-setup) supplies a complete configuration with explicit, disjoint outputs:
+
+```typescript
+import {loadMultiServiceConfig, runMultiServicePipeline} from "@techspokes/typescript-wsdl-client";
+
+const options = await loadMultiServiceConfig("./services.json");
+const result = await runMultiServicePipeline(options);
+```
+
+```typescript
+interface MultiServiceEntry {
+  key: string;
+  generation: PipelineOptions;
+}
+
+interface MultiServicePipelineOptions {
+  services: readonly MultiServiceEntry[];
+  openapi: OpenApiCompositionOptions & {outFile: string};
+  gateway: {
+    outDir: string;
+    imports?: "js" | "ts" | "bare";
+    openapiPath?: string | false;
+  };
+}
+
+interface MultiServicePipelineResult {
+  openapiDoc: ComposedOpenApiDocument;
+  services: Record<string, {compiled: CompiledCatalog; clientDir: string; gatewayDir: string}>;
+  pluginFile: string;
+  openapiFile: string;
+}
+
+declare function runMultiServicePipeline(options: MultiServicePipelineOptions): Promise<MultiServicePipelineResult>;
+declare function loadMultiServiceConfig(file: string): Promise<MultiServicePipelineOptions>;
+```
+
+`loadMultiServiceConfig` resolves filesystem paths against the JSON configuration file; direct API callers supply paths relative to their process working directory. Every service needs `wsdl`, `catalogOut`, `clientOutDir`, `openapi.outFile`, `openapi.basePath`, `gateway.outDir`, `gateway.serviceSlug` and `gateway.versionSlug`. Service keys use unique lowercase letters, digits and hyphens, starting with a letter; gateway service slugs and decorators must remain unique after normalization.
+
+The API preserves each source's compiler and stream settings, generated client, catalog and SOAP dispatch. It refuses overlapping output ownership, duplicate final paths, lost operation routes, and unsupported app/test/checked settings. A failed later service can leave earlier service artifacts, while the previously published aggregate spec/plugin pair remains intact.
+
+The generated aggregate plugin exports `createClients`, `MultiServiceClientOptions`, `MultiServiceClients` and `openapi`. `createClients` requires exactly the service keys, each with its generated client's constructor options, including an explicit runtime `source`; register the plugin with `{clients}`. Prefixes come from each service's `openapi.basePath`, and the aggregate refuses runtime Fastify prefixes.
+
+## composeOpenApiDocuments
+
+Compose existing OpenAPI 3.1 documents without generating clients or routers:
+
+```typescript
+interface OpenApiCompositionEntry {key: string; document: unknown}
+interface OpenApiCompositionOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: readonly string[];
+}
+
+declare function composeOpenApiDocuments(
+  entries: readonly OpenApiCompositionEntry[],
+  options?: OpenApiCompositionOptions,
+): ComposedOpenApiDocument;
+```
+
+Components become `serviceKey__ComponentName`, while operation IDs and tags become `serviceKey.originalName`. The merger rewrites supported reference-bearing positions, link operation targets, discriminator targets and security scheme names, preserving service-local security and server semantics. It also qualifies the known `x-wsdl-tsc-stream.itemSchema` reference so clients can discover the stream record contract.
+
+Literal examples and unrelated extension payloads remain data. Duplicate paths, unresolved local references, relative external references and unsupported schema resource/anchor contexts are refused.
+
 ## Stream Configuration Helpers
 
 These exports back the `--stream-config` CLI flag and are also usable directly in programmatic flows.
@@ -415,4 +512,25 @@ const streamOp = compiled.operations.find((op) => op.stream);
 console.log(streamOp?.stream?.mediaType); // "application/x-ndjson" by default
 ```
 
-The generated client exports a `StreamOperationResponse<RecordType>` type; each stream-configured operation returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`.
+### Generated stream client contract
+
+Generated `operations.ts` exports `StreamOperationResponse<RecordType>` and `StreamCallOptions`; `client.ts` also re-exports `StreamCallOptions`. Each stream-configured operation accepts `(args, options?)` and returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`:
+
+```typescript
+interface StreamCallOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+interface StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> {
+  records: AsyncIterable<RecordType>;
+  headers: HeadersType;
+  requestRaw?: string;
+}
+```
+
+Records use the public legacy DTO mapping: flattened attributes, projected scalar values, typed simple content, XML lists and declared repeated-element arrays. Each record is mapped after its closing XML tag; the low-level parser still returns lexical values and attribute bags. Gateway wrapper flattening applies per record when enabled, and checked value shapes are unchanged.
+
+Only stream-enabled generated clients add constructor `streamRequestOptions?: IExOptions` from `soap`. These HTTP options are separate from WSDL loading and support a verified HTTPS agent, HTTP timeout and signal; `options.httpClient` must implement `requestStream`, or the standard node-soap HTTP client is used with `options.request`. Stream calls honor the current endpoint override, static headers and supported `ISecurity` hooks; see [transport support and refusals](gateway-guide.md#streaming-transport-settings).
+
+Per-call `timeoutMs` is a positive integer deadline for the upstream HTTP exchange and record consumption, starting after metadata initialization. A per-call signal already aborted rejects before metadata initialization. Exhaust or return the iterator to release transport resources; generated gateways connect downstream disconnects to that signal before waiting for SOAP headers and throughout delivery. Dates retain the existing type-level mapping, and `bigint` has no additional JSON encoding convention.

package/docs/checked-gateway.md

@@ -4,8 +4,18 @@ Generation offers legacy, the default, and opt-in checked components. Start with
 
 ## Component service generation
 
+SOAP 1.2 document/literal operations use the selected binding's envelope namespace and `application/soap+xml` action parameter. Select service, port and binding through the existing checked configuration when multiple ports are available; a SOAP version flag is unnecessary. SOAP 1.2 artifacts have their own compatibility scope, so regenerate matched clients, capsules and gateways together. Existing SOAP 1.1 and direct-runtime artifacts retain their contracts.
+
+Generated SOAP 1.2 clients use the additive `checkedComponentRuntimeV2` package-root binding with protocol `checked-component-soap12-runtime-v1`. Existing SOAP 1.1 clients keep `checkedComponentRuntimeV1` and `checked-component-runtime-v2`, including their TypeScript injection contract. The older binding refuses SOAP 1.2 artifacts before SOAP dispatch.
+
+SOAP 1.2 faults retain code, nested subcodes, language-tagged reasons and optional Node/Role metadata. Declared application detail uses the existing native mapping and gateway fault validation. A valid protocol fault without declared application detail carries fault metadata without a typed application value; the client retains original response bytes. Gateways return HTTP 502 for upstream faults, including SOAP Sender faults received on HTTP 400. SOAP 1.2 protocol rules follow [the messaging framework](https://www.w3.org/TR/soap12-part1/#soapfault) and [HTTP binding](https://www.w3.org/TR/soap12-part2/#soapinhttp).
+
+SOAP 1.2 header processing uses the default ultimate receiver and next roles. Unknown mandatory blocks targeted at this receiver refuse; other-role and optional blocks may be ignored. The `mustUnderstand` and `relay` attributes accept SOAP 1.2 Boolean lexical forms. This does not enable outgoing application headers, WS-Security, streaming or RPC/encoded SOAP 1.2.
+
 The additive `checked-components-v1` mode uses the same command family and native owners for qualified structured operations, imported schema snapshots, attributes, recursive records, simple content and ordered values. It preserves the shipped direct runtime and legacy defaults. Source, mapping, artifact and transport checks remain authoritative; unsupported schema or security features refuse rather than disappearing from a successful service claim. This is a qualified component fragment, not universal XSD, streaming or provider acceptance.
 
+The [bounded SOAP 1.1 RPC/encoded profile](supported-patterns.md#checked-soap-11-rpc-string-profile) adds source-owned scalar and flat Boolean record parts without document element roots. Component responses additionally accept exact Latin1 with encoding agreement. See the [NOAA qualification](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/noaa-ndfd-qualification.md) for native restrictions, opaque string/reference results and separate owned-server/live evidence limits.
+
 For a supported local WSDL or HTTP(S) root URL with one service/port/binding candidate, omit `--checked-config`. The planner selects all operations of that binding and derives supported mappings through the existing native owners. Local sources default to their containing directory; remote sources authorize their same-origin declared dependency graph. Canonical containment, redirect permission checks and native qualification still apply.
 
 ```bash