@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/dist/checkedPlanning.js

@@ -0,0 +1,245 @@
+/** WSDL-first diagnostics over the existing component generation owners.
+ * @since Unreleased
+ * @constraints Reports are data; separate invocations always reload and requalify source.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { types } from 'node:util';
+import { parseCheckedComponentOptions, parseCheckedComponentChoices, prepareComponentStages } from './checkedPipeline.js';
+import { inspectDirectOperation } from './compiler/directOperation.js';
+import { loadSemanticSchemaInput, prepareSchemaSnapshotFiles } from './loader/schemaInput.js';
+import { resolveResourceUri } from './loader/schemaResources.js';
+import { syntaxElements, syntaxAttribute, resolveLexicalQName, WSDL_NAMESPACE, XSD_NAMESPACE, SchemaLoadingError } from './loader/orderedSyntax.js';
+const same = (a, b) => a.namespace === b.namespace && a.local === b.local;
+const order = (items) => items.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b), 'en'));
+/** Refused generation retains actionable, serializable diagnostics.
+ * @since Unreleased
+ */
+export class CheckedPlanningError extends Error {
+    report;
+    constructor(report) {
+        super(formatCheckedComponentPlan(report));
+        this.report = report;
+        this.name = 'CheckedPlanningError';
+    }
+}
+/** Format deterministic human diagnostics without source bytes or transport details.
+ * @param report Diagnostic data only.
+ * @returns Summary and every independently collected blocker.
+ */
+export function formatCheckedComponentPlan(report) {
+    return [`${report.model}: ${report.ready ? 'generation-ready' : 'blocked'}; discovered=${report.inventory.operations}; selected=${report.selection?.selectors.length ?? 0}; generated=0; executed=0; inventory=${report.inventory.complete ? 'complete' : 'incomplete'}`,
+        ...report.blockers.map(b => `${b.category} [${b.stage}/${b.dimension}] ${b.reason}${b.source ? ` at ${b.source.resource}:${b.source.line}:${b.source.column} ${b.source.path}` : ''}; affected=${b.affected.map(s => `{${s.portType.namespace}}${s.portType.local}/{${s.binding.namespace}}${s.binding.local}/${s.operation}`).join(',') || 'inventory unassessed'}; ${b.action} (${b.pointer})`)].join('\n');
+}
+/** Inspect a WSDL using the same native preparation as generation, without writing or dispatching.
+ * @param source WSDL file or HTTP(S) root; declared dependencies remain subject to native policy.
+ * @param choices Partial explicit configuration; only missing unambiguous selections are inferred.
+ * @returns Diagnostic data; ready is generation readiness, never provider or runtime acceptance.
+ * @throws Error Only for unexpected report construction failures.
+ * @sideEffects Reads authorized metadata only; never contacts a SOAP endpoint.
+ */
+export async function planCheckedComponents(source, choices) {
+    return (await prepareCheckedComponentPlan(source, choices)).report;
+}
+/** Write explicitly requested diagnostic data without replacing consumer files by default.
+ * @param file Explicit output path.
+ * @param value Data to serialize; report content grants no native authority.
+ * @param force Explicit replacement permission.
+ * @returns Nothing.
+ * @throws Error On existing files without force or filesystem failures.
+ * @sideEffects Creates only the requested report or draft file and its parent directory.
+ */
+export function writeCheckedPlanningFile(file, value, force = false) {
+    fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { flag: force ? 'w' : 'wx' });
+}
+// @constraints Internal composition only. Native handles are never attached to the public report.
+export async function prepareCheckedComponentPlan(source, choices = {}, outputs) {
+    const documents = [], blockers = [];
+    let complete = false, config;
+    let intake;
+    let unresolved = [];
+    const explicit = Object.create(null);
+    let selectors = [];
+    let candidates = [], operations = [];
+    const counts = { services: 0, ports: 0, bindings: 0, portTypes: 0, operations: 0 };
+    const locator = (s) => ({ resource: `resource-${documents.findIndex(d => d.uri === s.uri) + 1}`, path: s.path, line: s.start.line, column: s.start.column });
+    const add = (category, stage, reason, action, pointer, affected = selectors, source, dimension = 'source') => {
+        blockers.push({ category, stage, dimension, reason, affected, action, pointer, ...(source ? { source: locator(source) } : {}) });
+    };
+    const inventory = () => {
+        candidates = [];
+        operations = [];
+        counts.services = counts.ports = counts.bindings = counts.portTypes = counts.operations = 0;
+        const bindings = documents.flatMap(d => syntaxElements(d.root, WSDL_NAMESPACE, 'binding').map(n => ({ node: n, name: { namespace: syntaxAttribute(d.root, 'targetNamespace') ?? '', local: syntaxAttribute(n, 'name') ?? '' } })));
+        counts.bindings = bindings.length;
+        for (const document of documents) {
+            const namespace = syntaxAttribute(document.root, 'targetNamespace') ?? '';
+            for (const service of syntaxElements(document.root, WSDL_NAMESPACE, 'service')) {
+                counts.services++;
+                for (const port of syntaxElements(service, WSDL_NAMESPACE, 'port')) {
+                    counts.ports++;
+                    const binding = resolveLexicalQName(syntaxAttribute(port, 'binding') ?? '', port);
+                    const matches = bindings.filter(b => same(b.name, binding));
+                    const type = matches.length === 1 ? syntaxAttribute(matches[0].node, 'type') : undefined;
+                    candidates.push({ service: { namespace, local: syntaxAttribute(service, 'name') ?? '' }, port: syntaxAttribute(port, 'name') ?? '', binding,
+                        ...(type ? { portType: resolveLexicalQName(type, matches[0].node) } : {}), source: locator(port.source) });
+                }
+            }
+            for (const type of syntaxElements(document.root, WSDL_NAMESPACE, 'portType')) {
+                counts.portTypes++;
+                const portType = { namespace, local: syntaxAttribute(type, 'name') ?? '' };
+                for (const operation of syntaxElements(type, WSDL_NAMESPACE, 'operation')) {
+                    counts.operations++;
+                    const name = syntaxAttribute(operation, 'name') ?? '';
+                    const bound = bindings.filter(b => { const t = syntaxAttribute(b.node, 'type'); return t && same(resolveLexicalQName(t, b.node), portType); });
+                    for (const binding of bound.length ? bound.map(b => b.name) : [undefined])
+                        operations.push({ portType, ...(binding ? { binding } : {}), operation: name,
+                            requested: false, selected: false, generated: false, executed: false });
+                }
+            }
+        }
+        order(candidates);
+        order(operations);
+    };
+    let native;
+    let preparingNative = false;
+    try {
+        if (!choices || typeof choices !== 'object' || types.isProxy(choices) || ![null, Object.prototype].includes(Object.getPrototypeOf(choices)))
+            throw new TypeError('Data-only choices required');
+        for (const key of Reflect.ownKeys(choices)) {
+            const d = Object.getOwnPropertyDescriptor(choices, key);
+            if (typeof key !== 'string' || !('value' in d))
+                throw new TypeError('Unknown component configuration or accessor');
+            explicit[key] = d.value;
+        }
+        const root = resolveResourceUri(source);
+        intake = { fileRoots: new URL(root).protocol === 'file:' ? [path.dirname(fileURLToPath(root))] : [],
+            sourceResources: [], sourceOrigins: new URL(root).protocol === 'file:' ? [] : [new URL(root).origin],
+            ...parseCheckedComponentChoices(explicit) };
+        if (!Object.hasOwn(explicit, 'sourceResources') && new URL(root).protocol !== 'file:' && intake.sourceOrigins.length) {
+            intake = { ...intake, sourceOrigins: [...new Set([new URL(root).origin, ...intake.sourceOrigins])].sort() };
+        }
+        if (intake.namespaceLocations?.some(n => n.location === 'REQUIRED_SCHEMA_LOCATION'))
+            throw new TypeError('Resolve REQUIRED_SCHEMA_LOCATION before loading');
+        if (new Set(intake.namespaceLocations?.map(n => n.namespace)).size !== (intake.namespaceLocations?.length ?? 0))
+            throw new TypeError('Unique namespace locations required');
+        const snapshotUris = [root, ...intake.sourceResources.map(r => resolveResourceUri(r.uri))];
+        if (new Set(snapshotUris).size !== snapshotUris.length)
+            throw new TypeError('Duplicate logical schema snapshot');
+        if (intake.signal?.aborted) {
+            add('cancelled', 'loading', 'caller-cancelled', 'Rerun with an active signal.', 'signal');
+        }
+        else {
+            const loading = { policy: { fileRoots: intake.fileRoots, allowedOrigins: intake.sourceOrigins }, signal: intake.signal,
+                namespaceLocations: new Map(intake.namespaceLocations?.map(n => [n.namespace, n.location])),
+                onDocument: (document) => { documents.push(document); } };
+            const prepared = Object.hasOwn(explicit, 'sourceResources') ? await prepareSchemaSnapshotFiles(source, intake.sourceResources, loading) : undefined;
+            const input = await loadSemanticSchemaInput(intake.sourceUri ?? prepared?.source ?? source, prepared?.loading ?? loading);
+            complete = true;
+            inventory();
+            const possible = candidates.filter(c => (!Object.hasOwn(explicit, 'service') || intake.service !== undefined && same(c.service, intake.service))
+                && (!Object.hasOwn(explicit, 'port') || c.port === intake.port)
+                && (!Object.hasOwn(explicit, 'selectors') || intake.selectors !== undefined && intake.selectors.every(s => same(s.binding, c.binding) && c.portType && same(s.portType, c.portType))));
+            if (possible.length !== 1)
+                add('ambiguous-selection', 'selection', possible.length ? 'multiple-service-port-binding-candidates' : 'no-matching-service-port-binding', 'Choose service, port and selectors from candidates; conflicting choices must be corrected.', 'checkedComponents.service/port/selectors', [], undefined, 'selection');
+            else {
+                const chosen = possible[0];
+                selectors = Object.hasOwn(explicit, 'selectors') ? [...intake.selectors] : operations.filter(o => o.binding && same(o.binding, chosen.binding))
+                    .map(o => ({ portType: o.portType, binding: o.binding, operation: o.operation }));
+                if (!selectors.length)
+                    add('configuration', 'selection', 'no-operations-for-candidate', 'Correct the binding/portType declarations.', 'checkedComponents.selectors', [], undefined, 'selection');
+                else
+                    config = parseCheckedComponentOptions({ ...intake, selectors, service: chosen.service, port: chosen.port });
+            }
+            operations = operations.map(o => {
+                const selected = selectors.some(s => same(s.portType, o.portType) && o.binding && same(s.binding, o.binding) && s.operation === o.operation);
+                return { ...o, requested: selected, selected };
+            });
+            const missing = new Map();
+            for (const schema of input.schemas)
+                for (const child of syntaxElements(schema.syntax, XSD_NAMESPACE, 'import')) {
+                    const namespace = syntaxAttribute(child, 'namespace') ?? '';
+                    if (syntaxAttribute(child, 'schemaLocation') === undefined && !loading.namespaceLocations.has(namespace)
+                        && !input.schemas.some(s => s.targetNamespace === namespace)
+                        && namespace !== XSD_NAMESPACE)
+                        missing.set(namespace, child.source);
+                }
+            for (const [namespace, at] of missing)
+                add('missing-dependency', 'loading', `locationless-import:${namespace}`, 'Supply an authorized schema path for this namespace.', `checkedComponents.namespaceLocations[${JSON.stringify(namespace)}].location`, selectors.length ? selectors : operations.flatMap(o => o.binding ? [{ portType: o.portType, binding: o.binding, operation: o.operation }] : []), at);
+            if (missing.size)
+                unresolved = [...(intake.namespaceLocations ?? []), ...[...missing.keys()].sort().map(namespace => ({ namespace, location: 'REQUIRED_SCHEMA_LOCATION' }))];
+            if (!blockers.length && config) {
+                if (!Object.hasOwn(explicit, 'standardLibraries') && input.schemas.some(s => syntaxElements(s.syntax, XSD_NAMESPACE, 'import')
+                    .some(n => syntaxAttribute(n, 'namespace') === XSD_NAMESPACE && syntaxAttribute(n, 'schemaLocation') === undefined))) {
+                    config = { ...config, standardLibraries: ['w3c-xsd10-schema-element-2004-v1'] };
+                }
+                // @why Machine-derived snapshot bookkeeping is separate from authored schema semantics.
+                const known = new Set(config.sourceResources.map(r => resolveResourceUri(r.uri)));
+                config = { ...config, sourceResources: [...config.sourceResources, ...input.resources.filter(r => r.uri !== input.root.uri && !known.has(r.uri) && new URL(r.uri).protocol === 'file:')
+                            .map(r => ({ uri: r.uri, file: fileURLToPath(r.uri) }))] };
+                preparingNative = true;
+                native = await prepareComponentStages(source, config, !prepared && new URL(input.root.uri).protocol !== 'file:' ? input : undefined, outputs);
+                if (native.expected.length) {
+                    const fresh = inspectDirectOperation(native.expected[0].contract).source;
+                    if (input.resources.length !== fresh.resources.length || input.resources.some(r => !fresh.resources.some(n => n.uri === r.uri && n.digest === r.digest))) {
+                        add('operational-failure', 'native-preparation', 'source-changed-during-planning', 'Keep source files stable and rerun discovery and native checks.', 'wsdl/sourceResources');
+                    }
+                }
+                for (const refusal of native.refusals) {
+                    if (refusal.rule.startsWith('ambiguous-record-path:')) {
+                        add('ambiguous-selection', 'native-preparation', refusal.rule, 'Supply recordPath using expanded names to select one declared repeated complex record in this companion source.', 'checkedComponents.recordProjections[].recordPath', [refusal.selector], undefined, 'mapping-and-artifact');
+                        continue;
+                    }
+                    const category = refusal.kind === 'invalid-schema' && refusal.dimension === 'qualification-and-correspondence' ? 'invalid-source' : refusal.kind === 'unsupported' ? 'unsupported-capability'
+                        : refusal.kind === 'cancelled' || refusal.kind === 'resource-limit' ? refusal.kind : refusal.kind === 'selection-refused' ? 'configuration' : 'inconclusive';
+                    add(category, 'native-preparation', refusal.rule, 'Resolve the native rule or extend the qualified capability; no validity override is available.', 'checkedComponents.selectors', [refusal.selector], undefined, refusal.dimension);
+                }
+                if (blockers.length)
+                    native = undefined;
+            }
+        }
+    }
+    catch (error) {
+        if (!complete) {
+            try {
+                inventory();
+            }
+            catch { /* Partial malformed identities remain unassessed. */ }
+        }
+        if (intake?.signal?.aborted)
+            add('cancelled', complete ? 'native-preparation' : 'loading', 'caller-cancelled', 'Rerun with an active signal.', 'signal');
+        else if (error instanceof SchemaLoadingError && error.message === 'Duplicate logical schema snapshot') {
+            add('configuration', 'configuration', 'duplicate-logical-snapshot', 'Supply unique logical snapshot identities.', 'checkedComponents.sourceResources');
+        }
+        else if (error instanceof SchemaLoadingError) {
+            const http = /^Schema retrieval returned HTTP (\d{3})$/.exec(error.message)?.[1];
+            const permission = /authoriz|outside/.test(error.message);
+            const category = permission ? 'permission' : error.category === 'invalid-schema' ? 'invalid-source'
+                : error.category === 'resource-limit' ? 'resource-limit' : error.category === 'unsupported-capability' ? 'unsupported-capability' : 'missing-dependency';
+            add(category, 'loading', permission ? 'source-permission-required' : http ? `metadata-http-${http}` : error.category, http === '401' || http === '403' ? 'Metadata access was denied. Supply accessible independently authorized physical snapshots; SOAP credentials do not authorize metadata.'
+                : 'Check resource availability and explicit roots/origins; permit a declared second origin once in sourceOrigins or supply authorized snapshots, then rerun fresh checks.', 'checkedComponents.fileRoots/sourceOrigins/sourceResources', selectors, error.source);
+        }
+        else {
+            const configurationError = (!preparingNative || error instanceof TypeError && error.message.startsWith('applicationGroups')) && (error instanceof TypeError || error instanceof RangeError);
+            add(configurationError ? 'configuration' : 'operational-failure', complete ? 'native-preparation' : 'configuration', configurationError ? `invalid-or-unresolved-configuration:${error.message}` : 'native-preparation-failed', 'Correct the configuration or inspect the local I/O failure and rerun.', 'checkedComponents');
+        }
+        native = undefined;
+    }
+    const report = { version: 'checked-component-plan-v1', model: 'checked-components-v1', scope: 'native-component-source-and-mapping',
+        ready: !!native && !blockers.length, executed: false, runtime: 'not-assessed-operation-invocation-required',
+        dimensions: { sourceLegality: native ? 'established' : blockers.some(b => b.category === 'invalid-source') ? 'disproved' : 'unassessed',
+            correspondence: native ? 'established' : 'unassessed', mapping: native ? 'established' : 'unassessed', runtime: 'unassessed' },
+        inventory: { complete, unassessed: complete ? [] : ['unloaded documents and their service/binding/operation identities; native whole-source prerequisites'], ...counts },
+        candidates, resources: documents.map((d, i) => ({ resource: `resource-${i + 1}`, digest: d.digest })), operations,
+        ...(native && native.projections.size ? { responseProjections: native.expected.flatMap(operation => operation.responseProjection
+                ? [{ selector: operation.contract.selector, spec: operation.responseProjection.spec,
+                        delivery: 'buffered', retainedValue: 'complete-companion-payload' }] : []) } : {}),
+        ...(config && selectors.length ? { selection: { service: config.service, port: config.port, selectors } } : {}), blockers: order(blockers),
+        ...(intake && blockers.some(b => b.category === 'missing-dependency' && b.reason.startsWith('locationless-import:')) ? { resolution: {
+                instructions: 'Save configuration as checked JSON. Replace REQUIRED_SCHEMA_LOCATION with an authorized schema path; paths resolve from the invocation working directory. Rerun the same pipeline with --checked-config. Reports never authorize generation.',
+                configuration: { ...Object.fromEntries(Object.entries(explicit).filter(([key]) => key !== 'signal')), namespaceLocations: unresolved }
+            } } : {}) };
+    return { report, ...(config ? { config } : {}), ...(native ? { native } : {}) };
+}

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -9,15 +9,19 @@
  * invocation (no subcommand) is kept for backward compatibility and behaves like the client
  * command with legacy flags.
  */
