@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/repositories/postgresql-resource-repository.backend.service.ts

@@ -0,0 +1,1207 @@
+import type {
+  ResourceConfiguration,
+  ResourceConfiguration_Operation,
+  ResourceConfiguration_OperationRepositoryPath,
+  ResourceType,
+} from '@wildo-ai/saas-models';
+import {
+  CoreResourceOperation,
+  ErrorCustomMessageReference,
+  ErrorType,
+  ResourceOperationsUtils,
+  ResourcesConfig_OperationPathUtils,
+  Resources_PaginationRequest,
+  Resources_PaginatedResult,
+} from '@wildo-ai/saas-models';
+import type { ResourceFilter } from '~wildo-backend-lib/databases/models/filter.backend.schemas';
+import type { TransactionContext } from '~wildo-backend-lib/databases/models/transaction.shared.schemas';
+import type { EnumLikeType } from '@wildo-ai/zod-decorators';
+import type { z } from 'zod';
+
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import type { ResourceOperationHelperBackendService } from '~wildo-backend-lib/base-classes/services/resource-operations-helper.backend.service';
+import type {
+  IdOrFilterType,
+  IdOrIdsOrFilterType,
+  IdsOrFilterType,
+  RepositoryOptions,
+} from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import type { SqlWhereExpression } from '~wildo-backend-lib/databases/models/sql.backend.schemas';
+import type { PostgreSQLDatabaseBackendService } from '~wildo-backend-lib/databases/services/postgresql-database.backend.service';
+import { PostgreSQLFilterBackendService } from '~wildo-backend-lib/databases/services/postgresql-filter.backend.service';
+import { ZodToSqlHybridSchemaPlannerBackendService } from '~wildo-backend-lib/databases/services/zod-to-sql-hybrid-schema.planner';
+import type { ResourceIdBackendService } from '~wildo-backend-lib/resources/services/resource-id.backend.service';
+import { sql } from 'kysely';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+// Forward declaration to avoid circular dependency (matches Mongo repository style)
+type RepositoriesRegistryHandlerBackendService = any;
+
+/**
+ * PostgreSQL Repository Skeleton (Hybrid JSONB + Kysely)
+ *
+ * NOTE:
+ * - This is a scaffolding class to be completed in the next steps.
+ * - It mirrors `RepositoryResourceBackendService` construction (per resourceType),
+ *   but targets PostgreSQL via Kysely.
+ * - Migrations/DDL are owned by apps-manager.
+ */
+export class PostgreSQLResourceRepositoryBackendService<
+  TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+  TMainSchema extends z.ZodTypeAny = z.ZodTypeAny
+> {
+  private readonly resourceConfiguration: ResourceConfiguration<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+  private readonly filterService: PostgreSQLFilterBackendService;
+  private readonly jsonbRoots: Set<string>;
+  private readonly tableName: string;
+  private readonly operationsMap: Map<string, ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>>;
+  private readonly plannedFieldNames: Set<string>;
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    resourceType: ResourceType,
+    private readonly dbService: PostgreSQLDatabaseBackendService,
+    private readonly logger: LoggerService,
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    private readonly resourceRegistry: ResourcesRegistryBackendService,
+    private readonly resourceOperationHelper: ResourceOperationHelperBackendService,
+    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    private readonly sqlPlanner: ZodToSqlHybridSchemaPlannerBackendService,
+    private readonly resourceIdService?: ResourceIdBackendService
+  ) {
+    this.resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+    this.logDebug = this.logger.debugByType(`PostgreSQLRepositoryResource_${resourceType}`);
+    this.logger.setDebugTypeLogging(`PostgreSQLRepositoryResource_${resourceType}`, false);
+
+    // Configure JSONB roots for dot-notation support:
+    // - always include variantConfig for hybrid inheritance
+    // - include any object/array fields planned as JSONB
+    const planned = this.sqlPlanner.planSqlHybridTable(
+      this.resourceConfiguration as any,
+      this.resourceConfiguration.mainSchema as any
+    );
+    this.jsonbRoots = new Set<string>(
+      planned.fields.filter((f) => f.storage === 'jsonb').map((f) => f.name)
+    );
+    this.jsonbRoots.add('variantConfig');
+    this.plannedFieldNames = new Set<string>(planned.fields.map((f) => f.name));
+
+    this.filterService = new PostgreSQLFilterBackendService(this.logger, this.errorBuilder);
+    this.filterService.setJsonbFields(this.jsonbRoots);
+
+    this.tableName = PostgreSQLFilterBackendService.normalizeTableName(String(this.resourceConfiguration.resourceIdentifier));
+
+    this.operationsMap = new Map();
+    this.initializeOperationsMap();
+
+    this.logDebug('PostgreSQL repository skeleton created', {
+      resourceType: this.resourceConfiguration.resourceIdentifier,
+      tableName: this.tableName,
+      jsonbRoots: Array.from(this.jsonbRoots),
+    });
+  }
+
+  /**
+   * Extract native SQL transaction client from RepositoryOptions (if any).
+   * Includes a runtime safety check similar to Mongo repository.
+   */
+  protected getTransaction(options?: RepositoryOptions): TransactionContext | undefined {
+    if (!options?.transaction) return undefined;
+    if (options.transaction.databaseType !== 'postgresql') {
+      throw new Error(
+        `PostgreSQL repository received non-PostgreSQL transaction. ` +
+          `Expected databaseType='postgresql', got '${options.transaction.databaseType}'.`
+      );
+    }
+    return options.transaction;
+  }
+
+  /**
+   * Build a SQL where expression from a Mongo-style filter.
+   */
+  protected buildWhere(filter: ResourceFilter | null | undefined): SqlWhereExpression | null {
+    return this.filterService.buildWhereExpression(filter);
+  }
+
+  // ===========================================================================
+  // Operation routing (align with Mongo repository surface)
+  // ===========================================================================
+
+  public async doByPath<T = any, U = any>(
+    operationRepositoryPath: ResourceConfiguration_OperationRepositoryPath,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const key = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKey(operationRepositoryPath);
+    return this.doByKey<T, U>(key, executionContext, id_or_ids_or_filter, data, options);
+  }
+
+  public async doByKey<T = any, U = any>(
+    operationRepositoryPathKey: string,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    ResourcesConfig_OperationPathUtils.validateOperationRepositoryPathKey(operationRepositoryPathKey);
+
+    const operation = this.operationsMap.get(operationRepositoryPathKey);
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationRepositoryPathKey },
+      });
+    }
+
+    return (await this.doOperation(operation, executionContext, id_or_ids_or_filter, data, options)) as T;
+  }
+
+  public async doByExecutionContext<T = any>(
+    executionContext: ExecutionContext<ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>>,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const operation = executionContext.operation;
+    const id_or_ids_or_filter = this.resourceOperationHelper.extractIdsFromExecutionContext(
+      executionContext,
+      this.resourceConfiguration.resourceFieldIdentifier
+    );
+    return (await this.doOperation(operation, executionContext, id_or_ids_or_filter as any, data, options)) as T;
+  }
+
+  private async doOperation(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const operationRepositoryPathKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKeyFromOperation(operation);
+
+    if (operation.resourceIdentifier !== this.resourceConfiguration.resourceIdentifier) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationRepositoryPathKey, resourceIdentifier: this.resourceConfiguration.resourceIdentifier },
+      });
+    }
+
+    const opIdentifier = ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation);
+    if (!opIdentifier) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationRepositoryPathKey },
+      });
+    }
+
+    switch (opIdentifier) {
+      case CoreResourceOperation.CREATE:
+        return this._doCreate(operation, executionContext, data, options);
+      case CoreResourceOperation.CREATE_MANY:
+        return this._doCreateMany(operation, executionContext, data, options);
+      case CoreResourceOperation.READ:
+        if (Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+            context: { operationRepositoryPathKey, id_or_ids_or_filter },
+          });
+        }
+        return this._doRead(operation, executionContext, id_or_ids_or_filter as any, options);
+      case CoreResourceOperation.UPDATE:
+        if (Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+            context: { operationRepositoryPathKey, id_or_ids_or_filter },
+          });
+        }
+        return this._doUpdate(operation, executionContext, id_or_ids_or_filter as any, data, options);
+      case CoreResourceOperation.UPDATE_MANY:
+        return this._doUpdateMany(operation, executionContext, id_or_ids_or_filter as IdsOrFilterType, data, options);
+      case CoreResourceOperation.DELETE:
+        if (Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+            context: { operationRepositoryPathKey, id_or_ids_or_filter },
+          });
+        }
+        return this._doDelete(operation, executionContext, id_or_ids_or_filter as any, options);
+      case CoreResourceOperation.DELETE_MANY:
+        return this._doDeleteMany(operation, executionContext, id_or_ids_or_filter as any, options);
+      case CoreResourceOperation.LIST:
+        return this._doList(operation, executionContext, id_or_ids_or_filter as any, options);
+      case CoreResourceOperation.COUNT:
+        return this._doCount(operation, executionContext, id_or_ids_or_filter as any, options);
+      case CoreResourceOperation.SEARCH:
+        return this._doSearch(operation, executionContext, data?.query || '', {}, options as any);
+      default:
+        throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+          customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+          context: { resourceIdentifier: this.resourceConfiguration.resourceIdentifier, opIdentifier },
+        });
+    }
+  }
+
+  private initializeOperationsMap(): void {
+    const ops = this.resourceConfiguration.operations || [];
+    for (const operation of ops) {
+      const key = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKeyFromOperation(operation);
+      if (this.operationsMap.has(key)) {
+        this.logger.warn(`Duplicate repository operation key '${key}' for resource '${String(this.resourceConfiguration.resourceIdentifier)}'. Last operation wins.`);
+      }
+      this.operationsMap.set(key, operation);
+    }
+  }
+
+  // The method surface should mirror the Mongo repository public API so the
+  // service layer can remain database-agnostic.
+  //
+  // Implementation will:
+  // - Use this.dbService.getDb() to get a Kysely instance
+  // - Apply SqlWhereExpression compilation to Kysely query builder
+  // - Apply hybrid transforms via sqlPlanner.transformForSqlWrite/transformFromSqlRead
+  // - Respect RepositoryOptions.transaction (nativeSession contains transaction client)
+
+  // NOTE: These signatures are intentionally aligned with the resource-system expectations
+  // but kept minimal for initial PostgreSQL adapter bring-up.
+
+  public async create<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.CREATE && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.CREATE },
+      });
+    }
+    return this._doCreate(operation as any, executionContext, data, options);
+  }
+
+  public async createMany<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    data: any[],
+    options?: RepositoryOptions
+  ): Promise<any[]> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.CREATE_MANY && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.CREATE_MANY },
+      });
+    }
+    return this._doCreateMany(operation as any, executionContext, data, options);
+  }
+
+  public async read<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.READ && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.READ },
+      });
+    }
+    return this._doRead(operation as any, executionContext, id_or_filter, options);
+  }
+
+  public async update<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.UPDATE && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.UPDATE },
+      });
+    }
+    return this._doUpdate(operation as any, executionContext, id_or_filter, data, options);
+  }
+
+  public async updateMany<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any[]> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.UPDATE_MANY && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.UPDATE_MANY },
+      });
+    }
+    return this._doUpdateMany(operation as any, executionContext, undefined, data, options);
+  }
+
+  public async delete(
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter: IdOrIdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.DELETE && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.DELETE },
+      });
+    }
+    const deleted = await this._doDelete(operation as any, executionContext, id_or_ids_or_filter, options);
+    return deleted?._id ?? deleted?.id ?? '';
+  }
+
+  public async deleteMany(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string[]> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.DELETE_MANY && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.DELETE_MANY },
+      });
+    }
+    return this._doDeleteMany(operation as any, executionContext, ids_or_filter, options);
+  }
+
+  public async list<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<any[]>;
+  public async list<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options: RepositoryOptions & { paginated: true; listOptions?: Partial<Resources_PaginationRequest> }
+  ): Promise<Resources_PaginatedResult<any>>;
+  public async list<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions & { listOptions?: Partial<Resources_PaginationRequest>; paginated?: boolean }
+  ): Promise<any[] | Resources_PaginatedResult<any>> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.LIST && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.LIST },
+      });
+    }
+    return this._doList(operation as any, executionContext, ids_or_filter, options);
+  }
+
+  public async search<T = any>(
+    executionContext: ExecutionContext<any>,
+    searchQuery: string,
+    filter: any = {},
+    searchOptions: any = {},
+    options?: RepositoryOptions
+  ): Promise<Resources_PaginatedResult<T>> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.SEARCH && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.SEARCH },
+      });
+    }
+    return this._doSearch(operation as any, executionContext, searchQuery, filter, { ...options, searchOptions } as any);
+  }
+
+  public async count(
+    executionContext: ExecutionContext<any>,
+    filter: any = {},
+    options?: RepositoryOptions
+  ): Promise<{ count: number }> {
+    const operation = this.resourceConfiguration.operations.find(
+      (op) => op.operationIdentifier === CoreResourceOperation.COUNT && op.isDefault
+    );
+    if (!operation) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.COUNT },
+      });
+    }
+    return this._doCount(operation as any, executionContext, filter, options);
+  }
+
+  public supportsOperation(operationIdentifier: string): boolean {
+    return this.resourceConfiguration.operations.some(
+      (op) => op.operationIdentifier === operationIdentifier && op.isDefault
+    );
+  }
+
+  // ===========================================================================
+  // Core private ops (initial subset)
+  // ===========================================================================
+
+  private async _doCreate(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const cleaned = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.CREATE);
+    const validated = this.repositoriesRegistry.validateRequestData(
+      cleaned,
+      this.resourceConfiguration.resourceIdentifier as ResourceType,
+      CoreResourceOperation.CREATE
+    );
+    const enriched = this.resourceOperationHelper.enrichDataWithContext(
+      validated,
+      executionContext,
+      this.resourceConfiguration.mainSchema,
+      this.resourceConfiguration.resourceFieldIdentifier,
+      CoreResourceOperation.CREATE,
+      options
+    );
+
+    if (executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable) {
+      enriched.userId = null;
+    }
+
+    const withLiterals = this.resourceOperationHelper.injectNonDiscriminatorLiteralValues(
+      enriched,
+      this.resourceConfiguration.mainSchema
+    );
+
+    const withTracking = this.addUserTrackingAndTimestamps(withLiterals, executionContext, CoreResourceOperation.CREATE);
+
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+    const toWrite = this.sqlPlanner.transformForSqlWrite(withTracking, inheritanceDef);
+
+    const inserted = await db
+      .insertInto(this.tableName)
+      .values(toWrite as any)
+      .returningAll()
+      .executeTakeFirst();
+
+    if (!inserted) return null;
+    return this.sqlPlanner.transformFromSqlRead(inserted as any, inheritanceDef);
+  }
+
+  private async _doCreateMany(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any[]> {
+    const dataArray = Array.isArray(data) ? data : [];
+    const cleanedArray = this.resourceOperationHelper.cleanInputDataArray(dataArray, CoreResourceOperation.CREATE_MANY);
+    const isBulkOperation = 'isBulkOperation' in operation && operation.isBulkOperation === true;
+    const validatedArray = cleanedArray.map((item) =>
+      this.repositoriesRegistry.validateRepositoryWriteData(
+        item,
+        this.resourceConfiguration.resourceIdentifier as ResourceType,
+        String(operation.operationIdentifier),
+        isBulkOperation
+      )
+    ) as any[];
+
+    const isAnonymousCreate = executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable;
+    const enrichedArray = (Array.isArray(validatedArray) ? validatedArray : []).map((item) => {
+      const enriched = this.resourceOperationHelper.enrichDataWithContext(
+        item,
+        executionContext,
+        this.resourceConfiguration.mainSchema,
+        this.resourceConfiguration.resourceFieldIdentifier,
+        CoreResourceOperation.CREATE_MANY,
+        options
+      );
+      if (isAnonymousCreate) { enriched.userId = null; }
+      return enriched;
+    });
+
+    const withLiteralsArray = enrichedArray.map((item) =>
+      this.resourceOperationHelper.injectNonDiscriminatorLiteralValues(item, this.resourceConfiguration.mainSchema)
+    );
+
+    const withTrackingArray = withLiteralsArray.map((item) =>
+      this.addUserTrackingAndTimestamps(item, executionContext, CoreResourceOperation.CREATE)
+    );
+
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+    const toWriteArray = withTrackingArray.map((item) => this.sqlPlanner.transformForSqlWrite(item, inheritanceDef));
+
+    if (toWriteArray.length === 0) return [];
+
+    const insertedRows = await db.insertInto(this.tableName).values(toWriteArray as any).returningAll().execute();
+    return insertedRows.map((row: any) => this.sqlPlanner.transformFromSqlRead(row, inheritanceDef));
+  }
+
+  private async _doRead(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    // Align with Mongo behavior: READ requires an id or filter.
+    if (!id_or_filter) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { operationIdentifier: CoreResourceOperation.READ, message: 'READ requires an id_or_filter' },
+      });
+    }
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const { baseFilter } = this.buildBaseFilterFromIdOrFilter(id_or_filter, executionContext);
+    const contextualFilter = this.buildContextualFilter(executionContext, baseFilter, options);
+    const where = this.buildWhere(contextualFilter);
+
+    const qb = this.filterService.applyWhere(db.selectFrom(this.tableName).selectAll(), where);
+    const row = await qb.executeTakeFirst();
+
+    if (!row) return null;
+    return this.sqlPlanner.transformFromSqlRead(row as any, inheritanceDef);
+  }
+
+  private async _doUpdate(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const { baseFilter } = this.buildBaseFilterFromIdOrFilter(id_or_filter, executionContext);
+    const id = await this.resolveSingleId(executionContext, baseFilter, options);
+    if (!id) return null;
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const cleaned = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.UPDATE);
+    const isBulkOperation = 'isBulkOperation' in operation && operation.isBulkOperation === true;
+    const validated = this.repositoriesRegistry.validateRepositoryWriteData(
+      cleaned,
+      this.resourceConfiguration.resourceIdentifier as ResourceType,
+      String(operation.operationIdentifier),
+      isBulkOperation
+    );
+    const enriched = this.resourceOperationHelper.enrichDataWithContext(
+      validated,
+      executionContext,
+      this.resourceConfiguration.mainSchema,
+      this.resourceConfiguration.resourceFieldIdentifier,
+      CoreResourceOperation.UPDATE,
+      options
+    );
+
+    const withTracking = this.addUserTrackingAndTimestamps(enriched, executionContext, CoreResourceOperation.UPDATE);
+    const toWrite = this.sqlPlanner.transformForSqlWrite(withTracking, inheritanceDef);
+
+    const contextualFilter = this.buildContextualFilter(executionContext, { _id: id } as any, options);
+    const scopedWhere = this.buildWhere(contextualFilter);
+
+    const updated = await db
+      .updateTable(this.tableName)
+      .set(toWrite as any)
+      .$call((qb: any) => this.filterService.applyWhere(qb, scopedWhere))
+      .returningAll()
+      .executeTakeFirst();
+
+    if (!updated) return null;
+    return this.sqlPlanner.transformFromSqlRead(updated as any, inheritanceDef);
+  }
+
+  private async _doDelete(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter: IdOrIdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const { baseFilter } = this.buildBaseFilterFromIdOrFilter(id_or_ids_or_filter as any, executionContext);
+    const id = await this.resolveSingleId(executionContext, baseFilter, options);
+    if (!id) return null;
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const contextualFilter = this.buildContextualFilter(executionContext, { _id: id } as any, options);
+    const scopedWhere = this.buildWhere(contextualFilter);
+
+    const deleted = await db
+      .deleteFrom(this.tableName)
+      .$call((qb: any) => this.filterService.applyWhere(qb, scopedWhere))
+      .returningAll()
+      .executeTakeFirst();
+
+    if (!deleted) return null;
+    return this.sqlPlanner.transformFromSqlRead(deleted as any, inheritanceDef);
+  }
+
+  private async _doDeleteMany(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string[]> {
+    const db = await this.getDbOrTrx(options);
+
+    const filter = this.normalizeIdsOrFilter(ids_or_filter);
+    const contextualFilter = this.buildContextualFilter(executionContext, filter, options);
+    const where = this.buildWhere(contextualFilter);
+
+    // Return deleted ids (best-effort; depends on table having _id)
+    const deletedRows = await db
+      .deleteFrom(this.tableName)
+      .$call((qb: any) => this.filterService.applyWhere(qb, where))
+      .returning(['_id' as any])
+      .execute();
+
+    return (deletedRows || [])
+      .map((r: any) => r?._id)
+      .filter((v: any) => typeof v === 'string' && v.length > 0);
+  }
+
+  private async _doUpdateMany(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType | undefined,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<any[]> {
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const cleaned = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.UPDATE_MANY);
+    const isBulkOperation = 'isBulkOperation' in operation && operation.isBulkOperation === true;
+    const validated = this.repositoriesRegistry.validateRepositoryWriteData(
+      cleaned,
+      this.resourceConfiguration.resourceIdentifier as ResourceType,
+      String(operation.operationIdentifier),
+      isBulkOperation
+    );
+    const enriched = this.resourceOperationHelper.enrichDataWithContext(
+      validated,
+      executionContext,
+      this.resourceConfiguration.mainSchema,
+      this.resourceConfiguration.resourceFieldIdentifier,
+      CoreResourceOperation.UPDATE_MANY,
+      options
+    );
+
+    const withTracking = this.addUserTrackingAndTimestamps(enriched, executionContext, CoreResourceOperation.UPDATE);
+    const toWrite = this.sqlPlanner.transformForSqlWrite(withTracking, inheritanceDef);
+
+    const filter = this.normalizeIdsOrFilter(ids_or_filter);
+    const contextualFilter = this.buildContextualFilter(executionContext, filter, options);
+    const where = this.buildWhere(contextualFilter);
+
+    const updatedRows = await db
+      .updateTable(this.tableName)
+      .set(toWrite as any)
+      .$call((qb: any) => this.filterService.applyWhere(qb, where))
+      .returningAll()
+      .execute();
+
+    return (updatedRows || []).map((row: any) => this.sqlPlanner.transformFromSqlRead(row, inheritanceDef));
+  }
+
+  private async _doList(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter?: IdsOrFilterType,
+    options?: RepositoryOptions & { listOptions?: { page?: number; limit?: number }; paginated?: boolean }
+  ): Promise<any[] | Resources_PaginatedResult<any>> {
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const filter = this.normalizeIdsOrFilter(ids_or_filter);
+    const contextualFilter = this.buildContextualFilter(executionContext, filter, options);
+    const where = this.buildWhere(contextualFilter);
+
+    const paginated = (options as any)?.paginated ?? false;
+    const listOptions = (options as any)?.listOptions;
+    const hasPagination = paginated || listOptions?.page !== undefined || listOptions?.limit !== undefined;
+
+    let page = 1;
+    let limit = 0;
+    let offset = 0;
+    let total = 0;
+    let totalPages = 1;
+
+    if (paginated || hasPagination) {
+      const countRow = await this.filterService.applyWhere(
+        db.selectFrom(this.tableName).select(sql<number>`count(*)`.as('count')),
+        where
+      ).executeTakeFirst();
+
+      const countVal = (countRow as any)?.count;
+      total = typeof countVal === 'number' ? countVal : typeof countVal === 'string' ? Number(countVal) : 0;
+      page = Math.max(1, listOptions?.page || 1);
+      limit = Math.min(100, Math.max(1, listOptions?.limit || 20));
+      offset = (page - 1) * limit;
+      totalPages = limit > 0 ? Math.max(1, Math.ceil(total / limit)) : 1;
+    }
+
+    let qb: any = this.filterService.applyWhere(db.selectFrom(this.tableName).selectAll(), where);
+    if (this.plannedFieldNames.has('createdAt')) {
+      qb = qb.orderBy('createdAt', 'desc');
+    }
+    if (hasPagination) {
+      qb = qb.limit(limit).offset(offset);
+    }
+
+    const rows = await qb.execute();
+    const dataRows = rows.map((r: any) => this.sqlPlanner.transformFromSqlRead(r, inheritanceDef));
+
+    if (paginated) {
+      return {
+        data: dataRows,
+        pagination: { page, limit: limit || dataRows.length, total: total || dataRows.length, totalPages },
+      };
+    }
+
+    return dataRows;
+  }
+
+  private async _doSearch<T = any>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    searchQuery: string,
+    filter: any = {},
+    options?: RepositoryOptions & { searchOptions?: { fieldsToSearch?: string[]; page?: number; limit?: number; sort?: any } }
+  ): Promise<Resources_PaginatedResult<T>> {
+    const db = await this.getDbOrTrx(options);
+    const inheritanceDef = (this.resourceConfiguration as any)?.inheritenceSchemaDefinition;
+
+    const searchConfig = this.findSearchOperationConfiguration();
+    if (!searchConfig) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_SEARCH_NOT_CONFIGURED,
+      });
+    }
+
+    const op = searchConfig as unknown as {
+      isSearchable?: boolean;
+      maxPaginatedResultPerPageLimit?: number;
+    };
+
+    if (!op.isSearchable) {
+      throw this.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_SEARCH_NOT_ENABLED,
+      });
+    }
+
+    const trimmed = String(searchQuery || '').trim();
+    const baseFilter = this.sanitizeRequestFilter(filter, searchConfig);
+
+    const page = Math.max(1, options?.searchOptions?.page || 1);
+    const maxLimit = op.maxPaginatedResultPerPageLimit || 50;
+    const limit = Math.min(maxLimit, Math.max(1, options?.searchOptions?.limit || 20));
+    const offset = (page - 1) * limit;
+
+    const searchFilter = trimmed
+      ? this.constructSearchQuery(trimmed, searchConfig, options?.searchOptions?.fieldsToSearch)
+      : {};
+    const combinedFilter = trimmed ? ({ $and: [baseFilter, searchFilter] } as any) : baseFilter;
+    const contextualFilter = this.buildContextualFilter(executionContext, combinedFilter, options);
+    const where = this.buildWhere(contextualFilter);
+
+    const sortOptions = this.constructValidatedSortOptions(options?.searchOptions?.sort, searchConfig);
+
+    let qb: any = this.filterService.applyWhere(db.selectFrom(this.tableName).selectAll(), where);
+    if (sortOptions.length > 0) {
+      sortOptions.forEach((s) => {
+        qb = qb.orderBy(s.field, s.direction);
+      });
+    } else if (this.plannedFieldNames.has('createdAt')) {
+      qb = qb.orderBy('createdAt', 'desc');
+    }
+
+    qb = qb.limit(limit).offset(offset);
+
+    const countRow = await this.filterService.applyWhere(
+      db.selectFrom(this.tableName).select(sql<number>`count(*)`.as('count')),
+      where
+    ).executeTakeFirst();
+
+    const countVal = (countRow as any)?.count;
+    const total = typeof countVal === 'number' ? countVal : typeof countVal === 'string' ? Number(countVal) : 0;
+
+    const rows = await qb.execute();
+    const data = rows.map((r: any) => this.sqlPlanner.transformFromSqlRead(r, inheritanceDef)) as T[];
+
+    return {
+      data,
+      pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+    };
+  }
+
+  private async _doCount(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    filter: any = {},
+    options?: RepositoryOptions
+  ): Promise<{ count: number }> {
+    const db = await this.getDbOrTrx(options);
+    const contextualFilter = this.buildContextualFilter(executionContext, filter as any, options);
+    const where = this.buildWhere(contextualFilter);
+
+    const qb = this.filterService.applyWhere(
+      db.selectFrom(this.tableName).select(sql<number>`count(*)`.as('count')),
+      where
+    );
+
+    const row = await qb.executeTakeFirst();
+    const countVal = (row as any)?.count;
+    if (typeof countVal === 'number') return { count: countVal };
+    if (typeof countVal === 'string') return { count: Number(countVal) };
+    return { count: 0 };
+  }
+
+  // ===========================================================================
+  // DB client resolution
+  // ===========================================================================
+
+  private async getDbOrTrx(options?: RepositoryOptions): Promise<any> {
+    const tx = this.getTransaction(options);
+    if (tx) {
+      return tx.nativeSession as any;
+    }
+    return await this.dbService.getDb();
+  }
+
+  // ===========================================================================
+  // Helpers
+  // ===========================================================================
+
+  private normalizeIdsOrFilter(ids_or_filter?: IdsOrFilterType): ResourceFilter {
+    if (!ids_or_filter) return {};
+    if (Array.isArray(ids_or_filter)) return { _id: { $in: ids_or_filter } } as any;
+    if (typeof ids_or_filter === 'object' && ids_or_filter !== null && 'ids' in (ids_or_filter as any)) {
+      const ids = (ids_or_filter as any).ids;
+      const filter = (ids_or_filter as any).filter;
+      const base = Array.isArray(ids) ? { _id: { $in: ids } } : {};
+      return filter ? ({ $and: [base, filter] } as any) : (base as any);
+    }
+    return ids_or_filter as any;
+  }
+
+  /**
+   * Validate an ID using ResourceIdBackendService if available.
+   * For PostgreSQL, IDs should be valid UUIDs.
+   *
+   * @param id - The ID to validate
+   * @param executionContext - Execution context for error handling
+   * @throws Error if ID is invalid
+   */
+  private validateId(id: string, executionContext: ExecutionContext<any>): void {
+    if (this.resourceIdService) {
+      const resourceType = String(this.resourceConfiguration.resourceIdentifier);
+      if (!this.resourceIdService.validateForResource(id, resourceType)) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+          customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+          context: { message: `Invalid ID format for resource ${resourceType}: ${id}` },
+        });
+      }
+    }
+  }
+
+  private buildBaseFilterFromIdOrFilter(
+    id_or_filter: IdOrFilterType,
+    executionContext: ExecutionContext<any>
+  ): { baseFilter: ResourceFilter } {
+    let baseFilter: ResourceFilter = {};
+    if (!id_or_filter) return { baseFilter };
+
+    if (typeof id_or_filter === 'string') {
+      this.validateId(id_or_filter, executionContext);
+      baseFilter = { _id: id_or_filter } as any;
+    } else if (typeof id_or_filter === 'object' && !Array.isArray(id_or_filter)) {
+      if ('id' in (id_or_filter as any)) {
+        const id = (id_or_filter as any).id;
+        if (typeof id === 'string') this.validateId(id, executionContext);
+        baseFilter = { _id: id } as any;
+        const extra = (id_or_filter as any).filter;
+        if (extra && Object.keys(extra).length > 0) {
+          baseFilter = { $and: [baseFilter, extra] } as any;
+        }
+      } else if ('id_or_ids' in (id_or_filter as any)) {
+        const ids = (id_or_filter as any).id_or_ids;
+        if (typeof ids === 'string') {
+          this.validateId(ids, executionContext);
+          baseFilter = { _id: ids } as any;
+        } else if (Array.isArray(ids)) {
+          ids.forEach((id: string) => this.validateId(id, executionContext));
+          baseFilter = { _id: { $in: ids } } as any;
+        }
+        const extra = (id_or_filter as any).filter;
+        if (extra && Object.keys(extra).length > 0) {
+          baseFilter = { $and: [baseFilter, extra] } as any;
+        }
+      } else {
+        baseFilter = id_or_filter as any;
+      }
+    } else {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: { message: 'Invalid id_or_filter format' },
+      });
+    }
+
+    return { baseFilter };
+  }
+
+  private buildContextualFilter(
+    executionContext: ExecutionContext<any>,
+    baseFilter: ResourceFilter,
+    options?: RepositoryOptions
+  ): ResourceFilter {
+    const contextualFilter: ResourceFilter = { ...(baseFilter || {}) } as any;
+
+    if (options?.excludeContextualFilter === true) {
+      return contextualFilter;
+    }
+
+    const blacklistedFields = new Set<string>();
+    blacklistedFields.add(this.resourceConfiguration.resourceFieldIdentifier);
+    if (Array.isArray(options?.excludeContextualFilter)) {
+      options.excludeContextualFilter.forEach((f) => blacklistedFields.add(f));
+    }
+
+    const contextResourceIds = executionContext.getContextResourceIds();
+    contextResourceIds.forEach((resourceId, fieldIdentifier) => {
+      if (blacklistedFields.has(fieldIdentifier)) return;
+      const matchingPaths = this.resourceOperationHelper.findRequiredNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema,
+        fieldIdentifier,
+        executionContext,
+        {
+          reason: 'context_filter',
+          resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+          message: `Execution context field '${fieldIdentifier}' is missing from schema for resource '${this.resourceConfiguration.resourceIdentifier}' during contextual filtering`,
+        }
+      );
+      matchingPaths.forEach((fullPath) => {
+        if (!this.resourceOperationHelper.hasNestedPath(contextualFilter, fullPath)) {
+          this.resourceOperationHelper.setNestedValue(contextualFilter, fullPath, resourceId);
+        }
+      });
+    });
+
+    // Ensure organization scoping when available and not already set
+    const orgId = executionContext.initiatorIds?.organizationId;
+    if (orgId && this.plannedFieldNames.has('organizationId') && !blacklistedFields.has('organizationId')) {
+      const orgPaths = this.resourceOperationHelper.findNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema,
+        'organizationId'
+      );
+      orgPaths.forEach((fullPath) => {
+        if (!this.resourceOperationHelper.hasNestedPath(contextualFilter, fullPath)) {
+          this.resourceOperationHelper.setNestedValue(contextualFilter, fullPath, orgId);
+        }
+      });
+    }
+
+    // Defense-in-depth: enforce userId = null for ANONYMOUS scope on isAnonymizable resources
+    if (executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable) {
+      const userPaths = this.resourceOperationHelper.findNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema, 'userId'
+      );
+      userPaths.forEach(fullPath => {
+        this.resourceOperationHelper.setNestedValue(contextualFilter, fullPath, null);
+      });
+    }
+
+    this.applyFKRelationshipFilters(executionContext, contextualFilter, blacklistedFields);
+    return contextualFilter;
+  }
+
+  private applyFKRelationshipFilters(
+    executionContext: ExecutionContext<any>,
+    filter: ResourceFilter,
+    blacklistedFields: Set<string>
+  ): void {
+    const relationshipContexts = executionContext.relationshipContexts;
+    if (!relationshipContexts || relationshipContexts.length === 0) return;
+
+    for (const relationshipContext of relationshipContexts) {
+      const { relationshipField, resourceId } = relationshipContext;
+      if (!relationshipField) continue;
+      if (blacklistedFields.has(relationshipField)) continue;
+
+      const matchingPaths = this.resourceOperationHelper.findRequiredNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema,
+        relationshipField,
+        executionContext,
+        {
+          reason: 'fk_filter',
+          resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+          message: `Relationship field '${relationshipField}' is missing from schema for resource '${this.resourceConfiguration.resourceIdentifier}' during FK-path filtering`,
+        }
+      );
+
+      matchingPaths.forEach((fullPath) => {
+        if (!this.resourceOperationHelper.hasNestedPath(filter, fullPath)) {
+          this.resourceOperationHelper.setNestedValue(filter, fullPath, resourceId);
+        }
+      });
+    }
+  }
+
+  private async resolveSingleId(
+    executionContext: ExecutionContext<any>,
+    baseFilter: ResourceFilter,
+    options?: RepositoryOptions
+  ): Promise<string | null> {
+    if (baseFilter && typeof baseFilter === 'object' && !Array.isArray(baseFilter) && '_id' in baseFilter) {
+      const idVal = (baseFilter as any)._id;
+      if (typeof idVal === 'string') return idVal;
+      if (idVal && typeof idVal === 'object' && Array.isArray((idVal as any).$in) && (idVal as any).$in.length > 0) {
+        return (idVal as any).$in[0];
+      }
+    }
+
+    const contextualFilter = this.buildContextualFilter(executionContext, baseFilter, options);
+    const where = this.buildWhere(contextualFilter);
+    const db = await this.getDbOrTrx(options);
+
+    let qb: any = this.filterService.applyWhere(db.selectFrom(this.tableName).select(['_id' as any]), where);
+    if (this.plannedFieldNames.has('createdAt')) {
+      qb = qb.orderBy('createdAt', 'desc');
+    }
+    const row = await qb.executeTakeFirst();
+    return row?._id ?? null;
+  }
+
+  private findSearchOperationConfiguration():
+    | ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+    | null {
+    return Array.from(this.operationsMap.values()).find(
+      operation => operation.operationIdentifier === CoreResourceOperation.SEARCH
+    ) ?? null;
+  }
+
+  private constructSearchQuery(
+    searchQuery: string,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    fieldsOverride?: string[]
+  ): ResourceFilter {
+    if (!searchQuery?.trim()) return {};
+
+    const op = searchConfig as unknown as { searchableFields?: string[] };
+    const allowed = Array.isArray(op.searchableFields)
+      ? op.searchableFields
+      : [];
+    const fields = Array.isArray(fieldsOverride) && fieldsOverride.length > 0
+      ? fieldsOverride.filter((f) => allowed.includes(f))
+      : allowed;
+    const orClauses = fields.map((f) => ({ [f]: { $contains: searchQuery, $options: 'i' } } as any));
+    return orClauses.length > 0 ? ({ $or: orClauses } as any) : {};
+  }
+
+  private sanitizeRequestFilter(
+    filter: ResourceFilter,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): ResourceFilter {
+    if (!filter || typeof filter !== 'object') return {};
+    const { filterFields } = searchConfig as unknown as { filterFields?: Record<string, unknown> };
+    if (!filterFields || Object.keys(filterFields).length === 0) return filter;
+    const allowedKeys = Object.keys(filterFields);
+    const allowField = (field: string): boolean =>
+      allowedKeys.includes(field) || allowedKeys.some((a) => field.startsWith(`${a}.`));
+
+    const sanitizeObject = (obj: any): any => {
+      if (!obj || typeof obj !== 'object') return obj;
+      const out: any = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (key === '$and' || key === '$or') {
+          if (Array.isArray(value)) {
+            const arr = value.map((v) => sanitizeObject(v)).filter((v) => v && Object.keys(v).length > 0);
+            if (arr.length > 0) out[key] = arr;
+          }
+          continue;
+        }
+        if (key === '$not') {
+          const inner = sanitizeObject(value as any);
+          if (inner && Object.keys(inner).length > 0) out[key] = inner;
+          continue;
+        }
+        if (allowField(key)) out[key] = value;
+      }
+      return out;
+    };
+
+    return sanitizeObject(filter);
+  }
+
+  private constructValidatedSortOptions(
+    requestedSort: Record<string, 1 | -1> | undefined,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): Array<{ field: string; direction: 'asc' | 'desc' }> {
+    const op = searchConfig as unknown as { sortFields?: readonly string[] };
+    const sortFields = Array.isArray(op.sortFields)
+      ? (op.sortFields as string[])
+      : [];
+    const validated: Array<{ field: string; direction: 'asc' | 'desc' }> = [];
+
+    if (sortFields.length === 0) return validated;
+    if (!requestedSort) {
+      const first = sortFields[0];
+      return first ? [{ field: first, direction: 'desc' }] : validated;
+    }
+
+    Object.entries(requestedSort).forEach(([field, dir]) => {
+      if (sortFields.includes(field) && (dir === 1 || dir === -1)) {
+        validated.push({ field, direction: dir === 1 ? 'asc' : 'desc' });
+      }
+    });
+
+    return validated;
+  }
+
+  private addUserTrackingAndTimestamps(
+    enrichedData: any,
+    executionContext: ExecutionContext<any>,
+    operation: CoreResourceOperation
+  ): any {
+    const out = { ...(enrichedData || {}) };
+    const userId = (executionContext as any)?.initiatorIds?.userId;
+    const now = new Date();
+
+    if (operation === CoreResourceOperation.CREATE) {
+      if (this.plannedFieldNames.has('createdAt') && !out.createdAt) out.createdAt = now;
+      if (this.plannedFieldNames.has('updatedAt') && !out.updatedAt) out.updatedAt = now;
+      if (userId && this.plannedFieldNames.has('createdByUserId') && !out.createdByUserId) out.createdByUserId = userId;
+    }
+
+    if (operation === CoreResourceOperation.UPDATE) {
+      if (this.plannedFieldNames.has('updatedAt')) out.updatedAt = now;
+      if (userId && this.plannedFieldNames.has('updatedByUserId') && !out.updatedByUserId) out.updatedByUserId = userId;
+      if (userId && this.plannedFieldNames.has('lastUpdatedByUserId') && !out.lastUpdatedByUserId) out.lastUpdatedByUserId = userId;
+    }
+
+    return out;
+  }
+}
+