@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/dist/checkedPipeline.js

@@ -0,0 +1,448 @@
+/**
+ * Opt-in direct gateway orchestration over the existing native owners.
+ * @since Unreleased
+ * @see ../docs/decisions/003-content-model-contracts.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
+import { types } from 'node:util';
+import { createHash } from 'node:crypto';
+import { resolveResourceUri } from './loader/schemaResources.js';
+import { selectComponentOperations, inspectDirectOperation } from './compiler/directOperation.js';
+import { prepareComponentSourceForOperation } from './compiler/directSourceCapsule.js';
+import { inspectComponentSourceService } from './compiler/directSourceCapsule.js';
+import { generateComponentClient, writeComponentServiceClient } from './client/generateDirectClient.js';
+import { copyOriginalSchemaResource, prepareSchemaSnapshotFiles } from './loader/schemaInput.js';
+import { createApplicationBudget } from './compiler/semanticBudget.js';
+import { directLoadingLimits } from './compiler/directExecutionPolicy.js';
+import { generateComponentServiceGateway } from './gateway/generateCheckedGateway.js';
+import { generateCheckedApp } from './app/generateCheckedApp.js';
+import { generateCheckedTests } from './test/generateCheckedTests.js';
+import { commonSourceDirectory, assertCanonicalSourceLayout } from './generation/sourceLayout.js';
+import { createComponentRecordProjection, inspectComponentRecordProjection } from './compiler/componentRecordProjection.js';
+import { acquireStandardSchemaLibrary, SCHEMA_ELEMENT_LIBRARY } from './compiler/standardSchemaComponents.js';
+import { ComponentSoapPreparation } from './compiler/componentSoapPreparation.js';
+import { parseApplicationGroups } from './compiler/applicationGroups.js';
+import { inspectComponentValueMapping } from './compiler/directValues.js';
+/** Read explicit component configuration without invoking getters or accepting unknown controls.
+ * @returns A copied configuration; all schema, mapping and operation decisions remain native duties.
+ * @throws TypeError For missing, malformed, duplicate or unsupported configuration.
+ */
+export function parseCheckedComponentOptions(value) {
+    return parseComponentOptions(value, true);
+}
+/** Validate caller choices before discovery without fabricating resolved identities.
+ * @param value Data-only optional choices.
+ * @returns Copied choices; absent selections remain absent.
+ * @throws TypeError For malformed or unsupported controls.
+ */
+export function parseCheckedComponentChoices(value) {
+    return parseComponentOptions(value, false);
+}
+function parseComponentOptions(value, resolved) {
+    const record = (input, allowed, required = allowed) => {
+        if (!input || typeof input !== 'object' || types.isProxy(input) || ![null, Object.prototype].includes(Object.getPrototypeOf(input)))
+            throw new TypeError('Data-only component configuration required');
+        const result = Object.create(null);
+        for (const key of Reflect.ownKeys(input)) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (typeof key !== 'string' || !allowed.includes(key) || !('value' in descriptor))
+                throw new TypeError('Unknown component configuration or accessor');
+            result[key] = descriptor.value;
+        }
+        if (required.some(key => !Object.hasOwn(result, key)))
+            throw new TypeError('Missing component configuration');
+        return result;
+    };
+    const array = (input) => {
+        if (!Array.isArray(input) || types.isProxy(input) || Reflect.ownKeys(input).length !== input.length + 1)
+            throw new TypeError('Dense component configuration array required');
+        const result = [];
+        for (let index = 0; index < input.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+            if (!descriptor || !('value' in descriptor))
+                throw new TypeError('Data-only component configuration array required');
+            result.push(descriptor.value);
+        }
+        return result;
+    };
+    const text = (input) => { if (typeof input !== 'string' || !input.length)
+        throw new TypeError('Nonempty configuration string required'); return input; };
+    const name = (input) => {
+        const n = record(input, ['namespace', 'local']);
+        if (typeof n.namespace !== 'string')
+            throw new TypeError('Namespace string required');
+        return { namespace: n.namespace, local: text(n.local) };
+    };
+    const selector = (input) => {
+        const s = record(input, ['portType', 'binding', 'operation']);
+        return { portType: name(s.portType), binding: name(s.binding), operation: text(s.operation) };
+    };
+    const libraries = (input) => {
+        const ids = array(input).map(text);
+        if (ids.some(id => id !== SCHEMA_ELEMENT_LIBRARY) || new Set(ids).size !== ids.length)
+            throw new TypeError('Known unique standard libraries required');
+        return ids.sort();
+    };
+    const data = record(value, ['selectors', 'service', 'port', 'fileRoots', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'basePath', 'signal', 'standardLibraries', 'recordProjections', 'applicationGroups'], resolved ? ['selectors', 'service', 'port', 'fileRoots', 'sourceResources', 'sourceOrigins'] : []);
+    if (['selectors', 'service', 'port', 'fileRoots', 'sourceResources', 'sourceOrigins'].some(key => Object.hasOwn(data, key) && data[key] === undefined))
+        throw new TypeError('Explicit component choices must not be undefined');
+    const selectors = data.selectors === undefined ? undefined : array(data.selectors).map(selector);
+    if (selectors && (!selectors.length || new Set(selectors.map(selector => JSON.stringify(selector))).size !== selectors.length))
+        throw new TypeError('Nonempty unique component selectors required');
+    const fileRoots = data.fileRoots === undefined ? undefined : array(data.fileRoots).map(text);
+    const sourceResources = data.sourceResources === undefined ? undefined : array(data.sourceResources).map(input => {
+        const r = record(input, ['uri', 'file', 'canonicalUri'], ['uri', 'file']);
+        return { uri: text(r.uri), file: text(r.file), ...(r.canonicalUri === undefined ? {} : { canonicalUri: resolveResourceUri(text(r.canonicalUri)) }) };
+    });
+    const sourceOrigins = data.sourceOrigins === undefined ? undefined : array(data.sourceOrigins).map(text);
+    const standardLibraries = data.standardLibraries === undefined ? undefined : libraries(data.standardLibraries);
+    const recordProjections = data.recordProjections === undefined ? undefined : array(data.recordProjections).map(input => {
+        const r = record(input, ['selector', 'source', 'recordSelector', 'spec', 'scope', 'recordPath', 'standardLibraries'], ['selector', 'source', 'recordSelector']);
+        const common = { selector: selector(r.selector), source: text(r.source), recordSelector: selector(r.recordSelector),
+            ...(r.standardLibraries === undefined ? {} : { standardLibraries: libraries(r.standardLibraries) }) };
+        const path = (input) => { const names = array(input).map(name); if (!names.length)
+            throw new TypeError('Nonempty record path required'); return names; };
+        if (!Object.hasOwn(r, 'spec')) {
+            if (r.scope !== 'records-with-declared-wrapper-scope')
+                throw new TypeError('Explicit records-with-declared-wrapper-scope acknowledgement required');
+            return { ...common, scope: r.scope, ...(r.recordPath === undefined ? {} : { recordPath: path(r.recordPath) }) };
+        }
+        if (Object.hasOwn(r, 'scope') || Object.hasOwn(r, 'recordPath'))
+            throw new TypeError('Conflicting concise and complete record projection choices');
+        const s = record(r.spec, ['version', 'scope', 'payloadPath', 'recordPath', 'opaqueExclusions']);
+        if (s.version !== 'component-record-scope-v1' || s.scope !== 'records-with-declared-wrapper-scope')
+            throw new TypeError('Supported explicit record projection required');
+        const opaqueExclusions = array(s.opaqueExclusions).map(input => {
+            const e = record(input, ['path', 'reason']);
+            if (e.reason !== 'standard-schema-metadata' && e.reason !== 'wrapper-declaration-universe')
+                throw new TypeError('Explicit supported exclusion reason required');
+            return { path: path(e.path), reason: e.reason };
+        });
+        const spec = { version: 'component-record-scope-v1', scope: 'records-with-declared-wrapper-scope',
+            payloadPath: path(s.payloadPath), recordPath: path(s.recordPath), opaqueExclusions };
+        return { ...common, spec };
+    });
+    if (recordProjections) {
+        const keys = recordProjections.map(item => JSON.stringify(item.selector));
+        if (new Set(keys).size !== keys.length || selectors && keys.some(key => !selectors.some(selector => JSON.stringify(selector) === key)))
+            throw new TypeError('Record projections require unique requested outer selectors');
+    }
+    const namespaceLocations = data.namespaceLocations === undefined ? undefined : array(data.namespaceLocations).map(input => {
+        const r = record(input, ['namespace', 'location']);
+        if (typeof r.namespace !== 'string')
+            throw new TypeError('Namespace string required');
+        return { namespace: r.namespace, location: text(r.location) };
+    });
+    const basePath = data.basePath === undefined ? undefined : text(data.basePath);
+    if (basePath && (!basePath.startsWith('/') || basePath.endsWith('/') || basePath.split('/').slice(1).some(segment => !/^(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+$/.test(segment))))
+        throw new TypeError('Literal nonempty route prefix required');
+    if (data.signal !== undefined && !(data.signal instanceof AbortSignal))
+        throw new TypeError('Native AbortSignal required');
+    return { ...(selectors ? { selectors } : {}), ...(data.service === undefined ? {} : { service: name(data.service) }),
+        ...(Object.hasOwn(data, 'applicationGroups') ? { applicationGroups: parseApplicationGroups(data.applicationGroups) } : {}),
+        ...(data.port === undefined ? {} : { port: text(data.port) }), ...(fileRoots ? { fileRoots } : {}),
+        ...(sourceResources ? { sourceResources } : {}), ...(sourceOrigins ? { sourceOrigins } : {}),
+        ...(data.sourceUri === undefined ? {} : { sourceUri: resolveResourceUri(text(data.sourceUri)) }),
+        ...(standardLibraries ? { standardLibraries } : {}), ...(recordProjections ? { recordProjections } : {}),
+        ...(namespaceLocations ? { namespaceLocations } : {}), ...(basePath ? { basePath } : {}), ...(data.signal ? { signal: data.signal } : {}) };
+}
+/**
+ * Generate the bounded preview without creating a flattened catalog authority.
+ * @param opts Public pipeline options with the checked model explicitly selected.
+ * @returns Documentation and an operation inventory; no native authority is serialized as a report.
+ * @throws Error Before emission for unsupported controls or failed native qualification.
+ * @sideEffects Writes generator-owned artifacts and preserves existing scaffolds unless forced.
+ */
+export async function runCheckedPipeline(opts) {
+    const model = 'checked-components-v1';
+    if (opts.catalogOut !== undefined && opts.catalogOut !== '')
+        throw new Error(`${model} does not accept legacy catalog output`);
+    if (opts.test && !opts.app)
+        throw new Error('Checked scaffold tests require app generation');
+    if (!opts.clientOutDir || !opts.gateway?.outDir || !opts.openapi?.outFile) {
+        throw new Error(`${model} requires explicit client, OpenAPI and gateway outputs`);
+    }
+    if (opts.streamConfig || opts.streamConfigFile || opts.compiler && Object.keys(opts.compiler).length) {
+        throw new Error(`${model} does not accept legacy compiler or streaming controls`);
+    }
+    const rejectExtra = (v, allowed) => {
+        if (v && Object.entries(v).some(([k, val]) => val !== undefined && !allowed.includes(k))) {
+            throw new Error('Unsupported checked pipeline stage control; use the documented checked options');
+        }
+    };
+    rejectExtra(opts.openapi, ['outFile']);
+    rejectExtra(opts.gateway, ['outDir', 'versionSlug', 'serviceSlug']);
+    rejectExtra(opts.app, ['appDir', 'force', 'host', 'port']);
+    rejectExtra(opts.test, ['testDir', 'force']);
+    const { versionSlug, serviceSlug } = opts.gateway;
+    if (![versionSlug, serviceSlug].every(s => /^[A-Za-z0-9_-]+$/.test(s)))
+        throw new Error('Checked route slugs must use letters, digits, underscores or hyphens');
+    const clientDir = path.resolve(opts.clientOutDir), gatewayDir = path.resolve(opts.gateway.outDir);
+    const openapiFile = path.resolve(opts.openapi.outFile);
+    const outputs = [clientDir, gatewayDir, openapiFile, ...(opts.test ? [path.resolve(opts.test.testDir)] : [])];
+    if (opts.app) {
+        const appDir = path.resolve(opts.app.appDir);
+        if (outputs.some(p => { const relative = path.relative(appDir, p); return !relative || relative.startsWith('..') || path.isAbsolute(relative); })) {
+            throw new Error('Checked project client, gateway, OpenAPI and tests must be within appDir');
+        }
+        const reserved = new Set(['server.ts', 'package.json', 'tsconfig.json', 'readme.md', '.gitignore',
+            'checked-gateway.example.json', 'checked-gateway.local.json', 'dist', 'node_modules', '.git']);
+        if (outputs.some(p => reserved.has(path.relative(appDir, p).split(path.sep)[0].toLowerCase()))) {
+            throw new Error('Checked artifact outputs must not occupy scaffold files or build/dependency directories');
+        }
+    }
+    for (const [i, output] of outputs.entries()) {
+        for (const other of outputs.slice(i + 1)) {
+            const a = path.relative(output, other), b = path.relative(other, output);
+            if (!a || !a.startsWith('..') && !path.isAbsolute(a) || !b.startsWith('..') && !path.isAbsolute(b)) {
+                throw new Error('Checked artifact output locations must not overlap');
+            }
+        }
+    }
+    const layout = { clientDir, gatewayDir, openapiFile, basePath: `/${versionSlug}/${serviceSlug}` };
+    const planning = await (await import('./checkedPlanning.js')).prepareCheckedComponentPlan(opts.wsdl, opts.checkedComponents, layout);
+    if (!planning.native || !planning.config)
+        throw new (await import('./checkedPlanning.js')).CheckedPlanningError(planning.report);
+    return runComponentStages(opts, planning.config, { clientDir, gatewayDir, openapiFile,
+        basePath: planning.config.basePath ?? `/${versionSlug}/${serviceSlug}` }, planning.native, planning.report);
+}
+/** Prepare through native owners only; internal handles remain within this invocation. */
+export async function prepareComponentStages(wsdl, config, acquired, outputs = { clientDir: 'client', gatewayDir: 'gateway', openapiFile: 'openapi.json', basePath: '/v1/service' }) {
+    const tick = () => { if (config.signal?.aborted)
+        throw new Error('Checked component generation cancelled'); };
+    const namespaces = new Map(config.namespaceLocations?.map(location => [location.namespace, location.location]));
+    if (namespaces.size !== (config.namespaceLocations?.length ?? 0))
+        throw new TypeError('Duplicate namespace location');
+    const budget = createApplicationBudget();
+    const loading = { policy: {
+            fileRoots: config.fileRoots, allowedOrigins: config.sourceOrigins
+        }, namespaceLocations: namespaces,
+        limits: directLoadingLimits(budget), signal: config.signal, chargeWork: (amount) => { tick(); budget.chargeWork(amount); } };
+    const offlineResources = acquired ? new Map([...acquired.resourceAliases].map(([alias, uri]) => {
+        const resource = acquired.resources.find(r => r.uri === uri);
+        return [alias, { bytes: copyOriginalSchemaResource(acquired, uri, loading.chargeWork), digest: resource.digest, canonicalUri: uri }];
+    })) : undefined;
+    const prepared = acquired ? { source: resolveResourceUri(wsdl), loading: { ...loading, offlineResources } }
+        : await prepareSchemaSnapshotFiles(wsdl, config.sourceResources, { ...loading, sourceUri: config.sourceUri });
+    const selected = await selectComponentOperations(config.sourceUri ?? prepared.source, config.selectors, { loading: prepared.loading, signal: config.signal,
+        standardLibraries: config.standardLibraries?.map(acquireStandardSchemaLibrary) });
+    const refusals = selected.flatMap((result, index) => result.kind === 'selected' ? [] : [{ selector: config.selectors[index], kind: result.kind, rule: result.rule, dimension: 'qualification-and-correspondence' }]);
+    const expected = [];
+    const projections = new Map();
+    const groups = new Map();
+    for (const projection of config.recordProjections ?? []) {
+        const key = JSON.stringify([resolveResourceUri(projection.source), projection.standardLibraries ?? []]);
+        const group = groups.get(key) ?? [];
+        group.push(projection);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        tick();
+        const first = group[0];
+        const source = await prepareSchemaSnapshotFiles(first.source, config.sourceResources, { policy: {
+                fileRoots: config.fileRoots, allowedOrigins: config.sourceOrigins
+            }, namespaceLocations: namespaces,
+            limits: directLoadingLimits(budget), signal: config.signal, chargeWork: amount => { tick(); budget.chargeWork(amount); } });
+        const companions = await selectComponentOperations(source.source, group.map(item => item.recordSelector), { loading: source.loading,
+            signal: config.signal, standardLibraries: first.standardLibraries?.map(acquireStandardSchemaLibrary) });
+        for (const [index, entry] of group.entries()) {
+            tick();
+            const companion = companions[index], outer = selected[config.selectors.findIndex(selector => JSON.stringify(selector) === JSON.stringify(entry.selector))];
+            if (outer.kind !== 'selected')
+                continue;
+            if (companion.kind !== 'selected') {
+                refusals.push({ selector: entry.selector, kind: companion.kind, rule: `record-source:${companion.rule}`, dimension: 'mapping-and-artifact' });
+                continue;
+            }
+            const native = createComponentRecordProjection(outer.contract, companion.contract, entry.spec ?? {
+                scope: entry.scope, ...(entry.recordPath ? { recordPath: entry.recordPath } : {})
+            }, { signal: config.signal });
+            if (native.kind !== 'component-record-projection') {
+                refusals.push({ selector: entry.selector, kind: native.kind, rule: native.rule, dimension: 'mapping-and-artifact' });
+                continue;
+            }
+            projections.set(JSON.stringify(entry.selector), native);
+        }
+    }
+    const preparation = new ComponentSoapPreparation();
+    for (const result of selected) {
+        tick();
+        if (result.kind !== 'selected')
+            continue;
+        const projection = projections.get(JSON.stringify(result.contract.selector));
+        if (!projection && config.recordProjections?.some(entry => JSON.stringify(entry.selector) === JSON.stringify(result.contract.selector)))
+            continue;
+        const native = await prepareComponentSourceForOperation(result.contract, { service: config.service, port: config.port }, preparation, config.signal, projection, config.applicationGroups);
+        if (native.kind !== 'reconstructed-component') {
+            refusals.push({ selector: result.contract.selector, kind: native.kind, rule: native.rule, dimension: 'mapping-and-artifact' });
+            continue;
+        }
+        expected.push(native);
+    }
+    const groupTargets = new Map(), groupRecords = new Map();
+    for (const operation of expected)
+        for (const mapping of operation.mappings) {
+            if (mapping.kind !== 'component-mapping')
+                continue;
+            const groups = inspectComponentValueMapping(mapping, operation.contract).applicationGroups;
+            for (const target of groups?.targets ?? [])
+                groupTargets.set(target.target, target);
+            for (const record of groups?.dispositions ?? [])
+                groupRecords.set(record.source, record);
+        }
+    if (config.applicationGroups) {
+        for (const [index, item] of (config.applicationGroups.names ?? []).entries())
+            if (!groupTargets.has(item.target))
+                throw new TypeError(`applicationGroups.names[${index}]: unknown, stale or retained-ordered target ${item.target}`);
+        const types = new Map();
+        for (const target of groupTargets.values()) {
+            const previous = types.get(target.resolved.typeName);
+            if (previous && previous !== target.target)
+                throw new TypeError(`applicationGroups ${target.source}: typeName collision ${target.resolved.typeName}`);
+            types.set(target.resolved.typeName, target.target);
+        }
+    }
+    const applicationGroups = config.applicationGroups ? { targets: [...groupTargets.values()].sort((a, b) => a.target.localeCompare(b.target, 'en')),
+        records: [...groupRecords.values()].sort((a, b) => a.source.localeCompare(b.source, 'en')) } : undefined;
+    let layout;
+    const generatedClients = [];
+    let gateway;
+    if (!refusals.length) {
+        try {
+            layout = prepareComponentLayout(expected, projections, tick);
+        }
+        catch (error) {
+            refusals.push({ selector: config.selectors[0], kind: config.signal?.aborted ? 'cancelled' : 'unsupported',
+                rule: error instanceof Error ? error.message : 'source-relocation', dimension: 'mapping-and-artifact' });
+        }
+        for (const operation of inspectComponentSourceService(expected)) {
+            tick();
+            const generated = await generateComponentClient(operation, config.signal);
+            if (generated.kind !== 'generated-component-client')
+                refusals.push({ selector: operation.contract.selector, kind: generated.kind, rule: generated.rule, dimension: 'mapping-and-artifact' });
+            else
+                generatedClients.push(generated);
+        }
+        if (!refusals.length) {
+            try {
+                gateway = await generateComponentServiceGateway(expected, { ...outputs, basePath: config.basePath ?? outputs.basePath, signal: config.signal, emit: false });
+            }
+            catch (error) {
+                const exhausted = expected.some(operation => inspectDirectOperation(operation.contract).context.budget.exhausted());
+                if (!config.signal?.aborted && !exhausted)
+                    throw error;
+                for (const operation of expected)
+                    refusals.push({ selector: operation.contract.selector,
+                        kind: exhausted ? 'resource-limit' : 'cancelled', rule: exhausted ? 'request-budget' : 'cooperative-cancellation', dimension: 'mapping-and-artifact' });
+            }
+        }
+    }
+    return { expected, projections, namespaces, refusals, layout, generatedClients, gateway, applicationGroups };
+}
+function prepareComponentLayout(expected, projections, tick) {
+    const inspection = inspectDirectOperation(expected[0].contract), input = inspection.source;
+    const inputs = new Set([input]);
+    for (const projection of projections.values())
+        inputs.add(inspectDirectOperation(inspectComponentRecordProjection(projection).companion).source);
+    const resources = new Map();
+    for (const source of inputs) {
+        // @constraints Local symlink aliases still require explicit consumer configuration; HTTP aliases are recorded offline.
+        assertCanonicalSourceLayout(source, tick);
+        for (const resource of source.resources) {
+            tick();
+            const previous = resources.get(resource.uri);
+            if (previous && (previous.resource.digest !== resource.digest || !Buffer.from(copyOriginalSchemaResource(previous.input, resource.uri, tick))
+                .equals(Buffer.from(copyOriginalSchemaResource(source, resource.uri, tick)))))
+                throw new Error('Conflicting original source snapshots');
+            resources.set(resource.uri, { input: source, resource });
+        }
+    }
+    const allResources = [...resources.values()].map(entry => entry.resource).sort((a, b) => a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0);
+    const files = allResources.filter(resource => new URL(resource.uri).protocol === 'file:');
+    const common = files.length ? commonSourceDirectory(fileURLToPath(files[0].uri), files.map(resource => fileURLToPath(resource.uri)), tick) : '';
+    return { inspection, input, resources, allResources, common };
+}
+async function runComponentStages(opts, config, outputs, native, report) {
+    const { expected, projections, namespaces } = native;
+    const tick = () => { if (config.signal?.aborted)
+        throw new Error('Checked component generation cancelled'); };
+    const { clientDir, gatewayDir, openapiFile, basePath } = outputs;
+    if (!native.layout)
+        throw new TypeError('Prepared source layout required');
+    const { inspection, input, resources, allResources, common } = native.layout;
+    const copied = new Map();
+    const destinations = new Set();
+    for (const resource of allResources) {
+        const destination = new URL(resource.uri).protocol === 'file:'
+            ? path.join(clientDir, 'source', 'files', path.relative(common, fileURLToPath(resource.uri)))
+            : path.join(clientDir, 'source', 'metadata', createHash('sha256').update(resource.uri).digest('hex') + '.xml');
+        const key = process.platform === 'win32' ? destination.toLowerCase() : destination;
+        if (destinations.has(key))
+            throw new Error('Conflicting copied source destinations');
+        destinations.add(key);
+        copied.set(resource.uri, destination);
+    }
+    const root = copied.get(input.root.uri);
+    const relocated = (uri) => new URL(uri).protocol === 'file:' && copied.has(uri) ? pathToFileURL(copied.get(uri)).href : uri;
+    const sourceResources = allResources
+        .filter(resource => resource.uri !== input.root.uri || new URL(resource.uri).protocol !== 'file:')
+        .map(resource => ({ uri: relocated(resource.uri), file: copied.get(resource.uri) }));
+    for (const { input: source } of resources.values())
+        for (const [alias, uri] of source.resourceAliases) {
+            if (alias !== uri && !sourceResources.some(r => r.uri === alias))
+                sourceResources.push({ uri: alias, file: copied.get(uri), canonicalUri: relocated(uri) });
+        }
+    sourceResources.sort((a, b) => a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0);
+    const namespaceLocations = [...namespaces].map(([namespace, location]) => ({ namespace,
+        location: relocated(resolveResourceUri(location)) }));
+    tick();
+    const contracts = await writeComponentServiceClient(expected, clientDir, config.signal, native.generatedClients);
+    for (const resource of allResources) {
+        tick();
+        const file = copied.get(resource.uri);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, copyOriginalSchemaResource(resources.get(resource.uri).input, resource.uri, amount => inspection.context.budget.chargeWork(amount)));
+    }
+    const sourceRecords = allResources.map(resource => ({ originalUri: resource.uri,
+        logicalUri: relocated(resource.uri), file: path.relative(clientDir, copied.get(resource.uri)).replaceAll('\\', '/'), digest: resource.digest,
+        aliases: [...new Set([...resources.values()].flatMap(({ input: source }) => [...source.resourceAliases]
+                .filter(([alias, uri]) => uri === resource.uri && alias !== uri).map(([alias]) => alias)))].sort() }));
+    if (!native.gateway)
+        throw new TypeError('Prepared gateway required');
+    const { doc, routes } = native.gateway;
+    await native.gateway.emit();
+    const operations = [...config.selectors.flatMap(selector => report.operations.filter(o => o.binding && JSON.stringify(o.portType) === JSON.stringify(selector.portType)
+            && JSON.stringify(o.binding) === JSON.stringify(selector.binding) && o.operation === selector.operation)), ...report.operations.filter(o => !o.selected)]
+        .map(operation => ({ ...operation, generated: operation.selected, executed: false, status: operation.selected ? 'generated' : 'unselected-not-assessed' }));
+    const inventory = { model: 'checked-components-v1', assurance: 'native-component-source-and-mapping', admitted: false,
+        ...(native.applicationGroups ? { applicationGroups: native.applicationGroups } : {}),
+        selection: { selector: config.selectors[0], selectors: config.selectors, service: config.service, port: config.port }, operations };
+    fs.writeFileSync(path.join(clientDir, 'inventory.json'), JSON.stringify(inventory, null, 2) + '\n');
+    const component = { source: root, capsules: Object.fromEntries(Object.entries(contracts).map(([name, file]) => [name, path.resolve(clientDir, file)])),
+        sourceResources, sourceOrigins: config.sourceOrigins, ...(new URL(input.root.uri).protocol === 'file:' ? {} : { sourceUri: input.root.uri }),
+        ...(namespaceLocations.length ? { namespaceLocations } : {}),
+        ...(projections.size ? { recordSources: expected.filter(item => item.responseProjection).map(item => ({ selector: item.contract.selector,
+                source: copied.get(inspectDirectOperation(inspectComponentRecordProjection(item.responseProjection).companion).source.root.uri) })) } : {}),
+        ...((config.standardLibraries?.length || config.recordProjections?.some(item => item.standardLibraries?.length))
+            ? { standardLibraries: [...new Set([...(config.standardLibraries ?? []), ...(config.recordProjections ?? []).flatMap(item => item.standardLibraries ?? [])])].sort() } : {}) };
+    const relativeFile = (file) => path.relative(clientDir, file).replaceAll('\\', '/') || '.';
+    const logical = (uri) => new URL(uri).protocol === 'file:' ? relativeFile(fileURLToPath(uri)) : uri;
+    fs.writeFileSync(path.join(clientDir, 'source-resources.json'), JSON.stringify({ version: 'checked-source-resources-v2', resources: sourceRecords,
+        runtime: { localSource: relativeFile(component.source), fileRoots: ['.'],
+            capsuleFiles: Object.fromEntries(Object.entries(component.capsules).map(([name, file]) => [name, relativeFile(file)])),
+            sourceResources: component.sourceResources.map(resource => ({ uri: logical(resource.uri), file: relativeFile(resource.file),
+                ...(resource.canonicalUri === undefined ? {} : { canonicalUri: logical(resource.canonicalUri) }) })), sourceOrigins: component.sourceOrigins,
+            ...(component.sourceUri === undefined ? {} : { sourceUri: component.sourceUri }),
+            ...(component.namespaceLocations ? { namespaceLocations: component.namespaceLocations.map(location => ({ ...location, location: logical(location.location) })) } : {}),
+            ...(component.recordSources ? { recordSources: component.recordSources.map(record => ({ ...record, source: relativeFile(record.source) })) } : {}),
+            ...(component.standardLibraries ? { standardLibraries: component.standardLibraries } : {}) } }, null, 2) + '\n');
+    if (opts.app)
+        await generateCheckedApp({ clientDir, gatewayDir, openapiFile, ...opts.app, component });
+    if (opts.test && opts.app)
+        await generateCheckedTests({ clientDir, appDir: opts.app.appDir, routePath: Object.values(routes)[0],
+            ...opts.test, routePaths: Object.values(routes), sourceFile: root });
+    return { compiled: undefined, openapiDoc: doc, checked: inventory, planning: report };
+}

