@skmtc/core 0.0.984 → 0.16.1

package/esm/context/GenerateContext.js

@@ -9,15 +9,18 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _GenerateContext_instances, _GenerateContext_files, _GenerateContext_previews, _GenerateContext_mappings, _GenerateContext_runOperationGenerator, _GenerateContext_runModelGenerator, _GenerateContext_addPreview, _GenerateContext_addMapping, _GenerateContext_getFile, _GenerateContext_defineAndRegister, _GenerateContext_addFile;
-import { normalize } from '../deps/jsr.io/@std/path/1.1.3/normalize.js';
-import { Import } from '../dsl/Import.js';
-import { Definition } from '../dsl/Definition.js';
-import { OperationDriver } from '../dsl/operation/OperationDriver.js';
+var _GenerateContext_instances, _GenerateContext_files, _GenerateContext_previews, _GenerateContext_mappings, _GenerateContext_captureChannel, _GenerateContext_supports, _GenerateContext_subjectDefaults, _GenerateContext_runOasOperationGenerator, _GenerateContext_runWebhookGenerator, _GenerateContext_runGqlOperationGenerator, _GenerateContext_runModelGenerator, _GenerateContext_addPreview, _GenerateContext_addMapping;
+import { normalize } from '../deps/jsr.io/@std/path/1.1.4/normalize.js';
+import { OasOperationDriver } from '../dsl/operation/oas/OasOperationDriver.js';
+import { WebhookDriver } from '../dsl/webhook/WebhookDriver.js';
+import { GqlOperationDriver } from '../dsl/operation/gql/GqlOperationDriver.js';
 import { ModelDriver } from '../dsl/model/ModelDriver.js';
 import { ContentSettings } from '../dsl/ContentSettings.js';
+import { DEFAULT_VARIANT } from '../types/Variant.js';
+import { toVariantList } from '../helpers/toVariantList.js';
+import get from 'lodash-es/get.js';
 import { Inserted } from '../dsl/Inserted.js';
-import { File } from '../dsl/File.js';
+import { CodeFileBase } from '../dsl/CodeFileBase.js';
 import { JsonFile } from '../dsl/JsonFile.js';
 import invariant from 'tiny-invariant';
 /**
@@ -44,15 +47,15 @@ import invariant from 'tiny-invariant';
  *
  * @example Basic usage in a model generator
  * ```typescript
- * import { ModelBase } from '@skmtc/core';
+ * import { ModelProjectionBase } from '@skmtc/core';
  *
- * class TypeScriptInterface extends ModelBase {
+ * class TypeScriptInterface extends ModelProjectionBase {
  *   generate(): Definition {
  *     const schema = this.context.getSchema(this.refName);
  *
  *     return new Definition({
  *       context: this.context,
- *       identifier: Identifier.createType(this.refName),
+ *       identifier: createType(this.refName),
  *       description: schema.description,
  *       value: {
  *         generatorKey: this.generatorKey,
@@ -63,19 +66,23 @@ import invariant from 'tiny-invariant';
  * }
  * ```
  */
