genoc 0.3.0 → 0.4.1

package/dist/analyzer/discriminator-registry.js

@@ -0,0 +1,209 @@
+import { buildSchemaRenameMap, sanitizeTypeName } from '../utils/generator-helpers.js';
+import { RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
+import { parseJsonPointer } from '../utils/url.js';
+/**
+ * Family-aware discriminator registry (plan D5) — the single knowledge source
+ * for discriminator families the mapper seam will translate through:
+ *
+ * - One record per discriminator family (a component schema declaring
+ *   `discriminator`), keyed by `familyId` (the base's raw component name).
+ * - Variant entries keyed by the FULL `$ref` string (mapping values are exact
+ *   ref strings) plus a derived rename-aware name index.
+ * - Literals are stored PRE-ESCAPED (D8: `'` and `\` only) so the mapper never
+ *   interpolates raw values into string literals.
+ * - Implicit variants (oneOf/anyOf `$ref` members absent from `mapping`) carry
+ *   the RAW last ref segment as their literal (D3 precedence: mapping key >
+ *   own `const` > single-value `enum` > raw segment).
+ *
+ * Field budget (D5): audited — every remaining field has a live consumer in
+ * production (seam / Variant-union emission) or in the registry unit tests.
+ * Rename-aware keying is mandatory: the name index goes through the same
+ * `buildSchemaRenameMap` machinery `analyze()` uses (see the past-bug note at
+ * schema-mapper.ts:75–78 — raw-name keying silently drops literal injection
+ * for renamed subtypes).
+ */
+/** Rename-aware type-name derivation — the exact expression `analyze()` wires
+ * into the mapper's `typeNameGenerator` (`renameMap.get(raw) ?? sanitized`).
+ * Single source of truth so registry name keys can never diverge from the
+ * names the mapper emits for the same `$ref`.
+ */
+export function renameAwareTypeName(renameMap, rawName) {
+    return renameMap.get(rawName) ?? sanitizeTypeName(rawName);
+}
+function isRefObject(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        !Array.isArray(obj) &&
+        '$ref' in obj);
+}
+/** Decode the last segment of a `$ref` string into its raw component key (`~1`/`~0` unescaped). */
+function rawRefSegment(refStr) {
+    const segments = refStr.startsWith('#') ? parseJsonPointer(refStr.slice(1)) : refStr.split('/');
+    return segments[segments.length - 1] ?? refStr;
+}
+/** Encode a component key for embedding in a `#/components/schemas/…` ref string. */
+function encodePointerSegment(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * A discriminator variant's own declared literal on the discriminator
+ * property: `const` first, then a single-value `enum` (D3 steps 2–3).
+ * Returns the string form; multi-value enums and absent props yield nothing.
+ */
+function resolveOwnDiscriminatorLiteral(resolved, propertyName, resolver) {
+    if (!resolved)
+        return undefined;
+    let prop = resolved.properties?.[propertyName];
+    if (prop === undefined)
+        return undefined;
+    if (isRefObject(prop)) {
+        try {
+            prop = resolver.resolveSchema(prop);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (prop.const !== undefined)
+        return { value: String(prop.const), source: 'const' };
+    if (prop.enum !== undefined && prop.enum.length === 1) {
+        return { value: String(prop.enum[0]), source: 'enum' };
+    }
+    return undefined;
+}
+/** Resolve a mapping/oneOf ref target for flag facts; unresolvable refs degrade to undefined (mapper-style try/catch). */
+function resolveTargetSchema(resolver, refStr) {
+    try {
+        return resolver.resolveSchema({ $ref: refStr });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the family-aware discriminator registry from the component schemas.
+ *
+ * Inputs must be the SAME `renameMap` / `allSchemaNames` `analyze()` derives
+ * (the rename-aware keying discipline) — pass `buildSchemaRenameMap`'s output
+ * and the emitted-name set, never a parallel sanitization. Pure with respect
+ * to the document: no mutation of the schemas; warnings (D3 mapping-key
+ * conflicts) go to `warnSink`.
+ */
+export function buildDiscriminatorRegistry(schemas, resolver, renameMap, allSchemaNames, warnSink) {
+    const warn = warnSink ??
+        ((message) => {
+            process.stderr.write(message);
+        });
+    const registry = {
+        families: new Map(),
+        byRef: new Map(),
+        byName: new Map(),
+        baseRefs: new Map(),
+    };
+    if (!schemas)
+        return registry;
+    // Pass 1 — discover families; per family, register mapping entries first
+    // (D3: mapping key wins), then implicit oneOf/anyOf variants absent from
+    // the mapping (literal = own const > single-value enum > RAW ref segment).
+    for (const [name, schema] of Object.entries(schemas)) {
+        const resolved = resolver.resolve(schema);
+        const disc = resolved.discriminator;
+        if (!disc)
+            continue;
+        const familyId = name;
+        const family = {
+            familyId,
+            baseTypeName: renameAwareTypeName(renameMap, name),
+            baseRefStr: `#/components/schemas/${encodePointerSegment(name)}`,
+            propertyName: disc.propertyName,
+            variantUnionName: '',
+            variantUnionMembers: [],
+            entriesByRef: new Map(),
+        };
+        const mappedRefStrs = new Set();
+        if (disc.mapping) {
+            for (const [mappingKey, refStr] of Object.entries(disc.mapping)) {
+                if (mappedRefStrs.has(refStr))
+                    continue; // two keys → same target: first key wins
+                mappedRefStrs.add(refStr);
+                const target = resolveTargetSchema(resolver, refStr);
+                const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+                if (own !== undefined && own.value !== mappingKey) {
+                    warn(`Warning: Discriminator mapping key "${mappingKey}" for "${refStr}" conflicts with its own declared ${own.source} literal "${own.value}"; the mapping key wins.\n`);
+                }
+                const rawSegment = rawRefSegment(refStr);
+                const entry = {
+                    propertyName: disc.propertyName,
+                    literalValue: escapeStringLiteral(mappingKey),
+                    isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                    isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                    isNullable: target?.nullable === true ||
+                        (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                    familyId,
+                    refStr,
+                    typeName: renameAwareTypeName(renameMap, rawSegment),
+                };
+                family.entriesByRef.set(refStr, entry);
+            }
+        }
+        const implicitRefs = [];
+        for (const member of [...(resolved.oneOf ?? []), ...(resolved.anyOf ?? [])]) {
+            if (isRefObject(member))
+                implicitRefs.push(member.$ref);
+        }
+        for (const refStr of implicitRefs) {
+            if (mappedRefStrs.has(refStr))
+                continue; // already registered via mapping
+            const target = resolveTargetSchema(resolver, refStr);
+            const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+            const rawSegment = rawRefSegment(refStr);
+            const entry = {
+                propertyName: disc.propertyName,
+                // D3 fallback chain for unmapped variants: own const > single-value
+                // enum > RAW last ref segment (the runtime value, NOT the sanitized
+                // type name).
+                literalValue: escapeStringLiteral(own?.value ?? rawSegment),
+                isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                isNullable: target?.nullable === true ||
+                    (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                familyId,
+                refStr,
+                typeName: renameAwareTypeName(renameMap, rawSegment),
+            };
+            family.entriesByRef.set(refStr, entry);
+        }
+        registry.families.set(familyId, family);
+    }
+    // Pass 2 — flat lookups + per-family name index + union members
+    // (mapping order, then unmapped oneOf/anyOf refs; deduped by refStr and
+    // by typeName — alias refs to one emitted name collapse).
+    for (const family of registry.families.values()) {
+        const memberNames = [];
+        const seenNames = new Set();
+        for (const [refStr, entry] of family.entriesByRef) {
+            if (!registry.byRef.has(refStr))
+                registry.byRef.set(refStr, entry);
+            if (!registry.byName.has(entry.typeName))
+                registry.byName.set(entry.typeName, entry);
+            if (!seenNames.has(entry.typeName)) {
+                seenNames.add(entry.typeName);
+                memberNames.push(entry.typeName);
+            }
+        }
+        family.variantUnionMembers = memberNames;
+        registry.baseRefs.set(family.baseRefStr, family);
+    }
+    // Pass 3 — collision-safe `{Base}Variant` union names (D6): candidates go
+    // through the SAME reserved-name machinery as schemas, seeded with every
+    // emitted schema name, so a user schema literally named `ThingVariant`
+    // forces the generated union to `ThingVariantModel` (no duplicate export).
+    const unionCandidates = [...registry.families.values()].map((f) => `${f.baseTypeName}Variant`);
+    const unionRenames = buildSchemaRenameMap(unionCandidates, new Set([...RESERVED_TYPE_NAMES, ...allSchemaNames]));
+    for (const family of registry.families.values()) {
+        const candidate = `${family.baseTypeName}Variant`;
+        family.variantUnionName = unionRenames.get(candidate) ?? candidate;
+    }
+    return registry;
+}

package/dist/analyzer/path-analyzer.d.ts

@@ -5,8 +5,8 @@ export interface AnalyzedParameter {
     name: string;
     in: 'path' | 'query' | 'header' | 'cookie';
     required: boolean;
+    /** Resolved param schema — analyzer-internal translation input for `analyze()`; renderers must not read it. */
     schema: SchemaObject | undefined;
-    tsType: string;
     description?: string;
     deprecated?: boolean;
     example?: unknown;
@@ -14,18 +14,35 @@ export interface AnalyzedParameter {
 export interface AnalyzedRequestBody {
     required: boolean;
     contentTypes: string[];
-    schema: SchemaObject | ReferenceObject | undefined;
-    tsType: string;
+    /**
+     * Whether the first content entry carries a schema — drives the
+     * `{Prefix}Body` emission-presence decision (both the emission inventory in
+     * operation-naming and the Section-3 emission in analyze() read this fact,
+     * so they can never desync). The raw schema itself travels beside the
+     * operations array in `AnalyzedPathsResult`.
+     */
+    hasSchema: boolean;
     isMultipart: boolean;
+    isBinary: boolean;
     description?: string;
 }
 export interface AnalyzedResponse {
     statusCode: string;
     description?: string;
+    /** Raw (possibly `$ref`) first-content schema — analyzer-internal translation input for `analyze()`; renderers must not read it. */
     schema: SchemaObject | ReferenceObject | undefined;
-    tsType: string;
     isSuccess: boolean;
     isBinary: boolean;
+    /**
+     * True exactly for schema-less, non-binary 2xx responses with no content
+     * (or empty content) — the "empty body → void" classification.
+     */
+    isVoid: boolean;
+    /**
+     * Finished (real-mapper) TS type text — StreamResponse substitution and
+     * discriminator variant rewrites applied. Set by `analyze()`.
+     */
+    finishedType?: string;
 }
 export interface AnalyzedOperation {
     method: string;
@@ -46,8 +63,28 @@ export interface AnalyzedOperation {
     responses: AnalyzedResponse[];
 }
 /**
- * Analyze all paths and operations from an OpenAPI document into structured data
- * for code generation.
+ * Analyzer-internal analysis result: the analyzed operations plus the raw
+ * request body schemas in a PARALLEL ARRAY (same length and order as
+ * `operations`). The raw schemas are translation input for `analyze()` and
+ * deliberately do not travel on the `AnalyzedRequestBody` seam.
+ */
+export interface AnalyzedPathsResult {
+    operations: AnalyzedOperation[];
+    requestBodySchemas: (SchemaObject | ReferenceObject | undefined)[];
+}
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation, carrying the raw request body schemas alongside.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param resolver - A RefResolver for resolving $ref pointers
+ * @param strategy - Method naming strategy (defaults to 'path-based')
+ * @returns Operations with parallel raw request body schemas
+ */
+export declare function analyzePathsDetailed(doc: OpenAPIDocument, resolver: RefResolver, strategy?: MethodNameStrategy): AnalyzedPathsResult;
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation.
  *
  * @param doc - The parsed and validated OpenAPI document
  * @param resolver - A RefResolver for resolving $ref pointers

package/dist/analyzer/path-analyzer.js

@@ -1,63 +1,16 @@
 import { RefResolver } from '../parser/ref-resolver.js';
-import { sanitizeTypeName, getOperationTypePrefix } from '../utils/generator-helpers.js';
+import { isBinaryContentType } from '../utils/generator-helpers.js';
+import { getOperationTypePrefix } from '../utils/operation-naming.js';
 import { getMethodName } from './naming.js';
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
-function isRef(obj) {
-    return obj !== null && typeof obj === 'object' && '$ref' in obj;
-}
-function isBinaryContentType(ct) {
-    if (ct === 'application/octet-stream')
-        return true;
-    if (ct.startsWith('image/'))
-        return true;
-    if (ct.startsWith('video/'))
-        return true;
-    if (ct.startsWith('audio/'))
-        return true;
-    return false;
-}
-function schemaToTsType(schema, resolver) {
+/**
+ * Resolve a possibly-$ref-ed schema and check for an exact top-level `format: binary`
+ * match. Top-level only — intentionally no deep-walk into items/allOf/oneOf/anyOf.
+ */
+function isBinarySchema(schema, resolver) {
     if (!schema)
-        return 'unknown';
-    if (isRef(schema)) {
-        const resolved = resolver.resolve(schema);
-        const refStr = schema.$ref;
-        const lastSegment = sanitizeTypeName(refStr.split('/').pop());
-        if (lastSegment && resolved.type) {
-            return lastSegment;
-        }
-        return lastSegment ?? 'unknown';
-    }
-    const s = schema;
-    if (s.type === undefined)
-        return 'unknown';
-    if (Array.isArray(s.type)) {
-        const nonNull = s.type.filter((t) => t !== 'null');
-        if (nonNull.length === 0)
-            return 'null';
-        return schemaToTsType({ ...s, type: nonNull[0] }, resolver);
-    }
-    switch (s.type) {
-        case 'string':
-            return 'string';
-        case 'integer':
-        case 'number':
-            return 'number';
-        case 'boolean':
-            return 'boolean';
-        case 'array':
-            if (s.items) {
-                const itemType = schemaToTsType(s.items, resolver);
-                return `${itemType}[]`;
-            }
-            return 'unknown[]';
-        case 'object':
-            return 'object';
-        case 'null':
-            return 'null';
-        default:
-            return 'unknown';
-    }
+        return false;
+    return resolver.resolveSchema(schema).format === 'binary';
 }
 function resolveParameter(param, resolver) {
     return resolver.resolve(param);
@@ -75,7 +28,6 @@ function analyzeParameter(param, resolver) {
         in: param.in,
         required: param.required ?? param.in === 'path',
         schema,
-        tsType: schemaToTsType(param.schema, resolver),
         description: param.description,
         deprecated: param.deprecated,
         example: param.example,
@@ -100,28 +52,40 @@ function mergeParameters(pathItemParams, operationParams, resolver) {
     }
     return merged;
 }
+/**
+ * Analyze one request body. Returns the structural facts plus the RAW
+ * (possibly `$ref`) first-content schema as a separate value — the schema is
+ * analyzer-internal translation input for `analyze()` and does not travel on
+ * the `AnalyzedRequestBody` seam.
+ */
 function analyzeRequestBody(body, resolver) {
     if (!body)
         return undefined;
     const resolved = resolveRequestBody(body, resolver);
     const contentTypes = Object.keys(resolved.content);
     let schema;
-    let tsType = 'unknown';
     if (contentTypes.length > 0) {
         const firstContent = resolved.content[contentTypes[0]];
         if (firstContent?.schema) {
             schema = firstContent.schema;
-            tsType = schemaToTsType(schema, resolver);
         }
     }
     const isMultipart = contentTypes.length > 0 && contentTypes[0] === 'multipart/form-data';
+    // Contract with the generators: multipart bodies keep the FileInput shape
+    // and must never be Blob-ified, so the binary signals are bypassed.
+    const isBinary = isMultipart
+        ? false
+        : contentTypes.some(isBinaryContentType) || isBinarySchema(schema, resolver);
     return {
-        required: resolved.required ?? false,
-        contentTypes,
-        schema,
-        tsType,
-        isMultipart,
-        description: resolved.description,
+        requestBody: {
+            required: resolved.required ?? false,
+            contentTypes,
+            hasSchema: schema !== undefined,
+            isMultipart,
+            isBinary,
+            description: resolved.description,
+        },
+        rawSchema: schema,
     };
 }
 function analyzeResponses(responses, resolver) {
@@ -129,7 +93,6 @@ function analyzeResponses(responses, resolver) {
     for (const [statusCode, response] of Object.entries(responses)) {
         const resolved = resolveResponse(response, resolver);
         let schema;
-        let tsType = 'unknown';
         let contentTypes = [];
         if (resolved.content) {
             contentTypes = Object.keys(resolved.content);
@@ -137,24 +100,22 @@ function analyzeResponses(responses, resolver) {
                 const firstContent = resolved.content[contentTypes[0]];
                 if (firstContent?.schema) {
                     schema = firstContent.schema;
-                    tsType = schemaToTsType(schema, resolver);
                 }
             }
         }
         // Empty-body success responses → void
-        if (tsType === 'unknown' &&
+        const isVoid = schema === undefined &&
             statusCode.startsWith('2') &&
-            (!resolved.content || contentTypes.length === 0)) {
-            tsType = 'void';
-        }
-        const isBinary = contentTypes.length > 0 && isBinaryContentType(contentTypes[0]);
+            (!resolved.content || contentTypes.length === 0);
+        const isBinary = contentTypes.length > 0 &&
+            (isBinaryContentType(contentTypes[0]) || isBinarySchema(schema, resolver));
         result.push({
             statusCode,
             description: resolved.description,
             schema,
-            tsType,
             isSuccess: statusCode.startsWith('2'),
             isBinary,
+            isVoid,
         });
     }
     return result;
@@ -183,18 +144,19 @@ function categorizeParameters(params) {
     return { pathParams, queryParams, headerParams, cookieParams };
 }
 /**
- * Analyze all paths and operations from an OpenAPI document into structured data
- * for code generation.
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation, carrying the raw request body schemas alongside.
  *
  * @param doc - The parsed and validated OpenAPI document
  * @param resolver - A RefResolver for resolving $ref pointers
  * @param strategy - Method naming strategy (defaults to 'path-based')
- * @returns Array of AnalyzedOperation objects
+ * @returns Operations with parallel raw request body schemas
  */
-export function analyzePaths(doc, resolver, strategy = 'path-based') {
+export function analyzePathsDetailed(doc, resolver, strategy = 'path-based') {
     const operations = [];
+    const requestBodySchemas = [];
     if (!doc.paths)
-        return operations;
+        return { operations, requestBodySchemas };
     const usedTypePrefixes = new Set();
     const usedMethodNames = new Set();
     for (const [urlPath, pathItem] of Object.entries(doc.paths)) {
@@ -205,7 +167,7 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
             const mergedParams = mergeParameters(pathItem.parameters, operation.parameters, resolver);
             const analyzedParams = mergedParams.map((p) => analyzeParameter(p, resolver));
             const categorized = categorizeParameters(analyzedParams);
-            const requestBody = analyzeRequestBody(operation.requestBody, resolver);
+            const requestBodyResult = analyzeRequestBody(operation.requestBody, resolver);
             const responses = analyzeResponses(operation.responses, resolver);
             const methodName = getMethodName(method, urlPath, operation.operationId, strategy);
             operations.push({
@@ -218,17 +180,16 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
                 deprecated: operation.deprecated ?? false,
                 tags: operation.tags ?? [],
                 ...categorized,
-                requestBody,
+                requestBody: requestBodyResult?.requestBody,
                 responses,
             });
+            requestBodySchemas.push(requestBodyResult?.rawSchema);
         }
     }
     // Dedupe type prefixes and method names so that distinct routes folding to
     // the same identifier (e.g. "/weird" and "/weird-", or "/Weird" and
     // "/weird") cannot produce duplicate exported types or client methods.
-    // NOTE: analyzePaths runs twice per generation (contracts pass + client
-    // pass); this assignment must stay deterministic - it relies on insertion
-    // order and the fixed HTTP_METHODS loop - so both passes agree.
+    // Assignment relies on insertion order and the fixed HTTP_METHODS loop.
     for (const op of operations) {
         const baseTypePrefix = getOperationTypePrefix(op);
         let typePrefix = baseTypePrefix;
@@ -249,5 +210,17 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
         usedMethodNames.add(methodName);
         op.methodName = methodName;
     }
-    return operations;
+    return { operations, requestBodySchemas };
+}
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param resolver - A RefResolver for resolving $ref pointers
+ * @param strategy - Method naming strategy (defaults to 'path-based')
+ * @returns Array of AnalyzedOperation objects
+ */
+export function analyzePaths(doc, resolver, strategy = 'path-based') {
+    return analyzePathsDetailed(doc, resolver, strategy).operations;
 }

package/dist/analyzer/schema-mapper.d.ts

@@ -1,10 +1,32 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import type { TypeMappingResult } from '../types/contracts.js';
 import type { SchemaObject, ReferenceObject } from '../types/openapi.js';
+import type { DiscriminatorRegistry } from './discriminator-registry.js';
 /**
  * Callback to customize how $ref strings are converted to TypeScript type names.
  */
 export type TypeNameGenerator = (refString: string) => string;
+/**
+ * Optional construction dependencies for {@link SchemaMapper}. Every field is
+ * optional and defaults exactly as the previous positional constructor
+ * parameters did.
+ */
+export interface SchemaMapperOptions {
+    typeNameGenerator?: TypeNameGenerator;
+    discriminatorTargets?: Map<string, {
+        propertyName: string;
+        literalValue: string;
+    }>;
+    emittedNames?: Set<string>;
+    warnSink?: (message: string) => void;
+    discriminatorRegistry?: DiscriminatorRegistry;
+    /**
+     * Effective OpenAPI dialect. Omitted is treated as '3.1' (the nullable
+     * deprecation warning fires). Pass '3.0' to silence it — 'nullable' is the
+     * correct mechanism in 3.0.
+     */
+    effectiveVersion?: '3.0' | '3.1';
+}
 /**
  * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
  *
@@ -15,13 +37,13 @@ export declare class SchemaMapper {
     private readonly resolver;
     private readonly typeNameGenerator;
     private readonly discriminatorTargets;
-    private readonly reservedNames;
+    private readonly emittedNames;
+    private readonly discriminatorRegistry;
     private readonly brandedTypes;
-    private static nullableWarned;
-    constructor(resolver: RefResolver, typeNameGenerator?: TypeNameGenerator, discriminatorTargets?: Map<string, {
-        propertyName: string;
-        literalValue: string;
-    }>, reservedNames?: Set<string>);
+    private nullableWarned;
+    private readonly warnSink;
+    private readonly effectiveVersion;
+    constructor(resolver: RefResolver, opts?: SchemaMapperOptions);
     getBrandedTypes(): Map<string, {
         name: string;
         format: string;
@@ -36,12 +58,52 @@ export declare class SchemaMapper {
      * @returns TypeMappingResult with tsType string and imports array
      */
     mapSchema(schema: SchemaObject | ReferenceObject, name?: string, context?: 'request' | 'response'): TypeMappingResult;
+    /**
+     * Append the discriminator literal intersection exactly ONCE (site 2),
+     * parenthesizing a top-level union so `X | null & {...}` cannot bind the
+     * literal to the last union member only (D9).
+     */
+    private appendDiscriminatorLiteral;
     private getBrandTypeName;
     private mapInternal;
+    /**
+     * The single ref-translation seam (site 1). When the mapper carries a
+     * discriminator registry, EVERY `$ref` resolves through here:
+     *
+     * - a discriminator BASE becomes `{Base}Variant` at all sites except
+     *   inside a same-family member's own definition spine, where it stays
+     *   the bare base name (structural inheritance, no circularity — D1);
+     * - a same-family mapping target inside a spine becomes `Omit<M, 'P'>`,
+     *   falling back to inline expansion WITHOUT the literal when M is a
+     *   union, nullable, unnamed or non-object (D2/D4);
+     * - a mapping target at any other site is its bare name — the literal is
+     *   injected exactly once, at the target's own named definition.
+     */
+    private translateRefThroughSeam;
+    /**
+     * D2/D4 spine rule for a same-family `$ref`. `Omit<M, 'P'>` strips the
+     * sibling's own literal so the appender can re-add ours; the inline-strip
+     * fallback covers the cases where `Omit` would silently drop data
+     * (union target: `Omit<A|B,K>` drops variant props; nullable target:
+     * `Omit<M|null,K>` collapses to `{}`; unnamed/non-object target).
+     */
+    private mapSameFamilySpineRef;
+    /** Normalize a `#/components/schemas/…` ref to its canonically-encoded form (`a/b` ↔ `a~1b`). */
+    private canonicalSchemasRef;
+    private tryResolveRef;
+    private isObjectIshSchema;
     private resolveDiscriminatorInfo;
     private mapEnumValues;
     private mapCombinator;
     private mapDiscriminatedUnion;
+    /**
+     * D3 literal precedence for registry-mode wrapper literals (inline variant
+     * schemas and foreign refs): mapping key > own `const` on the discriminant
+     * property > single-value `enum` > RAW last ref segment (the runtime
+     * value, NOT the sanitized type name). Values are escaped for a
+     * single-quoted TS string.
+     */
+    private resolveRegistryDiscriminantValue;
     private resolveDiscriminantValue;
     private mapArray;
     /**