package/dist/checkedPlanning.d.ts

@@ -0,0 +1,123 @@
+import { prepareComponentStages } from './checkedPipeline.js';
+import type { CheckedComponentOptions } from './checkedPipeline.js';
+import type { DirectOperationSelector } from './compiler/directOperation.js';
+import type { ExpandedName } from './loader/orderedSyntax.js';
+type Category = 'missing-dependency' | 'permission' | 'ambiguous-selection' | 'invalid-source' | 'unsupported-capability' | 'inconclusive' | 'cancelled' | 'resource-limit' | 'operational-failure' | 'configuration';
+export interface ComponentPlanBlocker {
+    readonly category: Category;
+    readonly stage: 'configuration' | 'loading' | 'selection' | 'native-preparation';
+    readonly dimension: 'source' | 'selection' | 'qualification-and-correspondence' | 'mapping-and-artifact';
+    readonly reason: string;
+    readonly source?: {
+        readonly resource: string;
+        readonly path: string;
+        readonly line: number;
+        readonly column: number;
+    };
+    readonly affected: readonly DirectOperationSelector[];
+    readonly action: string;
+    readonly pointer: string;
+}
+interface Candidate {
+    readonly service: ExpandedName;
+    readonly port: string;
+    readonly binding: ExpandedName;
+    readonly portType?: ExpandedName;
+    readonly source: NonNullable<ComponentPlanBlocker['source']>;
+}
+/** Versioned diagnostic data, with no portable native authority.
+ * @since Unreleased
+ */
+export interface CheckedComponentPlan {
+    readonly version: 'checked-component-plan-v1';
+    readonly model: 'checked-components-v1';
+    readonly scope: 'native-component-source-and-mapping';
+    readonly ready: boolean;
+    readonly executed: false;
+    readonly runtime: 'not-assessed-operation-invocation-required';
+    readonly dimensions: {
+        readonly sourceLegality: 'established' | 'disproved' | 'unassessed';
+        readonly correspondence: 'established' | 'unassessed';
+        readonly mapping: 'established' | 'unassessed';
+        readonly runtime: 'unassessed';
+    };
+    readonly inventory: {
+        readonly complete: boolean;
+        readonly unassessed: readonly string[];
+        readonly services: number;
+        readonly ports: number;
+        readonly bindings: number;
+        readonly portTypes: number;
+        readonly operations: number;
+    };
+    readonly candidates: readonly Candidate[];
+    readonly resources: readonly {
+        readonly resource: string;
+        readonly digest: string;
+    }[];
+    readonly selection?: {
+        readonly service: ExpandedName;
+        readonly port: string;
+        readonly selectors: readonly DirectOperationSelector[];
+    };
+    readonly responseProjections?: readonly {
+        readonly selector: DirectOperationSelector;
+        readonly spec: import('./compiler/componentRecordProjection.js').ComponentRecordProjectionSpec;
+        readonly delivery: 'buffered';
+        readonly retainedValue: 'complete-companion-payload';
+    }[];
+    readonly operations: readonly {
+        readonly portType: ExpandedName;
+        readonly binding?: ExpandedName;
+        readonly operation: string;
+        readonly requested: boolean;
+        readonly selected: boolean;
+        readonly generated: false;
+        readonly executed: false;
+    }[];
+    readonly blockers: readonly ComponentPlanBlocker[];
+    readonly resolution?: {
+        readonly instructions: string;
+        readonly configuration: Partial<CheckedComponentOptions>;
+    };
+}
+/** Refused generation retains actionable, serializable diagnostics.
+ * @since Unreleased
+ */
+export declare class CheckedPlanningError extends Error {
+    readonly report: CheckedComponentPlan;
+    constructor(report: CheckedComponentPlan);
+}
+/** Format deterministic human diagnostics without source bytes or transport details.
+ * @param report Diagnostic data only.
+ * @returns Summary and every independently collected blocker.
+ */
+export declare function formatCheckedComponentPlan(report: CheckedComponentPlan): string;
+/** 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 declare function planCheckedComponents(source: string, choices?: Partial<CheckedComponentOptions>): Promise<CheckedComponentPlan>;
+/** 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 declare function writeCheckedPlanningFile(file: string, value: unknown, force?: boolean): void;
+export declare function prepareCheckedComponentPlan(source: string, choices?: unknown, outputs?: {
+    clientDir: string;
+    gatewayDir: string;
+    openapiFile: string;
+    basePath: string;
+}): Promise<{
+    report: CheckedComponentPlan;
+    config?: CheckedComponentOptions;
+    native?: Awaited<ReturnType<typeof prepareComponentStages>>;
+}>;
+export {};