+const isGqlInsertOperationArgs = (args) => args.operation.oasType === 'gqlOperation';
+const isGqlToOperationSettingsArgs = (args) => args.operation.oasType === 'gqlOperation';
+/** A non-null object — the subject-scope leaf of an enrichment-defaults umbrella
+ *  (`{ fields, title, … }`). Narrows `unknown` without an `as` cast. */
+const isEnrichmentLeaf = (value) => typeof value === 'object' && value !== null;
 export class GenerateContext {
-    /**
-     * Creates a new GenerateContext instance for the generation phase.
-     *
-     * @param args - Constructor arguments including document, settings, and handlers
-     */
-    constructor({ oasDocument, settings, logger, captureCurrentResult, toGeneratorConfigMap }) {
+    constructor({ document, settings, logger, captureCurrentResult, toGeneratorConfigMap, captureChannel }) {
         _GenerateContext_instances.add(this);
         _GenerateContext_files.set(this, void 0);
         _GenerateContext_previews.set(this, void 0);
         _GenerateContext_mappings.set(this, void 0);
-        /** The parsed OpenAPI document being processed */
-        Object.defineProperty(this, "oasDocument", {
+        /**
+         * Parsed source document, wrapped in the {@link SkmtcParsedDocument}
+         * discriminated union. Canonical representation; both protocol-neutral
+         * (model) and protocol-specific (operation) dispatch reads through this.
+         */
+        Object.defineProperty(this, "document", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -116,15 +123,32 @@ export class GenerateContext {
             writable: true,
             value: void 0
         });
+        /**
+         * Creates a new GenerateContext instance for the generation phase.
+         *
+         * @param args - Constructor arguments including document, settings, and handlers
+         */
+        /** Shared attribution capture channel (see {@link ConstructorArgs}). */
+        _GenerateContext_captureChannel.set(this, void 0);
         this.logger = logger;
         __classPrivateFieldSet(this, _GenerateContext_files, new Map(), "f");
         __classPrivateFieldSet(this, _GenerateContext_previews, {}, "f");
         __classPrivateFieldSet(this, _GenerateContext_mappings, {}, "f");
-        this.oasDocument = oasDocument;
+        this.document = document;
         this.settings = settings;
         this.captureCurrentResult = captureCurrentResult;
         this.toGeneratorConfigMap = toGeneratorConfigMap;
         this.modelDepth = {};
+        __classPrivateFieldSet(this, _GenerateContext_captureChannel, captureChannel, "f");
+    }
+    /**
+     * The active attribution capture sink, or `undefined` outside the
+     * capture interval. Every `SnippetBase` instance's `toString` wrapper
+     * reads this; `RenderContext` opens/closes the interval by flipping the
+     * shared channel's `sink`.
+     */
+    get captureSink() {
+        return __classPrivateFieldGet(this, _GenerateContext_captureChannel, "f")?.sink;
     }
     /**
      * @internal
@@ -133,21 +157,68 @@ export class GenerateContext {
         const generators = Object.values(this.toGeneratorConfigMap());
         generators.forEach(generatorConfig => {
             stackTrail.trace(generatorConfig.id, st => {
+                // Whole-generator skip (string entry in `skip`). Silent no-op:
+                // no per-operation `skipped` results emitted.
                 if (this.settings?.skip?.includes(generatorConfig.id)) {
                     return;
                 }
+                // `include` is per-generator, not document-global. A generator
+                // with a per-operation include slice runs in allow-list mode
+                // (only the listed operations); a generator absent from
+                // `include` is unaffected and runs default-on. There is
+                // therefore no whole-generator include gate here — the slice
+                // extracted below is applied per-operation in the run* arms.
+                // (Whole-generator opt-out is `skip`. A bare-string `include`
+                // entry carries no per-operation filter and is a no-op.)
                 const skip = this.settings?.skip?.find((skip) => {
                     return typeof skip === 'object' && Boolean(skip[generatorConfig.id]);
                 });
+                // Extract the per-generator include slice (if any). Same
+                // dispatch shape as skip: object entries get matched by key,
+                // string entries don't produce a per-op filter (they mean
+                // "everything from this generator is included", which is
+                // semantically equivalent to "no per-op filter" once the
+                // whole-generator gate above has admitted us).
+                const include = this.settings?.include?.find((entry) => {
+                    return typeof entry === 'object' && Boolean(entry[generatorConfig.id]);
+                });
                 switch (generatorConfig.type) {
-                    case 'operation':
-                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runOperationGenerator).call(this, this.oasDocument, generatorConfig, toSkipPaths(skip, generatorConfig.id), st);
+                    case 'oasOperation':
+                        if (this.document.type !== 'oas') {
+                            // Generator targets OAS; current document is GraphQL — skip silently.
+                            return;
+                        }
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runOasOperationGenerator).call(this, this.document.value, generatorConfig, toIncludePaths(include, generatorConfig.id), toSkipPaths(skip, generatorConfig.id), st);
+                        break;
+                    case 'webhook':
+                        if (this.document.type !== 'oas') {
+                            // Webhooks are an OAS 3.1 feature; current document is GraphQL —
+                            // skip silently.
+                            return;
+                        }
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runWebhookGenerator).call(this, this.document.value, generatorConfig, toIncludePaths(include, generatorConfig.id), toSkipPaths(skip, generatorConfig.id), st);
+                        break;
+                    case 'gqlOperation':
+                        if (this.document.type !== 'gql') {
+                            // Generator targets GraphQL; current document is OAS — skip silently.
+                            return;
+                        }
+                        // GraphQL operations don't yet have skip/include support
+                        // at the per-operation level. The whole-generator gate
+                        // above does apply (so `include: ['my-gql-gen']` works as
+                        // expected), but per-(rootKind, fieldName) filtering is a
+                        // follow-up that needs the same dispatch shape added for
+                        // GqlOperation. Tracked alongside the existing GQL-skip
+                        // gap.
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runGqlOperationGenerator).call(this, this.document.value, generatorConfig, st);
                         break;
                     case 'model':
-                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runModelGenerator).call(this, this.oasDocument, generatorConfig, toSkipModels(skip, generatorConfig.id), st);
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_runModelGenerator).call(this, this.document, generatorConfig, toIncludeModels(include, generatorConfig.id), toSkipModels(skip, generatorConfig.id), st);
                         break;
-                    default:
-                        throw new Error(`Invalid generator type: '${generatorConfig.type}' on ${generatorConfig.id}`);
+                    default: {
+                        const _exhaustive = generatorConfig;
+                        throw new Error(`Invalid generator type: ${JSON.stringify(_exhaustive)}`);
+                    }
                 }
             });
         });
@@ -158,29 +229,181 @@ export class GenerateContext {
         };
     }
     /**
-     * Create and register a definition with the given `identifier` at `destinationPath`.
+     * Evaluate each generator's `isSupported` over the parsed document's subjects
+     * and report the subjects each generator supports — capability only, no
+     * transform and no render. Operation generators report the operations their
+     * `isSupported` accepts; model generators report every model (the generate
+     * pipeline applies no model-level `isSupported`). A generator targeting the
+     * other protocol reports nothing.
+     */
+    toSupportedSubjects() {
+        const generators = Object.values(this.toGeneratorConfigMap());
+        const out = {};
+        generators.forEach(generatorConfig => {
+            switch (generatorConfig.type) {
+                case 'oasOperation': {
+                    const operations = this.document.type === 'oas'
+                        ? this.document.value.operations
+                            .filter(operation => __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_supports).call(this, () => generatorConfig.isSupported({ operation, context: this, variant: DEFAULT_VARIANT })))
+                            .map(operation => ({ path: operation.path, method: operation.method }))
+                        : [];
+                    out[generatorConfig.id] = { type: 'oasOperation', operations };
+                    break;
+                }
+                case 'webhook': {
+                    const webhooks = this.document.type === 'oas'
+                        ? this.document.value.webhooks
+                            .filter(webhook => __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_supports).call(this, () => generatorConfig.isSupported({ webhook, context: this, variant: DEFAULT_VARIANT })))
+                            .map(webhook => ({ name: webhook.name, method: webhook.method }))
+                        : [];
+                    out[generatorConfig.id] = { type: 'webhook', webhooks };
+                    break;
+                }
+                case 'gqlOperation': {
+                    const operations = this.document.type === 'gql'
+                        ? this.document.value.operations
+                            .filter(operation => __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_supports).call(this, () => generatorConfig.isSupported({ operation, context: this, variant: DEFAULT_VARIANT })))
+                            .map(operation => ({
+                            rootKind: operation.rootKind,
+                            fieldName: operation.fieldName
+                        }))
+                        : [];
+                    out[generatorConfig.id] = { type: 'gqlOperation', operations };
+                    break;
+                }
+                case 'model': {
+                    const refNames = this.document.type === 'oas'
+                        ? (this.document.value.components?.toSchemasRefNames() ?? [])
+                        : this.document.value.registry.toSchemasRefNames();
+                    out[generatorConfig.id] = { type: 'model', models: [...refNames] };
+                    break;
+                }
+                default: {
+                    const _exhaustive = generatorConfig;
+                    throw new Error(`Invalid generator type: ${JSON.stringify(_exhaustive)}`);
+                }
+            }
+        });
+        return out;
+    }
+    /**
+     * The seed enrichment values each configured generator derives from the
+     * document — the *values* counterpart of {@link toSupportedSubjects}. For
+     * every generator that advertises `toEnrichmentDefaults`, calls it over the
+     * subjects the generator supports and keeps the non-`undefined` subject-scope
+     * leaves, keyed by the `client.json#settings.enrichments` routing:
+     * `[id][path][method]['main']` for operations, `[id][refName]['main']` for
+     * models. Seeding targets the `'main'` variant; a generator that advertises
+     * no defaults (or whose every subject returns `undefined`) is omitted.
      *
-     * @experimental
+     * Like {@link toSupportedSubjects} it neither transforms nor renders, and is
+     * defensive: a generator whose hook throws contributes nothing rather than
+     * failing the whole pass.
      */
-    defineAndRegister({ identifier, value, destinationPath, noExport }) {
-        // @TODO cache check is duplicatd if call comes from
-        // createAndRegisterDefinition. Look for a way to share code between
-        // these two functions
-        const cachedDefinition = this.findDefinition({
-            name: identifier.name,
-            exportPath: destinationPath
+    toEnrichmentDefaults() {
+        const generators = Object.values(this.toGeneratorConfigMap());
+        const out = {};
+        generators.forEach(generatorConfig => {
+            switch (generatorConfig.type) {
+                case 'oasOperation': {
+                    const toDefaults = generatorConfig.toEnrichmentDefaults;
+                    if (!toDefaults || this.document.type !== 'oas')
+                        break;
+                    const operations = {};
+                    this.document.value.operations.forEach(operation => {
+                        if (!__classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_supports).call(this, () => generatorConfig.isSupported({ operation, context: this, variant: DEFAULT_VARIANT }))) {
+                            return;
+                        }
+                        const leaf = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_subjectDefaults).call(this, () => toDefaults({ operation, context: this, variant: DEFAULT_VARIANT }));
+                        if (leaf === undefined)
+                            return;
+                        const methods = (operations[operation.path] ??= {});
+                        methods[operation.method] = { [DEFAULT_VARIANT]: leaf };
+                    });
+                    if (Object.keys(operations).length > 0) {
+                        out[generatorConfig.id] = operations;
+                    }
+                    break;
+                }
+                case 'webhook': {
+                    const toDefaults = generatorConfig.toEnrichmentDefaults;
+                    if (!toDefaults || this.document.type !== 'oas')
+                        break;
+                    const webhooks = {};
+                    this.document.value.webhooks.forEach(webhook => {
+                        if (!__classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_supports).call(this, () => generatorConfig.isSupported({ webhook, context: this, variant: DEFAULT_VARIANT }))) {
+                            return;
+                        }
+                        const leaf = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_subjectDefaults).call(this, () => toDefaults({ webhook, context: this, variant: DEFAULT_VARIANT }));
+                        if (leaf === undefined)
+                            return;
+                        const methods = (webhooks[webhook.name] ??= {});
+                        methods[webhook.method] = { [DEFAULT_VARIANT]: leaf };
+                    });
+                    if (Object.keys(webhooks).length > 0) {
+                        out[generatorConfig.id] = webhooks;
+                    }
+                    break;
+                }
+                case 'model': {
+                    const toDefaults = generatorConfig.toEnrichmentDefaults;
+                    if (!toDefaults)
+                        break;
+                    // Model entries carry no `isSupported` — the generate pipeline visits
+                    // every refName and filters inside the callback. Mirror that here: the
+                    // hook itself returns `undefined` for schemas it doesn't seed.
+                    const refNames = this.document.type === 'oas'
+                        ? (this.document.value.components?.toSchemasRefNames() ?? [])
+                        : this.document.value.registry.toSchemasRefNames();
+                    const models = {};
+                    for (const refName of refNames) {
+                        const leaf = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_subjectDefaults).call(this, () => toDefaults({ refName, context: this, variant: DEFAULT_VARIANT }));
+                        if (leaf === undefined)
+                            continue;
+                        models[refName] = { [DEFAULT_VARIANT]: leaf };
+                    }
+                    if (Object.keys(models).length > 0) {
+                        out[generatorConfig.id] = models;
+                    }
+                    break;
+                }
+                case 'gqlOperation': {
+                    // No `toEnrichmentDefaults` on the GraphQL projection base — seeding is
+                    // OAS-operation / model only today, so a GQL generator contributes
+                    // nothing.
+                    break;
+                }
+                default: {
+                    const _exhaustive = generatorConfig;
+                    throw new Error(`Invalid generator type: ${JSON.stringify(_exhaustive)}`);
+                }
+            }
         });
