@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/dist/gateway/generateCheckedGateway.js

@@ -0,0 +1,293 @@
+/**
+ * Lowers issued direct mappings into HTTP documentation and a checked gateway.
+ * @since 1.1.6
+ * @constraints Serialized descriptions never issue native source or execution authority.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { componentSourceCapsuleBytes, inspectReconstructedComponentSource, inspectComponentSourceService } from '../compiler/directSourceCapsule.js';
+import { lowerComponentShape } from '../generation/componentShape.js';
+import { checkSemanticBudget } from '../compiler/semanticBudget.js';
+import { inspectDirectOperation } from '../compiler/directOperation.js';
+import { inspectComponentValueMapping } from '../compiler/directValues.js';
+import { composeGeneratedSource, resolvePreamble } from '../generation/preamble.js';
+const draft07 = 'http://json-schema.org/draft-07/schema#';
+/** Lower component mappings through the existing checked gateway emitter, retaining native supplemental validation. */
+export async function generateComponentGateway(expected, options) {
+    inspectReconstructedComponentSource(expected);
+    return generateGatewayFromReconstruction(expected, options);
+}
+async function generateGatewayFromReconstruction(expected, options) {
+    if (options.signal?.aborted)
+        throw new Error('Checked gateway generation cancelled');
+    inspectReconstructedComponentSource(expected);
+    const capsule = { bytes: componentSourceCapsuleBytes(expected, options.signal) };
+    const runtime = 'checkedComponentRuntimeV1';
+    if (!options.routePath.startsWith('/') || options.routePath.split('/').slice(1)
+        .some(segment => !segment || !/^(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+$/.test(segment))) {
+        throw new TypeError('Checked routePath requires literal nonempty path segments');
+    }
+    const input = expected.mappings.find(mapping => mapping.direction.kind === 'input');
+    const output = expected.mappings.find(mapping => mapping.direction.kind === 'output');
+    if (!input || !output)
+        throw new TypeError('Issued input and output mappings required');
+    const schema = (mapping, role) => {
+        const { budget } = inspectDirectOperation(expected.contract).context;
+        return lowerComponentShape(expected.contract, mapping, role, () => {
+            checkSemanticBudget(budget);
+            if (options.signal?.aborted)
+                throw new Error('Checked gateway generation cancelled');
+        }).schema;
+    };
+    const request = schema(input, 'Request'), response = schema(output, 'Response');
+    const faults = expected.mappings.filter(mapping => mapping.direction.kind === 'fault').map(mapping => {
+        if (mapping.direction.kind !== 'fault')
+            throw new TypeError('Declared fault mapping required');
+        return { name: mapping.direction.name, value: schema(mapping, `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`) };
+    });
+    const faultVariants = faults.map(fault => ({
+        type: 'object', additionalProperties: false, required: ['fault', 'value'],
+        properties: {
+            value: fault.value,
+            fault: {
+                type: 'object', additionalProperties: false, required: ['name', 'code', 'string'],
+                properties: {
+                    name: { const: fault.name }, string: { type: 'string' }, actor: { type: 'string' },
+                    code: { type: 'object', additionalProperties: false, required: ['namespace', 'local'],
+                        properties: { namespace: { type: 'string' }, local: { type: 'string' } } },
+                },
+            },
+        },
+    }));
+    const fault = faultVariants.length ? { oneOf: faultVariants } : { not: {} };
+    const schemas = { request: { $schema: draft07, ...request }, response: { $schema: draft07, ...response }, fault: { $schema: draft07, ...fault } };
+    const grouped = expected.mappings.some(mapping => mapping.kind === 'component-mapping'
+        && inspectComponentValueMapping(mapping, expected.contract).applicationGroups);
+    const components = Object.create(null);
+    const documented = (value, dictionary = false) => {
+        if (Array.isArray(value))
+            return value.map(item => documented(item));
+        if (!value || typeof value !== 'object')
+            return value;
+        const record = value, result = Object.create(null);
+        // @why Property names belong to the application; definitions and $id are keywords only at schema nodes.
+        if (dictionary) {
+            for (const [key, item] of Object.entries(record))
+                result[key] = documented(item);
+            return result;
+        }
+        if (Object.hasOwn(record, 'definitions'))
+            for (const [key, definition] of Object.entries(record.definitions)) {
+                const resolved = documented(definition);
+                if (components[key] && JSON.stringify(components[key]) !== JSON.stringify(resolved))
+                    throw new TypeError(`applicationGroups OpenAPI component collision ${key}`);
+                components[key] = resolved;
+            }
+        for (const [key, item] of Object.entries(record)) {
+            if (key === 'definitions' || key === '$id')
+                continue;
+            result[key] = ['const', 'enum', 'default', 'examples'].includes(key) ? item
+                : key === '$ref' && typeof item === 'string' && item.startsWith('#/definitions/') ? item.replace('#/definitions/', '#/components/schemas/')
+                    : documented(item, ['properties', 'patternProperties', 'dependencies', 'dependentSchemas'].includes(key));
+        }
+        return result;
+    };
+    const documentation = grouped ? { request: documented(request), response: documented(response), fault: documented(fault) } : { request, response, fault };
+    const doc = {
+        openapi: '3.1.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
+        info: { title: expected.selection.service.local, version: '1.0.0' },
+        ...(grouped ? { components: { schemas: components } } : {}),
+        'x-checked-model': { model: 'checked-components-v1', scope: 'native-component-structured-soap11',
+            ...(expected.responseProjection
+                ? { responseProjection: { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
+            documentationDialect: '2020-12', runtimeDialect: 'draft-07', jsonShapeComplete: false,
+            supplementalValidation: ['native-source-compatibility', 'native-xml-scalar-and-particle'], admitted: false,
+            selection: { selector: expected.contract.selector, ...expected.selection } },
+        paths: { [options.routePath]: { post: { operationId: expected.contract.selector.operation,
+                    ...(expected.responseProjection
+                        ? { 'x-response-projection': { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
+                    requestBody: { required: true, content: { 'application/json': { schema: documentation.request } } },
+                    responses: { '200': { description: 'Independently validated SOAP response', content: { 'application/json': { schema: documentation.response } } },
+                        '400': { description: 'Invalid HTTP request; no SOAP request is dispatched' },
+                        '502': { description: 'Declared SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentation.fault,
+                                            { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
+                        '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
+    };
+    let clientImport = path.relative(options.gatewayDir, path.join(options.clientDir, 'client.js')).replace(/\\/g, '/');
+    if (!clientImport.startsWith('.'))
+        clientImport = './' + clientImport;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    // language=TypeScript
+    const body = `import type {FastifyPluginAsync} from 'fastify';
+import {Ajv} from 'ajv';
+import {types} from 'node:util';
+import {${runtime}} from '@techspokes/typescript-wsdl-client';
+import {createClient, expectedCapsuleBase64, type Options, type Request} from ${literal(clientImport)};
+
+export interface CheckedGatewayOptions { readonly clientOptions: Options }
+// @constraints JSON parsing preserves XML names such as __proto__ as ordinary own data properties.
+export const schemas = JSON.parse(${literal(JSON.stringify(schemas))}) as {request: Record<string, unknown>; response: Record<string, unknown>; fault: Record<string, unknown>};
+export const expectedOpenApiJson = ${literal(JSON.stringify(doc))};
+
+// @constraints Read only data properties before composing per-request cancellation.
+function dataCopy<T extends object>(value: T): T {
+  if (!value || typeof value !== 'object' || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError('Data-only checked gateway options required');
+  const copy: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (typeof key !== 'string' || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Data-only checked gateway options required');
+    copy[key] = descriptor.value;
+  }
+  return copy as T;
+}
+
+const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, options) => {
+  if (expectedCapsuleBase64 !== ${literal(Buffer.from(capsule.bytes).toString('base64'))}) throw new Error('incompatible-artifact: generated gateway/client mismatch; regenerate the complete project');
+  const client = createClient(${runtime});
+  const ajv = new Ajv({coerceTypes: false, useDefaults: false, removeAdditional: false, ownProperties: true, strict: true, allErrors: true});
+  const validateRequest = ajv.compile(schemas.request);
+  const validateResponse = ajv.compile(schemas.response);
+  const validateFault = ajv.compile(schemas.fault);
+  const base = dataCopy(options.clientOptions);
+  const soap = dataCopy(base.soap);
+  fastify.post(${literal(options.routePath)}, {
+    schema: {body: schemas.request},
+    validatorCompiler: () => validateRequest,
+    // @constraints Serialization preserves every validated member and never establishes validity.
+    serializerCompiler: () => value => JSON.stringify(value),
+  }, async (request, reply) => {
+    const controller = new AbortController();
+    const disconnected = () => {if (!reply.raw.writableEnded) controller.abort();};
+    request.raw.once('aborted', disconnected);
+    reply.raw.once('close', disconnected);
+    if (request.raw.aborted || reply.raw.destroyed) controller.abort();
+    try {
+      const signal = soap.signal ? AbortSignal.any([soap.signal, controller.signal]) : controller.signal;
+      const result = await client[${literal(expected.contract.selector.operation)}](request.body as Request,
+        {...base, soap: {...soap, signal}});
+      if (result.kind === 'soap-response') {
+        if (!validateResponse(result.value)) return reply.code(502).send({kind: 'value-invalid', rule: 'http-response-shape'});
+        return reply.type('application/json').serializer(value => JSON.stringify(value)).send(result.value);
+      }
+      if (result.kind === 'soap-fault') {
+        const fault = {name: result.fault.name, code: {namespace: result.fault.code.namespace, local: result.fault.code.local},
+          string: result.fault.string, ...(result.fault.actor === undefined ? {} : {actor: result.fault.actor})};
+        const value = {fault, value: result.value};
+        if (!validateFault(value)) return reply.code(502).send({kind: 'value-invalid', rule: 'http-fault-shape'});
+        return reply.code(502).type('application/json').serializer(value => JSON.stringify(value)).send(value);
+      }
+      const status = result.kind === 'incompatible-artifact' || result.kind === 'missing-authority' ? 500
+        : result.kind === 'cancelled' ? 499 : result.phase === 'input' ? 400 : 502;
+      return reply.code(status).send({kind: result.kind, rule: result.rule});
+    } finally {
+      request.raw.removeListener('aborted', disconnected);
+      reply.raw.removeListener('close', disconnected);
+    }
+  });
+};
+export default plugin;
+`;
+    if (options.signal?.aborted)
+        throw new Error('Checked gateway generation cancelled');
+    const source = composeGeneratedSource(body, resolvePreamble('gateway'));
+    const emit = async () => {
+        inspectReconstructedComponentSource(expected);
+        checkSemanticBudget(inspectDirectOperation(expected.contract).context.budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
+        await mkdir(options.gatewayDir, { recursive: true });
+        await mkdir(path.dirname(options.openapiFile), { recursive: true });
+        await writeFile(path.join(options.gatewayDir, 'plugin.ts'), source, 'utf8');
+        await writeFile(path.join(options.gatewayDir, 'schemas.json'), JSON.stringify(schemas, null, 2) + '\n', 'utf8');
+        await writeFile(options.openapiFile, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    };
+    if (options.emit !== false)
+        await emit();
+    return { doc, emit };
+}
+/** Compose per-operation checked routers without merging native source, service or binding identities.
+ * @returns One OpenAPI document and exact operation-to-route mapping, both descriptions rather than authority.
+ * @throws For mixed native handles, invalid/colliding paths, cancellation or filesystem failures.
+ */
+export async function generateComponentServiceGateway(expected, options) {
+    const operations = inspectComponentSourceService(expected), routes = Object.create(null);
+    const paths = Object.create(null);
+    const documents = [];
+    const emissions = [];
+    const tick = () => {
+        checkSemanticBudget(inspectDirectOperation(operations[0].contract).context.budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
+    };
+    for (const [index, operation] of operations.entries()) {
+        tick();
+        const name = operation.contract.selector.operation, routePath = `${options.basePath}/${encodeURIComponent(name)}`;
+        const result = await generateComponentGateway(operation, { clientDir: path.join(options.clientDir, 'operations', String(index)),
+            gatewayDir: path.join(options.gatewayDir, 'routes', String(index)), openapiFile: path.join(options.gatewayDir, 'routes', String(index), 'openapi.json'), routePath, signal: options.signal, emit: false });
+        emissions.push(result.emit);
+        const doc = result.doc;
+        documents.push(doc);
+        routes[name] = routePath;
+        for (const [route, value] of Object.entries(doc.paths)) {
+            if (Object.hasOwn(paths, route))
+                throw new TypeError('Duplicate checked route');
+            paths[route] = value;
+        }
+    }
+    const { responseProjection: firstProjection, ...serviceModel } = documents[0]['x-checked-model'];
+    void firstProjection;
+    const componentSchemas = Object.create(null);
+    for (const document of documents) {
+        const schemas = document.components?.schemas ?? {};
+        for (const [name, schema] of Object.entries(schemas)) {
+            if (componentSchemas[name] && JSON.stringify(componentSchemas[name]) !== JSON.stringify(schema))
+                throw new TypeError(`applicationGroups OpenAPI component collision ${name}`);
+            componentSchemas[name] = schema;
+        }
+    }
+    const doc = { ...documents[0], ...(Object.keys(componentSchemas).length ? { components: { schemas: componentSchemas } } : {}), 'x-checked-model': { ...serviceModel,
+            selection: { service: operations[0].selection.service, port: operations[0].selection.port,
+                selectors: operations.map(operation => operation.contract.selector) } }, paths };
+    let clientImport = path.relative(options.gatewayDir, path.join(options.clientDir, 'client.js')).replaceAll('\\', '/');
+    if (!clientImport.startsWith('.'))
+        clientImport = './' + clientImport;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    const names = operations.map(operation => operation.contract.selector.operation);
+    const lines = ["import type {FastifyPluginAsync} from 'fastify';", "import {types} from 'node:util';",
+        `import type {Options} from ${literal(clientImport)};`,
+        ...operations.map((_, index) => `import operation_${index} from './routes/${index}/plugin.js';`),
+        'export interface CheckedGatewayOptions {readonly clientOptions: Options; readonly capsules: Readonly<Record<string, Uint8Array>>}',
+        `export const expectedOpenApiJson = ${literal(JSON.stringify(doc))};`,
+        'function data(value: unknown, allowed: readonly string[]): Record<string, unknown> {',
+        "  if (!value || typeof value !== 'object' || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError('Data-only service options required');",
+        '  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;',
+        '  for (const key of Reflect.ownKeys(value)) {',
+        '    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;',
+        "    if (typeof key !== 'string' || !allowed.includes(key) || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Unsupported service option');",
+        '    result[key] = descriptor.value;', '  }', '  return result;', '}',
+        'const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, options) => {',
+        "  const outer = data(options, ['clientOptions', 'capsules', 'prefix']);",
+        "  const clientOptions = data(outer.clientOptions, ['localSource', 'fileRoots', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'standardLibraries', 'recordSources', 'soap']) as unknown as Options;",
+        `  const capsules = data(outer.capsules, ${literal(names)});`,
+        ...operations.map((operation, index) => `  if (!Object.hasOwn(capsules, ${literal(operation.contract.selector.operation)})) throw new TypeError('Missing operation capsule');
+  await fastify.register(operation_${index}, {clientOptions: {...clientOptions, capsule: capsules[${literal(operation.contract.selector.operation)}] as Uint8Array}});`),
+        '};', 'export default plugin;', '',
+    ];
+    tick();
+    const source = composeGeneratedSource(lines.join('\n'), resolvePreamble('gateway'));
+    const emit = async () => {
+        tick();
+        for (const write of emissions) {
+            tick();
+            await write();
+        }
+        await mkdir(options.gatewayDir, { recursive: true });
+        await mkdir(path.dirname(options.openapiFile), { recursive: true });
+        await writeFile(path.join(options.gatewayDir, 'plugin.ts'), source, 'utf8');
+        await writeFile(options.openapiFile, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    };
+    if (options.emit !== false)
+        await emit();
+    return { doc, routes: Object.freeze(routes), emit };
+}

package/dist/gateway/generateGateway.d.ts

@@ -83,4 +83,3 @@ export interface GenerateGatewayOptions {
  * });
  */
 export declare function generateGateway(opts: GenerateGatewayOptions): Promise<void>;
-//# sourceMappingURL=generateGateway.d.ts.map

package/dist/gateway/generateGateway.js

@@ -21,6 +21,7 @@
  *     routes.ts      - Route registration module
  */
 import fs from "node:fs";
+import { readLegacyCatalogFile } from "../compiler/semanticCatalog.js";
 import path from "node:path";
 import * as yaml from "js-yaml";
 import { buildParamSchemasForOperation, getJsonSchemaRefName, isNumericStatus, resolveClientMeta, resolveOperationMeta, } from "./helpers.js";
@@ -126,8 +127,7 @@ export async function generateGateway(opts) {
     // Load catalog if provided (for operation metadata)
     let catalog = undefined;
     if (opts.catalogFile && fs.existsSync(opts.catalogFile)) {
-        const catalogRaw = fs.readFileSync(opts.catalogFile, "utf8");
-        catalog = JSON.parse(catalogRaw);
+        catalog = readLegacyCatalogFile(opts.catalogFile);
     }
     // Resolve client metadata for full handler generation
     const clientMeta = resolveClientMeta({

package/dist/gateway/generators.d.ts

@@ -170,4 +170,3 @@ export declare function emitTypeCheckFixture(outDir: string, clientMeta: ClientM
  * @param {any} [catalog] - Compiled catalog for detecting ArrayOf* wrapper types to unwrap
  */
 export declare function emitRouteFilesWithHandlers(outDir: string, routesDir: string, versionSlug: string, serviceSlug: string, operations: OperationMetadata[], importsMode: "js" | "ts" | "bare", clientMeta: ClientMeta, catalog?: any): void;
-//# sourceMappingURL=generators.d.ts.map

package/dist/gateway/helpers.d.ts

@@ -256,4 +256,3 @@ export declare function resolveOperationMeta(operationId: string, operationSlug:
  * @returns Number of unique schema components reachable via $ref
  */
 export declare function measureSchemaRefComplexity(startSchemaName: string, allSchemas: Record<string, any>, limit?: number): number;
-//# sourceMappingURL=helpers.d.ts.map

package/dist/generation/componentShape.d.ts

@@ -0,0 +1,14 @@
+import type { DirectOperationContract } from '../compiler/directOperation.js';
+type Schema = Record<string, unknown>;
+/** Lower an authenticated mapping to recursive TypeScript and JSON shape descriptions.
+ * @remarks Scalar restrictions, fixed/default semantics, ordered occurrence correlation and strict wildcard
+ *   declaration membership require native validation. These descriptions never grant source/runtime authority.
+ * @returns Role-scoped definitions and root descriptions; no native handles or retrieval paths are emitted.
+ * @throws TypeError For foreign mappings or unsupported scalar representation. Caller cancellation propagates.
+ */
+export declare function lowerComponentShape(contract: DirectOperationContract, supplied: unknown, role: string, check: () => void): {
+    type: string;
+    declarations: readonly string[];
+    schema: Schema;
+};
+export {};

package/dist/generation/componentShape.js

@@ -0,0 +1,269 @@
+/** Documentation/static shape lowering only; source, scalar facets and particle languages remain native duties. */
+import { inspectDirectOperation } from '../compiler/directOperation.js';
+import { inspectComponentValueMapping } from '../compiler/directValues.js';
+import { projectionScalarRepresentation, inspectOrderedProjectionWildcards, inspectUnassessedProjectionWildcards } from '../compiler/directStructurePlan.js';
+import { createHash } from 'node:crypto';
+import { isComponentRecordProjection, inspectComponentRecordProjection } from '../compiler/componentRecordProjection.js';
+import { applicationRecordName } from '../compiler/applicationGroups.js';
+const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+/** Lower an authenticated mapping to recursive TypeScript and JSON shape descriptions.
+ * @remarks Scalar restrictions, fixed/default semantics, ordered occurrence correlation and strict wildcard
+ *   declaration membership require native validation. These descriptions never grant source/runtime authority.
+ * @returns Role-scoped definitions and root descriptions; no native handles or retrieval paths are emitted.
+ * @throws TypeError For foreign mappings or unsupported scalar representation. Caller cancellation propagates.
+ */
+export function lowerComponentShape(contract, supplied, role, check) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(role))
+        throw new TypeError('TypeScript role identifier required');
+    if (isComponentRecordProjection(supplied)) {
+        const owned = inspectComponentRecordProjection(supplied, contract);
+        return lowerComponentShape(owned.companion, owned.mapping, role, check);
+    }
+    const { projection, applicationGroups } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    const names = new Map(projection.records.map((record, index) => [record.type.id, applicationGroups
+            ? applicationRecordName(record.type.id) : `${role}_Record_${index}`]));
+    const definitions = Object.create(null);
+    const declarations = [];
+    const lexicalAttribute = { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { anyOf: [
+                { type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }] } },
+                { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                        $namespace: { type: 'string', minLength: 1 }, $value: {}
+                    } }
+            ] } };
+    const lexicalAttributeType = 'Readonly<Record<string, string | number | boolean | readonly (string | number | boolean)[] | {readonly "$namespace": string; readonly "$value": unknown}>>';
+    const openName = applicationGroups ? 'ApplicationOpenValue' : `${role}_OpenValue`;
+    let openDeclared = false;
+    const openShape = () => {
+        if (!openDeclared) {
+            openDeclared = true;
+            const attribute = { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { anyOf: [{ type: 'string' },
+                        { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: { $namespace: { type: 'string', minLength: 1 }, $value: { type: 'string' } } }] } };
+            definitions[openName] = { type: 'object', additionalProperties: false, required: ['$namespace', '$content'], properties: {
+                    $namespace: { type: 'string' }, $namespaces: { type: 'object', additionalProperties: { type: 'string' } }, $attributes: { type: 'array', items: attribute },
+                    $content: { type: 'array', items: { anyOf: [
+                                { type: 'object', additionalProperties: false, required: ['$value'], properties: { $value: { type: 'string' } } },
+                                { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { $ref: '#/definitions/' + openName } },
+                            ] } },
+                } };
+            declarations.push(`export type ${openName} = {readonly "$namespace": string; readonly "$namespaces"?: Readonly<Record<string, string>>; `
+                + 'readonly "$attributes"?: readonly Readonly<Record<string, string | {readonly "$namespace": string; readonly "$value": string}>>[]; '
+                + `readonly "$content": readonly ({readonly "$value": string} | Readonly<Record<string, ${openName}>>)[]};`);
+        }
+        return { type: `Readonly<Record<string, ${openName}>>`, schema: { type: 'object', minProperties: 1, maxProperties: 1,
+                additionalProperties: { $ref: '#/definitions/' + openName } } };
+    };
+    const scalar = (value) => {
+        check();
+        // @why A list-level pattern retains one lexical witness; its HTTP value is a string rather than an item array.
+        const item = value.retainLexical ? value : value.list ?? value;
+        const type = item.retainLexical ? 'string' : projectionScalarRepresentation(item.builtin);
+        if (!type)
+            throw new TypeError('Unsupported native scalar representation');
+        const schema = type === 'number' ? { type: 'integer', minimum: -2147483648, maximum: 2147483647 }
+            : type === 'string' ? { type, pattern: '^[\\u0009\\u000A\\u000D\\u0020-\\uD7FF\\uE000-\\uFFFD\\u{10000}-\\u{10FFFF}]*$' } : { type };
+        return value.list && !value.retainLexical ? { type: `readonly ${type}[]`, schema: { type: 'array', items: schema } } : { type, schema };
+    };
+    const shape = (value) => {
+        check();
+        const ordinary = (() => {
+            if (value.kind === 'scalar')
+                return scalar(value);
+            const name = names.get(value.type);
+            if (!name)
+                throw new TypeError('Missing native projection record');
+            return { type: name, schema: { $ref: '#/definitions/' + name } };
+        })();
+        if (!value.nillable || value.constraint?.kind === 'fixed')
+            return ordinary;
+        const record = value.kind === 'record' ? projection.records.find(record => record.type.id === value.type) : undefined;
+        const attributes = record?.attributes ?? [];
+        const properties = Object.create(null);
+        properties.$nil = { const: true };
+        const required = ['$nil'], members = ['readonly "$nil": true'];
+        for (const attribute of attributes) {
+            if (attribute.bag)
+                continue;
+            check();
+            const key = attribute.declaration.name.local, description = scalar(attribute);
+            properties[key] = description.schema;
+            if (attribute.required)
+                required.push(key);
+            members.push(`readonly ${literal(key)}${attribute.required ? '' : '?'}: ${description.type}`);
+        }
+        const bag = attributeBag(attributes, !!record?.attributeWildcard);
+        if (bag) {
+            properties.$attributes = bag.schema;
+            members.push(`readonly "$attributes"${bag.required ? '' : '?'}: ${bag.type}`);
+            if (bag.required)
+                required.push('$attributes');
+        }
+        if (record?.contextual) {
+            properties.$namespaces = { type: 'object', additionalProperties: { type: 'string' } };
+            members.push('readonly "$namespaces"?: Readonly<Record<string, string>>');
+        }
+        // @why Nil and ordinary values are disjoint: source data cannot use reserved $nil, and nil has no content fields.
+        return { type: `(${ordinary.type} | {${members.join('; ')}})`, schema: { anyOf: [ordinary.schema,
+                    { type: 'object', additionalProperties: false, properties, required }] } };
+    };
+    const attributeBag = (attributes, open = false) => {
+        const entries = attributes.filter(attribute => attribute.bag).map(attribute => {
+            const key = attribute.declaration.name.local, description = scalar(attribute);
+            const ambiguous = !!attribute.declaration.name.namespace && (open || attributes.some(other => other !== attribute && other.declaration.name.local === key));
+            const value = ambiguous ? { type: `{readonly "$namespace": ${literal(attribute.declaration.name.namespace)}; readonly "$value": ${description.type}}`,
+                schema: { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                        $namespace: { const: attribute.declaration.name.namespace }, $value: description.schema
+                    } } } : description;
+            return { type: `{readonly ${literal(key)}: ${value.type}}`, schema: { type: 'object', additionalProperties: false,
+                    required: [key], properties: { [key]: value.schema } } };
+        });
+        if (open)
+            entries.push({ type: lexicalAttributeType, schema: lexicalAttribute });
+        return entries.length ? { type: `readonly (${entries.map(entry => entry.type).join(' | ')})[]`,
+            schema: { type: 'array', items: { anyOf: entries.map(entry => entry.schema) } }, required: attributes.some(attribute => attribute.bag && attribute.required) } : undefined;
+    };
+    const groupObject = (nodes) => {
+        const properties = Object.create(null);
+        const required = [], members = [];
+        const visit = (node) => {
+            check();
+            if (!node.slot && !node.target) {
+                for (const child of node.children)
+                    visit(child);
+                return;
+            }
+            const key = node.slot?.element.name.local ?? node.target.resolved.propertyName;
+            let description;
+            if (node.slot)
+                description = shape(node.slot.value);
+            else {
+                const name = node.target.resolved.typeName;
+                if (node.alternatives) {
+                    const alternatives = node.children.map((child, index) => {
+                        const alternative = node.alternatives[index].resolved.typeName, body = groupObject(child.children);
+                        definitions[alternative] = body.schema;
+                        declarations.push(`export type ${alternative} = ${body.type};`);
+                        return { type: alternative, schema: { $ref: '#/definitions/' + alternative } };
+                    });
+                    definitions[name] = { anyOf: alternatives.map(a => a.schema) };
+                    declarations.push(`export type ${name} = ${alternatives.map(a => a.type).join(' | ')};`);
+                }
+                else {
+                    const body = groupObject(node.children);
+                    definitions[name] = body.schema;
+                    declarations.push(`export type ${name} = ${body.type};`);
+                }
+                description = { type: name, schema: { $ref: '#/definitions/' + name } };
+            }
+            const repeated = node.particle.occurs.max !== '1', mandatory = node.particle.occurs.min !== '0';
+            if (repeated)
+                description = { type: `readonly (${description.type})[]`, schema: { type: 'array', items: description.schema,
+                        minItems: Number(node.particle.occurs.min), ...(node.particle.occurs.max === 'unbounded' ? {} : { maxItems: Number(node.particle.occurs.max) }) } };
+            properties[key] = description.schema;
+            if (mandatory)
+                required.push(key);
+            members.push(`readonly ${literal(key)}${mandatory ? '' : '?'}: ${description.type}`);
+        };
+        for (const node of nodes)
+            visit(node);
+        return { type: `{${members.join('; ')}}`, schema: { type: 'object', properties, required, additionalProperties: false } };
+    };
+    for (const record of projection.records) {
+        check();
+        const name = names.get(record.type.id);
+        const properties = Object.create(null);
+        const required = [], members = [];
+        const member = (key, value, mandatory) => {
+            check();
+            properties[key] = value.schema;
+            if (mandatory)
+                required.push(key);
+            members.push(`  readonly ${literal(key)}${mandatory ? '' : '?'}: ${value.type};`);
+        };
+        for (const attribute of record.attributes)
+            if (!attribute.bag)
+                member(attribute.declaration.name.local, scalar(attribute), attribute.required);
+        const bag = attributeBag(record.attributes, !!record.attributeWildcard);
+        if (bag)
+            member('$attributes', bag, bag.required);
+        if (record.contextual)
+            member('$namespaces', { type: 'Readonly<Record<string, string>>', schema: { type: 'object', additionalProperties: { type: 'string' } } }, false);
+        if (record.text)
+            member('$value', scalar(record.text), true);
+        const group = applicationGroups?.records[record.type.id];
+        if (group) {
+            const description = groupObject(group.children);
+            const schema = description.schema;
+            Object.assign(properties, schema.properties);
+            required.push(...schema.required);
+            members.push(description.type.slice(1, -1));
+        }
+        else if (record.ordered) {
+            const variants = new Map();
+            for (const slot of record.slots) {
+                check();
+                const value = shape(slot.value), expanded = slot.element.name, key = literal(expanded);
+                if (record.keyed) {
+                    const ambiguous = !record.fixedOrder && record.slots.some(other => other !== slot && other.element.name.local === expanded.local);
+                    const scalarValue = slot.value.kind === 'scalar' ? scalar(slot.value) : value;
+                    const holder = ambiguous ? { type: slot.value.kind === 'scalar'
+                            ? `{readonly "$namespace": ${literal(expanded.namespace)}; readonly "$value": ${scalarValue.type}}`
+                            : `(${value.type} & {readonly "$namespace": ${literal(expanded.namespace)}})`,
+                        schema: slot.value.kind === 'scalar' ? { type: 'object', additionalProperties: false, required: ['$namespace', '$value'], properties: {
+                                $namespace: { const: expanded.namespace }, $value: scalarValue.schema
+                            } }
+                            // @why Native validation owns the record's fixed fields; this structural superset must preserve the identity holder.
+                            : { type: 'object', required: ['$namespace'], properties: { $namespace: { const: expanded.namespace } }, additionalProperties: true } } : value;
+                    if (ambiguous && slot.value.kind === 'scalar' && slot.value.nillable && slot.value.constraint?.kind !== 'fixed') {
+                        holder.type = `(${holder.type} | {readonly "$namespace": ${literal(expanded.namespace)}; readonly "$nil": true})`;
+                        holder.schema = { anyOf: [holder.schema, { type: 'object', additionalProperties: false, required: ['$namespace', '$nil'], properties: {
+                                        $namespace: { const: expanded.namespace }, $nil: { const: true }
+                                    } }] };
+                    }
+                    variants.set(key, { type: `{readonly ${literal(expanded.local)}: ${holder.type}}`, schema: {
+                            type: 'object', additionalProperties: false, required: [expanded.local], properties: { [expanded.local]: holder.schema }
+                        } });
+                    continue;
+                }
+                variants.set(key, { type: `{readonly name: {readonly namespace: ${literal(expanded.namespace)}; readonly local: ${literal(expanded.local)}}; readonly value: ${value.type}}`,
+                    schema: { type: 'object', additionalProperties: false, required: ['name', 'value'], properties: {
+                            name: { type: 'object', additionalProperties: false, required: ['namespace', 'local'], properties: { namespace: { const: expanded.namespace }, local: { const: expanded.local } } }, value: value.schema
+                        } } });
+            }
+            if (record.content === 'mixed')
+                variants.set('$value', { type: '{readonly "$value": string}', schema: {
+                        type: 'object', additionalProperties: false, required: ['$value'], properties: { $value: { type: 'string' } }
+                    } });
+            if (inspectOrderedProjectionWildcards(context, record))
+                variants.set('*', record.keyed ? {
+                    type: 'Readonly<Record<string, Readonly<{"$namespace": string; [key: string]: unknown}>>>',
+                    schema: { type: 'object', minProperties: 1, maxProperties: 1, additionalProperties: { type: 'object',
+                            required: ['$namespace'], properties: { $namespace: { type: 'string' }, $namespaces: { type: 'object', additionalProperties: { type: 'string' } },
+                                $attributes: { type: 'array', items: lexicalAttribute }, $content: { type: 'array', items: { type: 'object' } }, $value: {} }, additionalProperties: true } },
+                } : {
+                    type: '{readonly name: {readonly namespace: string; readonly local: string}; readonly value: unknown}',
+                    schema: { type: 'object', additionalProperties: false, required: ['name', 'value'], properties: { name: { type: 'object', additionalProperties: false,
+                                required: ['namespace', 'local'], properties: { namespace: { type: 'string' }, local: { type: 'string' } } }, value: {} } },
+                });
+            if (record.keyed && inspectUnassessedProjectionWildcards(context, record))
+                variants.set('*', openShape());
+            const entries = [...variants.values()];
+            member('$content', { type: `readonly (${entries.map(entry => entry.type).join(' | ') || 'never'})[]`,
+                schema: { type: 'array', items: entries.length ? { anyOf: entries.map(entry => entry.schema) } : { not: {} } } }, true);
+        }
+        else
+            for (const slot of record.slots) {
+                check();
+                const value = shape(slot.value), repeated = slot.particle.occurs.max !== '1';
+                member(slot.element.name.local, repeated ? { type: slot.particle.occurs.min === '1'
+                        ? `readonly [${value.type}, ...(${value.type})[]]` : `readonly (${value.type})[]`, schema: { type: 'array', items: value.schema,
+                        minItems: Number(slot.particle.occurs.min) } } : value, repeated || slot.particle.occurs.min === '1');
+            }
+        declarations.push(`export type ${name} = ${members.length ? '{\n' + members.join('\n') + '\n}' : 'Readonly<Record<string, never>>'};`);
+        definitions[name] = { type: 'object', properties, required, additionalProperties: false };
+    }
+    const root = shape(projection.root);
+    const id = 'urn:checked-component:shape:' + createHash('sha256').update(JSON.stringify({ selector: contract.selector, role })).digest('hex');
+    // @why Nested identified fault schemas must not expose a root-only $ref that recurses during Ajv resource resolution.
+    const rootSchema = root.schema.$ref ? { allOf: [root.schema] } : root.schema;
+    return { type: root.type, declarations, schema: { $id: id, ...rootSchema, definitions } };
+}

package/dist/generation/preamble.d.ts

@@ -14,4 +14,3 @@ export declare const resolvePreamble: (artifact: string) => string;
  * @constraints Embedded fragments must not pass through this composer separately.
  */
 export declare function composeGeneratedSource(body: string, preamble: string): string;
-//# sourceMappingURL=preamble.d.ts.map

package/dist/generation/sourceLayout.d.ts

@@ -0,0 +1,13 @@
+/** Physical layout checks only; source interpretation and eligibility remain native responsibilities. */
+import path from 'node:path';
+import type { SchemaInput } from '../loader/schemaInput.js';
+/** Find a finite common directory using complete parent segments, including valid names beginning with two dots.
+ * @throws Error For cross-volume inputs, cancellation or an impossible ancestor search.
+ */
+export declare function commonSourceDirectory(root: string, files: readonly string[], check: () => void, paths?: Pick<typeof path, 'dirname' | 'parse' | 'relative' | 'isAbsolute' | 'sep'>): string;
+/** Refuse local retrieval aliases that cannot be copied as a relocatable physical tree.
+ * @remarks HTTP aliases use generated offline URI records. Local symlink aliases remain unsupported;
+ *   this scaffold does not invent filesystem links or rewrite original source bytes.
+ * @throws TypeError For unowned source input. Error For a nonrelocatable authenticated dependency or cancellation.
+ */
+export declare function assertCanonicalSourceLayout(input: SchemaInput, check: () => void): void;