@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/scalars/upload.scalar.ts

@@ -1,5 +1,5 @@
 import type { GraphQLScalarType } from 'graphql';
-import GraphQLUploadScalar from 'graphql-upload/GraphQLUpload.js';
+import GraphQLUploadScalar from 'graphql-upload/GraphQLUpload.mjs';
 
 /**
  * The GraphQL `Upload` scalar for multipart file uploads — import it from `@lenne.tech/nest-server`,
@@ -10,8 +10,13 @@ import GraphQLUploadScalar from 'graphql-upload/GraphQLUpload.js';
  * copy. A resolver that imports the scalar from the project's own graphql-upload therefore works only
  * while both resolve to the same version; with two copies every upload is refused as invalid. And the
  * import path itself is not stable across graphql-upload majors (15: `GraphQLUpload.js`, 16+:
- * `GraphQLUpload.mjs`). Importing it from here keeps scalar and middleware one copy and leaves the
- * path to the framework.
+ * `GraphQLUpload.mjs`, the one this package imports since 12.1.0). Importing it from here keeps scalar
+ * and middleware one copy and leaves the path to the framework.
+ *
+ * A default import, never `import = require()` or `import * as`: graphql-upload 16+ is ESM, so under
+ * `require(esm)` both of those yield the module NAMESPACE, not the scalar. Compiled to CommonJS, the
+ * default import still reaches it — Node marks a required ES module that has a default export with
+ * `__esModule`, which the interop helper reads.
  *
  * The path is a CONTRACT with the lt CLI: its generator checks whether `common/scalars/upload.scalar` exists in
  * the framework root (`dist/core/` in npm mode, `src/core/` vendored) and only then writes

package/src/core/common/services/core-cron-jobs.initializer.ts

@@ -1,5 +1,5 @@
 import { Injectable, OnApplicationShutdown, OnModuleInit, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../persistence/mongo/mongoose-compat.js';
 import type { Connection } from 'mongoose';
 
 import { setCronJobsInfrastructure } from './core-cron-jobs.registry.js';

package/src/core/common/services/core-cron-jobs.service.ts

@@ -4,6 +4,7 @@ import { CronJob } from 'cron';
 
 import { CronJobConfigWithTimeZone } from '../interfaces/cron-job-config-with-time-zone.interface.js';
 import { CronJobConfigWithUtcOffset } from '../interfaces/cron-job-config-with-utc-offset.interface.js';
+import { CRON_LOCK_COLLECTION, cronMongoLocks, defaultSqlLockStore } from '../persistence/infrastructure-locks.js';
 import { Falsy } from '../types/falsy.type.js';
 import { getCronJobsInfrastructure } from './core-cron-jobs.registry.js';
 
@@ -21,14 +22,6 @@ const cronLogger = new Logger('CronJobs');
 const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 const errorStack = (error: unknown): string | undefined => (error instanceof Error ? error.stack : undefined);
 
-/**
- * Collection holding the per-tick cron leases.
- *
- * It has no Mongoose schema, so the native driver is the correct access path here
- * (see docs/native-driver-security.md).
- */
-const CRON_LOCK_COLLECTION = 'cron-locks';
-
 /**
  * Lifetime of a cron lease: long enough to outlive any tick, short enough to keep
  * the lock collection / keyspace small.
@@ -120,6 +113,13 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
   /** Cached creation of the TTL index on the lock collection */
   protected leaseIndexReady?: Promise<void>;
 
+  /**
+   * Owner of the leases this instance takes. Per-tick keys are unique, so the owner only names who ran a tick; the
+   * lease collection (`cron-locks`, no Mongoose schema — native access is correct, see
+   * docs/native-driver-security.md) keeps the 12.0.0 document so older replicas dedupe against it
+   */
+  protected readonly leaseOwner = `cron:${process.pid}:${Math.random().toString(36).slice(2)}`;
+
   // ===================================================================================================================
   // Initializations
   // ===================================================================================================================
@@ -303,27 +303,38 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       }
     }
 