-        // @TODO add check to make sure retrieved definition
-        // used same generator and same schema #SKM-47
-        if (cachedDefinition) {
-            return cachedDefinition;
+        return out;
+    }
+    /**
+     * Look up an already-registered file by path, or `undefined` if none
+     * exists. Neutral primitive: returns the abstract `FileBase` and never
+     * constructs anything, so a (future) language-owned `register` can ask
+     * "does this file exist yet?" without the engine knowing the language.
+     * To create-on-miss, use the internal `#getFile`; to add a
+     * language-constructed file, use {@link addFile}.
+     */
+    getFile(filePath) {
+        return __classPrivateFieldGet(this, _GenerateContext_files, "f").get(normalize(filePath));
+    }
+    /**
+     * Store a language-constructed file. The engine never constructs a
+     * concrete (language) `File`; the language's `register` builds its own
+     * `FileBase` subclass and hands it in here. Throws if a file already
+     * exists at the (normalized) path.
+     */
+    addFile(file) {
+        const normalizedPath = normalize(file.path);
+        if (__classPrivateFieldGet(this, _GenerateContext_files, "f").has(normalizedPath)) {
+            throw new Error(`File already exists: ${normalizedPath}`);
         }
-        return __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_defineAndRegister).call(this, {
-            identifier,
-            value,
-            destinationPath,
-            noExport
-        });
+        __classPrivateFieldGet(this, _GenerateContext_files, "f").set(normalizedPath, file);
     }
     /**
      * Registers JSON content for output to a file.
@@ -189,7 +412,12 @@ export class GenerateContext {
      * @param args - Registration arguments with destination path and JSON content
      */
     registerJson({ destinationPath, json }) {
-        const currentFile = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_getFile).call(this, destinationPath);
+        const normalizedPath = normalize(destinationPath);
+        let currentFile = this.getFile(normalizedPath);
+        if (!currentFile) {
+            currentFile = new JsonFile({ path: normalizedPath, content: {} });
+            this.addFile(currentFile);
+        }
         invariant(currentFile instanceof JsonFile, `File at "${destinationPath}" is not a "JsonFile" type`);
         currentFile.content = json;
     }