+import { assessSchemaSource, serializeAssessmentReport, assessmentExitCode } from "./compiler/checkedAssessment.js";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveResourceUri } from "./loader/schemaResources.js";
 import { loadWsdl } from "./loader/wsdlLoader.js";
 import { compileCatalog } from "./compiler/schemaCompiler.js";
 import { generateTypes } from "./client/generateTypes.js";
 import { generateUtils } from "./client/generateUtils.js";
 import { generateCatalog } from "./compiler/generateCatalog.js";
+import { readLegacyCatalogFile, CatalogError } from "./compiler/semanticCatalog.js";
 import { generateClient } from "./client/generateClient.js";
 import { generateOperations } from "./client/generateOperations.js";
 import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
@@ -47,7 +51,7 @@ function loadStreamConfigOrExit(filePath) {
 // Process command line arguments, removing the first two elements (node executable and script path)
 const rawArgs = hideBin(process.argv);
 // Available commands
-const COMMANDS = ["compile", "client", "openapi", "gateway", "app", "pipeline"];
+const COMMANDS = ["compile", "client", "openapi", "gateway", "app", "pipeline", "assess"];
 // ---------------------------------------------------------------------------
 // Show help if no subcommand provided
 // ---------------------------------------------------------------------------
@@ -56,6 +60,7 @@ if (!rawArgs[0] || !COMMANDS.includes(rawArgs[0])) {
         .version(false)
         .scriptName("wsdl-tsc")
         .usage("$0 <command> [options]")
+        .command("assess", "Assess narrow direct-schema obligations; component readiness uses pipeline --checked-report")
         .command("compile", "Compile WSDL to catalog.json")
         .command("client", "Generate TypeScript SOAP client from WSDL or catalog")
         .command("openapi", "Generate OpenAPI specification from WSDL or catalog")
@@ -68,6 +73,45 @@ if (!rawArgs[0] || !COMMANDS.includes(rawArgs[0])) {
         .parse();
     process.exit(1);
 }
+// Assessment is deliberately independent of every generation command.
+if (rawArgs[0] === "assess") {
+    const argv = await yargs(rawArgs.slice(1)).version(false).scriptName("wsdl-tsc assess")
+        .option("wsdl-source", { type: "string", demandOption: true, desc: "Authorized local WSDL/XSD source" })
+        .option("report", { type: "string", demandOption: true, desc: "Diagnostic JSON report path" })
+        .option("schema-root", { type: "array", string: true, desc: "Authorized schema root; defaults to source directory" })
+        .option("schema-origin", { type: "array", string: true, desc: "Explicitly authorized HTTP(S) origin" })
+        .option("assessment-max-work", { type: "number", desc: "Inclusive shared request work limit" })
+        .option("assessment-max-nodes", { type: "number", desc: "Inclusive shared request node limit" })
+        .strict().help().parse();
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.on("SIGINT", cancel);
+    try {
+        const source = argv["wsdl-source"];
+        let localFile;
+        try {
+            const uri = resolveResourceUri(source);
+            localFile = uri.startsWith("file:") ? fileURLToPath(uri) : undefined;
+        }
+        catch {
+            // Root inference grants nothing on failure; the API still publishes its loading diagnostic.
+        }
+        const report = await assessSchemaSource(source, { signal: controller.signal, loading: { policy: {
+                    fileRoots: argv["schema-root"] ?? (localFile ? [path.dirname(localFile)] : []),
+                    allowedOrigins: argv["schema-origin"] ?? [],
+                } }, limits: { maxWork: argv["assessment-max-work"], maxNodes: argv["assessment-max-nodes"] } });
+        fs.writeFileSync(argv.report, serializeAssessmentReport(report), { encoding: "utf8" });
+        console.error(`Schema: ${report.schema}; correspondence: ${report.correspondence}; execution: ${report.execution}; generation: not admitted`);
+        process.exitCode = assessmentExitCode(report);
+    }
+    catch {
+        console.error("Assessment or report publication failed; source details redacted");
+        process.exitCode = 1;
+    }
+    finally {
+        process.off("SIGINT", cancel);
+    }
+}
 // ---------------------------------------------------------------------------
 // Compile subcommand - Parse WSDL and generate catalog
 // ---------------------------------------------------------------------------
@@ -191,8 +235,7 @@ if (rawArgs[0] === "client") {
     else {
         // Only catalog-file provided: it's an input, load it
         const catalogPath = path.resolve(String(clientArgv["catalog-file"]));
-        const catalogContent = fs.readFileSync(catalogPath, "utf-8");
-        compiled = JSON.parse(catalogContent);
+        compiled = readLegacyCatalogFile(catalogPath);
         success(`Loaded catalog from ${catalogPath}`);
     }
     // If we need to compile from WSDL
@@ -540,11 +583,12 @@ if (rawArgs[0] === "app") {
     let imports = appArgv["import-extensions"];
     if (!imports && fs.existsSync(catalogFile)) {
         try {
-            const catalogContent = fs.readFileSync(catalogFile, "utf-8");
-            const catalog = JSON.parse(catalogContent);
+            const catalog = readLegacyCatalogFile(catalogFile);
             imports = catalog?.options?.imports || "js";
         }
         catch (err) {
+            if (err instanceof CatalogError && err.category === "incompatible-artifact")
+                throw err;
             // If catalog read fails, fall back to "js"
             imports = "js";
         }
@@ -575,6 +619,11 @@ if (rawArgs[0] === "pipeline") {
         .scriptName("wsdl-tsc pipeline")
         .usage("$0 --wsdl-source <file|url> [--client-dir <dir>] [--openapi-file <path>] [--gateway-dir <dir> --gateway-service-name <slug> --gateway-version-prefix <slug>] [--catalog-file <path>] [options]")
         .option("wsdl-source", { type: "string", demandOption: true, desc: "Path or URL to the WSDL" })
+        .option("model", { type: "string", choices: ["legacy", "checked-components-v1"], default: "legacy", desc: "Generation model; components derive unambiguous WSDL selections" })
+        .option("checked-config", { type: "string", desc: "Optional component choices, extra metadata origins or closed offline snapshots" })
+        .option("checked-report", { type: "string", desc: "Write versioned component planning JSON on success or refusal" })
+        .option("checked-draft", { type: "string", desc: "Write minimal component missing-schema configuration when needed" })
+        .option("force-checked-files", { type: "boolean", default: false, desc: "Explicitly replace requested planning report/draft files" })
         // Per-artifact outputs
         .option("client-dir", {
         type: "string",
@@ -731,6 +780,75 @@ if (rawArgs[0] === "pipeline") {
         .strict()
         .help()
         .parse();
+    if (pipelineArgv.model === 'checked-components-v1') {
+        const allowed = new Set(['model', 'checked-config', 'checked-report', 'checked-draft', 'force-checked-files', 'wsdl-source', 'client-dir', 'gateway-dir', 'openapi-file',
+            'gateway-service-name', 'gateway-version-prefix', 'init-app', 'app-dir', 'app-host', 'app-port', 'force-init',
+            'test-dir', 'force-test', 'help', 'openapi-format']);
+        for (const arg of rawArgs.slice(1).filter(a => a.startsWith('--'))) {
+            if (!allowed.has(arg.slice(2).split('=')[0]))
+                handleCLIError(`Unsupported checked model option: ${arg.split('=')[0]}`);
+        }
+        if (pipelineArgv.model !== 'checked-components-v1' && (pipelineArgv['checked-report'] || pipelineArgv['checked-draft'] || pipelineArgv['force-checked-files']))
+            handleCLIError('Planning files require checked-components-v1');
+        if (pipelineArgv['init-app'] && !pipelineArgv['app-dir'])
+            handleCLIError(`${pipelineArgv.model} requires explicit --app-dir with --init-app`);
+        if (pipelineArgv['openapi-format'] && pipelineArgv['openapi-format'] !== 'json')
+            handleCLIError(`${pipelineArgv.model} emits JSON OpenAPI only`);
+        const { CheckedPlanningError, writeCheckedPlanningFile, prepareCheckedComponentPlan } = await import('./checkedPlanning.js');
+        const supplied = pipelineArgv['checked-config'] ? JSON.parse(fs.readFileSync(pipelineArgv['checked-config'], 'utf8')) : {};
+        const writePlan = (report) => {
+            if (pipelineArgv['checked-report'])
+                writeCheckedPlanningFile(pipelineArgv['checked-report'], report, pipelineArgv['force-checked-files']);
+            if (pipelineArgv['checked-draft'] && report.resolution)
+                writeCheckedPlanningFile(pipelineArgv['checked-draft'], report.resolution.configuration, pipelineArgv['force-checked-files']);
+        };
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        process.on('SIGINT', cancel);
+        let checkedExitCode = 0;
+        try {
+            if (pipelineArgv.model === 'checked-components-v1' && (!supplied || typeof supplied !== 'object' || Array.isArray(supplied))) {
+                throw new CheckedPlanningError((await prepareCheckedComponentPlan(pipelineArgv['wsdl-source'], supplied)).report);
+            }
+            const result = await runGenerationPipeline({
+                model: pipelineArgv.model,
+                checkedComponents: { ...supplied, signal: controller.signal },
+                wsdl: pipelineArgv['wsdl-source'], catalogOut: '',
+                clientOutDir: pipelineArgv['client-dir'],
+                openapi: { outFile: pipelineArgv['openapi-file'] },
+                gateway: { outDir: pipelineArgv['gateway-dir'] ?? '', serviceSlug: pipelineArgv['gateway-service-name'] ?? '',
+                    versionSlug: pipelineArgv['gateway-version-prefix'] ?? '' },
+                app: pipelineArgv['init-app'] ? { appDir: pipelineArgv['app-dir'] ?? '', force: pipelineArgv['force-init'],
+                    host: pipelineArgv['app-host'], port: pipelineArgv['app-port'] } : undefined,
+                test: pipelineArgv['test-dir'] ? { testDir: pipelineArgv['test-dir'], force: pipelineArgv['force-test'] } : undefined,
+            });
+            if (result.planning)
+                writePlan(result.planning);
+            console.log(JSON.stringify(result.checked, null, 2));
+        }
+        catch (error) {
+            if (!(error instanceof CheckedPlanningError))
+                throw error;
+            writePlan(error.report);
+            if (process.env.DEBUG?.split(/[\s,]+/).includes('wsdl-tsc'))
+                console.error(error);
+            else {
+                const { formatCheckedCliRefusal } = await import('./util/checkedCliDiagnostics.js');
+                console.error(formatCheckedCliRefusal(error.report));
+            }
+            // @why Drain diagnostic writes before the CLI's explicit exit, including piped DEBUG reports.
+            await new Promise(resolve => { process.stderr.write('', () => resolve()); });
+            checkedExitCode = 1;
+        }
+        finally {
+            process.off('SIGINT', cancel);
+        }
+        process.exit(checkedExitCode);
+    }
+    if (pipelineArgv['checked-config'])
+        handleCLIError('--checked-config requires --model checked-components-v1');
+    if (pipelineArgv['checked-report'] || pipelineArgv['checked-draft'] || pipelineArgv['force-checked-files'])
+        handleCLIError('Planning files require checked-components-v1');
     const format = pipelineArgv["openapi-format"] ?? "json";
     const clientOut = pipelineArgv["client-dir"];
     const openapiOut = pipelineArgv["openapi-file"];

package/dist/client/checkedDirectRuntime.d.ts

@@ -0,0 +1,96 @@
+import { DIRECT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_VERSION } from './directClientVersion.js';
+interface Name {
+    readonly namespace: string;
+    readonly local: string;
+}
+interface Usage {
+    readonly nodes: number;
+    readonly work: number;
+}
+interface Options {
+    readonly localSource: string;
+    readonly fileRoots: readonly string[];
+    readonly capsule: Uint8Array;
+    readonly soap: {
+        readonly service: Name;
+        readonly port: string;
+        readonly endpoint: string;
+        readonly allowEndpoint: (endpoint: URL) => boolean;
+        readonly signal?: AbortSignal;
+        readonly timeoutMs?: number;
+        readonly capabilities?: readonly string[];
+        readonly limits?: {
+            readonly maxBytes?: number;
+            readonly maxDepth?: number;
+            readonly maxNodes?: number;
+            readonly maxText?: number;
+        };
+    };
+}
+interface Failure {
+    readonly kind: 'incompatible-artifact' | 'unsupported' | 'missing-authority' | 'resource-limit' | 'cancelled' | 'inconclusive' | 'invalid-schema' | 'scalar-invalid' | 'value-invalid' | 'xml-invalid' | 'mismatch' | 'transport' | 'protocol';
+    readonly rule: string;
+    readonly usage: Usage;
+    readonly repair?: string;
+    readonly phase?: 'input' | 'response';
+}
+type Success = {
+    readonly value: unknown;
+    readonly admitted: false;
+    readonly status: number;
+    readonly usage: Usage;
+    readonly responseBytes: Uint8Array;
+} & ({
+    readonly kind: 'soap-response';
+} | {
+    readonly kind: 'soap-fault';
+    readonly fault: {
+        readonly name: string;
+        readonly code: Name;
+        readonly string: string;
+        readonly actor?: string;
+    };
+});
+type ComponentOptions = Omit<Options, 'soap'> & {
+    readonly sourceResources: readonly {
+        readonly uri: string;
+        readonly file: string;
+        readonly canonicalUri?: string;
+    }[];
+    readonly sourceUri?: string;
+    readonly sourceOrigins: readonly string[];
+    readonly namespaceLocations?: readonly {
+        readonly namespace: string;
+        readonly location: string;
+    }[];
+    readonly standardLibraries?: readonly string[];
+    readonly recordSources?: readonly {
+        readonly selector: {
+            readonly portType: Name;
+            readonly binding: Name;
+            readonly operation: string;
+        };
+        readonly source: string;
+    }[];
+    readonly soap: Omit<Options['soap'], 'endpoint' | 'allowEndpoint'> & {
+        readonly ca?: string;
+        readonly endpoint?: string;
+        readonly allowEndpoint?: (endpoint: URL) => boolean;
+    };
+};
+/** Scoped direct-grammar binding used by the opt-in checked gateway preview. */
+export declare const checkedDirectRuntimeV1: Readonly<{
+    version: typeof DIRECT_CLIENT_RUNTIME_VERSION;
+    execute(expectedBase64: string, input: unknown, options: Options, version: typeof DIRECT_CLIENT_RUNTIME_VERSION): Promise<Failure | Success>;
+}>;
+/** Component injection protocol over the shared checked source, artifact and SOAP runtime.
+ * @remarks Caller-authorized physical source resources are read independently of embedded artifact bytes.
+ *   Component runtime v2 derives endpoint intent; explicit restrictions and TLS trust still apply.
+ *   This entry accepts no diagnostic budget or deadline defaults.
+ * @returns Native-validated normal/fault values or explicit refusal. No gateway admission is issued here.
+ */
+export declare const checkedComponentRuntimeV1: Readonly<{
+    version: typeof COMPONENT_CLIENT_RUNTIME_VERSION;
+    execute(expectedBase64: string, input: unknown, options: ComponentOptions, version: typeof COMPONENT_CLIENT_RUNTIME_VERSION): Promise<Failure | Success>;
+}>;
+export {};

package/dist/client/checkedDirectRuntime.js

@@ -0,0 +1,43 @@
+import { types } from 'node:util';
+import { directClientRuntime, componentClientRuntime } from './directClientRuntime.js';
+import { DIRECT_CLIENT_RUNTIME_VERSION, DIRECT_CLIENT_RUNTIME_REPAIR, COMPONENT_CLIENT_RUNTIME_VERSION, COMPONENT_CLIENT_RUNTIME_REPAIR } from './directClientVersion.js';
+function dataOptions(options, allowed) {
+    return !!options && typeof options === 'object' && !types.isProxy(options)
+        && [null, Object.prototype].includes(Object.getPrototypeOf(options))
+        && !Reflect.ownKeys(options).some(key => typeof key !== 'string' || !allowed.includes(key)
+            || !Object.hasOwn(Object.getOwnPropertyDescriptor(options, key), 'value'));
+}
+/** Scoped direct-grammar binding used by the opt-in checked gateway preview. */
+export const checkedDirectRuntimeV1 = Object.freeze({
+    version: DIRECT_CLIENT_RUNTIME_VERSION,
+    async execute(expectedBase64, input, options, version) {
+        if (version !== DIRECT_CLIENT_RUNTIME_VERSION)
+            return Object.freeze({ kind: 'incompatible-artifact',
+                rule: 'generated-runtime-version', repair: DIRECT_CLIENT_RUNTIME_REPAIR,
+                usage: Object.freeze({ nodes: 0, work: 0 }) });
+        // The public entry never accepts the private profiling hook, even from JavaScript.
+        // Inspect descriptors before forwarding so getters/proxies cannot supply it.
+        if (!dataOptions(options, ['localSource', 'fileRoots', 'capsule', 'soap'])) {
+            return Object.freeze({ kind: 'unsupported', rule: 'data-only checked direct options required', usage: Object.freeze({ nodes: 0, work: 0 }) });
+        }
+        return directClientRuntime.execute(expectedBase64, input, options);
+    },
+});
+/** Component injection protocol over the shared checked source, artifact and SOAP runtime.
+ * @remarks Caller-authorized physical source resources are read independently of embedded artifact bytes.
+ *   Component runtime v2 derives endpoint intent; explicit restrictions and TLS trust still apply.
+ *   This entry accepts no diagnostic budget or deadline defaults.
+ * @returns Native-validated normal/fault values or explicit refusal. No gateway admission is issued here.
+ */
+export const checkedComponentRuntimeV1 = Object.freeze({
+    version: COMPONENT_CLIENT_RUNTIME_VERSION,
+    async execute(expectedBase64, input, options, version) {
+        if (version !== COMPONENT_CLIENT_RUNTIME_VERSION)
+            return Object.freeze({ kind: 'incompatible-artifact',
+                rule: 'generated-runtime-version', repair: COMPONENT_CLIENT_RUNTIME_REPAIR, usage: Object.freeze({ nodes: 0, work: 0 }) });
+        if (!dataOptions(options, ['localSource', 'fileRoots', 'capsule', 'soap', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'standardLibraries', 'recordSources'])) {
+            return Object.freeze({ kind: 'unsupported', rule: 'data-only checked component options required', usage: Object.freeze({ nodes: 0, work: 0 }) });
+        }
+        return componentClientRuntime.execute(expectedBase64, input, options);
+    },
+});