@skmtc/core 0.28.5 → 0.28.7

package/esm/dsl/model/toModelProjectionBase.js

@@ -1,3 +1,5 @@
+import { readProjectionOptions } from '../../types/ProjectionOptions.js';
+import { toPeerInsertOptions } from '../../types/InsertOptions.js';
 import { toModelGeneratorKey } from '../GeneratorKeys.js';
 import { DEFAULT_VARIANT } from '../../types/Variant.js';
 import { parseEnrichmentUmbrella } from '../../enrichments/parseEnrichmentUmbrella.js';
@@ -44,34 +46,39 @@ export const toModelProjectionBase = (base, config) => {
                     writable: true,
                     value: void 0
                 });
+                /** The caller's options. */
+                Object.defineProperty(this, "options", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
                 this.refName = args.refName;
                 this.settings = args.settings;
+                this.options = readProjectionOptions(args);
             }
             /**
              * Insert a related model and return its `Inserted` reference. The
              * inserted model is exported to this projection's own `exportPath`
-             * unless `noExport` is set.
+             * unless `noExport` is set. `{ options }` is required when the peer
+             * declares options and refused when it does not.
              */
-            insertModel(projection, refName, options = {}) {
+            insertModel(projection, refName, ...rest) {
                 return this.context.insertModel(projection, refName, {
-                    destinationPath: this.settings.exportPath,
-                    noExport: options.noExport,
-                    variant: options.variant
+                    ...toPeerInsertOptions(rest),
+                    destinationPath: this.settings.exportPath
                 });
             }
             /**
              * Insert a related model with reference normalization. If `schema` is a
              * `$ref`, the referenced name is used; otherwise `fallbackName` applies.
              */
-            insertNormalizedModel(projection, { schema, fallbackName }, options = {}) {
+            insertNormalizedModel(projection, { schema, fallbackName }, ...rest) {
                 return this.context.insertNormalizedModel(projection, {
                     schema,
                     fallbackName,
                     destinationPath: this.settings.exportPath
-                }, {
-                    noExport: options.noExport,
-                    variant: options.variant
-                });
+                }, ...rest);
             }
         },
         Object.defineProperty(_a, "id", {

package/esm/dsl/model/types.d.ts

@@ -6,6 +6,7 @@ import type { IdentifierType } from '../IdentifierType.js';
 import type { IdentifierBase } from '../IdentifierBase.js';
 import type { GeneratedValue } from '../GeneratedValue.js';
 import type { SchemaToValueFn } from '../../types/TypeSystem.js';
+import type { ProjectionOptionsArg } from '../../types/ProjectionOptions.js';
 /**
  * External constructor signature for a model projection class.
  *
@@ -13,13 +14,13 @@ import type { SchemaToValueFn } from '../../types/TypeSystem.js';
  * runtime base class ({@link ModelProjectionBase}) injects `generatorKey`
  * before calling `super()`.
  */
-export type ModelProjectionConstructorArgs<EnrichmentType = undefined> = {
+export type ModelProjectionConstructorArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     context: GenerateContextType;
     refName: RefName;
     settings: ContentSettings<EnrichmentType>;
     destinationPath: string;
     rootRef?: RefName;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 export type WithTransformModel = {
     transformModel: (refName: RefName) => void;
 };
@@ -67,33 +68,34 @@ export type ToModelMappingArgs = {
     variant: string;
 };
 /**
- * Arguments for a model projection's `toIdentifierName` — the pure,
- * cache-key-source half of the old `toIdentifier`.
+ * Arguments for a model projection's `toIdentifierName`. Fold `options` into the name when the output
+ * depends on them: definitions are cached by name and export path.
  */
-export type ToModelIdentifierNameArgs<EnrichmentType = undefined> = {
+export type ToModelIdentifierNameArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     refName: RefName;
     enrichments: EnrichmentType;
     /** Model variant the identifier should disambiguate (see {@link Variant}) */
     variant: string;
-};
-export type ToModelExportPathArgs<EnrichmentType = undefined> = {
+} & ProjectionOptionsArg<ProjectionOptions>;
+export type ToModelExportPathArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     refName: RefName;
     enrichments: EnrichmentType;
     /** Model variant the export path should disambiguate (see {@link Variant}) */
     variant: string;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 /**
  * Static structural type of a model projection class.
  *
  * Captures both the instance side (`new(...) => V`) and the static side
  * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
  * `toEnrichments`, `schemaToValueFn`). Passed as a type parameter to
- * `context.insertModel(...)`.
+ * `context.insertModel(...)`. `ProjectionOptions` is the caller options the
+ * class declares; the Drivers infer it from the constructor and statics.
  */
-export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = {
     prototype: V;
 } & {
-    new ({ context, refName, settings, destinationPath, rootRef }: ModelProjectionConstructorArgs<EnrichmentType>): V;
+    new ({ context, refName, settings, destinationPath, rootRef, options }: ModelProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): V;
     id: string;
     type: 'model';
     /**
@@ -104,7 +106,7 @@ export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined
      */
     lang: Lang;
     /** Pure: the cache-key name. */
-    toIdentifierName: (args: ToModelIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToModelIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Context-aware, overridable: the non-`name` parts of the identifier
      * (`type` / `typeName` / `exported`), derived from the schema. The engine
@@ -112,7 +114,7 @@ export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined
      * ...toIdentifierType(refName, context) })`.
      */
     toIdentifierType: (refName: RefName, context: GenerateContextType) => IdentifierType;
-    toExportPath: (args: ToModelExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToModelExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     toEnrichments: ({ refName, context, variant }: ToModelEnrichmentsArgs) => EnrichmentType;
     /**
      * Family-level capability predicate, surfaced as a static by
@@ -130,7 +132,7 @@ export type ModelProjection<V extends GeneratedValue, EnrichmentType = undefined
  * takes the plain {@link ModelProjection}, so a generator that never
  * inserts inline schemas declares neither.
  */
-export type NormalizedModelProjection<V extends GeneratedValue, EnrichmentType = undefined> = ModelProjection<V, EnrichmentType> & {
+export type NormalizedModelProjection<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = ModelProjection<V, EnrichmentType, ProjectionOptions> & {
     /** Builds the inline schema's value (the Definition body). */
     schemaToValueFn: SchemaToValueFn;
     /**
@@ -140,4 +142,3 @@ export type NormalizedModelProjection<V extends GeneratedValue, EnrichmentType =
      */
     createIdentifier: (name: string) => IdentifierBase;
 };
-//# sourceMappingURL=types.d.ts.map

package/esm/dsl/operation/gql/GqlOperationDriver.d.ts

@@ -3,22 +3,14 @@ import type { GqlOperation } from '../../../gql/operation/GqlOperation.js';
 import type { ContentSettings } from '../../ContentSettings.js';
 import type { GeneratedDefinition } from '../../GeneratedValue.js';
 import type { GeneratedValue } from '../../GeneratedValue.js';
-import type { GenerateContextType } from '../../../context/generateTypes.js';
-type CreateGqlOperationArgs<V extends GeneratedValue, EnrichmentType = undefined> = {
+import type { GenerateContextType, InsertGqlOperationArgs } from '../../../context/generateTypes.js';
+/**
+ * The `insertOperation` call plus the context. The Driver defaults
+ * `variant` to `'main'` and `noExport` to `false`, and reads the caller's
+ * options once for the identity statics and the constructor.
+ */
+type CreateGqlOperationArgs<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = InsertGqlOperationArgs<V, EnrichmentType, ProjectionOptions> & {
     context: GenerateContextType;
-    projection: GqlOperationProjection<V, EnrichmentType>;
-    operation: GqlOperation;
-    destinationPath?: string;
-    noExport?: boolean;
-    /**
-     * Target variant of the projection. The Driver resolves the
-     * peer's enrichment for this variant, asserts the variant exists
-     * (or is the default `'main'` which is always permitted), and
-     * threads it into the projection's `ContentSettings`.
-     * Optional — omitting it means `'main'`, so variants-unaware
-     * callers keep working unchanged.
-     */
-    variant?: string;
 };
 /**
  * Driver for the GraphQL operation insertion lifecycle.
@@ -29,16 +21,18 @@ type CreateGqlOperationArgs<V extends GeneratedValue, EnrichmentType = undefined
  * cache hit exists, registers the new definition, and stitches an import
  * into `destinationPath` if it differs from the projection's `exportPath`.
  */
-export declare class GqlOperationDriver<V extends GeneratedValue, EnrichmentType = undefined> {
+export declare class GqlOperationDriver<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> {
     context: GenerateContextType;
-    projection: GqlOperationProjection<V, EnrichmentType>;
+    projection: GqlOperationProjection<V, EnrichmentType, ProjectionOptions>;
     operation: GqlOperation;
     settings: ContentSettings<EnrichmentType>;
     destinationPath?: string;
     definition: GeneratedDefinition<V>;
-    noExport?: boolean;
+    noExport: boolean;
     variant: string;
-    constructor({ context, projection, operation, destinationPath, noExport, variant }: CreateGqlOperationArgs<V, EnrichmentType>);
+    /** The caller's options, as passed to `insertOperation`. */
+    options: ProjectionOptions;
+    constructor(args: CreateGqlOperationArgs<V, EnrichmentType, ProjectionOptions>);
     private apply;
     /**
      * Ensure the file at `path` exists, creating it on first write through
@@ -51,4 +45,3 @@ export declare class GqlOperationDriver<V extends GeneratedValue, EnrichmentType
     private affirmDefinition;
 }
 export {};
-//# sourceMappingURL=GqlOperationDriver.d.ts.map

package/esm/dsl/operation/gql/GqlOperationDriver.js

@@ -1,6 +1,8 @@
 import { normalize } from '../../../deps/jsr.io/@std/path/1.1.6/normalize.js';
 import { toGqlOperationGeneratorKey } from '../../GeneratorKeys.js';
 import { DEFAULT_VARIANT } from '../../../types/Variant.js';
+import { readProjectionOptions, toValueOptions } from '../../../types/ProjectionOptions.js';
+import isEqual from 'lodash-es/isEqual.js';
 /**
  * Driver for the GraphQL operation insertion lifecycle.
  *
@@ -11,7 +13,7 @@ import { DEFAULT_VARIANT } from '../../../types/Variant.js';
  * into `destinationPath` if it differs from the projection's `exportPath`.
  */
 export class GqlOperationDriver {
-    constructor({ context, projection, operation, destinationPath, noExport, variant = DEFAULT_VARIANT }) {
+    constructor(args) {
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
@@ -60,12 +62,21 @@ export class GqlOperationDriver {
             writable: true,
             value: void 0
         });
+        /** The caller's options, as passed to `insertOperation`. */
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const { context, projection, operation, destinationPath, noExport = false, variant = DEFAULT_VARIANT } = args;
         this.context = context;
         this.projection = projection;
         this.operation = operation;
         this.destinationPath = destinationPath;
         this.noExport = noExport;
         this.variant = variant;
+        this.options = readProjectionOptions(args);
         assertPeerVariantExists({
             context,
             generatorId: projection.id,
@@ -76,7 +87,8 @@ export class GqlOperationDriver {
         this.settings = this.context.toOperationContentSettings({
             operation,
             projection,
-            variant
+            variant,
+            options: this.options
         });
         this.definition = this.apply({ destinationPath });
     }
@@ -122,7 +134,8 @@ export class GqlOperationDriver {
         const value = new this.projection({
             context: this.context,
             operation: this.operation,
-            settings: this.settings
+            settings: this.settings,
+            options: this.options
         });
         const definition = this.projection.lang.toDefinition({
             context: this.context,
@@ -149,7 +162,16 @@ export class GqlOperationDriver {
         if (currentKey !== definition.generatorKey) {
             throw new Error(`Registered definition mismatch: '${definition.identifier.name}' in file '${exportPath}'. Cached key '${definition.generatorKey}' does not match new key '${currentKey}'`);
         }
-        return definition.value instanceof this.projection;
+        if (!(definition.value instanceof this.projection)) {
+            return false;
+        }
+        // Options are identity, like the variant, but cannot ride the key: a hit
+        // is checked against the options its value was built with.
+        const cachedOptions = toValueOptions(definition.value);
+        if (!isEqual(cachedOptions, this.options)) {
+            throw new Error(`Registered definition mismatch: '${definition.identifier.name}' in file '${exportPath}'. Cached options ${JSON.stringify(cachedOptions)} do not match new options ${JSON.stringify(this.options)}. Fold options into toIdentifierName.`);
+        }
+        return true;
     }
 }
 /**

package/esm/dsl/operation/gql/toGqlOperationEntry.d.ts

@@ -46,4 +46,3 @@ export type GqlOperationEntry<EnrichmentType = undefined> = {
  * @returns Configured operation generator entry ready for pipeline integration
  */
 export declare const toGqlOperationEntry: <EnrichmentType = undefined>({ id, transform, toEnrichmentSchema, isSupported, supportsVariant, toPreviewModule, toEnrichmentRequest }: ToGqlOperationConfigArgs<EnrichmentType>) => GqlOperationEntry<EnrichmentType>;
-//# sourceMappingURL=toGqlOperationEntry.d.ts.map

package/esm/dsl/operation/gql/toGqlOperationProjectionBase.d.ts

@@ -1,5 +1,7 @@
 import type { GenerateContextType } from '../../../context/generateTypes.js';
-import type { InsertOperationOptions, InsertModelOptions, InsertNormalizedModelArgs, InsertNormalizedModelReturn } from '../../../context/generateTypes.js';
+import type { InsertNormalizedModelArgs, InsertNormalizedModelOptions, InsertNormalizedModelReturn } from '../../../context/generateTypes.js';
+import { type ProjectionOptionsRest } from '../../../types/ProjectionOptions.js';
+import { type PeerInsertOptions } from '../../../types/InsertOptions.js';
 import type { GqlOperation } from '../../../gql/operation/GqlOperation.js';
 import type { ContentSettings } from '../../ContentSettings.js';
 import type { LangSnippetConstructor } from '../../Lang.js';
@@ -21,10 +23,10 @@ import type * as v from 'valibot';
  * `toIdentifierType`'s return tightens to that language's `type` vocabulary —
  * no recast.
  */
-export type GqlOperationProjectionBaseConfig<EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType> = {
+export type GqlOperationProjectionBaseConfig<EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType, ProjectionOptions = undefined> = {
     id: string;
     /** Pure: the cache-key name (the cache-check path runs this). */
-    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Context-aware, overridable: the non-`name` parts of the identifier,
      * derived from the operation/schema. Runs only on cache-miss. Returns this
@@ -32,7 +34,7 @@ export type GqlOperationProjectionBaseConfig<EnrichmentType = undefined, IdType
      * default); the tightening rides the type argument.
      */
     toIdentifierType: (operation: GqlOperation, context: GenerateContextType) => IdType;
-    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Required composite schema for the `{ subject, generator, stack }`
      * enrichment umbrella. Required (not optional) is load-bearing: it is what
@@ -78,36 +80,38 @@ type ToEnrichmentsArgs = {
  * `GqlOperationProjectionBase` lives here now, because the base class is no
  * longer statically known.
  */
-export declare const toGqlOperationProjectionBase: <EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType>(base: LangSnippetConstructor, config: GqlOperationProjectionBaseConfig<EnrichmentType, IdType>) => {
-    new (args: GqlOperationProjectionConstructorArgs<EnrichmentType>): {
+export declare const toGqlOperationProjectionBase: <EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType, ProjectionOptions = undefined>(base: LangSnippetConstructor, config: GqlOperationProjectionBaseConfig<EnrichmentType, IdType, ProjectionOptions>) => {
+    new (args: GqlOperationProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): {
         settings: ContentSettings<EnrichmentType>;
         operation: GqlOperation;
+        /** The caller's options. */
+        options: ProjectionOptions;
         /**
          * Insert a related operation. The inserted operation is exported to this
          * projection's own `exportPath` unless `noExport` is set.
          *
-         * Pass `{ variant }` to target a specific variant on the peer (e.g.
-         * to thread `this.settings.variant` into a within-package sibling
-         * Projection that's also variants-aware). Omitting it defaults to
-         * the peer's `'main'` variant — the safe choice for variants-unaware
-         * peers and the standard pattern for cross-package composition.
+         * Pass `{ variant }` to target a specific variant on the peer; omitting
+         * it defaults to the peer's `'main'` variant. `{ options }` is required
+         * when the peer declares options and refused when it does not.
          */
-        insertOperation<V extends GeneratedValue, PeerEnrichmentType = undefined>(projection: GqlOperationProjection<V, PeerEnrichmentType>, operation: GqlOperation, options?: Pick<InsertOperationOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType>;
+        insertOperation<V extends GeneratedValue, PeerEnrichmentType = undefined, PeerProjectionOptions = undefined>(projection: GqlOperationProjection<V, PeerEnrichmentType, PeerProjectionOptions>, operation: GqlOperation, ...rest: ProjectionOptionsRest<PeerInsertOptions<PeerProjectionOptions>, PeerProjectionOptions>): Inserted<V, PeerEnrichmentType>;
         /**
          * Insert a related model into this projection's export file.
          *
          * Pass `{ variant }` to target a specific variant on the peer model
-         * projection. Omitting it defaults to the peer's `'main'` variant.
+         * projection; omitting it defaults to the peer's `'main'` variant.
+         * `{ options }` is required when the peer declares options and refused
+         * when it does not.
          */
-        insertModel<V extends GeneratedValue, PeerEnrichmentType_1 = undefined>(projection: ModelProjection<V, PeerEnrichmentType_1>, refName: RefName, options?: Pick<InsertModelOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType_1>;
+        insertModel<V extends GeneratedValue, PeerEnrichmentType_1 = undefined, PeerProjectionOptions_1 = undefined>(projection: ModelProjection<V, PeerEnrichmentType_1, PeerProjectionOptions_1>, refName: RefName, ...rest: ProjectionOptionsRest<PeerInsertOptions<PeerProjectionOptions_1>, PeerProjectionOptions_1>): Inserted<V, PeerEnrichmentType_1>;
         /**
          * Insert a related model with reference normalization. Useful for
          * schemas that may be either a `$ref` or a concrete object.
          *
-         * `{ variant }` flows through the `$ref` branch only; for inline
-         * schemas, bake the variant into `fallbackName`.
+         * `{ variant }` and `{ options }` flow through the `$ref` branch only;
+         * for inline schemas, bake what distinguishes them into `fallbackName`.
          */
-        insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<"schema"> | OasVoid, PeerEnrichmentType_2 = undefined>(projection: NormalizedModelProjection<V, PeerEnrichmentType_2>, { schema, fallbackName }: Omit<InsertNormalizedModelArgs<Schema>, "destinationPath">, options?: Pick<InsertModelOptions, "noExport" | "variant">): InsertNormalizedModelReturn<V, Schema>;
+        insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<"schema"> | OasVoid, PeerEnrichmentType_2 = undefined, PeerProjectionOptions_2 = undefined>(projection: NormalizedModelProjection<V, PeerEnrichmentType_2, PeerProjectionOptions_2>, { schema, fallbackName }: Omit<InsertNormalizedModelArgs<Schema>, "destinationPath">, ...rest: ProjectionOptionsRest<InsertNormalizedModelOptions<PeerProjectionOptions_2>, PeerProjectionOptions_2>): InsertNormalizedModelReturn<V, Schema>;
         context: GenerateContextType;
         skipped: boolean;
         generatorKey: import("../../GeneratorKeys.js").GeneratorKey | undefined;
@@ -115,9 +119,9 @@ export declare const toGqlOperationProjectionBase: <EnrichmentType = undefined,
     };
     id: string;
     type: "gqlOperation";
-    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     toIdentifierType: (operation: GqlOperation, context: GenerateContextType) => IdType;
-    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     isSupported: (args: {
         operation: GqlOperation;
         context: GenerateContextType;
@@ -126,4 +130,3 @@ export declare const toGqlOperationProjectionBase: <EnrichmentType = undefined,
     lang: import("../../Lang.js").Lang;
 };
 export {};
-//# sourceMappingURL=toGqlOperationProjectionBase.d.ts.map

package/esm/dsl/operation/gql/toGqlOperationProjectionBase.js

@@ -1,3 +1,5 @@
+import { readProjectionOptions } from '../../../types/ProjectionOptions.js';
+import { toPeerInsertOptions } from '../../../types/InsertOptions.js';
 import { toGqlOperationGeneratorKey } from '../../GeneratorKeys.js';
 import { DEFAULT_VARIANT } from '../../../types/Variant.js';
 import { parseEnrichmentUmbrella } from '../../../enrichments/parseEnrichmentUmbrella.js';
@@ -46,57 +48,60 @@ export const toGqlOperationProjectionBase = (base, config) => {
                     writable: true,
                     value: void 0
                 });
+                /** The caller's options. */
+                Object.defineProperty(this, "options", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
                 this.operation = args.operation;
                 this.settings = args.settings;
+                this.options = readProjectionOptions(args);
             }
             /**
              * Insert a related operation. The inserted operation is exported to this
              * projection's own `exportPath` unless `noExport` is set.
              *
-             * Pass `{ variant }` to target a specific variant on the peer (e.g.
-             * to thread `this.settings.variant` into a within-package sibling
-             * Projection that's also variants-aware). Omitting it defaults to
-             * the peer's `'main'` variant — the safe choice for variants-unaware
-             * peers and the standard pattern for cross-package composition.
+             * Pass `{ variant }` to target a specific variant on the peer; omitting
+             * it defaults to the peer's `'main'` variant. `{ options }` is required
+             * when the peer declares options and refused when it does not.
              */
-            insertOperation(projection, operation, options = {}) {
+            insertOperation(projection, operation, ...rest) {
                 return this.context.insertOperation({
                     projection,
                     operation,
                     destinationPath: this.settings.exportPath,
-                    noExport: options.noExport,
-                    variant: options.variant
+                    ...toPeerInsertOptions(rest)
                 });
             }
             /**
              * Insert a related model into this projection's export file.
              *
              * Pass `{ variant }` to target a specific variant on the peer model
-             * projection. Omitting it defaults to the peer's `'main'` variant.
+             * projection; omitting it defaults to the peer's `'main'` variant.
+             * `{ options }` is required when the peer declares options and refused
+             * when it does not.
              */
-            insertModel(projection, refName, options = {}) {
+            insertModel(projection, refName, ...rest) {
                 return this.context.insertModel(projection, refName, {
-                    destinationPath: this.settings.exportPath,
-                    noExport: options.noExport,
-                    variant: options.variant
+                    ...toPeerInsertOptions(rest),
+                    destinationPath: this.settings.exportPath
                 });
             }
             /**
              * Insert a related model with reference normalization. Useful for
              * schemas that may be either a `$ref` or a concrete object.
              *
-             * `{ variant }` flows through the `$ref` branch only; for inline
-             * schemas, bake the variant into `fallbackName`.
+             * `{ variant }` and `{ options }` flow through the `$ref` branch only;
+             * for inline schemas, bake what distinguishes them into `fallbackName`.
              */
-            insertNormalizedModel(projection, { schema, fallbackName }, options = {}) {
+            insertNormalizedModel(projection, { schema, fallbackName }, ...rest) {
                 return this.context.insertNormalizedModel(projection, {
                     schema,
                     fallbackName,
                     destinationPath: this.settings.exportPath
-                }, {
-                    noExport: options.noExport,
-                    variant: options.variant
-                });
+                }, ...rest);
             }
         },
         Object.defineProperty(_a, "id", {

package/esm/dsl/operation/gql/types.d.ts

@@ -4,17 +4,18 @@ import type { ContentSettings } from '../../ContentSettings.js';
 import type { GenerateContextType } from '../../../context/generateTypes.js';
 import type { IdentifierType } from '../../IdentifierType.js';
 import type { GeneratedValue } from '../../GeneratedValue.js';
+import type { ProjectionOptionsArg } from '../../../types/ProjectionOptions.js';
 /**
  * External constructor signature for a GraphQL operation projection class.
  *
  * The pipeline calls `new SomeProjection(args)` with this shape; the
  * runtime base class injects `generatorKey` before calling `super()`.
  */
-export type GqlOperationProjectionConstructorArgs<EnrichmentType = undefined> = {
+export type GqlOperationProjectionConstructorArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     context: GenerateContextType;
     settings: ContentSettings<EnrichmentType>;
     operation: GqlOperation;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 export type TransformGqlOperationArgs = {
     context: GenerateContextType;
     operation: GqlOperation;
@@ -54,33 +55,34 @@ export type ToGqlOperationMappingArgs = {
     variant: string;
 };
 /**
- * Arguments for a GraphQL operation projection's `toIdentifierName` — the
- * pure, cache-key-source half of the old `toIdentifier`.
+ * Arguments for a GraphQL operation projection's `toIdentifierName`. Fold `options` into the name when the output
+ * depends on them: definitions are cached by name and export path.
  */
-export type ToGqlOperationIdentifierNameArgs<EnrichmentType = undefined> = {
+export type ToGqlOperationIdentifierNameArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     operation: GqlOperation;
     enrichments: EnrichmentType;
     /** Operation variant the identifier should disambiguate (see {@link Variant}) */
     variant: string;
-};
-export type ToGqlOperationExportPathArgs<EnrichmentType = undefined> = {
+} & ProjectionOptionsArg<ProjectionOptions>;
+export type ToGqlOperationExportPathArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     operation: GqlOperation;
     enrichments: EnrichmentType;
     /** Operation variant the export path should disambiguate (see {@link Variant}) */
     variant: string;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 /**
  * Static structural type of a GraphQL operation projection class.
  *
  * Captures both the instance side (`new(...) => V`) and the static side
  * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
  * `toEnrichments`). Passed as a type parameter to
- * `context.insertOperation(...)`.
+ * `context.insertOperation(...)`. `ProjectionOptions` is the caller options
+ * the class declares; the Drivers infer it from the constructor and statics.
  */
-export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = {
     prototype: V;
 } & {
-    new ({ context, settings, operation }: GqlOperationProjectionConstructorArgs<EnrichmentType>): V;
+    new ({ context, settings, operation, options }: GqlOperationProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): V;
     id: string;
     type: 'gqlOperation';
     /**
@@ -91,7 +93,7 @@ export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = un
      */
     lang: Lang;
     /** Pure: the cache-key name. */
-    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Context-aware, overridable: the non-`name` parts of the identifier,
      * derived from the operation/schema. The engine assembles
@@ -99,7 +101,7 @@ export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = un
      * ...toIdentifierType(operation, context) })`.
      */
     toIdentifierType: (operation: GqlOperation, context: GenerateContextType) => IdentifierType;
-    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     toEnrichments: ({ operation, context }: ToGqlOperationEnrichmentsArgs) => EnrichmentType;
     /**
      * Family-level capability predicate, surfaced as a static by
@@ -111,4 +113,3 @@ export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = un
      */
     isSupported?: (args: IsSupportedGqlOperationArgs) => boolean;
 } & Function;
-//# sourceMappingURL=types.d.ts.map

package/esm/dsl/operation/oas/OasOperationDriver.d.ts

@@ -3,22 +3,14 @@ import type { OasOperation } from '../../../oas/operation/Operation.js';
 import type { ContentSettings } from '../../ContentSettings.js';
 import type { GeneratedDefinition } from '../../GeneratedValue.js';
 import type { GeneratedValue } from '../../GeneratedValue.js';
-import type { GenerateContextType } from '../../../context/generateTypes.js';
-type CreateOperationArgs<V extends GeneratedValue, EnrichmentType = undefined> = {
+import type { GenerateContextType, InsertOasOperationArgs } from '../../../context/generateTypes.js';
+/**
+ * The `insertOperation` call plus the context. The Driver defaults
+ * `variant` to `'main'` and `noExport` to `false`, and reads the caller's
+ * options once for the identity statics and the constructor.
+ */
+type CreateOperationArgs<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = InsertOasOperationArgs<V, EnrichmentType, ProjectionOptions> & {
     context: GenerateContextType;
-    projection: OasOperationProjection<V, EnrichmentType>;
-    operation: OasOperation;
-    destinationPath?: string;
-    noExport?: boolean;
-    /**
-     * Target variant of the projection. The Driver resolves the
-     * peer's enrichment for this variant, asserts the variant exists
-     * (or is the default `'main'` which is always permitted), and
-     * threads it into the projection's `ContentSettings`.
-     * Optional — omitting it means `'main'`, so variants-unaware
-     * callers keep working unchanged.
-     */
-    variant?: string;
 };
 /**
  * Driver for the OAS operation insertion lifecycle.
@@ -29,16 +21,19 @@ type CreateOperationArgs<V extends GeneratedValue, EnrichmentType = undefined> =
  * definition, and stitches an import into `destinationPath` if it differs
  * from the projection's `exportPath`.
  */
-export declare class OasOperationDriver<V extends GeneratedValue, EnrichmentType = undefined> {
+export declare class OasOperationDriver<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> {
+    #private;
     context: GenerateContextType;
-    projection: OasOperationProjection<V, EnrichmentType>;
+    projection: OasOperationProjection<V, EnrichmentType, ProjectionOptions>;
     operation: OasOperation;
     settings: ContentSettings<EnrichmentType>;
     destinationPath?: string;
     definition: GeneratedDefinition<V>;
-    noExport?: boolean;
+    noExport: boolean;
     variant: string;
-    constructor({ context, projection, operation, destinationPath, noExport, variant }: CreateOperationArgs<V, EnrichmentType>);
+    /** The caller's options, as passed to `insertOperation`. */
+    options: ProjectionOptions;
+    constructor(args: CreateOperationArgs<V, EnrichmentType, ProjectionOptions>);
     private apply;
     /**
      * Ensure the file at `path` exists, creating it on first write through
@@ -51,4 +46,3 @@ export declare class OasOperationDriver<V extends GeneratedValue, EnrichmentType
     private affirmDefinition;
 }
 export {};
-//# sourceMappingURL=OasOperationDriver.d.ts.map