@@ -204,81 +432,99 @@ export class GenerateContext {
      *
      * @mutates this.files
      */
-    register({ imports = {}, definitions, destinationPath, reExports }) {
-        // TODO deduplicate import names and definition names against each other
-        const currentFile = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_getFile).call(this, destinationPath);
-        invariant(currentFile instanceof File, `File at "${destinationPath}" is not a "File" type`);
-        Object.entries(reExports ?? {}).forEach(([importModule, identifiers]) => {
-            if (!currentFile.reExports.get(importModule) && identifiers.length) {
-                currentFile.reExports.set(importModule, {});
-            }
-            identifiers.forEach(identifier => {
-                const entityType = identifier.entityType.type;
-                const module = currentFile.reExports.get(importModule);
-                invariant(module, 'Module not found');
-                if (!module[entityType]) {
-                    module[entityType] = new Set();
-                }
-                module[entityType].add(identifier.name);
-            });
-        });
-        Object.entries(imports).forEach(([importModule, importNames]) => {
-            const module = currentFile.imports.get(importModule);
-            const importItem = new Import({ module: importModule, importNames });
-            if (module) {
-                importItem.importNames.forEach(n => module.add(`${n}`));
-            }
-            else {
-                currentFile.imports.set(importModule, new Set(importItem.importNames.map(n => `${n}`)));
-            }
-        });
+    register({ imports = [], reExports = [], definitions, destinationPath }) {
+        const normalizedPath = normalize(destinationPath);
+        const currentFile = this.getFile(normalizedPath);
+        // `register` never creates files — it speaks pure data and the engine
+        // never names a file class. Callers pre-create the destination file
+        // through their language (the lang package's register function, the
+        // Drivers' ensureFile); reaching a file-miss here is a bug at the
+        // caller.
+        invariant(currentFile, `Cannot register into '${normalizedPath}' — the file does not exist. ` +
+            `Pre-create it through your lang (its register function does this).`);
+        // Definitions merge is language-neutral — `addDefinition` lives on
+        // `FileBase`, so this works for any language's file.
         definitions?.forEach(definition => {
-            if (!definition) {
-                return;
-            }
-            const { name } = definition.identifier;
-            if (!currentFile.definitions.has(name)) {
-                currentFile.definitions.set(name, definition);
+            if (definition) {
+                currentFile.addDefinition(definition);
             }
         });
+        // Imports and re-exports are standardised `ImportBase` /
+        // `ReExportBase` objects; the neutral merges (keyed by `mergeKey`)
+        // live on `CodeFileBase`. `JsonFile` has neither, so the guard skips
+        // it.
+        if (imports.length > 0 && currentFile instanceof CodeFileBase) {
+            currentFile.addImports(imports);
+        }
+        if (reExports.length > 0 && currentFile instanceof CodeFileBase) {
+            currentFile.addReExports(reExports);
+        }
     }
     /**
      * Insert operation into the output file with path `destinationPath`.
      *
      * Insert will perform the following steps:
-     * 1. Generate content settings for the supplied operation
-     * 2. Look up definition in file with path `destinationPath`
-     * 3. If definition is not found, it will create a new one and register it
-     * 4. If the definition is defined at a location that is different from
-     *    the current file, it will add an import to the current file from
-     *    that location
-     * 5. Use the content settings to generate the operation using the
-     *    insertable's driver
+     * Insert an operation definition into `destinationPath`.
+     *
+     * Resolves identifier and export path from the projection, registers the
+     * definition (or reuses a cached one), and stitches an import into
+     * `destinationPath` if it differs from the projection's `exportPath`.
+     *
      * @mutates this.files
      */
-    insertOperation(insertable, operation, { destinationPath, noExport = false } = {}) {
-        const { settings, definition } = new OperationDriver({
+    insertOperation(args) {
+        // Default to the canonical variant. Callers who explicitly thread
+        // a variant (e.g. variants-aware Projections threading
+        // `this.settings.variant`) override this default.
+        const variant = args.variant ?? DEFAULT_VARIANT;
+        if (isGqlInsertOperationArgs(args)) {
+            const { settings, definition } = new GqlOperationDriver({
+                context: this,
+                projection: args.projection,
+                operation: args.operation,
+                destinationPath: args.destinationPath,
+                noExport: args.noExport ?? false,
+                variant
+            });
+            return new Inserted({ settings, definition });
+        }
+        const { settings, definition } = new OasOperationDriver({
+            context: this,
+            projection: args.projection,
+            operation: args.operation,
+            destinationPath: args.destinationPath,
+            noExport: args.noExport ?? false,
+            variant
+        });
+        return new Inserted({ settings, definition });
+    }
+    /**
+     * Insert a webhook's projection. Sibling of {@link insertOperation} for
+     * the OAS 3.1 webhook subject — webhooks are OAS-only, so there is no
+     * protocol discrimination.
+     */
+    insertWebhook(args) {
+        const variant = args.variant ?? DEFAULT_VARIANT;
+        const { settings, definition } = new WebhookDriver({
             context: this,
-            insertable,
-            operation,
-            destinationPath,
-            noExport
+            projection: args.projection,
+            webhook: args.webhook,
+            destinationPath: args.destinationPath,
+            noExport: args.noExport ?? false,
+            variant
         });
         return new Inserted({ settings, definition });
     }
     /**
-     * Inserts a normalized model definition into the generation context.
-     *
-     * @param insertable - Model insertable configuration with prototype and transform functions
-     * @param schema - OAS schema, reference, or void type to generate model from
-     * @param options - Insertion options including generation type and destination
-     * @returns Inserted model instance with settings and definition
+     * Insert a normalized model: dispatch to {@link insertModel} when the schema
+     * is a `$ref`, otherwise produce a one-off definition under `fallbackName`.
      */
-    insertNormalisedModel(insertable, { schema, fallbackName, destinationPath }, { noExport = false } = {}) {
+    insertNormalizedModel(projection, { schema, fallbackName, destinationPath }, { noExport = false, variant } = {}) {
         if (schema.isRef()) {
-            const { definition } = this.insertModel(insertable, schema.toRefName(), {
+            const { definition } = this.insertModel(projection, schema.toRefName(), {
                 destinationPath,
-                noExport
+                noExport,
+                variant
             });
             // @TODO Using mapped types would help avoid generics casting
             return definition;
@@ -292,77 +538,159 @@ export class GenerateContext {
         if (cachedDefinition) {
             return cachedDefinition;
         }
-        const value = insertable.schemaToValueFn({
+        const value = projection.schemaToValueFn({
             context: this,
             schema,
             destinationPath,
             required: true
         });
-        const definition = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_defineAndRegister).call(this, {
-            identifier: insertable.createIdentifier(fallbackName),
+        // The inline-schema fallback builds the Definition through the
+        // projection's language — the static read off the projection class at
+        // the use site (same ephemeral read the Drivers make) — pre-creates
+        // the destination file caller-side, and stores via the pure-data
+        // `register`.
+        const normalizedPath = normalize(destinationPath);
+        if (!this.getFile(normalizedPath)) {
+            this.addFile(projection.lang.createFile({ path: normalizedPath, settings: this.settings }));
+        }
+        const definition = projection.lang.toDefinition({
+            context: this,
+            identifier: projection.createIdentifier(fallbackName),
             value,
-            destinationPath,
             noExport
         });
+        this.register({ definitions: [definition], destinationPath: normalizedPath });
         // @TODO Using mapped types would help avoid generics casting
         return definition;
     }
     /**
-     * Insert model into the output file with path `destinationPath`.
+     * Insert a model definition into `destinationPath`.
+     *
+     * Resolves identifier and export path from the projection, registers the
+     * definition (or reuses a cached one), and stitches an import into
+     * `destinationPath` if it differs from the projection's `exportPath`.
      *
-     * Insert will perform the following steps:
-     * 1. Generate content settings for the supplied model
-     * 2. Look up definition in file with path `destinationPath`
-     * 3. If definition is not found, it will create a new one and register it
-     * 4. If the definition is defined at a location that is different from
-     *    the current file, it will add an import to the current file from
-     *    that location
-     * 5. Use the content settings to generate the model using the
-     *    insertable's driver
      * @mutates this.files
      */
-    insertModel(insertable, refName, { destinationPath, noExport = false } = {}) {
+    insertModel(projection, refName, { destinationPath, noExport = false, variant } = {}) {
+        // Default to the canonical variant. Callers who explicitly thread
+        // a variant (e.g. variants-aware Projections threading
+        // `this.settings.variant`) override this default.
+        const resolvedVariant = variant ?? DEFAULT_VARIANT;
         const { settings, definition } = new ModelDriver({
             context: this,
-            insertable,
+            projection,
             refName,
             destinationPath,
             rootRef: refName,
-            noExport
+            noExport,
+            variant: resolvedVariant
         });
         return new Inserted({ settings, definition });
     }
     /**
-     * Generate and return content settings for operation insertable and
-     * operation.
-     *
-     * Content settings are produced by passing base settings and operation
-     * through toIdentifier and toExportPath static methods on the
-     * insertable.
-     * @param { operation, insertable }
-     * @returns
+     * Build content settings for an operation projection by calling its
+     * statics `toIdentifierName` + `toIdentifierType`, `toExportPath`, and
+     * `toEnrichments` against the
+     * given operation.
+     */
+    toOperationContentSettings(args) {
+        const { variant } = args;
+        if (isGqlToOperationSettingsArgs(args)) {
+            const enrichments = args.projection.toEnrichments({
+                operation: args.operation,
+                context: this,
+                variant
+            });
+            return new ContentSettings({
+                identifier: args.projection.lang.toIdentifier({
+                    name: args.projection.toIdentifierName({
+                        operation: args.operation,
+                        enrichments,
+                        variant
+                    }),
+                    ...args.projection.toIdentifierType(args.operation, this)
+                }),
+                exportPath: args.projection.toExportPath({
+                    operation: args.operation,
+                    enrichments,
+                    variant
+                }),
+                enrichments,
+                variant
+            });
+        }
+        const enrichments = args.projection.toEnrichments({
+            operation: args.operation,
+            context: this,
+            variant
+        });
+        return new ContentSettings({
+            identifier: args.projection.lang.toIdentifier({
+                name: args.projection.toIdentifierName({
+                    operation: args.operation,
+                    enrichments,
+                    variant
+                }),
+                ...args.projection.toIdentifierType(args.operation, this)
+            }),
+            exportPath: args.projection.toExportPath({
+                operation: args.operation,
+                enrichments,
+                variant
+            }),
+            enrichments,
+            variant
+        });
+    }
+    /**
+     * Build content settings for a webhook projection. Sibling of
+     * {@link toOperationContentSettings}; webhooks are OAS-only, so there is no
+     * protocol discrimination.
      */
-    toOperationContentSettings({ operation, insertable }) {
+    toWebhookContentSettings(args) {
+        const { variant } = args;
+        const enrichments = args.projection.toEnrichments({
+            webhook: args.webhook,
+            context: this,
+            variant
+        });
         return new ContentSettings({
-            identifier: insertable.toIdentifier(operation),
-            exportPath: insertable.toExportPath(operation),
-            enrichments: insertable.toEnrichments({ operation, context: this })
+            identifier: args.projection.lang.toIdentifier({
+                name: args.projection.toIdentifierName({
+                    webhook: args.webhook,
+                    enrichments,
+                    variant
+                }),
+                ...args.projection.toIdentifierType(args.webhook, this)
+            }),
+            exportPath: args.projection.toExportPath({
+                webhook: args.webhook,
+                enrichments,
+                variant
+            }),
+            enrichments,
+            variant
         });
     }
     /**
-     * Generate and return content settings for model insertable and refName.
-     *
-     * Content settings are produced by passing base settings and refName
-     * through toIdentifier and toExportPath static methods on the
-     * insertable.
-     * @param { refName, insertable }
-     * @returns Content settings for model
+     * Build content settings for a model projection by calling its statics
+     * `toIdentifierName` (pure, for the name) + `toIdentifierType`
+     * (context-aware, for kind/typeName/exported), `toExportPath`, and
+     * `toEnrichments` against the given `refName` and `variant`. The full
+     * identifier is assembled through the projection's language
+     * (`lang.toIdentifier`).
      */
-    toModelContentSettings({ refName, insertable }) {
+    toModelContentSettings({ refName, projection, variant }) {
+        const enrichments = projection.toEnrichments({ refName, context: this, variant });
         return new ContentSettings({
-            identifier: insertable.toIdentifier(refName),
-            exportPath: insertable.toExportPath(refName),
-            enrichments: insertable.toEnrichments({ refName, context: this })
+            identifier: projection.lang.toIdentifier({
+                name: projection.toIdentifierName({ refName, enrichments, variant }),
+                ...projection.toIdentifierType(refName, this)
+            }),
+            exportPath: projection.toExportPath({ refName, enrichments, variant }),
+            enrichments,
+            variant
         });
     }
     /**
@@ -373,10 +701,17 @@ export class GenerateContext {
      */
     resolveSchemaRefOnce(refName, generatorId) {
         this.modelDepth[`${generatorId}:${refName}`]++;
-        const schema = this.oasDocument.components?.schemas?.[refName]?.resolveOnce();
+        const schema = this.document.type === 'oas'
+            ? this.document.value.components?.schemas?.[refName]?.resolveOnce()
+            : this.document.value.registry.schemas[refName];
         if (!schema) {
             throw new Error(`Schema not found: ${refName}`);
         }
+        // GqlRegistry stores raw OasSchema | OasRef entries that we need to
+        // resolve once for parity with the OAS code path.
+        if (this.document.type === 'gql' && 'resolveOnce' in schema) {
+            return schema.resolveOnce();
+        }
         return schema;
     }
     /**
@@ -387,70 +722,263 @@ export class GenerateContext {
      * @returns Matching definition if found or `undefined` otherwise
      */
     findDefinition({ name, exportPath }) {
-        const file = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_getFile).call(this, exportPath);
-        invariant(file instanceof File, `File at "${exportPath}" is not a "File" type`);
-        return file.definitions.get(name);
+        // Pure lookup — no file is created on a miss. `definitions` lives on
+        // `FileBase`, so this reads any language's file without narrowing.
+        return this.getFile(exportPath)?.definitions.get(name);
     }
 }
-_GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(), _GenerateContext_mappings = new WeakMap(), _GenerateContext_instances = new WeakSet(), _GenerateContext_runOperationGenerator = function _GenerateContext_runOperationGenerator(oasDocument, generatorConfig, skip, stackTrail) {
-    oasDocument.operations.reduce((acc, operation) => {
-        return stackTrail.trace(`${operation.path}:${operation.method}`, st => {
-            try {
-                if (typeof generatorConfig?.isSupported === 'function' &&
-                    !generatorConfig.isSupported({ operation, context: this })) {
-                    this.captureCurrentResult('notSupported', st);
-                    return acc;
-                }
-                if (skip?.[operation.path]?.includes(operation.method)) {
-                    this.captureCurrentResult('skipped', st);
-                    return acc;
-                }
-                const result = generatorConfig.transform({ context: this, operation, acc });
-                const source = toOperationSource({ operation, generatorId: generatorConfig.id });
-                __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, operation }));
-                __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, operation }));
-                this.captureCurrentResult('success', st);
-                return result;
-            }
-            catch (error) {
-                this.logger.error(error);
-                this.captureCurrentResult('error', st);
-            }
+_GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(), _GenerateContext_mappings = new WeakMap(), _GenerateContext_captureChannel = new WeakMap(), _GenerateContext_instances = new WeakSet(), _GenerateContext_supports = function _GenerateContext_supports(probe) {
+    try {
+        return probe();
+    }
+    catch (error) {
+        this.logger.error(error);
+        return false;
+    }
+}, _GenerateContext_subjectDefaults = function _GenerateContext_subjectDefaults(produce) {
+    try {
+        const umbrella = produce();
+        if (typeof umbrella !== 'object' || umbrella === null || !('subject' in umbrella)) {
+            return undefined;
+        }
+        const { subject } = umbrella;
+        return isEnrichmentLeaf(subject) ? subject : undefined;
+    }
+    catch (error) {
+        this.logger.error(error);
+        return undefined;
+    }
+}, _GenerateContext_runOasOperationGenerator = function _GenerateContext_runOasOperationGenerator(oasDocument, generatorConfig, include, skip, stackTrail) {
+    oasDocument.operations.forEach(operation => {
+        stackTrail.trace(`${operation.path}:${operation.method}`, opTrail => {
+            // Resolve the variant list to fan out over. The consumer's
+            // enrichments are keyed `[generatorId][path][method][variant]`;
+            // the block at `[path][method]` is therefore a record of
+            // variant names. Three cases handled in `toVariantList`:
+            //
+            //   - absent → run a single 'main' pass with no enrichment
+            //   - present, non-object → treat as a single 'main' pass
+            //     (the per-variant Valibot wrap will reject this shape
+            //     at config-load time once it lands)
+            //   - present, object → enumerate keys; 'main' must be among
+            //     them or we throw (loud beats silent zero-output)
+            const opEnrichments = get(this.settings, ['enrichments', generatorConfig.id, operation.path, operation.method]);
+            const variants = toVariantList({
+                opEnrichments,
+                generatorId: generatorConfig.id,
+                operationLabel: `${operation.method.toUpperCase()} ${operation.path}`
+            });
+            variants.forEach(variant => {
+                opTrail.trace(`variant: ${variant}`, st => {
+                    try {
+                        if (typeof generatorConfig?.isSupported === 'function' &&
+                            !generatorConfig.isSupported({ operation, context: this, variant })) {
+                            this.captureCurrentResult('notSupported', st);
+                            return;
+                        }
+                        // Order: isSupported (capability) → include (allow) → skip
+                        // (deny). Match is now on `(path, method, variant)`. An
+                        // empty variant array on a method means "every variant of
+                        // this method"; a populated array names the variants the
+                        // entry applies to.
+                        if (include !== undefined &&
+                            !matchesPathFilter({ paths: include, path: operation.path, method: operation.method, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        if (matchesPathFilter({ paths: skip, path: operation.path, method: operation.method, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        generatorConfig.transform({
+                            context: this,
+                            operation,
+                            variant
+                        });
+                        const source = toOasOperationSource({
+                            operation,
+                            generatorId: generatorConfig.id,
+                            variant
+                        });
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, operation, variant }));
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, operation, variant }));
+                        this.captureCurrentResult('success', st);
+                    }
+                    catch (error) {
+                        this.logger.error(error);
+                        this.captureCurrentResult('error', st);
+                    }
+                });
+            });
         });
-    }, undefined);
-}, _GenerateContext_runModelGenerator = function _GenerateContext_runModelGenerator(oasDocument, generatorConfig, skip, stackTrail) {
-    const refNames = oasDocument.components?.toSchemasRefNames() ?? [];
-    return refNames.reduce((acc, refName) => {
-        return stackTrail.trace(refName, st => {
-            try {
-                if (skip?.includes(refName)) {
-                    this.captureCurrentResult('skipped', st);
-                    return acc;
-                }
-                const result = generatorConfig.transform({ context: this, refName, acc });
-                const source = toModelSource({ refName, generatorId: generatorConfig.id });
-                __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, refName }));
-                __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, refName }));
-                this.captureCurrentResult('success', st);
-                return result;
-            }
-            catch (error) {
-                this.logger.error(error);
-                this.captureCurrentResult('error', st);
-            }
+    });
+}, _GenerateContext_runWebhookGenerator = function _GenerateContext_runWebhookGenerator(oasDocument, generatorConfig, include, skip, stackTrail) {
+    oasDocument.webhooks.forEach(webhook => {
+        stackTrail.trace(`webhook:${webhook.name}:${webhook.method}`, webhookTrail => {
+            // Variant fan-out, keyed `[generatorId][name][method][variant]` —
+            // the webhook analogue of the operation routing. `toVariantList`
+            // handles absent / non-object / object enrichment blocks and
+            // enforces the `'main'`-must-be-present rule.
+            const webhookEnrichments = get(this.settings, ['enrichments', generatorConfig.id, webhook.name, webhook.method]);
+            const variants = toVariantList({
+                opEnrichments: webhookEnrichments,
+                generatorId: generatorConfig.id,
+                operationLabel: `webhook '${webhook.name}' (${webhook.method.toUpperCase()})`
+            });
+            variants.forEach(variant => {
+                webhookTrail.trace(`variant: ${variant}`, st => {
+                    try {
+                        if (typeof generatorConfig?.isSupported === 'function' &&
+                            !generatorConfig.isSupported({ webhook, context: this, variant })) {
+                            this.captureCurrentResult('notSupported', st);
+                            return;
+                        }
+                        // Order: isSupported (capability) → include (allow) → skip
+                        // (deny). The skip/include shape is structurally identical to
+                        // operations (the webhook name occupies the `path` slot), so
+                        // `matchesPathFilter` is reused with `path: webhook.name`.
+                        if (include !== undefined &&
+                            !matchesPathFilter({ paths: include, path: webhook.name, method: webhook.method, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        if (matchesPathFilter({ paths: skip, path: webhook.name, method: webhook.method, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        generatorConfig.transform({
+                            context: this,
+                            webhook,
+                            variant
+                        });
+                        const source = toWebhookSource({
+                            webhook,
+                            generatorId: generatorConfig.id,
+                            variant
+                        });
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, webhook, variant }));
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, webhook, variant }));
+                        this.captureCurrentResult('success', st);
+                    }
+                    catch (error) {
+                        this.logger.error(error);
+                        this.captureCurrentResult('error', st);
+                    }
+                });
+            });
         });
-    }, undefined);
+    });
+}, _GenerateContext_runGqlOperationGenerator = function _GenerateContext_runGqlOperationGenerator(gqlDocument, generatorConfig, stackTrail) {
+    gqlDocument.operations.forEach(operation => {
+        stackTrail.trace(operation.identifier, opTrail => {
+            // GraphQL enrichment routing key is
+            // `[generatorId][rootKind][fieldName][variant]`.
+            const opEnrichments = get(this.settings, ['enrichments', generatorConfig.id, operation.rootKind, operation.fieldName]);
+            const variants = toVariantList({
+                opEnrichments,
+                generatorId: generatorConfig.id,
+                operationLabel: `${operation.rootKind} ${operation.fieldName}`
+            });
+            variants.forEach(variant => {
+                opTrail.trace(`variant: ${variant}`, st => {
+                    try {
+                        if (typeof generatorConfig.isSupported === 'function' &&
+                            !generatorConfig.isSupported({ operation, context: this, variant })) {
+                            this.captureCurrentResult('notSupported', st);
+                            return;
+                        }
+                        generatorConfig.transform({
+                            context: this,
+                            operation,
+                            variant
+                        });
+                        const source = toGqlOperationSource({
+                            operation,
+                            generatorId: generatorConfig.id,
+                            variant
+                        });
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, operation, variant }));
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, operation, variant }));
+                        this.captureCurrentResult('success', st);
+                    }
+                    catch (error) {
+                        this.logger.error(error);
+                        this.captureCurrentResult('error', st);
+                    }
+                });
+            });
+        });
+    });
+}, _GenerateContext_runModelGenerator = function _GenerateContext_runModelGenerator(document, generatorConfig, include, skip, stackTrail) {
+    const refNames = document.type === 'oas'
+        ? (document.value.components?.toSchemasRefNames() ?? [])
+        : document.value.registry.toSchemasRefNames();
+    refNames.forEach(refName => {
+        stackTrail.trace(refName, refTrail => {
+            // Resolve the variant list to fan out over. The consumer's
+            // enrichments are keyed `[generatorId][refName][variant]`; the
+            // block at `[refName]` is therefore a record of variant names.
+            // Three cases handled in `toVariantList`:
+            //
+            //   - absent → run a single 'main' pass with no enrichment
+            //   - present, non-object → treat as a single 'main' pass
+            //     (the per-variant Valibot wrap will reject this shape
+            //     at config-load time once it lands)
+            //   - present, object → enumerate keys; 'main' must be among
+            //     them or we throw (loud beats silent zero-output)
+            const modelEnrichments = get(this.settings, ['enrichments', generatorConfig.id, refName]);
+            const variants = toVariantList({
+                opEnrichments: modelEnrichments,
+                generatorId: generatorConfig.id,
+                operationLabel: refName
+            });
+            variants.forEach(variant => {
+                refTrail.trace(`variant: ${variant}`, st => {
+                    try {
+                        // Order: include (allow) → skip (deny). Match is now on
+                        // `(refName, variant)`. An empty variant array on a
+                        // refName means "every variant of this refName"; a
+                        // populated array names the variants the entry applies
+                        // to.
+                        if (include !== undefined &&
+                            !matchesRefFilter({ refs: include, refName, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        if (matchesRefFilter({ refs: skip, refName, variant })) {
+                            this.captureCurrentResult('skipped', st);
+                            return;
+                        }
+                        generatorConfig.transform({
+                            context: this,
+                            refName,
+                            variant
+                        });
+                        const source = toModelSource({
+                            refName,
+                            generatorId: generatorConfig.id,
+                            variant
+                        });
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addPreview).call(this, source, generatorConfig.toPreviewModule?.({ context: this, refName, variant }));
+                        __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addMapping).call(this, source, generatorConfig.toMappingModule?.({ context: this, refName, variant }));
+                        this.captureCurrentResult('success', st);
+                    }
+                    catch (error) {
+                        this.logger.error(error);
+                        this.captureCurrentResult('error', st);
+                    }
+                });
+            });
+        });
+    });
 }, _GenerateContext_addPreview = function _GenerateContext_addPreview(source, module) {
     if (!module) {
         return;
     }
-    if (!__classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.group]) {
-        __classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.group] = {};
-    }
-    if (__classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.group][module.name]) {
-        throw new Error(`Cannot override preview module "${module.name}" in group "${module.group}"`);
+    if (__classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.name]) {
+        throw new Error(`Cannot override preview module "${module.name}"`);
     }
