@skmtc/core 0.0.984 → 0.16.2

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

@@ -0,0 +1,200 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toGqlOperationProjectionBase = void 0;
+const GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
+const v = __importStar(require("valibot"));
+const get_js_1 = __importDefault(require("lodash-es/get.js"));
+const Variant_js_1 = require("../../../types/Variant.js");
+const Enrichments_js_1 = require("../../../types/Enrichments.js");
+/**
+ * Build a GraphQL operation projection base class from a per-generator
+ * config.
+ *
+ * The returned class extends `base` — the generator's language
+ * snippet base — so the projection hierarchy is language-bound at its root
+ * while core stays language-blind (the base arrives as an opaque
+ * constructor; core never names a concrete language class). The class
+ * exposes the generator's `id`, `toIdentifierName`, `toIdentifierType`,
+ * `toExportPath`, `toEnrichments`, and `isSupported` statics, inherits the
+ * static `lang`
+ * from the base, and injects `generatorKey` so subclasses don't have to.
+ *
+ * Defines NO `register` / `registerInto` — register ergonomics are typed by
+ * each language's concise vocabulary, which core can't name, so they live
+ * in the language package's projection-base veneer over this factory.
+ *
+ * The projection machinery previously hosted on
+ * `GqlOperationProjectionBase` lives here now, because the base class is no
+ * longer statically known.
+ */
+const toGqlOperationProjectionBase = (base, config) => {
+    var _a;
+    return _a = class extends base {
+            constructor(args) {
+                super({
+                    context: args.context,
+                    generatorKey: (0, GeneratorKeys_js_1.toGqlOperationGeneratorKey)({
+                        generatorId: config.id,
+                        operation: args.operation,
+                        variant: args.settings.variant ?? Variant_js_1.DEFAULT_VARIANT
+                    })
+                });
+                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
+                });
+                this.operation = args.operation;
+                this.settings = args.settings;
+            }
+            /**
+             * 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.
+             */
+            insertOperation(projection, operation, options = {}) {
+                return this.context.insertOperation({
+                    projection,
+                    operation,
+                    destinationPath: this.settings.exportPath,
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+            /**
+             * 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.
+             */
+            insertModel(projection, refName, options = {}) {
+                return this.context.insertModel(projection, refName, {
+                    destinationPath: this.settings.exportPath,
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+            /**
+             * 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`.
+             */
+            insertNormalizedModel(projection, { schema, fallbackName }, options = {}) {
+                return this.context.insertNormalizedModel(projection, {
+                    schema,
+                    fallbackName,
+                    destinationPath: this.settings.exportPath
+                }, {
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+        },
+        Object.defineProperty(_a, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.id
+        }),
+        Object.defineProperty(_a, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'gqlOperation'
+        }),
+        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 }) => {
+                // The three enrichment scopes assembled into the umbrella a generator
+                // reads off `this.settings.enrichments`. Subject is per-operation
+                // (`[id][rootKind][fieldName][variant]`) — GraphQL has no path/method,
+                // and the variant axis is core-owned; generator and stack are
+                // run-constants (`[id][_generator]`, `[_stack]`). The required composite
+                // schema parses the raw umbrella once — typed, cast-free.
+                const raw = {
+                    subject: (0, get_js_1.default)(context.settings, ['enrichments', config.id, operation.rootKind, operation.fieldName, variant]),
+                    generator: (0, get_js_1.default)(context.settings, ['enrichments', config.id, Enrichments_js_1.GENERATOR_ENRICHMENT_KEY]),
+                    stack: (0, get_js_1.default)(context.settings, ['enrichments', Enrichments_js_1.STACK_ENRICHMENT_KEY])
+                };
+                return v.parse(config.toEnrichmentSchema(), raw);
+            }
+        }),
+        _a;
+};
+exports.toGqlOperationProjectionBase = toGqlOperationProjectionBase;

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

@@ -0,0 +1,141 @@
+import type { GqlOperation } from '../../../gql/operation/GqlOperation.js';
+import type { Lang } from '../../Lang.js';
+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 { EnrichmentRequest } from '../../../types/EnrichmentRequest.js';
+import type * as v from 'valibot';
+import type { MappingModule, PreviewModule } from '../../../types/Preview.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> = {
+    context: GenerateContextType;
+    settings: ContentSettings<EnrichmentType>;
+    operation: GqlOperation;
+};
+export type TransformGqlOperationArgs = {
+    context: GenerateContextType;
+    operation: GqlOperation;
+    /**
+     * The operation variant the engine is dispatching for this call. The
+     * engine fans out one `transform` call per variant declared in the
+     * consumer's `enrichments[id][rootKind][fieldName]` block (or just
+     * `'main'` when no enrichments are configured). See {@link Variant}.
+     */
+    variant: string;
+};
+export type WithTransformGqlOperation = {
+    transformOperation: (operation: GqlOperation) => void;
+};
+export type IsSupportedGqlOperationConfigArgs<EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    operation: GqlOperation;
+    enrichments: EnrichmentType;
+    /** Operation variant being probed (see {@link Variant}) */
+    variant: string;
+};
+export type IsSupportedGqlOperationArgs = {
+    context: GenerateContextType;
+    operation: GqlOperation;
+    /** Operation variant being probed (see {@link Variant}) */
+    variant: string;
+};
+export type ToGqlOperationEnrichmentsArgs = {
+    operation: GqlOperation;
+    context: GenerateContextType;
+    /** Operation variant whose enrichment should be resolved (see {@link Variant}) */
+    variant: string;
+};
+export type ToGqlOperationPreviewModuleArgs = {
+    context: GenerateContextType;
+    operation: GqlOperation;
+    /** Operation variant the preview module describes (see {@link Variant}) */
+    variant: string;
+};
+export type ToGqlOperationMappingArgs = {
+    context: GenerateContextType;
+    operation: GqlOperation;
+    /** Operation variant the mapping module describes (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Arguments for a GraphQL operation projection's `toIdentifierName` — the
+ * pure, cache-key-source half of the old `toIdentifier`.
+ */
+export type ToGqlOperationIdentifierNameArgs<EnrichmentType = undefined> = {
+    operation: GqlOperation;
+    enrichments: EnrichmentType;
+    /** Operation variant the identifier should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+export type ToGqlOperationExportPathArgs<EnrichmentType = undefined> = {
+    operation: GqlOperation;
+    enrichments: EnrichmentType;
+    /** Operation variant the export path should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * 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(...)`.
+ */
+export type GqlOperationProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+    prototype: V;
+} & {
+    new ({ context, settings, operation }: GqlOperationProjectionConstructorArgs<EnrichmentType>): V;
+    id: string;
+    type: 'gqlOperation';
+    /**
+     * The projection's language — the static inherited from the language
+     * snippet base the projection class is built on
+     * (`toGqlOperationProjectionBase(TsSnippet, …)`). Drivers read
+     * it ephemerally at each use site, pre-construction (cache-hit path).
+     */
+    lang: Lang;
+    /** Pure: the cache-key name. */
+    toIdentifierName: (args: ToGqlOperationIdentifierNameArgs<EnrichmentType>) => string;
+    /**
+     * Context-aware, overridable: the non-`name` parts of the identifier,
+     * derived from the operation/schema. The engine assembles
+     * `lang.toIdentifier({ name: toIdentifierName(args),
+     * ...toIdentifierType(operation, context) })`.
+     */
+    toIdentifierType: (operation: GqlOperation, context: GenerateContextType) => IdentifierType;
+    toExportPath: (args: ToGqlOperationExportPathArgs<EnrichmentType>) => string;
+    toEnrichments: ({ operation, context }: ToGqlOperationEnrichmentsArgs) => EnrichmentType;
+    /**
+     * Family-level capability predicate, surfaced as a static by
+     * `toGqlOperationProjectionBase` (default `() => true`). The Driver
+     * probes it on every `insertOperation` so a peer is never handed an
+     * operation it has declared unsupported. Optional: a hand-rolled
+     * projection may omit it, in which case it is treated as supporting
+     * every operation.
+     */
+    isSupported?: (args: {
+        operation: GqlOperation;
+        context: GenerateContextType;
+    }) => boolean;
+} & Function;
+/**
+ * Pipeline-side configuration for a GraphQL operation projection (built by
+ * `toGqlOperationEntry`).
+ */
+export type GqlOperationConfig<EnrichmentType = undefined> = {
+    id: string;
+    type: 'gqlOperation';
+    transform: ({ context, operation, variant }: TransformGqlOperationArgs) => void;
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
+    isSupported: ({ context, operation }: IsSupportedGqlOperationArgs) => boolean;
+    toPreviewModule?: ({ context, operation }: ToGqlOperationPreviewModuleArgs) => PreviewModule;
+    toMappingModule?: ({ context, operation }: ToGqlOperationMappingArgs) => MappingModule;
+    toEnrichmentRequest?: <RequestedEnrichment extends EnrichmentType>(operation: GqlOperation) => EnrichmentRequest<RequestedEnrichment> | undefined;
+};
+//# sourceMappingURL=types.d.ts.map

package/script/dsl/operation/gql/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/dsl/operation/gql/types.ts"],"names":[],"mappings":"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"}

package/script/dsl/operation/gql/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,52 @@
+import type { OasOperationProjection } from './types.js';
+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> = {
+    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`.
+     */
+    variant: string;
+};
+/**
+ * Driver for the OAS operation insertion lifecycle.
+ *
+ * Resolves the projection's identifier and export path, looks up an
+ * existing `Definition` in the target file, instantiates the projection
+ * (constructing its value) when no cache hit exists, registers the new
+ * definition, and stitches an import into `destinationPath` if it differs
+ * from the projection's `exportPath`.
+ */
+export declare class OasOperationDriver<V extends GeneratedValue, EnrichmentType = undefined> {
+    context: GenerateContextType;
+    projection: OasOperationProjection<V, EnrichmentType>;
+    operation: OasOperation;
+    settings: ContentSettings<EnrichmentType>;
+    destinationPath?: string;
+    definition: GeneratedDefinition<V>;
+    noExport?: boolean;
+    variant: string;
+    constructor({ context, projection, operation, destinationPath, noExport, variant }: CreateOperationArgs<V, EnrichmentType>);
+    private apply;
+    /**
+     * Ensure the file at `path` exists, creating it on first write through
+     * the projection's language — the static read off the projection class
+     * at the use site, never persisted (works pre-construction on the
+     * cache-hit path). Returns the normalized path.
+     */
+    private ensureFile;
+    private getDefinition;
+    private affirmDefinition;
+}
+export {};
+//# sourceMappingURL=OasOperationDriver.d.ts.map

package/script/dsl/operation/oas/OasOperationDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OasOperationDriver.d.ts","sourceRoot":"","sources":["../../../../src/dsl/operation/oas/OasOperationDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAI/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAK5E,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,IAAI;IAC/E,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,EAAE,sBAAsB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IACrD,SAAS,EAAE,YAAY,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAWD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS;IAClF,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,EAAE,sBAAsB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IACrD,SAAS,EAAE,YAAY,CAAA;IACvB,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAA;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;gBAEH,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,eAAe,EACf,QAAQ,EACR,OAAO,EACR,EAAE,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC;IA0BzC,OAAO,CAAC,KAAK;IAsBb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,gBAAgB;CAsBzB"}

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

@@ -0,0 +1,227 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OasOperationDriver = void 0;
+const normalize_js_1 = require("../../../deps/jsr.io/@std/path/1.1.4/normalize.js");
+const GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
+const Variant_js_1 = require("../../../types/Variant.js");
+const get_js_1 = __importDefault(require("lodash-es/get.js"));
+/**
+ * Driver for the OAS operation insertion lifecycle.
+ *
+ * Resolves the projection's identifier and export path, looks up an
+ * existing `Definition` in the target file, instantiates the projection
+ * (constructing its value) when no cache hit exists, registers the new
+ * definition, and stitches an import into `destinationPath` if it differs
+ * from the projection's `exportPath`.
+ */
+class OasOperationDriver {
+    constructor({ context, projection, operation, destinationPath, noExport, variant }) {
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "projection", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "operation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "settings", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "destinationPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "definition", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "noExport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "variant", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.context = context;
+        this.projection = projection;
+        this.operation = operation;
+        this.destinationPath = destinationPath;
+        this.noExport = noExport;
+        this.variant = variant;
+        assertPeerVariantExists({
+            context,
+            generatorId: projection.id,
+            operation,
+            variant
+        });
+        assertPeerSupported({ context, projection, operation });
+        this.settings = this.context.toOperationContentSettings({
+            operation,
+            projection,
+            variant
+        });
+        this.definition = this.apply({ destinationPath });
+    }
+    apply({ destinationPath } = {}) {
+        const { identifier, exportPath } = this.settings;
+        const definition = this.getDefinition({ identifier, exportPath });
+        if (destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)) {
+            // 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.context.register({
+                imports: [this.projection.lang.toImport({ identifier, module: exportPath })],
+                destinationPath
+            });
+        }
+        return definition;
+    }
+    /**
+     * Ensure the file at `path` exists, creating it on first write through
+     * the projection's language — the static read off the projection class
+     * at the use site, never persisted (works pre-construction on the
+     * cache-hit path). Returns the normalized path.
+     */
+    ensureFile(path) {
+        const normalizedPath = (0, normalize_js_1.normalize)(path);
+        if (!this.context.getFile(normalizedPath)) {
+            this.context.addFile(this.projection.lang.createFile({ path: normalizedPath, settings: this.context.settings }));
+        }
+        return normalizedPath;
+    }
+    getDefinition({ identifier, exportPath }) {
+        const cachedDefinition = this.context.findDefinition({
+            name: identifier.name,
+            exportPath
+        });
+        if (this.affirmDefinition(cachedDefinition, exportPath)) {
+            return cachedDefinition;
+        }
+        const value = new this.projection({
+            context: this.context,
+            operation: this.operation,
+            settings: this.settings
+        });
+        const definition = this.projection.lang.toDefinition({
+            context: this.context,
+            identifier,
+            value,
+            noExport: this.noExport
+        });
+        this.ensureFile(exportPath);
+        this.context.register({
+            definitions: [definition],
+            destinationPath: exportPath
+        });
+        return definition;
+    }
+    affirmDefinition(definition, exportPath) {
+        if (!definition) {
+            return false;
+        }
+        const currentKey = (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;
+    }
+}
+exports.OasOperationDriver = OasOperationDriver;
+/**
+ * Guard the peer-variant-mismatch invariant.
+ *
+ * `'main'` is the universally-safe variant — it's guaranteed to be
+ * present on every peer (the engine fills it when no enrichments are
+ * configured, and the missing-`'main'` check throws when other
+ * variants exist without it). So calls with `variant === 'main'`
+ * always succeed regardless of the peer's enrichment shape.
+ *
+ * For any other variant, the peer's enrichment block at
+ * `[generatorId][path][method]` must explicitly declare that variant
+ * key. The Driver throws here — loud at the call site — rather than
+ * letting silently-wrong output reach the consumer.
+ */
+const assertPeerVariantExists = ({ context, generatorId, operation, variant }) => {
+    if (variant === Variant_js_1.DEFAULT_VARIANT) {
+        return;
+    }
+    const opEnrichments = (0, get_js_1.default)(context.settings, ['enrichments', generatorId, operation.path, operation.method]);
+    const operationLabel = `${operation.method.toUpperCase()} ${operation.path}`;
+    if (opEnrichments === null || opEnrichments === undefined) {
+        throw new Error(`[${generatorId}] Cannot insert variant '${variant}' for '${operationLabel}' — ` +
+            `peer has no enrichments configured. Only '${Variant_js_1.DEFAULT_VARIANT}' is permitted.`);
+    }
+    if (typeof opEnrichments !== 'object' || Array.isArray(opEnrichments)) {
+        throw new Error(`[${generatorId}] Cannot insert variant '${variant}' for '${operationLabel}' — ` +
+            `peer enrichment is not a variant record.`);
+    }
+    if (!(variant in opEnrichments)) {
+        const available = Object.keys(opEnrichments).join(', ');
+        throw new Error(`[${generatorId}] Cannot insert variant '${variant}' for '${operationLabel}'. ` +
+            `Available variants: ${available}.`);
+    }
+};
+/**
+ * Guard the peer-capability invariant.
+ *
+ * `insertOperation` materialises a peer's Definition regardless of the
+ * peer's `skip` / `include` configuration — dependency edges are
+ * intentionally filter-blind. Capability is different: a peer's
+ * `isSupported` declares which operations it can serve *at all* (a
+ * table generator cannot render an operation with no list response,
+ * for example). Handing a peer an operation it has declared
+ * unsupported would build a broken Definition or crash inside the
+ * peer's constructor.
+ *
+ * The Driver throws here instead. The throw unwinds into
+ * `GenerateContext`'s per-item `try/catch`, so the *calling*
+ * generator's item is recorded as `error` and the run continues —
+ * loud, isolated failure rather than silent broken output.
+ *
+ * A peer that exposes no static `isSupported` is treated as
+ * supporting every operation: `toOasOperationProjectionBase` defaults
+ * it to `() => true`, and a hand-rolled projection may omit it.
+ */
+const assertPeerSupported = ({ context, projection, operation }) => {
+    if (typeof projection.isSupported !== 'function') {
+        return;
+    }
+    if (!projection.isSupported({ operation, context })) {
+        const operationLabel = `${operation.method.toUpperCase()} ${operation.path}`;
+        throw new Error(`[${projection.id}] Cannot insert '${operationLabel}' — peer generator ` +
+            `does not support this operation (isSupported returned false).`);
+    }
+};