@devilsdev/rag-pipeline-utils 2.5.0 → 2.6.0

package/src/connectors/cohere-connector.js

@@ -1,6 +1,9 @@
 'use strict';
 
-const axios = require('axios');
+// axios loads on first use, so importing the package does not pay for it
+// (about 125 ms) unless this connector is constructed.
+const loadAxios = () => require('axios'); // eslint-disable-line global-require
+const { componentCacheKey } = require('../cache/component-keys');
 const { BaseConnector } = require('./base-connector');
 const {
   missingApiKeyError,
@@ -37,6 +40,21 @@ const DEFAULT_CONFIG = {
  * @extends BaseConnector
  */
 class CohereConnector extends BaseConnector {
+  /**
+   * Cache identity for createRagPipeline({ cache }).
+   * @param {'embedder'} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    if (role !== 'embedder') return null;
+    const c = this.config;
+    return componentCacheKey('cohere-embed', {
+      baseURL: c.baseURL,
+      model: c.embeddingModel,
+      queryInputType: c.queryInputType,
+    });
+  }
+
   /**
    * @param {Object} [options]
    * @param {string} [options.apiKey] - Cohere API key
@@ -53,7 +71,7 @@ class CohereConnector extends BaseConnector {
       ...options,
       apiKey: resolveApiKey(options, API_KEY_ENV),
     };
-    this.client = axios.create({
+    this.client = loadAxios().create({
       baseURL: this.config.baseURL,
       headers: {
         Authorization: `Bearer ${this.config.apiKey}`,

package/src/connectors/local-embedder.js

@@ -1,4 +1,5 @@
 'use strict';
+const { digest } = require('../cache/component-keys');
 
 const { BaseConnector } = require('./base-connector');
 const { tokenize } = require('../evaluate/scoring');
@@ -42,6 +43,7 @@ class LocalEmbedder extends BaseConnector {
    * @param {Array<string|{ content?: string, text?: string }>} documents - Training documents
    */
   train(documents) {
+    this._fingerprint = null; // the cache key changes with the training
     const docs = documents.map((doc) => {
       if (typeof doc === 'string') return doc;
       return doc.content || doc.text || String(doc);
@@ -171,11 +173,29 @@ class LocalEmbedder extends BaseConnector {
    * @param {{docCount: number, vocabulary: Array<[string, number]>, idf: Array<[string, number]>}} state
    */
   setState(state) {
+    this._fingerprint = null;
     this.docCount = state.docCount || 0;
     this.vocabulary = new Map(state.vocabulary || []);
     this.idf = new Map(state.idf || []);
   }
 
+  /**
+   * Cache identity for createRagPipeline({ cache }): a fingerprint of the
+   * trained vocabulary and IDF weights, so retraining invalidates cached
+   * query vectors (also across processes sharing a Redis cache).
+   * @param {'embedder'} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    if (role !== 'embedder') return null;
+    if (!this._fingerprint) {
+      this._fingerprint = digest(
+        JSON.stringify([this.docCount, [...this.vocabulary], [...this.idf]]),
+      );
+    }
+    return `local-embedder|${this._fingerprint}`;
+  }
+
   /** @returns {number} Vector length produced by embed() once trained */
   get dimensions() {
     return this.vocabulary.size;

package/src/connectors/memory-retriever.js

@@ -1,4 +1,5 @@
 'use strict';
+const { randomBytes } = require('crypto');
 
 const { BaseConnector } = require('./base-connector');
 const { throwIfAborted } = require('./connector-utils');
@@ -40,6 +41,21 @@ class MemoryRetriever extends BaseConnector {
     /** @type {number|null} Vector dimension, fixed by the first stored vector */
     this.dimensions = null;
     this.connected = true;
+    // Cache identity: unique per instance, bumped on every change, so a
+    // shared cache never returns another store's or an older state's results.
+    this._cacheId = randomBytes(8).toString('hex');
+    this._revision = 0;
+  }
+
+  /**
+   * Cache identity for createRagPipeline({ cache }).
+   * @param {'retriever'} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    return role === 'retriever'
+      ? `memory|${this._cacheId}|${this._revision}`
+      : null;
   }
 
   /**
@@ -111,6 +127,7 @@ class MemoryRetriever extends BaseConnector {
       this.emit('evicted', { count: evicted, total: this.documents.size });
     }
 
+    this._revision += 1;
     this.emit('stored', { count: vectors.length, total: this.documents.size });
   }
 
@@ -209,6 +226,7 @@ class MemoryRetriever extends BaseConnector {
   async clear() {
     this.documents.clear();
     this.dimensions = null;
+    this._revision += 1;
   }
 
   /**

package/src/connectors/ollama-connector.js

@@ -1,6 +1,8 @@
 'use strict';
 
-const axios = require('axios');
+// axios loads on first use, so importing the package does not pay for it
+// (about 125 ms) unless this connector is constructed.
+const loadAxios = () => require('axios'); // eslint-disable-line global-require
 const { BaseConnector } = require('./base-connector');
 const {
   raceAbort,
@@ -8,6 +10,7 @@ const {
   throwIfAborted,
 } = require('./connector-utils');
 const { buildRagPrompt } = require('./rag-prompt');
+const { componentCacheKey } = require('../cache/component-keys');
 
 /**
  * Default configuration for the Ollama connector.
@@ -30,6 +33,30 @@ const DEFAULT_CONFIG = {
  * @extends BaseConnector
  */
 class OllamaConnector extends BaseConnector {
+  /**
+   * Cache identity for createRagPipeline({ cache }).
+   * @param {'embedder'|'llm'} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    const c = this.config;
+    if (role === 'embedder') {
+      return componentCacheKey('ollama-embed', {
+        baseURL: c.baseURL,
+        model: c.embeddingModel,
+      });
+    }
+    if (role === 'llm') {
+      return componentCacheKey('ollama', {
+        baseURL: c.baseURL,
+        model: c.model,
+        temperature: c.temperature,
+        systemPrompt: c.systemPrompt,
+      });
+    }
+    return null;
+  }
+
   /**
    * @param {Object} options
    * @param {string} [options.baseURL='http://localhost:11434'] - Ollama server URL
@@ -44,7 +71,7 @@ class OllamaConnector extends BaseConnector {
   constructor(options = {}) {
     super({ name: 'ollama', ...options });
     this.config = { ...DEFAULT_CONFIG, ...options };
-    this.client = axios.create({
+    this.client = loadAxios().create({
       baseURL: this.config.baseURL,
       timeout: this.config.timeout,
     });

package/src/connectors/openai-connector.js

@@ -8,6 +8,7 @@ const {
   throwIfAborted,
 } = require('./connector-utils');
 const { buildRagPrompt } = require('./rag-prompt');
+const { componentCacheKey } = require('../cache/component-keys');
 
 const API_KEY_ENV = 'OPENAI_API_KEY';
 
@@ -36,23 +37,61 @@ const DEFAULT_CONFIG = {
  * @extends BaseConnector
  */
 class OpenAIConnector extends BaseConnector {
+  /**
+   * Cache identity for createRagPipeline({ cache }): the settings that
+   * change this connector's output in the given role.
+   * @param {'embedder'|'llm'} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    const c = this.config;
+    if (role === 'embedder') {
+      return componentCacheKey('openai-embed', {
+        baseURL: c.baseURL,
+        model: c.embeddingModel,
+      });
+    }
+    if (role === 'llm') {
+      return componentCacheKey('openai', {
+        baseURL: c.baseURL,
+        model: c.model,
+        temperature: c.temperature,
+        maxTokens: c.maxTokens,
+        systemPrompt: c.systemPrompt,
+      });
+    }
+    return null;
+  }
+
   /**
    * @param {Object} [options]
    * @param {string} [options.model='gpt-4o-mini'] - Chat model to use
    * @param {string} [options.embeddingModel='text-embedding-3-small'] - Embedding model
    * @param {number} [options.temperature=0.7] - Sampling temperature
    * @param {number} [options.maxTokens=4096] - Max tokens in completion
-   * @param {string} [options.apiKey] - OpenAI API key (defaults to OPENAI_API_KEY at construction)
+   * @param {string} [options.apiKey] - API key. Defaults to OPENAI_API_KEY at
+   *   construction, except when `baseURL` is set (see below)
+   * @param {string} [options.baseURL] - Base URL of an OpenAI-compatible API,
+   *   e.g. Groq, Together, the Hugging Face router, vLLM, LM Studio or
+   *   Ollama's `/v1` endpoint. With a custom base URL the key is never read
+   *   from OPENAI_API_KEY (that would send your OpenAI key to another
+   *   provider): pass `apiKey` explicitly, or omit it for servers that need
+   *   none
    * @param {number} [options.maxRetries=3] - Retries for transient failures (the SDK's own retries are disabled)
    * @param {number} [options.retryDelay=1000] - Base backoff delay in ms
    * @param {string} [options.systemPrompt] - System prompt used when RAG context is supplied
    */
   constructor(options = {}) {
     super({ name: 'openai', ...options });
+    const baseURL = options.baseURL ? String(options.baseURL) : undefined;
     this.config = {
       ...DEFAULT_CONFIG,
       ...options,
-      apiKey: resolveApiKey(options, API_KEY_ENV),
+      baseURL,
+      // A custom endpoint gets only an explicit key, never OPENAI_API_KEY.
+      apiKey: baseURL
+        ? options.apiKey || ''
+        : resolveApiKey(options, API_KEY_ENV),
     };
     this._client = null; // lazy-loaded
   }
@@ -67,7 +106,12 @@ class OpenAIConnector extends BaseConnector {
     if (!this._client) {
       const mod = require('openai');
       const OpenAI = mod.OpenAI || mod.default || mod;
-      this._client = new OpenAI({ apiKey: this.config.apiKey, maxRetries: 0 });
+      this._client = new OpenAI({
+        // Local OpenAI-compatible servers accept any key; the SDK needs one.
+        apiKey: this.config.apiKey || (this.config.baseURL ? 'not-needed' : ''),
+        ...(this.config.baseURL && { baseURL: this.config.baseURL }),
+        maxRetries: 0,
+      });
     }
     return this._client;
   }
@@ -77,7 +121,8 @@ class OpenAIConnector extends BaseConnector {
    * @private
    */
   _requireApiKey() {
-    if (!this.config.apiKey) {
+    // Only the OpenAI API itself requires a key; a custom baseURL may not.
+    if (!this.config.apiKey && !this.config.baseURL) {
       throw missingApiKeyError('OpenAI', API_KEY_ENV);
     }
   }

package/src/core/create-pipeline.js

@@ -3,6 +3,10 @@
 // `pluginRegistry.register()` are resolvable by name here.
 const defaultRegistry = require('./plugin-registry.js');
 const { embedQuery, canEmbed } = require('../utils/embed-query');
+const {
+  normalizeCacheOption,
+  PipelineCache,
+} = require('../cache/pipeline-cache');
 const { createRunAbort } = require('../utils/run-abort');
 
 /** Metrics that only need the query, the retrieved docs and a reference. */
@@ -102,6 +106,26 @@ async function* guardStream(source, { signal, finalize, onEnd }) {
   }
 }
 
+/**
+ * Pass a stream through and report its text when it completed: it reached a
+ * done chunk or its end, and the run was not aborted. A stream the consumer
+ * stops reading early is not reported, so a partial answer is never cached.
+ */
+async function* reportWhenComplete(source, signal, onComplete) {
+  let text = '';
+  let completed = false;
+  try {
+    for await (const chunk of source) {
+      text += typeof chunk === 'string' ? chunk : String(chunk?.token ?? '');
+      if (chunk && chunk.done) completed = true;
+      yield chunk;
+    }
+    completed = true;
+  } finally {
+    if (completed && !signal.aborted) await onComplete(text);
+  }
+}
+
 /**
  * Create a RAG pipeline: (embed) -> retrieve -> (filter) -> (rerank) ->
  * generate -> (citations, evaluation).
@@ -116,6 +140,12 @@ async function* guardStream(source, { signal, finalize, onEnd }) {
  *   `referenceAnswer` (ground truth for context recall)
  * - `filterResults(docs)`: hook applied after retrieval
  *
+ * `cache` (factory option): `true`, a CacheBackend, or
+ * `{ embeddings, retrieval, generation, ttlSeconds }` - see
+ * src/cache/pipeline-cache.js. Results then carry `cache: { embeddings,
+ * retrieval, generation }` ('hit', 'miss' or 'skip'), and the pipeline has
+ * `cacheStats()`.
+ *
  * Every component call receives the run's AbortSignal: `retriever.retrieve({
  * ..., signal })`, `embedder.embedQuery(text, { signal })` /
  * `embedder.embed(text, { signal })`, `reranker.rerank(query, docs, { topK,
@@ -133,6 +163,7 @@ module.exports.createRagPipeline = function createRagPipeline({
   retriever,
   llm,
   reranker,
+  cache,
 } = {}) {
   const reg = registry || defaultRegistry;
   const loaderI = loader ? resolve(reg, 'loader', loader) : null;
@@ -147,6 +178,16 @@ module.exports.createRagPipeline = function createRagPipeline({
   const llmI = llm ? resolve(reg, 'llm', llm) : null;
   const rerankerI = reranker ? resolve(reg, 'reranker', reranker) : null;
 
+  const cacheLayers = normalizeCacheOption(cache);
+  const pc = cacheLayers
+    ? new PipelineCache(cacheLayers, {
+        embedder: embedderI,
+        // The default stand-in retriever returns nothing; never cache it.
+        retriever: retriever ? retrieverI : null,
+        llm: llmI,
+      })
+    : null;
+
   async function runOnce({ query, queryVector, options = {} } = {}) {
     const opts = options || {};
     const { timeout, stream } = opts;
@@ -154,6 +195,11 @@ module.exports.createRagPipeline = function createRagPipeline({
     const { signal } = run;
     let streaming = false;
 
+    // Per-run cache outcome per layer: 'hit', 'miss' or 'skip'.
+    const cacheStatus = {};
+    const withCache = (result) =>
+      pc ? { ...result, cache: { ...cacheStatus } } : result;
+
     const doWork = (async () => {
       run.throwIfAborted();
       if (loaderI?.load) {
@@ -162,16 +208,34 @@ module.exports.createRagPipeline = function createRagPipeline({
       }
       let vector = queryVector;
       if (!vector && query && canEmbed(embedderI)) {
-        vector = await embedQuery(embedderI, query, { signal });
+        const key = pc && pc.embeddingKey(query);
+        vector = pc && (await pc.get('embeddings', key, cacheStatus));
+        if (!vector) {
+          vector = await embedQuery(embedderI, query, { signal });
+          run.throwIfAborted();
+          if (pc) await pc.set('embeddings', key, vector);
+        }
         run.throwIfAborted();
       }
 
-      let docs = await retrieverI.retrieve({
-        query,
-        queryVector: vector,
-        topK: opts.topK ?? 3,
-        signal,
-      });
+      // Raw retriever output is cached before filterResults (guardrail ACLs)
+      // and the reranker, so both still run on every request.
+      const topK = opts.topK ?? 3;
+      const retrievalKey =
+        pc && pc.retrievalKey({ query, queryVector: vector, topK });
+      let docs = pc && (await pc.get('retrieval', retrievalKey, cacheStatus));
+      if (!docs) {
+        docs = await retrieverI.retrieve({
+          query,
+          queryVector: vector,
+          topK,
+          signal,
+        });
+        run.throwIfAborted();
+        if (pc && Array.isArray(docs)) {
+          await pc.set('retrieval', retrievalKey, docs);
+        }
+      }
       run.throwIfAborted();
       // Hook for filtering (e.g. ACL guardrails) before anything downstream,
       // including the LLM, sees the retrieved documents.
@@ -190,6 +254,15 @@ module.exports.createRagPipeline = function createRagPipeline({
 
       const genOptions = { ...opts, signal };
       const wantsQuality = Boolean(opts.citations || opts.evaluate);
+      const generationKey =
+        pc && llmI
+          ? pc.generationKey({ query, docs: results, options: opts })
+          : null;
+      const cachedAnswer =
+        pc && llmI
+          ? await pc.get('generation', generationKey, cacheStatus)
+          : undefined;
+      run.throwIfAborted();
 
       if (stream) {
         let source;
@@ -207,6 +280,11 @@ module.exports.createRagPipeline = function createRagPipeline({
           });
           source = (async function* noAnswer() {})();
           finalize = () => ({ results, ...quality });
+        } else if (typeof cachedAnswer === 'string') {
+          source = (async function* cached() {
+            yield { token: cachedAnswer, done: false };
+            yield { token: '', done: true };
+          })();
         } else if (llmI.generateStream) {
           source = await llmI.generateStream(query, results, genOptions);
         } else if (llmI.generate) {
@@ -221,6 +299,11 @@ module.exports.createRagPipeline = function createRagPipeline({
         if (source) {
           run.throwIfAborted();
           streaming = true;
+          if (pc && llmI && generationKey && typeof cachedAnswer !== 'string') {
+            source = reportWhenComplete(source, signal, (text) =>
+              pc.set('generation', generationKey, text),
+            );
+          }
           return guardStream(source, {
             signal,
             finalize,
@@ -230,26 +313,33 @@ module.exports.createRagPipeline = function createRagPipeline({
       }
 
       if (!llmI) {
-        return {
+        return withCache({
           success: true,
           query,
           results,
           answer: null,
           ...computeQuality({ query, answer: null, results, options: opts }),
-        };
+        });
       }
 
-      const raw = (await llmI.generate?.(query, results, genOptions)) ?? '';
-      run.throwIfAborted();
-      const answer = String(raw);
+      let answer;
+      if (typeof cachedAnswer === 'string') {
+        answer = cachedAnswer;
+      } else {
+        const raw = (await llmI.generate?.(query, results, genOptions)) ?? '';
+        run.throwIfAborted();
+        answer = String(raw);
+        if (pc) await pc.set('generation', generationKey, answer);
+        run.throwIfAborted();
+      }
 
-      return {
+      return withCache({
         success: true,
         query,
         results,
         answer,
         ...computeQuality({ query, answer, results, options: opts }),
-      };
+      });
     })();
 
     try {
@@ -264,5 +354,12 @@ module.exports.createRagPipeline = function createRagPipeline({
     }
   }
 
-  return { run: runOnce, cleanup() {} };
+  return {
+    run: runOnce,
+    cleanup() {},
+    /** Cache hits, misses and skips per layer; null when caching is off. */
+    cacheStats() {
+      return pc ? pc.stats() : null;
+    },
+  };
 };

package/src/core/performance/parallel-processor.js

@@ -36,16 +36,77 @@ class Semaphore {
   }
 }
 
+/** Built-in embedders whose embed() takes one string, not an array. */
+function isSingleTextEmbedder(embedder) {
+  /* eslint-disable global-require */
+  const singleText = [
+    require('../../connectors/local-embedder').LocalEmbedder,
+    require('../../connectors/openai-connector').OpenAIConnector,
+    require('../../connectors/ollama-connector').OllamaConnector,
+    require('../../connectors/cohere-connector').CohereConnector,
+  ];
+  /* eslint-enable global-require */
+  return singleText.some((Class) => Class && embedder instanceof Class);
+}
+
+const EMBED_MODES = ['auto', 'batch', 'single'];
+
 /**
  * Parallel processor for embedding operations with configurable concurrency
  */
 class ParallelEmbedder {
+  /**
+   * @param {object} embedder - Embedder with embed() and/or embedBatch()
+   * @param {object} [_options]
+   * @param {number} [_options.batchSize=10] - Texts per batch
+   * @param {number} [_options.maxConcurrency=3] - Batches in flight at once
+   * @param {number} [_options.retryAttempts=2] - Retries per failed batch
+   * @param {number} [_options.retryDelay=1000] - Base retry delay in ms
+   * @param {'auto'|'batch'|'single'} [_options.mode='auto'] - How a batch is
+   *   embedded: 'batch' calls embed(texts) and expects one vector per text,
+   *   'single' calls embed(text) for each text. 'auto' uses embedBatch(texts)
+   *   when the embedder has it, 'single' for the built-in connectors (which
+   *   embed one string at a time) and 'batch' otherwise.
+   */
   constructor(embedder, _options = {}) {
     this.embedder = embedder;
     this.batchSize = _options.batchSize || 10;
     this.maxConcurrency = _options.maxConcurrency || 3;
     this.retryAttempts = _options.retryAttempts || 2;
     this.retryDelay = _options.retryDelay || 1000;
+    const mode = _options.mode || 'auto';
+    if (!EMBED_MODES.includes(mode)) {
+      throw new Error(
+        `Invalid mode "${mode}". Expected one of: ${EMBED_MODES.join(', ')}`,
+      );
+    }
+    this.mode = mode;
+  }
+
+  /**
+   * Embed one batch according to the mode.
+   * @param {string[]} batch
+   * @returns {Promise<number[][]>}
+   * @private
+   */
+  async _embed(batch) {
+    const embedder = this.embedder;
+    if (this.mode === 'auto' && typeof embedder.embedBatch === 'function') {
+      return embedder.embedBatch(batch);
+    }
+    const single =
+      this.mode === 'single' ||
+      (this.mode === 'auto' && isSingleTextEmbedder(embedder));
+    if (!single) {
+      return embedder.embed(batch);
+    }
+    // One text at a time within a batch, so maxConcurrency still bounds the
+    // number of requests in flight.
+    const vectors = [];
+    for (const text of batch) {
+      vectors.push(await embedder.embed(text));
+    }
+    return vectors;
   }
 
   /**
@@ -133,7 +194,7 @@ class ParallelEmbedder {
 
     for (let attempt = 0; attempt <= this.retryAttempts; attempt++) {
       try {
-        const result = await this.embedder.embed(batch);
+        const result = await this._embed(batch);
 
         // Validate result
         if (!Array.isArray(result) || result.length !== batch.length) {

package/src/core/plugin-registry.js

@@ -2,7 +2,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv');
+// ajv loads with the contracts; see _ensureContracts().
+const loadAjv = () => require('ajv'); // eslint-disable-line global-require
 const {
   createPluginVerifier,
 } = require('../security/plugin-signature-verifier.js');
@@ -42,7 +43,43 @@ class PluginRegistry {
         ? options.validateContractSchema
         : true; // Enable schema validation by default
 
-    // Initialize Ajv for contract schema validation
+    // Environment-aware signature verification defaults
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const isProduction = process.env.NODE_ENV === 'production';
+
+    this._signatureVerifier = createPluginVerifier({
+      enabled:
+        options.verifySignatures !== undefined
+          ? options.verifySignatures
+          : isProduction, // Enabled by default in production, disabled in development
+      failClosed:
+        options.failClosed !== undefined ? options.failClosed : isProduction, // Fail closed in production, fail open in development
+      trustedKeysPath: options.trustedKeysPath,
+      requireContentDigest: options.requireContentDigest === true,
+    });
+    // Opt-in: when verification is enabled, refuse plugins registered
+    // without a signed manifest (default false for backward compatibility).
+    this._requireSignedPlugins = options.requireSignedPlugins === true;
+
+    // Contracts (and ajv, which validates them) load in the constructor, or
+    // on first use with `lazyContracts: true`. The shared registry exported
+    // by this module is lazy, so importing the package does not pay for
+    // them unless a plugin is registered or validated.
+    this._contractsLoaded = false;
+    if (!options.lazyContracts) {
+      this._ensureContracts();
+    }
+  }
+
+  /**
+   * Load the contract schema and the stage contracts once.
+   * @private
+   */
+  _ensureContracts() {
+    if (this._contractsLoaded) return;
+    this._contractsLoaded = true;
+
+    const Ajv = loadAjv();
     this._ajv = new Ajv({
       allErrors: true,
       verbose: true,
@@ -70,23 +107,6 @@ class PluginRegistry {
       }
     }
 
-    // Environment-aware signature verification defaults
-    const isDevelopment = process.env.NODE_ENV === 'development';
-    const isProduction = process.env.NODE_ENV === 'production';
-
-    this._signatureVerifier = createPluginVerifier({
-      enabled:
-        options.verifySignatures !== undefined
-          ? options.verifySignatures
-          : isProduction, // Enabled by default in production, disabled in development
-      failClosed:
-        options.failClosed !== undefined ? options.failClosed : isProduction, // Fail closed in production, fail open in development
-      trustedKeysPath: options.trustedKeysPath,
-      requireContentDigest: options.requireContentDigest === true,
-    });
-    // Opt-in: when verification is enabled, refuse plugins registered
-    // without a signed manifest (default false for backward compatibility).
-    this._requireSignedPlugins = options.requireSignedPlugins === true;
     this._loadContracts();
   }
 
@@ -205,6 +225,7 @@ class PluginRegistry {
    * @since 2.2.4
    */
   checkContractExists(type) {
+    this._ensureContracts();
     return this._contracts.has(type);
   }
 
@@ -357,6 +378,7 @@ class PluginRegistry {
   }
 
   _validatePluginContract(category, impl) {
+    this._ensureContracts();
     const contract = this._contracts.get(category);
     if (!contract) {
       // Use new warning method when registering a plugin without a contract
@@ -609,6 +631,7 @@ class PluginRegistry {
 const registry = new PluginRegistry({
   verifySignatures: process.env.NODE_ENV === 'production',
   failClosed: process.env.NODE_ENV === 'production',
+  lazyContracts: true,
 });
 
 // CJS+ESM interop pattern