-    __classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.group][module.name] = {
+    __classPrivateFieldGet(this, _GenerateContext_previews, "f")[module.name] = {
         module,
         source
     };
@@ -458,97 +986,198 @@ _GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(
     if (!module) {
         return;
     }
-    if (!__classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.group]) {
-        __classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.group] = {};
+    if (__classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.name]) {
+        throw new Error(`Cannot override mapping module "${module.name}"`);
     }
-    if (__classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.group][module.name]) {
-        throw new Error(`Cannot override mapping module "${module.name}" in group "${module.group}"`);
-    }
-    __classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.group][module.name] = {
+    __classPrivateFieldGet(this, _GenerateContext_mappings, "f")[module.name] = {
         module,
         source
     };
-}, _GenerateContext_getFile = function _GenerateContext_getFile(filePath, { throwIfNotFound = false } = {}) {
-    const normalisedPath = normalize(filePath);
-    const currentFile = __classPrivateFieldGet(this, _GenerateContext_files, "f").get(normalisedPath);
-    if (!currentFile) {
-        if (throwIfNotFound) {
-            throw new Error(`File not found: '${normalisedPath}'`);
-        }
-        else {
-            return __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_addFile).call(this, normalisedPath);
-        }
+};
+/**
+ * Match a `(path, method, variant)` tuple against an operation-shaped
+ * skip or include entry. Shared by both arms because skip and include
+ * have the same matching rules; only the engine's interpretation of
+ * the result differs (skip = deny, include = allow).
+ *
+ * Returns `false` when:
+ * - `paths` is `undefined` (no filter applies)
+ * - the `path` isn't keyed in the entry
+ * - the `method` isn't present in the inner record
+ *
+ * Returns `true` when:
+ * - the method's variant array is empty (matches every variant)
+ * - the method's variant array contains `variant`
+ */
+const matchesPathFilter = ({ paths, path, method, variant }) => {
+    if (!paths) {
+        return false;
     }
-    return currentFile;
-}, _GenerateContext_defineAndRegister = function _GenerateContext_defineAndRegister({ identifier, value, destinationPath, noExport }) {
-    const definition = new Definition({
-        context: this,
-        identifier,
-        value,
-        noExport
-    });
-    this.register({
-        definitions: [definition],
-        destinationPath
-    });
-    return definition;
-}, _GenerateContext_addFile = function _GenerateContext_addFile(normalisedPath) {
-    if (__classPrivateFieldGet(this, _GenerateContext_files, "f").has(normalisedPath)) {
-        throw new Error(`File already exists: ${normalisedPath}`);
-    }
-    const extension = normalisedPath.split('.').pop();
-    let newFile;
-    switch (extension) {
-        case 'json':
-            newFile = new JsonFile({ path: normalisedPath, content: {} });
-            break;
-        default:
-            newFile = new File({ path: normalisedPath, settings: this.settings });
-            break;
-    }
-    __classPrivateFieldGet(this, _GenerateContext_files, "f").set(normalisedPath, newFile);
-    return newFile;
+    const methodMap = paths[path];
+    if (!methodMap) {
+        return false;
+    }
+    const variants = methodMap[method];
+    if (variants === undefined) {
+        return false;
+    }
+    if (variants.length === 0) {
+        return true;
+    }
+    return variants.includes(variant);
 };
 /**
- * Creates an OperationSource from an operation and generator ID.
+ * Match a `(refName, variant)` tuple against a model-shaped skip or
+ * include entry. Sibling to {@link matchesPathFilter} — both arms
+ * share matching rules; only the engine's interpretation of the
+ * result differs (skip = deny, include = allow).
+ *
+ * Returns `false` when:
+ * - `refs` is `undefined` (no filter applies)
+ * - the `refName` isn't keyed in the entry
+ *
+ * Returns `true` when:
+ * - the refName's variant array is empty (matches every variant)
+ * - the refName's variant array contains `variant`
+ */
+const matchesRefFilter = ({ refs, refName, variant }) => {
+    if (!refs) {
+        return false;
+    }
+    const variants = refs[refName];
+    if (variants === undefined) {
+        return false;
+    }
+    if (variants.length === 0) {
+        return true;
+    }
+    return variants.includes(variant);
+};
+/**
+ * Creates an OasOperationSource from an operation, generator ID, and variant.
  *
  * Transforms operation and generator information into a source descriptor
  * that can be used for tracking operation origins in the generation pipeline.
  *
- * @param args - Arguments containing operation and generator ID
- * @returns OperationSource descriptor for the operation
+ * @param args - Arguments containing operation, generator ID, and variant
+ * @returns OasOperationSource descriptor for the operation
  */
