@techspokes/typescript-wsdl-client 1.1.4 → 1.1.5

package/dist/loader/schemaResources.d.ts

@@ -0,0 +1,59 @@
+export declare const DEFAULT_LOADING_LIMITS: Readonly<{
+    resources: 128;
+    resourceBytes: number;
+    totalBytes: number;
+    resolutionDepth: 32;
+    redirects: 5;
+    resourceMs: 15000;
+    totalIoMs: 120000;
+    syntaxDepth: 256;
+}>;
+export type LoadingLimits = Readonly<{
+    [K in keyof typeof DEFAULT_LOADING_LIMITS]: number;
+}>;
+export type SchemaResourcePolicy = Readonly<{
+    fileRoots?: readonly string[];
+    /** Exact HTTP(S) origins, including ports. No implicit host or scheme permission. */
+    allowedOrigins?: readonly string[];
+}>;
+export type OfflineSchemaResource = Readonly<{
+    bytes: Uint8Array;
+    digest: string;
+}>;
+export type ResourceMetadata = Readonly<{
+    uri: string;
+    digest: string;
+    byteLength: number;
+}>;
+export type FetchedSchemaResource = ResourceMetadata & Readonly<{
+    bytes: Uint8Array;
+}>;
+export declare function loadingLimits(overrides?: Partial<LoadingLimits>): LoadingLimits;
+/** Canonical URL spelling; queries remain distinct, fragments are not retrieval identity. */
+export declare function resolveResourceUri(reference: string, baseUri?: string): string;
+/** One instance per compilation. Bytes and aliases are confined to this I/O boundary. */
+export declare class SchemaResourceLoader {
+    private readonly roots;
+    private readonly lexicalRoots;
+    private readonly origins;
+    private readonly offline?;
+    private readonly charge?;
+    private readonly signal?;
+    readonly limits: LoadingLimits;
+    private readonly resources;
+    private readonly aliases;
+    private readonly resourceKeys;
+    private totalBytes;
+    private ioMs;
+    private constructor();
+    static create(policy: SchemaResourcePolicy, overrides?: Partial<LoadingLimits>, offline?: ReadonlyMap<string, OfflineSchemaResource>, charge?: (amount: number) => void, signal?: AbortSignal): Promise<SchemaResourceLoader>;
+    get metadata(): readonly ResourceMetadata[];
+    get metrics(): Readonly<{
+        resources: number;
+        totalBytes: number;
+        ioMs: number;
+    }>;
+    private authorize;
+    fetchResource(reference: string): Promise<FetchedSchemaResource>;
+}
+//# sourceMappingURL=schemaResources.d.ts.map

package/dist/loader/schemaResources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaResources.d.ts","sourceRoot":"","sources":["../../src/loader/schemaResources.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;KAAE,CAAC,IAAI,MAAM,OAAO,sBAAsB,GAAG,MAAM;CAAC,CAAC,CAAC;AAC3F,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qFAAqF;IACrF,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,CAAC,CAAC;AAErF,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAQnF;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB9E;AAOD,yFAAyF;AACzF,qBAAa,oBAAoB;IAOX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAqB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAAqB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAChH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAA8C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACtH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAR1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO;WAIM,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuBnO,IAAI,QAAQ,IAAI,SAAS,gBAAgB,EAAE,CAG1C;IACD,IAAI,OAAO,IAAI,QAAQ,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAE7E;YAEa,SAAS;IAejB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA4HvE"}

package/dist/loader/schemaResources.js

