@skmtc/core 0.28.5 → 0.28.7

package/script/dsl/operation/oas/OasOperationDriver.js

@@ -1,9 +1,27 @@
 "use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _OasOperationDriver_into;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasOperationDriver = void 0;
 const normalize_js_1 = require("../../../deps/jsr.io/@std/path/1.1.6/normalize.js");
+const tiny_invariant_1 = __importDefault(require("tiny-invariant"));
 const GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
 const Variant_js_1 = require("../../../types/Variant.js");
+const ProjectionOptions_js_1 = require("../../../types/ProjectionOptions.js");
+const isEqual_js_1 = __importDefault(require("lodash-es/isEqual.js"));
 /**
  * Driver for the OAS operation insertion lifecycle.
  *
@@ -14,7 +32,7 @@ const Variant_js_1 = require("../../../types/Variant.js");
  * from the projection's `exportPath`.
  */
 class OasOperationDriver {
-    constructor({ context, projection, operation, destinationPath, noExport, variant = Variant_js_1.DEFAULT_VARIANT }) {
+    constructor(args) {
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
@@ -63,12 +81,26 @@ class OasOperationDriver {
             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
+        });
+        /**
+         * The definition this projection's own definition goes inside, when it
+         * declared one — its name, which is how a place is addressed.
+         */
+        _OasOperationDriver_into.set(this, void 0);
+        const { context, projection, operation, destinationPath, noExport = false, variant = Variant_js_1.DEFAULT_VARIANT } = args;
         this.context = context;
         this.projection = projection;
         this.operation = operation;
         this.destinationPath = destinationPath;
         this.noExport = noExport;
         this.variant = variant;
+        this.options = (0, ProjectionOptions_js_1.readProjectionOptions)(args);
         assertPeerVariantExists({
             context,
             generatorId: projection.id,
@@ -76,27 +108,61 @@ class OasOperationDriver {
             variant
         });
         assertPeerSupported({ context, projection, operation, variant });
+        // A member's place is declared on the projection, like its name and its
+        // file are. The container is inserted the same way anything else is —
+        // its own run of this Driver, with its own identity, cache probe and
+        // integrity check — so nothing about placing a definition is written
+        // twice. Resolved before the member's settings, which take its file.
+        const container = projection.toContainer?.({
+            operation,
+            enrichments: projection.toEnrichments({ operation, context, variant }),
+            variant,
+            options: this.options
+        });
+        const insertedContainer = container
+            ? this.context.insertOperation({ projection: container, operation, variant })
+            : undefined;
+        __classPrivateFieldSet(this, _OasOperationDriver_into, insertedContainer?.settings.identifier.name, "f");
         this.settings = this.context.toOperationContentSettings({
             operation,
             projection,
-            variant
+            variant,
+            options: this.options,
+            // Same reason as the register/findDefinition spreads: a projection with
+            // no container is asked for its settings exactly as it always was.
+            ...(insertedContainer !== undefined
+                ? { exportPath: insertedContainer.settings.exportPath }
+                : {})
         });
         this.definition = this.apply({ destinationPath });
     }
     apply({ destinationPath } = {}) {
         const { identifier, exportPath } = this.settings;
+        // The file an import has to be stitched into, or `undefined` when there
+        // is none to stitch — no destination, or the projection's own file.
+        const importInto = destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)
+            ? destinationPath
+            : undefined;
+        // A member is declared inside its container, so it has no module-level
+        // name — an import of it would name a symbol its file never exports, and
+        // the `Inserted.toName()` handed back would be unresolvable. What a caller
+        // in another file wants is the container, which it can insert itself.
+        // Only the cross-file case is refused: a member inserted into the file its
+        // container already lives in stitches no import and needs no name.
+        (0, tiny_invariant_1.default)(!(__classPrivateFieldGet(this, _OasOperationDriver_into, "f") !== undefined && importInto !== undefined), `'${identifier.name}' is declared inside '${__classPrivateFieldGet(this, _OasOperationDriver_into, "f")}', so it cannot be ` +
+            `imported into '${destinationPath}'. Insert its container instead.`);
         const definition = this.getDefinition({ identifier, exportPath });
-        if (destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)) {
+        if (importInto !== undefined) {
             // Cross-file import of the peer's identifier from its export path.
             // The language builds the import object (`toImport`) and creates the
             // destination file on first write (caller-side); the engine stores
             // via the pure-data `context.register`. The import lands in the
             // caller's file (`destinationPath`); `insertOperation` only composes
             // same-language generators, so the peer's `lang` is the caller's.
-            this.ensureFile(destinationPath);
+            this.ensureFile(importInto);
             this.context.register({
                 imports: [this.projection.lang.toImport({ identifier, module: exportPath })],
-                destinationPath
+                destinationPath: importInto
             });
         }
         return definition;
@@ -115,9 +181,19 @@ class OasOperationDriver {
         return normalizedPath;
     }
     getDefinition({ identifier, exportPath }) {
+        // A member's place is its container, resolved (and created, on the first
+        // member) before the member itself — `register` stores, it never builds
+        // a declaration, exactly as it never builds a file.
+        // Presence, not truthiness: a container whose identifier name is empty
+        // would otherwise route the member to file level, silently landing it
+        // beside its container instead of inside it.
+        const into = __classPrivateFieldGet(this, _OasOperationDriver_into, "f");
+        // Spread rather than always-pass: a non-member's call shape is exactly
+        // what it was, so nothing downstream sees a key it never had.
         const cachedDefinition = this.context.findDefinition({
             name: identifier.name,
-            exportPath
+            exportPath,
+            ...(into !== undefined ? { into } : {})
         });
         if (this.affirmDefinition(cachedDefinition, exportPath)) {
             return cachedDefinition;
@@ -125,7 +201,8 @@ class OasOperationDriver {
         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,
@@ -136,7 +213,8 @@ class OasOperationDriver {
         this.ensureFile(exportPath);
         this.context.register({
             definitions: [definition],
-            destinationPath: exportPath
+            destinationPath: exportPath,
+            ...(into !== undefined ? { into } : {})
         });
         return definition;
     }
@@ -144,18 +222,32 @@ class OasOperationDriver {
         if (!definition) {
             return false;
         }
-        const currentKey = (0, GeneratorKeys_js_1.toOasOperationGeneratorKey)({
-            generatorId: this.projection.id,
-            operation: this.operation,
-            variant: this.settings.variant
-        });
+        // The projection knows how its own key is made — a subject's projection
+        // keys on its subject, a container on the group its members share. A
+        // hand-rolled projection that declares neither is keyed on its subject.
+        const currentKey = this.projection.toGeneratorKey?.({ operation: this.operation, settings: this.settings }) ??
+            (0, GeneratorKeys_js_1.toOasOperationGeneratorKey)({
+                generatorId: this.projection.id,
+                operation: this.operation,
+                variant: this.settings.variant
+            });
         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 = (0, ProjectionOptions_js_1.toValueOptions)(definition.value);
+        if (!(0, isEqual_js_1.default)(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;
     }
 }
 exports.OasOperationDriver = OasOperationDriver;
+_OasOperationDriver_into = new WeakMap();
 /**
  * Guard the peer-variant-mismatch invariant.
  *

package/script/dsl/operation/oas/toOasOperationContainerBase.d.ts

@@ -0,0 +1,131 @@
+import type * as v from 'valibot';
+import type { OasOperation } from '../../../oas/operation/Operation.js';
+import type { GenerateContextType } from '../../../context/generateTypes.js';
+import type { ContentSettings } from '../../ContentSettings.js';
+import type { DefinitionBase } from '../../Definition.js';
+import type { FindDefinitionsQuery } from '../../CodeFileBase.js';
+import type { IdentifierType } from '../../IdentifierType.js';
+import type { LangSnippetConstructor } from '../../Lang.js';
+import type { GeneratorKey } from '../../GeneratorKeys.js';
+import type { IsSupportedOasOperationArgs, ToGeneratorKeyArgs, ToOasOperationGroupNameArgs, ToOasOperationEnrichmentsArgs, ToOasOperationExportPathArgs, ToOasOperationIdentifierNameArgs } from './types.js';
+/**
+ * Configuration for {@link toOasOperationContainerBase}.
+ *
+ * The identity half is an operation projection's: `toIdentifierName` and
+ * `toExportPath` are pure functions of `(operation, enrichments, variant)`,
+ * resolved before construction so the cache probe stays cheap. What differs
+ * is that they are expected to be functions of the operation's GROUP — its
+ * tag, its file — so every operation in the group resolves to one
+ * declaration. Nothing enforces that; an identity that varies per operation
+ * simply yields one container per operation, visible in the output.
+ *
+ * Enrichments are read exactly as an operation projection's are, from the
+ * operation inserting into the container.
+ */
+export type OasOperationContainerBaseConfig<EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType> = {
+    id: string;
+    /**
+     * The group this container collects — the operation's tag, its module,
+     * whatever the generator gathers subjects by. Pure, and a function of the
+     * subject like its identity siblings, so every member of a group computes
+     * the same one.
+     *
+     * It is what the container's key is made of. Deriving the key from the
+     * group rather than from where the container lands keeps it saying what
+     * the definition is rather than where it sits, and keeps it stable when a
+     * generator changes its naming or file policy.
+     */
+    toGroupName: (args: ToOasOperationGroupNameArgs<EnrichmentType>) => string;
+    /** Pure: the cache-key name, a function of the operation's group. */
+    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<EnrichmentType>) => string;
+    /** Runs only on cache-miss. Returns this language's identifier type. */
+    toIdentifierType: (operation: OasOperation, context: GenerateContextType) => IdType;
+    /** Pure: the file the container is declared in. */
+    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType>) => string;
+    /** The generator's composite `{ subject, generator, stack }` schema. */
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
+    isSupported?: (args: IsSupportedOasOperationArgs) => boolean;
+};
+/**
+ * Arguments every container projection's constructor receives — the same
+ * shape an operation projection gets, from the operation that reached the
+ * container first.
+ */
+export type OasOperationContainerConstructorArgs<EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    operation: OasOperation;
+    settings: ContentSettings<EnrichmentType>;
+};
+/**
+ * Build a base class for a declaration that HOLDS definitions — a Kotlin
+ * interface body, a C# class body — rather than one that is a subject's
+ * artifact.
+ *
+ * Two things separate it from {@link import('./toOasOperationProjectionBase.ts').toOasOperationProjectionBase}:
+ *
+ * The value carries a {@link toContainerGeneratorKey} rather than the
+ * operation's own. A subject-derived key is what makes many operations
+ * resolving to one definition fail the integrity check on the second of
+ * them; an identity-derived one is computed identically by every member,
+ * while still carrying the `generatorId` that stops another generator
+ * claiming the declaration.
+ *
+ * And it implements the member store, so the engine can insert into it —
+ * which is also what makes the class assignable where a container is asked
+ * for, with nothing to declare. The subclass renders those members; where
+ * they sit in the declaration, and at what indentation, is the language's
+ * business, not the engine's.
+ */
+export declare const toOasOperationContainerBase: <EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType>(base: LangSnippetConstructor, config: OasOperationContainerBaseConfig<EnrichmentType, IdType>) => {
+    new (args: OasOperationContainerConstructorArgs<EnrichmentType>): {
+        settings: ContentSettings<EnrichmentType>;
+        operation: OasOperation;
+        /**
+         * The members inserted into this declaration, in arrival order — which
+         * is the engine's sweep order, so it is stable across runs.
+         */
+        definitions: DefinitionBase[];
+        /**
+         * {@link import('@/dsl/DefinitionContainer.ts').DefinitionContainer}
+         *
+         * Re-adding a member already present is a no-op, keyed the way a file
+         * keys its own duplication rule
+         * ({@link import('@/dsl/IdentifierBase.ts').IdentifierBase.declarationKey}).
+         * Without it a container and a file disagree about duplicates, and a
+         * second registration of one member renders it twice.
+         */
+        addDefinition(definition: DefinitionBase): void;
+        /**
+         * {@link import('@/dsl/DefinitionContainer.ts').DefinitionContainer}
+         *
+         * `name` only. A declaration's `type` is the language's, readable just
+         * from its own identifier subclass, which core cannot name — so the
+         * extractor here always answers `undefined` and a `type` filter would
+         * silently match nothing. A language veneer that narrows the identifier
+         * should override this to answer both, the way its file class does.
+         */
+        findDefinitions(query?: FindDefinitionsQuery): DefinitionBase[] | undefined;
+        context: GenerateContextType;
+        skipped: boolean;
+        generatorKey: GeneratorKey | undefined;
+        stackTrail: import("../../../mod.js").StackTrail;
+    };
+    id: string;
+    type: "oasOperation";
+    toGroupName: (args: ToOasOperationGroupNameArgs<EnrichmentType>) => string;
+    /**
+     * Keyed on the group, so every member of it computes the same key.
+     *
+     * A method rather than a field, and reading `toGroupName` through
+     * `this`: a subclass overriding the group — the normal way a cloned
+     * generator adjusts one policy — must change the key the container is
+     * stored under, not just what callers are told.
+     */
+    toGeneratorKey({ operation, settings }: ToGeneratorKeyArgs<EnrichmentType>): GeneratorKey;
+    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierType: (operation: OasOperation, context: GenerateContextType) => IdType;
+    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType>) => string;
+    isSupported: (args: IsSupportedOasOperationArgs) => boolean;
+    toEnrichments: ({ operation, context, variant }: ToOasOperationEnrichmentsArgs) => EnrichmentType;
+    lang: import("../../Lang.js").Lang;
+};

package/script/dsl/operation/oas/toOasOperationContainerBase.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOasOperationContainerBase = void 0;
+const GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
+const Variant_js_1 = require("../../../types/Variant.js");
+const parseEnrichmentUmbrella_js_1 = require("../../../enrichments/parseEnrichmentUmbrella.js");
+const CodeFileBase_js_1 = require("../../CodeFileBase.js");
+/**
+ * Build a base class for a declaration that HOLDS definitions — a Kotlin
+ * interface body, a C# class body — rather than one that is a subject's
+ * artifact.
+ *
+ * Two things separate it from {@link import('./toOasOperationProjectionBase.ts').toOasOperationProjectionBase}:
+ *
+ * The value carries a {@link toContainerGeneratorKey} rather than the
+ * operation's own. A subject-derived key is what makes many operations
+ * resolving to one definition fail the integrity check on the second of
+ * them; an identity-derived one is computed identically by every member,
+ * while still carrying the `generatorId` that stops another generator
+ * claiming the declaration.
+ *
+ * And it implements the member store, so the engine can insert into it —
+ * which is also what makes the class assignable where a container is asked
+ * for, with nothing to declare. The subclass renders those members; where
+ * they sit in the declaration, and at what indentation, is the language's
+ * business, not the engine's.
+ */
+const toOasOperationContainerBase = (base, config) => {
+    var _a;
+    return _a = class extends base {
+            /**
+             * Keyed on the group, so every member of it computes the same key.
+             *
+             * A method rather than a field, and reading `toGroupName` through
+             * `this`: a subclass overriding the group — the normal way a cloned
+             * generator adjusts one policy — must change the key the container is
+             * stored under, not just what callers are told.
+             */
+            static toGeneratorKey({ operation, settings }) {
+                const variant = settings.variant ?? Variant_js_1.DEFAULT_VARIANT;
+                return (0, GeneratorKeys_js_1.toContainerGeneratorKey)({
+                    generatorId: config.id,
+                    group: this.toGroupName({ operation, enrichments: settings.enrichments, variant }),
+                    name: settings.identifier.name,
+                    variant
+                });
+            }
+            constructor(args) {
+                super({
+                    context: args.context,
+                    // `new.target` is the most-derived class, so a subclass override of
+                    // `toGroupName` reaches the key the value actually carries.
+                    generatorKey: new.target.toGeneratorKey({
+                        operation: args.operation,
+                        settings: args.settings
+                    })
+                });
+                Object.defineProperty(this, "settings", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                Object.defineProperty(this, "operation", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                /**
+                 * The members inserted into this declaration, in arrival order — which
+                 * is the engine's sweep order, so it is stable across runs.
+                 */
+                Object.defineProperty(this, "definitions", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: []
+                });
+                this.operation = args.operation;
+                this.settings = args.settings;
+            }
+            /**
+             * {@link import('@/dsl/DefinitionContainer.ts').DefinitionContainer}
+             *
+             * Re-adding a member already present is a no-op, keyed the way a file
+             * keys its own duplication rule
+             * ({@link import('@/dsl/IdentifierBase.ts').IdentifierBase.declarationKey}).
+             * Without it a container and a file disagree about duplicates, and a
+             * second registration of one member renders it twice.
+             */
+            addDefinition(definition) {
+                const key = definition.identifier.declarationKey();
+                if (this.definitions.some(member => member.identifier.declarationKey() === key)) {
+                    return;
+                }
+                this.definitions.push(definition);
+            }
+            /**
+             * {@link import('@/dsl/DefinitionContainer.ts').DefinitionContainer}
+             *
+             * `name` only. A declaration's `type` is the language's, readable just
+             * from its own identifier subclass, which core cannot name — so the
+             * extractor here always answers `undefined` and a `type` filter would
+             * silently match nothing. A language veneer that narrows the identifier
+             * should override this to answer both, the way its file class does.
+             */
+            findDefinitions(query) {
+                return (0, CodeFileBase_js_1.matchDefinitions)(this.definitions, query, () => undefined);
+            }
+        },
+        Object.defineProperty(_a, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.id
+        }),
+        Object.defineProperty(_a, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'oasOperation'
+        }),
+        Object.defineProperty(_a, "toGroupName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toGroupName.bind(config)
+        }),
+        Object.defineProperty(_a, "toIdentifierName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierName.bind(config)
+        }),
+        Object.defineProperty(_a, "toIdentifierType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierType.bind(config)
+        }),
+        Object.defineProperty(_a, "toExportPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toExportPath.bind(config)
+        }),
+        Object.defineProperty(_a, "isSupported", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.isSupported ?? (() => true)
+        }),
+        Object.defineProperty(_a, "toEnrichments", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ({ operation, context, variant }) => {
+                return (0, parseEnrichmentUmbrella_js_1.parseEnrichmentUmbrella)({
+                    context,
+                    generatorId: config.id,
+                    subjectSegments: [operation.path, operation.method, variant],
+                    schema: config.toEnrichmentSchema()
+                });
+            }
+        }),
+        _a;
+};
+exports.toOasOperationContainerBase = toOasOperationContainerBase;