-export const toOperationSource = ({ operation, generatorId }) => ({
-    type: 'operation',
+export const toOasOperationSource = ({ operation, generatorId, variant }) => ({
+    type: 'oasOperation',
     generatorId,
     operationPath: operation.path,
-    operationMethod: operation.method
+    operationMethod: operation.method,
+    variant
+});
+/**
+ * Creates a {@link WebhookSource} from a webhook, generator ID, and variant.
+ * Sibling of {@link toOasOperationSource} for the 3.1 webhook subject.
+ */
+export const toWebhookSource = ({ webhook, generatorId, variant }) => ({
+    type: 'webhook',
+    generatorId,
+    webhookName: webhook.name,
+    webhookMethod: webhook.method,
+    variant
 });
 /**
- * Creates a ModelSource from a reference name and generator ID.
+ * Creates a GraphQL operation source descriptor.
+ *
+ * Sibling to {@link toOasOperationSource} for the GraphQL protocol — encodes
+ * `rootKind` and `fieldName` instead of `path` / `method`.
+ */
+export const toGqlOperationSource = ({ operation, generatorId, variant }) => ({
+    type: 'gqlOperation',
+    generatorId,
+    rootKind: operation.rootKind,
+    fieldName: operation.fieldName,
+    variant
+});
+/**
+ * Creates a ModelSource from a reference name, generator ID, and variant.
  *
  * Transforms model reference and generator information into a source descriptor
  * that can be used for tracking model origins in the generation pipeline.
  *
- * @param args - Arguments containing reference name and generator ID
+ * @param args - Arguments containing reference name, generator ID, and variant
  * @returns ModelSource descriptor for the model
  */
-export const toModelSource = ({ refName, generatorId }) => ({
+export const toModelSource = ({ refName, generatorId, variant }) => ({
     type: 'model',
     generatorId,
-    refName
+    refName,
+    variant
 });
 const toSkipPaths = (skip, generatorId) => {
     const generatorSkip = skip?.[generatorId];
-    if (typeof generatorSkip === 'object' && !Array.isArray(generatorSkip)) {
-        return generatorSkip;
+    // Operation-shaped entries have records-of-records at the inner
+    // slot (`Record<path, Record<method, variant[]>>`); model-shaped
+    // entries have records-of-arrays (`Record<refName, variant[]>`).
+    // Discriminate by inner value shape. An empty record is ambiguous
+    // and admitted by both helpers — each arm will see its own empty
+    // filter (`{}`), which means "match nothing" in both cases.
+    if (typeof generatorSkip === 'object' &&
+        generatorSkip !== null &&
+        !Array.isArray(generatorSkip)) {
+        const values = Object.values(generatorSkip);
+        if (values.length === 0 ||
+            values.every(v => typeof v === 'object' && v !== null && !Array.isArray(v))) {
+            return generatorSkip;
+        }
     }
     return undefined;
 };
 const toSkipModels = (skip, generatorId) => {
     const generatorSkip = skip?.[generatorId];
-    if (Array.isArray(generatorSkip)) {
-        return generatorSkip;
+    // SkipModelRefs is `Record<refName, variant[]>`. The operation arm
+    // entries are `Record<path, Record<method, variant[]>>` — discriminate
+    // by inner value shape (arrays vs nested records). An empty record is
+    // ambiguous and admitted by both helpers — see `toSkipPaths`.
+    if (typeof generatorSkip === 'object' &&
+        generatorSkip !== null &&
+        !Array.isArray(generatorSkip)) {
+        const values = Object.values(generatorSkip);
+        if (values.length === 0 || values.every(v => Array.isArray(v))) {
+            return generatorSkip;
+        }
+    }
+    return undefined;
+};
+/**
+ * Extracts the per-operation include slice for a generator, mirroring
+ * {@link toSkipPaths}. Returns `undefined` when the include entry
+ * isn't operation-shaped for this generator (e.g. the user passed a
+ * model-shaped array or no entry at all) — the caller then treats
+ * "no per-op filter active" as the semantics.
+ */
+const toIncludePaths = (include, generatorId) => {
+    const generatorInclude = include?.[generatorId];
+    // Same model/operation discrimination as `toSkipPaths`.
+    if (typeof generatorInclude === 'object' &&
+        generatorInclude !== null &&
+        !Array.isArray(generatorInclude)) {
+        const values = Object.values(generatorInclude);
+        if (values.length === 0 ||
+            values.every(v => typeof v === 'object' && v !== null && !Array.isArray(v))) {
+            return generatorInclude;
+        }
+    }
+    return undefined;
+};
+/**
+ * Extracts the per-model include slice for a generator, mirroring
+ * {@link toSkipModels}. Returns `undefined` when the include entry
+ * isn't model-shaped for this generator.
+ */
+const toIncludeModels = (include, generatorId) => {
+    const generatorInclude = include?.[generatorId];
+    if (typeof generatorInclude === 'object' &&
+        generatorInclude !== null &&
+        !Array.isArray(generatorInclude)) {
+        const values = Object.values(generatorInclude);
+        if (values.length === 0 || values.every(v => Array.isArray(v))) {
+            return generatorInclude;
+        }
     }
     return undefined;
 };