@@ -0,0 +1,292 @@
+/** Policy-checked, bounded I/O for schema inputs only. Legacy fetching is separate. */
+import { createHash } from "node:crypto";
+import { open, realpath, lstat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { SchemaLoadingError } from "./orderedSyntax.js";
+export const DEFAULT_LOADING_LIMITS = Object.freeze({
+    resources: 128, resourceBytes: 8 * 1024 * 1024, totalBytes: 64 * 1024 * 1024,
+    resolutionDepth: 32, redirects: 5, resourceMs: 15_000, totalIoMs: 120_000, syntaxDepth: 256,
+});
+export function loadingLimits(overrides = {}) {
+    const limits = { ...DEFAULT_LOADING_LIMITS, ...overrides };
+    for (const [key, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < (['redirects', 'resourceMs', 'totalIoMs'].includes(key) ? 0 : 1)) {
+            throw new RangeError(`Invalid schema loading limit: ${key}`);
+        }
+    }
+    return Object.freeze(limits);
+}
+/** Canonical URL spelling; queries remain distinct, fragments are not retrieval identity. */
+export function resolveResourceUri(reference, baseUri) {
+    let url;
+    try {
+        url = baseUri ? new URL(reference, baseUri)
+            : /^[a-z][a-z0-9+.-]*:/i.test(reference) && !/^[a-z]:[\\/]/i.test(reference)
+                ? new URL(reference) : pathToFileURL(path.resolve(reference));
+    }
+    catch {
+        throw new SchemaLoadingError("invalid-schema", "Invalid schema resource URI");
+    }
+    if (!["file:", "http:", "https:"].includes(url.protocol)) {
+        throw new SchemaLoadingError("unsupported-capability", "Unsupported schema resource scheme");
+    }
+    if (url.username || url.password)
+        throw new SchemaLoadingError("unsupported-capability", "Credential-bearing resource URIs are forbidden");
+    if (url.protocol === "file:" && (url.search || (url.hostname && url.hostname !== "localhost"))) {
+        throw new SchemaLoadingError("unsupported-capability", "File URI queries and remote file authorities are forbidden");
+    }
+    url.hash = "";
+    return url.href;
+}
+function withinRoot(file, root) {
+    const relative = path.relative(root, file);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+/** One instance per compilation. Bytes and aliases are confined to this I/O boundary. */
+export class SchemaResourceLoader {
+    roots;
+    lexicalRoots;
+    origins;
+    offline;
+    charge;
+    signal;
+    limits;
+    resources = new Map();
+    aliases = new Map();
+    resourceKeys = new Map();
+    totalBytes = 0;
+    ioMs = 0;
+    constructor(roots, lexicalRoots, origins, limits, offline, charge, signal) {
+        this.roots = roots;
+        this.lexicalRoots = lexicalRoots;
+        this.origins = origins;
+        this.offline = offline;
+        this.charge = charge;
+        this.signal = signal;
+        this.limits = limits;
+    }
+    static async create(policy, overrides, offline, charge, signal) {
+        charge?.(1024 + (policy.fileRoots?.length ?? 0) * 128 + (policy.allowedOrigins?.length ?? 0) * 128 + (offline?.size ?? 0) * 256);
+        const configuredRoots = (policy.fileRoots ?? []).map(root => { charge?.(128 + root.length * 32); return path.resolve(root); });
+        let roots;
+        try {
+            roots = await Promise.all(configuredRoots.map(root => realpath(root)));
+        }
+        catch {
+            throw new SchemaLoadingError("transport", "An authorized schema root is unavailable");
+        }
+        const origins = new Set((policy.allowedOrigins ?? []).map(origin => {
+            charge?.(128 + origin.length * 32);
+            const url = new URL(origin);
+            if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+                throw new RangeError("allowedOrigins must contain HTTP(S) origins only");
+            }
+            return url.origin;
+        }));
+        // Copy the manifest; byte copies occur only after per-resource/aggregate checks.
+        const snapshots = offline ? new Map() : undefined;
+        if (offline)
+            for (const [uri, value] of offline) {
+                charge?.(256 + uri.length * 32);
+                snapshots.set(resolveResourceUri(uri), { bytes: value.bytes, digest: value.digest });
+            }
+        return new SchemaResourceLoader(roots, [...configuredRoots, ...roots], origins, loadingLimits(overrides), snapshots, charge, signal);
+    }
+    get metadata() {
+        this.charge?.(128 + this.resources.size * 256);
+        return Object.freeze([...this.resources.values()].map(({ uri, digest, byteLength }) => Object.freeze({ uri, digest, byteLength })));
+    }
+    get metrics() {
+        return Object.freeze({ resources: this.resources.size, totalBytes: this.totalBytes, ioMs: this.ioMs });
+    }
+    async authorize(uri) {
+        this.charge?.(1024 + uri.length * 32 + this.roots.length * 256);
+        const url = new URL(resolveResourceUri(uri));
+        if (url.protocol !== "file:") {
+            if (!this.origins.has(url.origin))
+                throw new SchemaLoadingError("unsupported-capability", "Schema resource origin is not authorized");
+            return url.href;
+        }
+        const file = fileURLToPath(url);
+        // Check lexical traversal before touching the filesystem, then symlink-resolved identity.
+        if (!this.lexicalRoots.some(root => withinRoot(file, root)))
+            throw new SchemaLoadingError("unsupported-capability", "Schema file is outside authorized roots");
+        const actual = await realpath(file);
+        if (!this.roots.some(root => withinRoot(actual, root)))
+            throw new SchemaLoadingError("unsupported-capability", "Schema symlink is outside authorized roots");
+        return pathToFileURL(actual).href;
+    }
+    async fetchResource(reference) {
+        this.charge?.(256 + reference.length * 4);
+        const requested = resolveResourceUri(reference);
+        // A previously authorized alias returns the compilation's pinned bytes without new I/O.
+        const pinned = this.resources.get(this.resourceKeys.get(this.aliases.get(requested) ?? requested) ?? "");
+        if (pinned)
+            return pinned;
+        const started = performance.now();
+        const remaining = this.limits.totalIoMs === 0 ? Infinity : this.limits.totalIoMs - this.ioMs;
+        if (remaining < 0)
+            throw new SchemaLoadingError("transport", "Total schema I/O deadline exhausted");
+        const budget = Math.min(this.limits.resourceMs === 0 ? Infinity : this.limits.resourceMs, remaining);
+        const controller = new AbortController();
+        const abort = () => controller.abort(this.signal?.reason);
+        this.signal?.addEventListener('abort', abort, { once: true });
+        if (this.signal?.aborted)
+            abort();
+        let timer;
+        let performedIo = new URL(requested).protocol === "file:";
+        const timeout = new Promise((_, reject) => {
+            // Limits are inclusive: an exactly-at-deadline completed resource is admitted.
+            if (Number.isFinite(budget))
+                timer = setTimeout(() => { controller.abort(); reject(new SchemaLoadingError("transport", "Schema resource or total I/O deadline exceeded")); }, budget + 1);
+        });
+        try {
+            const task = (async () => {
+                let uri = await this.authorize(requested);
+                if (controller.signal.aborted || performance.now() - started > budget)
+                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                const cached = this.resources.get(this.resourceKeys.get(this.aliases.get(uri) ?? uri) ?? "");
+                if (cached)
+                    return cached;
+                const checkResourceCount = () => {
+                    if (this.resources.size >= this.limits.resources)
+                        throw new SchemaLoadingError("resource-limit", `Schema resource count exceeds ${this.limits.resources}`);
+                };
+                performedIo = true;
+                const redirectAliases = [requested, uri];
+                const chunks = [];
+                let byteLength = 0;
+                const accept = (chunk) => {
+                    if (controller.signal.aborted || performance.now() - started > budget)
+                        throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                    // Reserve copying, hashing, decoding and bounded syntax preparation before retaining bytes.
+                    this.charge?.(64 + chunk.byteLength * 32);
+                    byteLength += chunk.byteLength;
+                    if (byteLength > this.limits.resourceBytes || this.totalBytes + byteLength > this.limits.totalBytes) {
+                        throw new SchemaLoadingError("resource-limit", "Decompressed schema byte budget exceeded");
+                    }
+                    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");
+                    accept(snapshot.bytes);
+                    const digest = createHash("sha256").update(snapshot.bytes).digest("hex");
+                    if (digest !== snapshot.digest)
+                        throw new SchemaLoadingError("invalid-schema", "Offline schema digest mismatch");
+                }
+                else if (new URL(uri).protocol === "file:") {
+                    checkResourceCount();
+                    const localPath = fileURLToPath(uri);
+                    if (!(await lstat(localPath)).isFile())
+                        throw new SchemaLoadingError("unsupported-capability", "Schema resource must be a regular file");
+                    const file = await open(localPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+                    try {
+                        if (!(await file.stat()).isFile())
+                            throw new SchemaLoadingError("unsupported-capability", "Schema resource must be a regular file");
+                        const stream = file.createReadStream({ autoClose: false, signal: controller.signal });
+                        try {
+                            for await (const chunk of stream)
+                                accept(chunk);
+                        }
+                        finally {
+                            stream.destroy();
+                        }
+                    }
+                    finally {
+                        await file.close();
+                    }
+                }
+                else {
+                    for (let redirects = 0;; redirects++) {
+                        const response = await fetch(uri, { redirect: "manual", signal: controller.signal, headers: { Accept: "application/xml,text/xml" } });
+                        if ([301, 302, 303, 307, 308].includes(response.status)) {
+                            await response.body?.cancel();
+                            if (redirects >= this.limits.redirects)
+                                throw new SchemaLoadingError("resource-limit", `Schema redirects exceed ${this.limits.redirects}`);
+                            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:")
+                                throw new SchemaLoadingError("unsupported-capability", "HTTP redirects cannot select file resources");
+                            redirectAliases.push(uri);
+                            const redirectedCache = this.resources.get(this.resourceKeys.get(this.aliases.get(uri) ?? uri) ?? "");
+                            if (redirectedCache) {
+                                if (controller.signal.aborted || performance.now() - started > budget)
+                                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                                for (const alias of redirectAliases)
+                                    this.aliases.set(alias, redirectedCache.uri);
+                                return redirectedCache;
+                            }
+                            continue;
+                        }
+                        if (!response.ok) {
+                            await response.body?.cancel();
+                            throw new SchemaLoadingError("transport", `Schema retrieval returned HTTP ${response.status}`);
+                        }
+                        if (this.resources.size >= this.limits.resources) {
+                            await response.body?.cancel();
+                            checkResourceCount();
+                        }
+                        // Manual fetch must preserve identity; an opaque/auto-following transport is rejected.
+                        if (response.redirected || (response.url && resolveResourceUri(response.url) !== uri)) {
+                            await response.body?.cancel();
+                            throw new SchemaLoadingError("unsupported-capability", "Schema transport changed retrieval identity without policy checks");
+                        }
+                        const reader = response.body?.getReader();
+                        if (reader) {
+                            const abort = () => { void reader.cancel().catch(() => { }); };
+                            controller.signal.addEventListener("abort", abort, { once: true });
+                            try {
+                                for (;;) {
+                                    const chunk = await reader.read();
+                                    if (chunk.done)
+                                        break;
+                                    accept(chunk.value);
+                                }
+                            }
+                            finally {
+                                controller.signal.removeEventListener("abort", abort);
+                                await reader.cancel().catch(() => { });
+                                reader.releaseLock();
+                            }
+                        }
+                        break;
+                    }
+                }
+                if (controller.signal.aborted || performance.now() - started > budget)
+                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                const bytes = Buffer.concat(chunks, byteLength);
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                const resource = Object.freeze({ uri, digest, byteLength, bytes });
+                // Byte cache identity is (final canonical URI, digest); aliases never change context's final URI.
+                const resourceKey = JSON.stringify([uri, digest]);
+                this.resources.set(resourceKey, resource);
+                this.resourceKeys.set(uri, resourceKey);
+                for (const alias of redirectAliases)
+                    this.aliases.set(alias, uri);
+                this.totalBytes += byteLength;
+                return resource;
+            })();
+            return await Promise.race([task, timeout]);
+        }
+        catch (error) {
+            controller.abort();
+            if (error instanceof SchemaLoadingError)
+                throw error;
+            // Do not expose filesystem paths, response text or credential-bearing transport errors.
+            throw new SchemaLoadingError("transport", "Unable to retrieve schema resource under the configured policy");
+        }
+        finally {
+            this.signal?.removeEventListener('abort', abort);
+            clearTimeout(timer);
+            if (performedIo)
+                this.ioMs += performance.now() - started;
+        }
+    }
+}

package/dist/openapi/generateOpenAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CA4TD"}
+{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAMnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CA2TD"}

package/dist/openapi/generateOpenAPI.js

@@ -27,6 +27,7 @@ import * as path from "path";
 import * as yaml from "js-yaml";
 import { loadWsdl } from "../loader/wsdlLoader.js";
 import { compileCatalog } from "../compiler/schemaCompiler.js";
+import { readLegacyCatalogFile } from "../compiler/semanticCatalog.js";
 import { generateSchemas } from "./generateSchemas.js";
 import { generatePaths } from "./generatePaths.js";
 import { error, info, warn } from "../util/cli.js";
@@ -50,8 +51,7 @@ export async function generateOpenAPI(opts) {
         compiled = opts.compiledCatalog;
     }
     else if (opts.catalogFile) {
-        const raw = fs.readFileSync(opts.catalogFile, "utf8");
-        compiled = JSON.parse(raw);
+        compiled = readLegacyCatalogFile(opts.catalogFile);
     }
     else {
         const wsdlCatalog = await loadWsdl(String(opts.wsdl));

package/dist/test/generateTests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateTests.d.ts","sourceRoot":"","sources":["../../src/test/generateTests.ts"],"names":[],"mappings":"AAkCA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAuBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiK7E"}
+{"version":3,"file":"generateTests.d.ts","sourceRoot":"","sources":["../../src/test/generateTests.ts"],"names":[],"mappings":"AAmCA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAuBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgK7E"}

package/dist/test/generateTests.js

@@ -12,6 +12,7 @@
  * 5. For each file: skip-if-exists check, then write
  */
 import fs from "node:fs";
+import { readLegacyCatalogFile } from "../compiler/semanticCatalog.js";
 import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { info, success } from "../util/cli.js";
@@ -63,8 +64,7 @@ export async function generateTests(opts) {
         throw new Error(`Catalog file does not exist: ${catalogFile}`);
     }
     // Read and parse catalog
-    const catalogRaw = fs.readFileSync(catalogFile, "utf-8");
-    const catalog = JSON.parse(catalogRaw);
+    const catalog = readLegacyCatalogFile(catalogFile);
     // Resolve client metadata
     const clientMeta = resolveClientMeta({
         clientDir,

package/dist/util/xmlWhitespace.d.ts

@@ -0,0 +1,3 @@
+/** XML Schema whiteSpace mapping; only the four XML whitespace characters. */
+export declare function normalizeWhitespace(value: string, mode: "preserve" | "replace" | "collapse"): string;
+//# sourceMappingURL=xmlWhitespace.d.ts.map

package/dist/util/xmlWhitespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xmlWhitespace.d.ts","sourceRoot":"","sources":["../../src/util/xmlWhitespace.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAEpG"}

package/dist/util/xmlWhitespace.js

@@ -0,0 +1,4 @@
+/** XML Schema whiteSpace mapping; only the four XML whitespace characters. */
+export function normalizeWhitespace(value, mode) {
+    return mode === "preserve" ? value : mode === "replace" ? value.replace(/[\t\r\n]/g, " ") : value.replace(/[\t\r\n ]+/g, " ").replace(/^ | $/g, "");
+}

package/docs/README.md

@@ -2,6 +2,8 @@
 
 Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. The root [README.md](../README.md) Documentation section is the authoritative index with descriptions; the list below is a quick local reference organized by reader intent.
 
+The [S06 research handoff](content-model-s06-research-handoff.md) links the four rule investigations and their unresolved acceptance gates.
+
 ## Evaluate
 
 - [start-here.md](start-here.md): what this is, who it is for, choose your path
@@ -30,7 +32,8 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [architecture.md](architecture.md): internal pipeline for contributors
 - [file-naming-and-path-organization.md](file-naming-and-path-organization.md): contributor convention for taxonomy paths and fixture retrieval
 - [agent-skill.md](agent-skill.md): release ZIP for consumer-project AI agents
-- [roadmap/README.md](roadmap/README.md): conformance framework, implementation slices, and release gates for 1.0
+- [Current roadmap](../ROADMAP.md): published baseline and active backlog
+- [roadmap/README.md](roadmap/README.md): historical completed 1.0 implementation and qualification plan
 - [decisions/002-streamable-responses.md](decisions/002-streamable-responses.md): opt-in streaming design (client `AsyncIterable`, gateway NDJSON or JSON array, `x-wsdl-tsc-stream` OpenAPI extension); shipped in 0.17.0 and extended in 0.28.0
 - [migration.md](migration.md): upgrading between package versions
 
@@ -45,6 +48,16 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 
 ## Related
 
+- [S02 handoff](content-model-s02-handoff.md): architecture decisions, feasibility evidence and S03 entry contracts
+- [Ordered schema loading](content-model-loading.md): internal syntax, provenance and controlled resolution contracts
+- [Canonical schema graph](content-model-graph.md): immutable declarations, use sites and lexical reference context
+- [Semantic catalog format 2](content-model-catalog.md): deterministic persistence, validation and compatibility routing
+- [RE01 research resolver implementation](content-model-s06-re-01-resolver-implementation.md): supplied-candidate and abstract wildcard checks, qualification limits and the future production adapter
+- [RE01 support reconstruction](content-model-s06-re-01-support-reconstruction.md): conditional copy/bundle reductions, value/name palettes and open bounds
+- [RE01 scalar witness construction](content-model-s06-re-01-scalar-witnesses.md): shared endpoint tuples and open materialization gates
+
+- [Direct scalar values](direct-values.md): internal source mapping, fresh inverse and codec handoff.
+
 - [Root README](../README.md): project overview, quick start, and authoritative Documentation section
 - [CONTRIBUTING.md](../CONTRIBUTING.md): development setup and workflow
 - [CHANGELOG.md](../CHANGELOG.md): version history

package/docs/architecture.md

@@ -4,6 +4,15 @@ Internal architecture of the wsdl-tsc code generator for contributors.
 
 See [CONTRIBUTING](../CONTRIBUTING.md) for development setup and [README](../README.md) for user documentation.
 
+## Planned Content Model Contracts
+
+[Ordered schema loading](content-model-loading.md) documents S03's internal input adapter and its migration boundary.
+[Canonical graph construction](content-model-graph.md) documents S04's immutable declarations and independent use-site particles.
+[Semantic catalog persistence](content-model-catalog.md) documents format 2 validation and the explicit legacy-reader boundary.
+Its controlled resource resolver supplies contextual syntax to S04 #173 while graph construction and downstream semantics remain separate owners.
+
+[ADR-003](decisions/003-content-model-contracts.md) defines the intended faithful content-model path and [decision register](content-model-decisions.md) assigns its owners. The S02 feasibility records and [handoff](content-model-s02-handoff.md) distinguish executed adapter/dialect evidence from later production implementation. The pipeline below describes current legacy behavior; S02 does not activate new defaults.
+
 ## Generated Source Policy
 
 Complete TypeScript writes pass through `src/generation/writeGeneratedSource.ts` after any scaffold ownership guard. Runtime/template loaders remain fragment loaders; provenance and documentation are preserved when the final body receives its preamble.

package/docs/cli-reference.md

@@ -6,7 +6,7 @@ Generation paths are explicit. Examples use the git-ignored `.generated/` direct
 
 ## Commands Overview
 
-The tool provides six commands for different integration scenarios.
+The tool provides six generation commands and the assessment-only `assess` command.
 
 TypeScript outputs automatically receive [generated preambles](generated-code.md#generated-preambles-and-eslint), including app/test scaffolds when actually written. Command syntax is unchanged and there is no preamble flag. `compile` and `openapi` data outputs remain unchanged.
 
@@ -18,6 +18,7 @@ TypeScript outputs automatically receive [generated preambles](generated-code.md
 | gateway | Fastify gateway from OpenAPI spec | Production REST gateway with SOAP backend |
 | app | Runnable Fastify app from client + gateway + OpenAPI | Local testing, demos |
 | compile | Parse WSDL to catalog.json only | Debugging, multi-stage builds |
+| assess | Source schema diagnostic report | Checked evidence and unresolved duties |
 
 ## pipeline
 
@@ -635,3 +636,22 @@ cat ./debug/catalog.json | jq '.types'
 ```bash
 cat ./debug/catalog.json | jq '.operations'
 ```
+
+## assess
+
+Inspect source schema evidence without generating artifacts or dispatching SOAP. The [assurance contract](decisions/003-content-model-contracts.md#checked-product-assessment-amendment-p1-d01) defines the native scope and qualified correspondence route.
+
+```bash
+npx wsdl-tsc assess --wsdl-source examples/minimal/weather.wsdl --report .generated/assessment.json
+```
+
+| Flag | Purpose |
+|---|---|
+| `--wsdl-source` | Required local path or explicitly authorized URL |
+| `--report` | Required diagnostic JSON output file; directory must exist |
+| `--schema-root` | Repeated authorized local roots; defaults to the local source directory |
+| `--schema-origin` | Repeated exact authorized HTTP(S) origins; no implicit network access |
+| `--assessment-max-work` | Inclusive sticky request work limit, including report publication |
+| `--assessment-max-nodes` | Inclusive cumulative preparation/context node limit |
+
+Exit 0 requires established native scope and qualified dated-XSD correspondence. Exit 2 is inconclusive, 3 native scope disproved, 4 resource-limit, 5 cancellation and 1 operational failure; execution failure takes precedence over schema facts. SIGINT requests cooperative cancellation and a cancelled report. Runtime readiness and generation admission remain separate; no assessment report activates generation.

package/docs/content-model-analysis.md

@@ -0,0 +1,92 @@
+# Exact Particle Analysis
+
+Internal S06 occurrence and emptiness contracts over the immutable graph. See the root [README](../README.md).
+
+## API and guarantees
+
+[`analyzeOccurrences`](../src/compiler/occurrenceAnalysis.ts) consumes the `ComposedGraph` from [the common source/catalog entry](content-model-companions.md).
+It returns `analyzed {analysis}` or `failure {diagnostic}` without partial success on exhaustion.
+The analysis retains the original composed/resolved/canonical graph and the `requires-schema-assessment` gate.
+
+Each particle summary records exact named-element and wildcard contributions, `nullable` and `hasRealization`.
+It also records `effectiveTotalRange` and `schemaEmptiable`, the formal XSD schema predicates, using the same exact occurrence algebra.
+Type summaries combine the ordered composed roots, preserving restriction replacement versus extension concatenation.
+The particle table and original graph retain alternative-local guarantees and ordered relationships; object-wide intervals cannot replace them.
+
+Finite bounds remain canonical decimal strings; `unbounded` is a distinct maximum.
+The shared occurrence algebra uses exact `BigInt` after charging operand/result work.
+Zero dominates multiplication in either position, including beneath unbounded descendants; finite repetitions are never expanded.
+
+## Contributions and emptiness
+
+Sequences and legal all groups add member contributions.
+Choices take minima/maxima across realizable alternatives, inserting zero for absent members.
+A single required branch stays required; a member in every branch retains their minimum guarantee.
+Local repetition multiplies contributions without changing declared occurrences or group definitions.
+
+An empty sequence or all group admits epsilon.
+An empty required choice admits no sequence; an optional empty choice admits epsilon through zero repetitions.
+A choice with an epsilon branch is nullable even with a positive occurrence minimum.
+Unrealizable alternatives supply no accepted branch; `hasRealization` distinguishes empty language from epsilon.
+
+Elements are atomic child events, independently of their type's child-content emptiness.
+`hasRealization` describes the particle language with elements as terminals; it does not certify finite recursively nested values or scalar validity.
+Scalar/mixed text, nil, attributes and defaults remain later owners' responsibilities.
+
+Legal element/type recursion terminates without empty definition stubs.
+Group/containment expansion uses iterative active/done traversal and memoization; S05 already rejects cycles in those edges.
+No recursive emptiness equation crosses element type edges because an element is never epsilon.
+S05's missing-reference and forbidden-cycle diagnostics remain applicable beneath zero bounds.
+
+## Intervals and opaque scope
+
+A repeated pair can have interval `2..4` while admitting only counts 2 and 4.
+Order, gaps and correlated branches remain in the original grammar for #180/#181; summaries are not payload validators.
+An opaque builtin contribution remains original data.
+The scope `declared-particles-with-opaque-builtin` qualifies every child summary, including named/wildcard counts, effective total range and both emptiness predicates.
+They describe declared contributions only; they cannot certify the counts or emptiness of the whole opaque content language.
+Analysis never promotes builtin or skip/lax content to full concrete validation.
+
+## Budgets and evidence
+
+Analysis independently applies S05's inclusive 100,000-node and 1,000,000-work-step defaults.
+Indexing, traversal, arithmetic digits, conservative multiplication work and contribution/provenance copying count before allocation.
+Positive safe-integer overrides follow existing semantic policy; exhausted analysis returns `resource-limit` without partial success.
+Later matcher, payload scalar and generated-output budgets retain their [ADR-003 D09 owners](decisions/003-content-model-contracts.md#provisional-resource-budgets-s02-d09).
+
+[`analysis.xsd`](../test/conformance/fixtures/xsd/analysis/analysis.xsd) and [Node reference checks](../test/conformance/reference/analysis-contract.test.ts) retain historical qualification separately from current primary and scoped payload checks under [NT-CONT-01](reference-validation.md). Original huge-schema construction remains unqualified; the adjusted small copy is a separately hashed input.
+The historical reference check raised xmlschema's model-depth setting from 15 to 32 and treated warnings as errors. Current libxml2 observations use the explicitly separate small copy; the original exact schema retains historical xmlschema qualification and current unsupported status.
+
+### Nested empty-choice qualification
+
+XSD 1.0 second-edition [Element Sequence Valid](https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#cvc-model-group) expressly states that no sequence is valid against an empty choice, while epsilon is valid against an empty sequence or all group.
+[Particle validity](https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#cvc-particle) applies that rule to each repetition; an optional enclosing particle can choose zero repetitions.
+The [restriction rule](https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#cos-particle-restrict) only calls an empty choice pointless when its minimum is zero, and does not remove a required empty choice during payload assessment.
+The complete original second-edition XML source was read through a [pinned mirror](https://github.com/jacoelho/xsd/blob/142f25ee187e17f041af87b6bfcfc82385254520/docs/spec/xml/structures.xml), whose publication URI and October 2004 source header identify the Recommendation; direct W3C retrieval was unavailable in the managed network.
+
+The executable `deadRequired`, `deadOptional`, `deadAndRequired` and `deadWildcard` cases retain a pinned-engine disagreement.
+Xmlschema 4.2.0 skips the nested required empty choice and accepts the preceding child, although it rejects an isolated required empty choice.
+Libxml2 2.14.6 rejects those children and accepts only zero enclosing repetitions where applicable, matching the primary rule.
+The analysis follows that primary rule; the test records both engine observations without declaring the primary engine's acceptance normative.
+#180/#181 must retain these cases when qualifying payload matching and independent enumeration; #179 retains schema validity separately.
+
+The formal [Particle Emptiable](https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#cos-group-emptiable) predicate uses [effective total range](https://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#cos-choice-range), which assigns an empty choice a zero range.
+Consequently a required empty choice has `schemaEmptiable: true` and `nullable: false`.
+#179 uses the former only where the specification invokes that formal schema predicate; #180 uses language nullability.
+Formal ranges include unrealizable branches and are not accepted count intervals.
+Declared zero-maximum particles remain in the graph for diagnostics and provenance; their range is zero as for the absent particle in the XSD component mapping, including an unbounded descendant.
+Zero-bound children are omitted from their containing choice's alternatives, while an optional non-disabled empty sequence remains an epsilon alternative.
+Root zero repetitions still admit epsilon.
+The `disabledChoice` and `disabledElementChoice` cases record pinned-engine deviations from this mapping; the terminal case preserves the S01/#181 zero-bound attribution qualification.
+
+### Commands and measurements
+
+[Unit tests](../test/unit/occurrence-analysis.test.ts) cover arithmetic, zero, alternatives, recursion, immutability and configured boundaries.
+Ignored measurements go to `tmp/conformance/analysis/measurements.json`; platform/broad qualification remains #208's responsibility.
+S01/#181 and S05 oracle disagreements and [S02 security qualifications](content-model-decisions.md) remain assigned downstream.
+
+```bash
+npx vitest run test/unit/occurrence-analysis.test.ts
+npx tsc -p test/unit/tsconfig.json
+npm run test:reference:full
+```