package/script/dsl/operation/oas/toOasOperationEntry.d.ts

@@ -71,4 +71,3 @@ export type OasOperationEntry<EnrichmentType = undefined> = {
  * ```
  */
 export declare const toOasOperationEntry: <EnrichmentType = undefined>({ id, transform, toEnrichmentSchema, isSupported, supportsVariant, toPreviewModule, toEnrichmentRequest, toEnrichmentDefaults }: ToOasOperationConfigArgs<EnrichmentType>) => OasOperationEntry<EnrichmentType>;
-//# sourceMappingURL=toOasOperationEntry.d.ts.map

package/script/dsl/operation/oas/toOasOperationProjectionBase.d.ts

@@ -1,5 +1,8 @@
+import type { GeneratorKey } from '../../GeneratorKeys.js';
 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 { OasOperation } from '../../../oas/operation/Operation.js';
 import type { ContentSettings } from '../../ContentSettings.js';
 import type { LangSnippetConstructor } from '../../Lang.js';
@@ -11,7 +14,7 @@ import type { RefName } from '../../../types/RefName.js';
 import type { OasSchema } from '../../../oas/schema/Schema.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { OasVoid } from '../../../oas/void/Void.js';
-import type { OasOperationProjection, OasOperationProjectionConstructorArgs, ToOasOperationIdentifierNameArgs, ToOasOperationExportPathArgs } from './types.js';
+import type { OasOperationContainerProjection, ToGeneratorKeyArgs, OasOperationProjection, OasOperationProjectionConstructorArgs, ToOasOperationContainerArgs, ToOasOperationIdentifierNameArgs, ToOasOperationExportPathArgs } from './types.js';
 import type * as v from 'valibot';
 /**
  * Configuration for {@link toOasOperationProjectionBase}.
@@ -21,10 +24,10 @@ import type * as v from 'valibot';
  * `toIdentifierType`'s return tightens to that language's `type` vocabulary —
  * no recast.
  */
-export type OasOperationProjectionBaseConfig<EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType> = {
+export type OasOperationProjectionBaseConfig<EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType, ProjectionOptions = undefined> = {
     id: string;
     /** Pure: the cache-key name (the cache-check path runs this). */
-    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<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 +35,22 @@ export type OasOperationProjectionBaseConfig<EnrichmentType = undefined, IdType
      * default); the tightening rides the type argument.
      */
     toIdentifierType: (operation: OasOperation, context: GenerateContextType) => IdType;
-    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
+    /**
+     * Declares this projection a MEMBER: its definition is inserted into the
+     * container this returns, rather than at file level.
+     *
+     * Shaped like its identity siblings, and run on the same cache-check path,
+     * so it must be pure. It returns the container class rather than naming
+     * one, which also defers the reference to call time — a module-level
+     * reference between a member and its container is one more way to build
+     * the load-order cycles a leaf module exists to break.
+     *
+     * A member's file is its container's, so `toExportPath` is not consulted
+     * when this is present. A container takes no caller options: the member's
+     * options may select the container class, never parameterise it.
+     */
+    toContainer?: (args: ToOasOperationContainerArgs<EnrichmentType, ProjectionOptions>) => OasOperationContainerProjection;
     /**
      * Required composite schema for the `{ subject, generator, stack }`
      * enrichment umbrella. Required (not optional) is load-bearing: it is what
@@ -87,47 +105,61 @@ type ToEnrichmentsArgs = {
  * `OasOperationProjectionBase` lives here now, because the base class is no
  * longer statically known.
  */
-export declare const toOasOperationProjectionBase: <EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType>(base: LangSnippetConstructor, config: OasOperationProjectionBaseConfig<EnrichmentType, IdType>) => {
-    new (args: OasOperationProjectionConstructorArgs<EnrichmentType>): {
+export declare const toOasOperationProjectionBase: <EnrichmentType = undefined, IdType extends IdentifierType = IdentifierType, ProjectionOptions = undefined>(base: LangSnippetConstructor, config: OasOperationProjectionBaseConfig<EnrichmentType, IdType, ProjectionOptions>) => {
+    new (args: OasOperationProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): {
         settings: ContentSettings<EnrichmentType>;
         operation: OasOperation;
+        /** 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: OasOperationProjection<V, PeerEnrichmentType>, operation: OasOperation, options?: Pick<InsertOperationOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType>;
+        insertOperation<V extends GeneratedValue, PeerEnrichmentType = undefined, PeerProjectionOptions = undefined>(projection: OasOperationProjection<V, PeerEnrichmentType, PeerProjectionOptions>, operation: OasOperation, ...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 inline
          * request/response schemas where the schema 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;
+        generatorKey: GeneratorKey | undefined;
         stackTrail: import("../../../mod.js").StackTrail;
     };
     id: string;
+    /**
+     * How this projection's key is computed — read by the Driver so it can
+     * check a cache hit without knowing whether it holds a subject's
+     * projection or a container.
+     *
+     * A method rather than a field, and reading `id` through `this`, for the
+     * same reason the container reads its group that way: a subclass
+     * overriding the generator id must change the key its values are stored
+     * under, not just what callers are told.
+     */
+    toGeneratorKey({ operation, settings }: ToGeneratorKeyArgs<EnrichmentType>): GeneratorKey;
     type: "oasOperation";
-    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToOasOperationIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     toIdentifierType: (operation: OasOperation, context: GenerateContextType) => IdType;
-    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToOasOperationExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
+    toContainer: ((args: ToOasOperationContainerArgs<EnrichmentType, ProjectionOptions>) => OasOperationContainerProjection) | undefined;
     isSupported: (args: {
         operation: OasOperation;
         context: GenerateContextType;
@@ -142,4 +174,3 @@ export declare const toOasOperationProjectionBase: <EnrichmentType = undefined,
     lang: import("../../Lang.js").Lang;
 };
 export {};
-//# sourceMappingURL=toOasOperationProjectionBase.d.ts.map