-    const connection = this.getConnection();
-    if (!connection) {
+    const sqlLocks = await defaultSqlLockStore('cron').catch((e) => {
+      cronLogger.error(`Cron lease store unavailable, running the tick anyway: ${errorMessage(e)}`, errorStack(e));
+      return null;
+    });
+    if (sqlLocks === null) {
+      return true;
+    }
+    const connection = sqlLocks ? undefined : this.getConnection();
+    if (!sqlLocks && !connection) {
       this.warnDedupInactive();
       return true;
     }
 
-    await this.ensureLeaseIndex(connection);
     try {
-      await connection.db.collection(CRON_LOCK_COLLECTION).insertOne({
-        _id: leaseKey as any,
-        createdAt: new Date(),
-        // Per-document expiry, so the short init window and the long tick window can
-        // share one collection (a fixed expireAfterSeconds could only express one).
-        expiresAt: new Date(Date.now() + ttlSeconds * 1000),
-      });
-      return true;
-    } catch (e: any) {
-      if (e?.code === 11000) {
+      let acquired: boolean;
+      if (sqlLocks) {
+        acquired = await sqlLocks.tryAcquire(leaseKey, this.leaseOwner, ttlSeconds);
+      } else {
+        // The TTL index only collects old leases — for this version and for older replicas, which still claim with a
+        // plain insert. Whether a lease is free is decided by its expiresAt (LockStore), never by the TTL monitor.
+        await this.ensureLeaseIndex(connection);
+        acquired = await cronMongoLocks(connection.db.collection(CRON_LOCK_COLLECTION)).tryAcquire(
+          leaseKey,
+          this.leaseOwner,
+          ttlSeconds,
+        );
+      }
+      if (!acquired) {
         this.logSkippedTick(leaseKey);
-        return false;
       }
+      return acquired;
+    } catch (e) {
       cronLogger.error(`Cron lease for ${leaseKey} failed, running the tick anyway: ${errorMessage(e)}`, errorStack(e));
       return true;
     }

package/src/core/common/services/crud.service.ts

@@ -1,27 +1,21 @@
 import { Logger, NotFoundException } from '@nestjs/common';
-import {
-  AggregateOptions,
-  Collection,
-  Connection,
-  Document,
-  Model as MongooseModel,
-  PipelineStage,
-  Query,
-  QueryFilter,
-  QueryOptions,
-  Types,
-} from 'mongoose';
+import type { Collection, Document, Model as MongooseModel, PipelineStage, QueryFilter } from 'mongoose';
+import type { Query } from 'mongoose';
+import type { AggregateOptions, Connection, QueryOptions, Types } from 'mongoose';
 
 import { FilterArgs } from '../args/filter.args.js';
 import { getStringIds } from '../helpers/db.helper.js';
 import { convertFilterArgsToQuery } from '../helpers/filter.helper.js';
 import { mergePlain, prepareServiceOptionsForCreate } from '../helpers/input.helper.js';
 import { ServiceOptions } from '../interfaces/service-options.interface.js';
+import type { FindOptions, Where } from '../persistence/data-store.interface.js';
+import { UnsupportedCapabilityError } from '../persistence/unsupported-capability.error.js';
 import { CoreModel } from '../models/core-model.model.js';
 import { PaginationInfo } from '../models/pagination-info.model.js';
 import { PlainObject } from '../types/plain-object.type.js';
 import { ConfigService } from './config.service.js';
 import { ModuleService } from './module.service.js';
+import { isMongooseQuery } from '../persistence/mongo/mongoose-compat.js';
 
 export abstract class CrudService<
   Model extends CoreModel = any,
@@ -38,6 +32,7 @@ export abstract class CrudService<
     pipeline: PipelineStage[],
     serviceOptions?: ServiceOptions & { aggregateOptions?: AggregateOptions },
   ): Promise<T> {
+    this.assertMongooseStore('aggregate');
     return this.process(
       async () => {
         const aggregateOptions = serviceOptions?.aggregateOptions || {};
@@ -79,6 +74,9 @@ export abstract class CrudService<
     return this.process(
       async (data) => {
         const currentUserId = serviceOptions?.currentUser?.id;
+        if (this.usesNeutralStore) {
+          return this.dataStore.insert({ ...data.input, createdBy: currentUserId, updatedBy: currentUserId } as any);
+        }
         return new (this.mainDbModel as MongooseModel<Document & Model>)({
           ...data.input,
           createdBy: currentUserId,
@@ -113,13 +111,20 @@ export abstract class CrudService<
    * Get distinct values of a property
    */
   distinct(property: string): Promise<string[]> {
-    return this.mainDbModel.distinct(property).exec() as Promise<string[]>;
+    return this.dataStore.distinct(property) as Promise<string[]>;
   }
 
   /**
    * Get item by ID
    */
   async get(id: string, serviceOptions?: ServiceOptions): Promise<Model> {
+    if (this.usesNeutralStore) {
+      const record = await this.dataStore.findById(id, neutralSelect(serviceOptions?.select));
+      if (!record) {
+        throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
+      }
+      return this.process(async () => record, { dbObject: record, serviceOptions });
+    }
     const query = this.mainDbModel.findById(id);
     if (serviceOptions?.select) {
       query.select(serviceOptions.select);
@@ -179,6 +184,11 @@ export abstract class CrudService<
           filterQuery.queryOptions = converted[1];
         }
 
+        if (this.usesNeutralStore) {
+          const { options, where } = neutralQuery(filterQuery, serviceOptions);
+          return this.dataStore.find(where, options);
+        }
+
         // Find in DB
         let find = this.mainDbModel.find(filterQuery.filterQuery, null, filterQuery.queryOptions);
         const collation = serviceOptions?.collation || ConfigService.get('mongoose.collation');
@@ -247,6 +257,26 @@ export abstract class CrudService<
           filterQuery.queryOptions = converted[1];
         }
 
+        if (this.usesNeutralStore) {
+          const { options, where } = neutralQuery(filterQuery, serviceOptions);
+          const [items, totalCount] = await Promise.all([
+            this.dataStore.find(where, filter?.samples ? { ...options, sample: filter.samples } : options),
+            this.dataStore.count(where),
+          ]);
+          const queryOptions = filterQuery.queryOptions || {};
+          return {
+            items,
+            pagination: PaginationInfo.create({
+              limit: queryOptions.limit,
+              offset: queryOptions.offset,
+              skip: queryOptions.skip,
+              take: queryOptions.take,
+              totalCount,
+            }),
+            totalCount,
+          };
+        }
+
         // Prepare aggregation (with fixed defined sequence)
         const aggregation: PipelineStage[] = [];
 
@@ -408,6 +438,16 @@ export abstract class CrudService<
           filterQuery.queryOptions = converted[1];
         }
 
+        if (this.usesNeutralStore) {
+          const { options, where } = neutralQuery(filterQuery, serviceOptions);
+          return this.dataStore.findOne(where, {
+            collation: options.collation,
+            exclude: options.exclude,
+            select: options.select,
+            sort: options.sort,
+          });
+        }
+
         // Find in DB
         let find = this.mainDbModel.findOne(filterQuery.filterQuery, null, filterQuery.queryOptions);
         const collation = serviceOptions?.collation || ConfigService.get('mongoose.collation');
@@ -458,6 +498,7 @@ export abstract class CrudService<
    * to ensure plugins (Tenant, Audit, RoleGuard) fire correctly.
    */
   getModel(): MongooseModel<Document & Model> {
+    this.assertMongooseStore('getModel');
     return this.mainDbModel as unknown as MongooseModel<Document & Model>;
   }
 
@@ -481,6 +522,7 @@ export abstract class CrudService<
    */
   protected getNativeCollection(reason: string): Collection {
     this.validateNativeAccessReason(reason, 'getNativeCollection');
+    this.assertMongooseStore('getNativeCollection');
 
     const modelName = (this.mainDbModel as any)?.modelName || 'Unknown';
     Logger.warn(`[SECURITY] Native collection access: ${reason} (Model: ${modelName})`, this.constructor.name);
@@ -509,6 +551,7 @@ export abstract class CrudService<
    */
   protected getNativeConnection(reason: string): Connection {
     this.validateNativeAccessReason(reason, 'getNativeConnection');
+    this.assertMongooseStore('getNativeConnection');
 
     const modelName = (this.mainDbModel as any)?.modelName || 'Unknown';
     Logger.warn(`[SECURITY] Native connection access: ${reason} (Model: ${modelName})`, this.constructor.name);
@@ -614,6 +657,22 @@ export abstract class CrudService<
    * Update item via ID
    */
   async update(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions): Promise<Model> {
+    if (this.usesNeutralStore) {
+      const stored = await this.dataStore.findById(id);
+      if (!stored) {
+        throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
+      }
+      return this.process(
+        async (data) => {
+          // The same write as on MongoDB: the stored record merged with the input, written back whole — minus
+          // the id, which never changes, and the update time, which the store stamps
+          const merged = mergePlain(stored, data.input, { updatedBy: serviceOptions?.currentUser?.id });
+          const { _id: _mongoId, id: _id, updatedAt: _updatedAt, ...patch } = merged as Record<string, any>;
+          return this.dataStore.updateById(id, patch as any);
+        },
+        { dbObject: stored, input, serviceOptions },
+      );
+    }
     const dbObject = await this.mainDbModel.findById(id).lean();
     if (!dbObject) {
       throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
@@ -656,6 +715,19 @@ export abstract class CrudService<
    * Delete item via ID
    */
   async delete(id: string, serviceOptions?: ServiceOptions): Promise<Model> {
+    if (this.usesNeutralStore) {
+      const stored = await this.dataStore.findById(id, neutralSelect(serviceOptions?.select));
+      if (!stored) {
+        throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
+      }
+      return this.process(
+        async () => {
+          await this.dataStore.deleteById(id);
+          return stored;
+        },
+        { dbObject: stored, serviceOptions },
+      );
+    }
     const query = this.mainDbModel.findById(id);
     if (serviceOptions?.select) {
       query.select(serviceOptions.select);
@@ -728,22 +800,11 @@ export abstract class CrudService<
       return;
     }
 
-    const stringId = getStringIds(id);
-    const pushOp: any = { $each: itemsArray };
-    if (options?.$slice !== undefined) {
-      pushOp.$slice = options.$slice;
-    }
-    if (options?.$position !== undefined) {
-      pushOp.$position = options.$position;
-    }
-    if (options?.$sort) {
-      pushOp.$sort = options.$sort;
-    }
-
-    await this.mainDbModel
-      .findByIdAndUpdate(stringId, { $push: { [field]: pushOp } } as any)
-      .lean()
-      .exec();
+    await this.dataStore.pushToArray(getStringIds(id), field, itemsArray, {
+      position: options?.$position,
+      slice: options?.$slice,
+      sort: options?.$sort,
+    });
   }
 
   /**
@@ -771,11 +832,7 @@ export abstract class CrudService<
       throw new Error(`pullFromArray: invalid field name "${field}"`);
     }
 
-    const stringId = getStringIds(id);
-    await this.mainDbModel
-      .findByIdAndUpdate(stringId, { $pull: { [field]: condition } } as any)
-      .lean()
-      .exec();
+    await this.dataStore.pullFromArray(getStringIds(id), field, condition);
   }
 
   /**
@@ -791,7 +848,8 @@ export abstract class CrudService<
   ): Promise<T> {
     return this.process(
       () => {
-        if (queryOrDocument instanceof Query) {
+        if (isMongooseQuery(queryOrDocument)) {
+          this.assertMongooseStore('processQueryOrDocument (with a Mongoose query)');
           if (serviceOptions?.select && queryOrDocument.select && typeof queryOrDocument.select === 'function') {
             queryOrDocument.select(serviceOptions.select);
           }
@@ -802,4 +860,77 @@ export abstract class CrudService<
       { serviceOptions },
     );
   }
+
+  /**
+   * Refuse an API that only exists on MongoDB when the main model is stored elsewhere. The Mongoose model may still
+   * be registered for such a model, so continuing would read or write ANOTHER database without a word.
+   */
+  protected assertMongooseStore(method: string): void {
+    if (this.usesNeutralStore) {
+      throw new UnsupportedCapabilityError(
+        `${method}() needs a MongoDB store, but ${this.dataStore.modelName} is stored on ${this.dataStore.driver} — ` +
+          'use this.dataStore (or this.dataStore.native(reason) for the engine API)',
+      );
+    }
+  }
+}
+
+/**
+ * A `select` service option as a data store's projection: names to return, or — with MongoDB's `-name` — names to leave
+ * out. Both at once is refused by the store, as by MongoDB.
+ */
+function neutralSelect(select: unknown): Pick<FindOptions, 'exclude' | 'select'> {
+  if (select === undefined || select === null) {
+    return {};
+  }
+  const names =
+    typeof select === 'string'
+      ? select.split(/\s+/).filter(Boolean)
+      : Array.isArray(select)
+        ? select.map(String)
+        : Object.entries(select as Record<string, unknown>).map(([name, include]) => (include ? name : `-${name}`));
+  const exclude = names.filter((name) => name.startsWith('-')).map((name) => name.slice(1));
+  const include = names.filter((name) => !name.startsWith('-')).map((name) => (name === '_id' ? 'id' : name));
+  return {
+    ...(exclude.length ? { exclude } : {}),
+    ...(include.length ? { select: include } : {}),
+  };
+}
+
+/** The filter and query options of a CrudService call as the neutral filter and find options */
+function neutralQuery(
+  query: { filterQuery?: unknown; queryOptions?: QueryOptions },
+  serviceOptions?: ServiceOptions,
+): { options: FindOptions; where: Where } {
+  const queryOptions = query.queryOptions || {};
+  const options: FindOptions = {
+    collation: (serviceOptions?.collation || ConfigService.get('mongoose.collation')) as Record<string, unknown>,
+    ...neutralSelect(serviceOptions?.select),
+  };
+  const skip = queryOptions.skip ?? queryOptions.offset;
+  const limit = queryOptions.limit ?? queryOptions.take;
+  if (skip) {
+    options.skip = skip;
+  }
+  if (limit) {
+    options.limit = limit;
+  }
+  if (queryOptions.sort) {
+    options.sort = neutralSort(queryOptions.sort);
+  }
+  return { options, where: (query.filterQuery ?? {}) as Where };
+}
+
+function neutralSort(sort: unknown): Record<string, -1 | 1> {
+  const result: Record<string, -1 | 1> = {};
+  if (typeof sort === 'string') {
+    for (const token of sort.split(/\s+/).filter(Boolean)) {
+      result[token.replace(/^-/, '')] = token.startsWith('-') ? -1 : 1;
+    }
+    return result;
+  }
+  for (const [field, direction] of Object.entries(sort as Record<string, unknown>)) {
+    result[field] = direction === -1 || direction === 'desc' || direction === 'descending' ? -1 : 1;
+  }
+  return result;
 }

package/src/core/common/services/model-doc.service.ts

@@ -1,5 +1,5 @@
 import { Injectable, OnApplicationBootstrap } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../persistence/mongo/mongoose-compat.js';
 import * as fs from 'fs';
 import type { Connection } from 'mongoose';
 import YumlDiagram from 'yuml-diagram';

package/src/core/common/services/module.service.ts

@@ -1,17 +1,23 @@
 import _ from 'lodash';
-import { Document, Model, Types } from 'mongoose';
+import type { Document, Model } from 'mongoose';
+import type { Types } from 'mongoose';
 
 import { ProcessType } from '../enums/process-type.enum.js';
-import { getStringIds, popAndMap } from '../helpers/db.helper.js';
+import { getStringIds, popAndMap, toPopulateOptions } from '../helpers/db.helper.js';
 import { check } from '../helpers/input.helper.js';
 import { prepareInput, prepareOutput } from '../helpers/service.helper.js';
 import { getTranslatablePropertyKeys, updateLanguage } from '../decorators/translatable.decorator.js';
 import { ServiceOptions } from '../interfaces/service-options.interface.js';
 import { CoreModel } from '../models/core-model.model.js';
+import type { DataStore } from '../persistence/data-store.interface.js';
+import { MongooseDataStore } from '../persistence/mongoose-data-store.js';
+import { populateNeutral } from '../persistence/neutral-populate.js';
+import { getStoreForModel } from '../persistence/persistence-runtime.registry.js';
 import { FieldSelection } from '../types/field-selection.type.js';
 import { ConfigService } from './config.service.js';
 import { ModelRegistry } from './model-registry.service.js';
 import { RequestContext } from './request-context.service.js';
+import { isObjectIdLike } from '../helpers/id.helper.js';
 
 /**
  * Mongoose Model with native driver access paths removed to prevent
@@ -51,21 +57,76 @@ export abstract class ModuleService<T extends CoreModel = any> {
    */
   protected mainDbModel: SafeModel<Document & T>;
 
+  /** Store passed explicitly to the constructor */
+  private explicitDataStore?: DataStore<T>;
+
+  /** Store derived from `mainDbModel`, rebuilt when the model is replaced */
+  private derivedDataStore?: { model: unknown; store: DataStore<T> };
+
+  /**
+   * Database-neutral data store of the main model.
+   *
+   * Derived from `mainDbModel` when none is passed — at access time, not in the constructor, because a
+   * subclass may assign `mainDbModel` after `super()`. Operations whose semantics are identical on every
+   * database run through it already; the Mongoose-document path of the CRUD pipeline stays behind the
+   * store's `mongoosePopulate` capability until a SQL store provides the neutral one.
+   */
+  protected get dataStore(): DataStore<T> | undefined {
+    if (this.explicitDataStore) {
+      return this.explicitDataStore;
+    }
+    if (!this.mainDbModel) {
+      return undefined;
+    }
+    // A model registered with `CorePersistenceModule.forFeature()` is served by the store of its data source — also for
+    // a service that only received the Mongoose model, which is how every existing service is written
+    const routed = getStoreForModel(this.mainDbModel);
+    if (routed) {
+      return routed as DataStore<T>;
+    }
+    if (this.derivedDataStore?.model !== this.mainDbModel) {
+      this.derivedDataStore = {
+        model: this.mainDbModel,
+        store: new MongooseDataStore<T>(this.mainDbModel as unknown as Model<any>),
+      };
+    }
+    return this.derivedDataStore.store;
+  }
+
+  /**
+   * Whether the main model is stored without Mongoose documents (a SQL store): the CRUD pipeline then reads and
+   * writes plain records through `dataStore` and populates references through the stores of their models.
+   */
+  protected get usesNeutralStore(): boolean {
+    const store = this.dataStore;
+    return !!store && !store.capabilities.mongoosePopulate;
+  }
+
   /**
    * Set main properties
    */
   protected constructor(options?: {
     configService?: ConfigService;
+    dataStore?: DataStore<T>;
     mainDbModel?: Model<Document & T>;
     mainModelConstructor?: new (...args: any[]) => T;
   }) {
     this.configService = options?.configService;
     this.mainDbModel = options?.mainDbModel as SafeModel<Document & T>;
+    this.explicitDataStore = options?.dataStore;
+    // A service written against the store alone (`@InjectStore()`) runs on MongoDB too: the Mongoose path of the
+    // pipeline takes the model behind the store
+    if (!this.mainDbModel && options?.dataStore?.capabilities.mongoosePopulate) {
+      this.mainDbModel = options.dataStore.native<SafeModel<Document & T>>(
+        'CrudService pipeline: the Mongoose model behind this data store',
+      );
+    }
     this.mainModelConstructor = options?.mainModelConstructor;
 
     // Auto-register model class for ResponseModelInterceptor lookups
-    if (options?.mainModelConstructor && options?.mainDbModel?.modelName) {
-      ModelRegistry.register(options.mainDbModel.modelName, options.mainModelConstructor);
+    const modelName = this.mainDbModel?.modelName ?? options?.dataStore?.modelName;
+    if (options?.mainModelConstructor && modelName) {
+      ModelRegistry.register(modelName, options.mainModelConstructor);
     }
   }
 
@@ -209,8 +270,15 @@ export abstract class ModuleService<T extends CoreModel = any> {
     // S_CREATOR and S_SELF checks. The full process() pipeline would remove
     // restricted fields, potentially breaking these checks.
     if (config.dbObject && config.checkRights && this.checkRights) {
-      if (typeof config.dbObject === 'string' || config.dbObject instanceof Types.ObjectId) {
-        if (this.mainDbModel) {
+      if (typeof config.dbObject === 'string' || isObjectIdLike(config.dbObject)) {
+        if (this.usesNeutralStore) {
+          const record = await this.dataStore.findById(getStringIds(config.dbObject));
+          if (record) {
+            config.dbObject = (this.mainModelConstructor as any)?.map
+              ? (this.mainModelConstructor as any).map(record)
+              : record;
+          }
+        } else if (this.mainDbModel) {
           const rawDoc = await this.mainDbModel.findById(getStringIds(config.dbObject)).lean().exec();
           if (rawDoc) {
             config.dbObject = (this.mainModelConstructor as any)?.map
@@ -429,6 +497,10 @@ export abstract class ModuleService<T extends CoreModel = any> {
       model?: new (...args: any[]) => T;
     } = {},
   ) {
+    if (this.usesNeutralStore && !options.dbModel) {
+      await populateNeutral(data, toPopulateOptions(fieldsSelection) as any, this.dataStore.modelName);
+      return data;
+    }
     const config = {
       dbModel: this.mainDbModel,
       model: this.mainModelConstructor,

package/src/core/common/types/field-selection.type.ts

@@ -1,5 +1,5 @@
 import { SelectionNode } from 'graphql';
-import { PopulateOptions } from 'mongoose';
+import type { PopulateOptions } from 'mongoose';
 
 import { ResolveSelector } from '../interfaces/resolve-selector.interface.js';
 

package/src/core/common/types/id.type.ts

@@ -1,3 +1,3 @@
-import { Types } from 'mongoose';
+import type { ObjectIdLike } from './object-id-like.type.js';
 
-export type IdType = string | Types.ObjectId | { _id?: string | Types.ObjectId; id?: string | Types.ObjectId };
+export type IdType = ObjectIdLike | string | { _id?: ObjectIdLike | string; id?: ObjectIdLike | string };

package/src/core/common/types/object-id-like.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Structural shape of an ObjectId, from whichever bson copy created it.
+ *
+ * The id types describe ids by shape instead of by `mongoose`'s `Types.ObjectId` class: a class
+ * identity breaks across two installed copies of bson (`instanceof` fails), and the id types must not
+ * tie the core to the MongoDB driver now that ids are opaque strings on every database. A mongoose
+ * `Types.ObjectId` satisfies this shape, so every caller that passed one keeps compiling.
+ */
+export interface ObjectIdLike {
+  toHexString(): string;
+}

package/src/core/common/types/populate-config.type.ts

@@ -1,4 +1,4 @@
-import { PopulateOptions } from 'mongoose';
+import type { PopulateOptions } from 'mongoose';
 
 /**
  * Configuration (path or options) for Mongoose populate methode

package/src/core/common/types/string-or-object-id.type.ts

@@ -1,6 +1,6 @@
-import { Types } from 'mongoose';
+import type { ObjectIdLike } from './object-id-like.type.js';
 
 /**
  * Everything which will be used by getStringIds or getObjectIds (see helpers/db.helper.ts)
  */
-export type StringOrObjectId<T = any> = string | T | Types.ObjectId;
+export type StringOrObjectId<T = any> = ObjectIdLike | string | T;

package/src/core/modules/ai/README.md

@@ -213,6 +213,16 @@ Matching details worth knowing before you debug a refusal:
   and the framework logs an error — from the outside that state is indistinguishable from
   "correctly unset", which is exactly why it is not silent.
 
+## Where the data lives
+
+The module's eleven models (connections, preferences, conversations, interactions, budget limits,
+prompts, prompt hints, slots, modes, tool grants, tool policies) are registered through
+`CorePersistenceModule.forFeature()` and every service works on its model's data store, so `database`
+routes them like any model — MongoDB or a SQL source, one code path. Budget sums run in the store
+(`sum()`), across tenants as before; an expired tool grant is refused on read, and on SQL the expiry
+sweep removes it. Code of your own that reads these models goes through the store
+(`@InjectStore('<model>')`), not through `connection.collection()`.
+
 ## Connections (DB configuration)
 
 Connections live in the `aiConnections` collection and are managed by admins via
@@ -690,8 +700,11 @@ Without Redis nothing changes: unknown ids answer `404` exactly as before.
 
 For generic MCP clients that auto-discover + register:
 `CoreAiMcpOAuthService` provides HMAC-signed access tokens (constant-time verify),
-PKCE S256, and MongoDB-backed client/code/refresh stores; the MCP controller then
-also accepts OAuth access tokens.
+PKCE S256, and client/code/refresh stores; the MCP controller then also accepts OAuth access
+tokens. The stores live wherever `database` routes the models `AiMcpOAuthClient`, `AiMcpOAuthCode`
+and `AiMcpOAuthRefreshToken` (MongoDB collections, or SQL tables). An authorization code is refused
+on read once it is older than ten minutes, on both databases — never only by a TTL index, which
+deletes late; on SQL the expiry sweep removes old codes, on MongoDB the TTL index does.
 
 ```typescript
 // config.env.ts — that is all: endpoints, consent page and sign-in come with it