@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/base-classes/services/repositories/postgresql-resource-repository.backend.service.js

@@ -1,4 +1,4 @@
-import { CoreResourceOperation, CoreResourceType, ErrorCustomMessageReference, ErrorType, PersistenceAdapter, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, ResourceOperationsUtils, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, CoreResourceType, ErrorCustomMessageReference, ErrorType, PersistenceAdapter, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, ResourceOperationsUtils, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, isSearchableRelationDescriptor, } from '@wildo-ai/saas-models';
 import { assignInitiatorOrganizationConfinementToFilter } from '../../../security/authorizations/initiator-organization-confinement.backend.js';
 import { assignScopeRootCollectionConfinementToFilter } from '../../../security/authorizations/scope-root-collection-confinement.backend.js';
 import { assignRetentionHideForOperation } from '../../../compliance/privacy/retention-hide-predicate.backend.js';
@@ -16,6 +16,7 @@ import { getZodObjectShape } from '@wildo-ai/zod-decorators';
 import { PostgreSQLFilterBackendService } from '../../../databases/services/postgresql-filter.backend.service.js';
 import { sql } from 'kysely';
 import { normalizeRepositoryVersionMetadata } from '../../../base-classes/services/repositories/repository-version-metadata.backend.utils.js';
+import { isEngineReservedFieldName } from './field-clearing-partition.backend.js';
 import { buildRetentionVisibleRowsSqlPredicate, isRetentionGovernedResource, withRetentionHideApplied, } from '../../../compliance/privacy/retention-hide-predicate.backend.js';
 import { quotePostgresColumnOf, quotePostgresIdentifier, } from '../../../databases/utils/postgresql-identifier.backend.utils.js';
 import { guardedMutationHasWork, RepositoryArrayAdditionPlacement, } from './repository-guarded-mutation.backend.types.js';
@@ -43,6 +44,25 @@ const ARRAY_JSONB_LITERAL = sql `'[]'::jsonb`;
 function uniqueColumnSetKey(columns) {
     return JSON.stringify([...columns].sort());
 }
+/**
+ * The id of a deleted row, from whatever `_doDelete` answered.
+ *
+ * ONE function because there are TWO doors into the same delete — the typed `delete()` wrapper and
+ * the `doOperation` dispatch — and for as long as only one of them unwrapped, the shape a caller got
+ * depended on which door it came through. That is the adapter/door-conditional guarantee this file
+ * has now been bitten by twice; keeping the unwrap in a single place is what stops a third.
+ *
+ * `_id` first, `id` second: PostgreSQL tables carry the framework's `_id`, and the `id` fallback is
+ * kept for a row shape that predates it. `''` for "nothing matched" is the contract both adapters
+ * already answer, and it is what lets the service distinguish a no-op delete from a successful one.
+ */
+export function extractDeletedRowId(deletedRow) {
+    if (!deletedRow || typeof deletedRow !== 'object')
+        return '';
+    const row = deletedRow;
+    const identity = row._id ?? row.id;
+    return typeof identity === 'string' && identity.length > 0 ? identity : '';
+}
 export class PostgreSQLResourceRepositoryBackendService {
     dbService;
     logger;
@@ -412,7 +432,11 @@ export class PostgreSQLResourceRepositoryBackendService {
         ResourcesConfig_OperationPathUtils.validateOperationRepositoryPathKey(operationRepositoryPathKey);
         const operation = this.operationsMap.get(operationRepositoryPathKey);
         if (!operation) {
-            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+            // CONFIGURATION, not NOT_FOUND — the same structural fault as the Mongo arm, fixed with it
+            // rather than after it. Both persistence adapters carry this lookup, which is the shape
+            // `invariant-call-site-enumeration.md` records for a port: a fix applied to one side leaves
+            // the other answering the old way.
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
                 customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
                 context: { operationRepositoryPathKey },
             });
@@ -469,7 +493,21 @@ export class PostgreSQLResourceRepositoryBackendService {
                         context: { operationRepositoryPathKey, id_or_ids_or_filter },
                     });
                 }
-                return this._doDelete(operation, executionContext, id_or_ids_or_filter, options);
+                /*
+                 * UNWRAPPED, exactly as the `delete()` wrapper does.
+                 *
+                 * `_doDelete` uses `.returningAll()` and answers the whole deleted ROW, while the DELETE
+                 * contract — `Promise<string>` on both adapters — is the id. `delete()` unwrapped it and this
+                 * dispatch did not, so which shape a caller got depended on WHICH DOOR it came through. The
+                 * service layer comes through here, so every single DELETE on a PostgreSQL-backed resource
+                 * returned a row; `composeDefaultOperationResponse` then built `{ id: <row> }`, the DELETE DTO
+                 * refused it, and the request answered 500 AFTER the row was already gone.
+                 *
+                 * MongoDB's `_doDelete` returns the id directly, so its dispatch was correct and this was
+                 * adapter-conditional — the failure shape this file's own `_doDelete` comment calls "worse than
+                 * no guarantee". Both doors now go through one function so they cannot drift apart again.
+                 */
+                return extractDeletedRowId(await this._doDelete(operation, executionContext, id_or_ids_or_filter, options));
             case CoreResourceOperation.DELETE_MANY:
                 return this._doDeleteMany(operation, executionContext, id_or_ids_or_filter, options);
             case CoreResourceOperation.LIST:
@@ -600,7 +638,7 @@ export class PostgreSQLResourceRepositoryBackendService {
             });
         }
         const deleted = await this._doDelete(operation, executionContext, id_or_ids_or_filter, options);
-        return deleted?._id ?? deleted?.id ?? '';
+        return extractDeletedRowId(deleted);
     }
     async deleteMany(executionContext, ids_or_filter, options) {
         const operation = this.resourceConfiguration.operations.find((op) => op.operationIdentifier === CoreResourceOperation.DELETE_MANY && op.isOperationDefault === true);
@@ -1029,6 +1067,41 @@ export class PostgreSQLResourceRepositoryBackendService {
         // Kysely reports affected rows as a bigint; coerce so callers compare a number, not a string.
         return Number(result?.numUpdatedRows ?? 0);
     }
+    /**
+     * The MULTI-row DELETE below the operation tier: destroy every row matching an already-built
+     * filter, returning how many went.
+     *
+     * retention-gate: N/A — the hide is applied ONCE by the caller
+     * (`deleteManyForInfrastructure`), matching every sibling on this tier.
+     *
+     * rag-removal-gate: N/A — a raw repository door, bounded by the hourly RAG reconciliation sweep's
+     * orphan reconciliation, exactly as `_doDelete` / `_doDeleteMany` are.
+     *
+     * **The empty-filter refusal is contract, not local defensiveness** — see the same guard in
+     * `prepareGuardedUpdate`, and the reason it is stricter here than in `countByRawFilter` /
+     * `findManyByRawFilter`: `applyWhere` returns the builder UNCHANGED for a null where-expression
+     * and `buildWhere` yields null for an empty or unusable filter, so without this a caller whose
+     * predicate came out empty would emit `DELETE FROM <table>` and get a cheerful count back. A read
+     * can legitimately ask a whole-table question; a delete cannot.
+     */
+    async deleteManyByRawFilter(filter, options) {
+        const where = this.buildWhere(filter);
+        if (!where) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    resourceType: this.tableName,
+                    reason: 'deleteManyByRawFilter requires a non-empty filter — refusing an unfiltered DELETE',
+                },
+            });
+        }
+        const db = await this.getDbOrTrx(options);
+        const result = await this.filterService
+            .applyWhere(db.deleteFrom(this.tableName), where)
+            .executeTakeFirst();
+        // Kysely reports affected rows as a bigint; coerce so callers compare a number, not a string.
+        return Number(result?.numDeletedRows ?? 0);
+    }
     /**
      * The expression a column currently carries in this statement, or its base value when nothing has
      * touched it yet.
@@ -1196,8 +1269,25 @@ export class PostgreSQLResourceRepositoryBackendService {
         // coverage of the write surface is a PROPERTY of the chokepoint set rather than a consequence of
         // who happens to call it today.
         await this.assertOrganizationUnitWriteWithinGrant(payload, CoreResourceOperation.CREATE, executionContext);
+        // Engine-reserved metadata is stripped from the CALLER's payload before anything else — the
+        // 7th site of an invariant the six sibling write paths already apply by hand (`_doCreate`,
+        // `_doCreateMany`, `_doUpdate`, `_doUpdateMany`, and both `upsertByFilter` branches each
+        // `delete ..._version`). This one was missed, and it is the ONLY write path data-seeding uses.
+        //
+        // It matters because a seed UPGRADE's payload is a READ PROJECTION: the managed-field overlay
+        // is the persisted row with managed paths replaced, and `transformPersistenceRow` publishes
+        // `_version_db_doc` as the public read-only `_version`. Writing that back names a column this
+        // table does not have — `column "_version" of relation "..." does not exist` — so every
+        // PostgreSQL seed upgrade failed. Applied via the named rule rather than a seventh hand-list so
+        // a future engine-owned key is covered without another enumeration.
+        const callerAuthoredPayload = {};
+        for (const key of Object.keys(payload)) {
+            if (isEngineReservedFieldName(key))
+                continue;
+            callerAuthoredPayload[key] = payload[key];
+        }
         const writePayload = {
-            ...payload,
+            ...callerAuthoredPayload,
             [DATA_SEED_ROW_METADATA_FIELD_KEY]: seedMetadata,
         };
         const trackedPayload = this.addUserTrackingAndTimestamps(writePayload, executionContext, existing ? CoreResourceOperation.UPDATE : CoreResourceOperation.CREATE);
@@ -1979,6 +2069,18 @@ export class PostgreSQLResourceRepositoryBackendService {
             // hard-coded on BOTH sides of this line — see the Mongo sibling for why the default is 100
             // rather than SEARCH's 50.
             const maxLimit = operation.maxPaginatedResultPerPageLimit || 100;
+            //
+            // ## What the pagination guarantee IS, and what it is not — decided 2026-09-08 (#471)
+            //
+            // This clamp bounds what an HTTP CALLER can request, and nothing else. With `paginated ===
+            // false` and no `listOptions` this block is skipped entirely and every row is returned — the
+            // internal-call contract, identical to the Mongo adapter's, where the same reasoning is
+            // written out at length.
+            //
+            // The residual risk is named rather than assumed away: an internal enumeration over a very
+            // large tenant can exhaust memory. Completeness is what sweeps, cascades and subject exports
+            // rely on, so the unbounded shape stays; an internal caller that does not need completeness
+            // pages explicitly by passing `listOptions`.
             limit = Math.min(maxLimit, Math.max(1, listOptions?.limit || 20));
             offset = (page - 1) * limit;
             totalPages = limit > 0 ? Math.max(1, Math.ceil(total / limit)) : 1;
@@ -2037,7 +2139,7 @@ export class PostgreSQLResourceRepositoryBackendService {
         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)
+            ? await this.constructSearchQuery(trimmed, searchConfig, options?.searchOptions?.fieldsToSearch)
             : {};
         const combinedFilter = trimmed ? { $and: [baseFilter, searchFilter] } : baseFilter;
         let contextualFilter = this.buildContextualFilter(executionContext, combinedFilter, CoreResourceOperation.SEARCH, options);
@@ -2143,6 +2245,86 @@ export class PostgreSQLResourceRepositoryBackendService {
         }
         return [...ids];
     }
+    /**
+     * Run THIS resource's own searchable surface against `searchQuery` and project the join values —
+     * the PostgreSQL half of relational search (#470).
+     *
+     * Exact contract parity with the Mongo sibling in `repository-resource.backend.service.ts`, and
+     * the shape is worth stating because it explains why this reached parity at all: **the relational
+     * search is not a JOIN.** Mongo does not `$lookup`; it runs a secondary query on the RELATED
+     * repository, collects join values, and folds them into one `{ localField: { $in } }` branch. That
+     * decomposition is adapter-agnostic — which is why the PostgreSQL arm needed this projection and a
+     * fold, not a query planner.
+     *
+     * Raw, lean, SYSTEM read by design, mirroring the Mongo sibling: no operation auth and no
+     * contextual filter. Tenant safety is unaffected because the CALLER's query stays scoped — this
+     * only ever narrows an already-scoped set by contributing ids to an OR branch.
+     *
+     * The retention hide IS applied: a retained row must not contribute a search match, exactly as the
+     * Mongo sibling AND-s `withRawRetentionHide` over its match filter.
+     */
+    async findSearchMatchTargetIds(searchQuery, joinField, options) {
+        if (!searchQuery?.trim())
+            return [];
+        /*
+         * Bound the candidate set so a broad term cannot build an unbounded `IN (…)`. The same cap and
+         * the same reasoning as the Mongo sibling — tenant safety is unaffected, this caps the fold size
+         * only — and it must STAY the same number, or the two adapters return different result sets for
+         * the same declaration, which is the drift this whole issue exists to remove.
+         */
+        const MATCH_ID_CAP = 1000;
+        const searchConfig = this.findSearchOperationConfiguration();
+        const op = searchConfig;
+        // Default to this resource's OWN string searchable fields — "use the juncted element's search" —
+        // unless the caller pins a subset. Descriptors are skipped here on purpose: a relational
+        // descriptor on the RELATED resource would recurse, and the Mongo sibling does not do it either.
+        const ownStringFields = (op?.searchableFields ?? []).filter((field) => typeof field === 'string');
+        const fields = options?.fields && options.fields.length > 0 ? options.fields : ownStringFields;
+        if (fields.length === 0) {
+            this.logDebug('findSearchMatchTargetIds: no searchable fields resolved for relational match', {
+                resourceType: this.resourceConfiguration.resourceIdentifier,
+            });
+            return [];
+        }
+        const matchConditions = fields.map((field) => ({ [field]: { $contains: searchQuery, $options: 'i' } }));
+        const matchFilter = matchConditions.length > 1
+            ? { $or: matchConditions }
+            : (matchConditions[0] ?? {});
+        const filter = isRetentionGovernedResource(this.resourceConfiguration)
+            ? withRetentionHideApplied(matchFilter)
+            : matchFilter;
+        const db = await this.getDbOrTrx();
+        const inheritanceDef = this.resourceConfiguration?.inheritenceSchemaDefinition;
+        const where = this.buildWhere(filter);
+        // Project the single column when it is planned; fall back to whole rows only when it is not,
+        // because an unplanned field lives inside a jsonb root that only the planner can reassemble.
+        // Identical reasoning to `findScopeRelatedTargetIds` above.
+        const joinIsPlannedColumn = this.plannedFieldNames.has(joinField);
+        const rows = await this.filterService
+            .applyWhere(joinIsPlannedColumn
+            ? db.selectFrom(this.tableName).select(joinField)
+            : db.selectFrom(this.tableName).selectAll(), where)
+            .limit(MATCH_ID_CAP + 1)
+            .execute();
+        if (rows.length > MATCH_ID_CAP) {
+            this.logDebug('findSearchMatchTargetIds: related match set truncated to cap', {
+                resourceType: this.resourceConfiguration.resourceIdentifier,
+                cap: MATCH_ID_CAP,
+            });
+        }
+        const ids = new Set();
+        for (const row of rows.slice(0, MATCH_ID_CAP)) {
+            const value = joinIsPlannedColumn
+                ? row[joinField]
+                : this.transformPersistenceRow(row, inheritanceDef)?.[joinField];
+            if (value === undefined || value === null)
+                continue;
+            const id = String(value);
+            if (id.length > 0)
+                ids.add(id);
+        }
+        return [...ids];
+    }
     /**
      * Aggregate a numeric field across rows matching the filter (feature-limit enforcement).
      *
@@ -2354,11 +2536,43 @@ export class PostgreSQLResourceRepositoryBackendService {
                 this.resourceOperationHelper.applyAuthoritativeContextFilterValue(contextualFilter, fieldIdentifier, resourceId, { fieldIdentifier, resourceIdentifier: String(this.resourceConfiguration.resourceIdentifier) });
                 return;
             }
-            const matchingPaths = this.resourceOperationHelper.findRequiredNestedFieldPathsFromZodSchema(this.resourceConfiguration.mainSchema, fieldIdentifier, executionContext, {
+            const allMatchingPaths = 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`,
             });
+            /*
+             * THE SCOPE FIELD FILTERS AT THE TOP LEVEL ONLY — the third site of the same invariant fixed
+             * on 2026-09-01 (the initiator-organization confinement, the Mongo context block, and this
+             * twin), and the one that was actually RUNNING when the defect was measured: this adapter
+             * served `wildoApplicationActorTasks`, whose schema nests
+             * `errorStates.errorItems.initiatorIds.organizationId` (a recorded error's initiator — data,
+             * not tenancy), and the unrestricted sweep put that dotted path into the filter, which this
+             * adapter's compiler refused as an invalid column reference — a 400 on every LIST. Read the
+             * Mongo sibling's block comment for the full account, including why Mongo's failure mode for
+             * the same sweep is WORSE (silent row-hiding rather than a crash). The write path had already
+             * learned this lesson (`enrichDataWithContextFields`: "Deep matches inside embedded payloads
+             * are never the scope column").
+             */
+            const isScopeField = fieldIdentifier === primaryScopeFieldIdentifier;
+            const matchingPaths = isScopeField
+                ? allMatchingPaths.filter((fullPath) => fullPath === fieldIdentifier)
+                : allMatchingPaths;
+            if (isScopeField && matchingPaths.length === 0 && allMatchingPaths.length > 0) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        reason: 'scope_field_modeled_only_nested',
+                        resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+                        fieldIdentifier,
+                        nestedPaths: allMatchingPaths,
+                        message: `Scope field '${fieldIdentifier}' appears only NESTED in the schema for resource `
+                            + `'${this.resourceConfiguration.resourceIdentifier}'. A scoped resource carries its scope FK as a `
+                            + 'top-level column (the write path injects it there); a nested occurrence of the name is data. '
+                            + 'Refusing rather than widening the query beyond its tenant.',
+                    },
+                });
+            }
             matchingPaths.forEach((fullPath) => {
                 /**
                  * D2 — resolve a SURROGATE primary key to the queryable column.
@@ -2580,27 +2794,88 @@ export class PostgreSQLResourceRepositoryBackendService {
         }
         return defaultSearchOperations[0] ?? searchOperations[0] ?? null;
     }
-    constructSearchQuery(searchQuery, searchConfig, fieldsOverride) {
+    /**
+     * Build the SEARCH filter, own-column conditions AND relational descriptors (#470).
+     *
+     * ## Parity with Mongo, and why it was reachable
+     *
+     * A relational `searchableFields` descriptor used to be FILTERED OUT here with a `logger.warn`, so
+     * an author on this adapter learned their declared search surface did not work only from a warning
+     * in a running process — if they read the log at all.
+     *
+     * Reaching parity turned out not to need query planning, because the Mongo adapter does not join:
+     * it runs a secondary query on the RELATED repository, collects join values, and folds them into
+     * one `{ localField: { $in: ids } }` branch. That decomposition is adapter-agnostic, and `$in` is
+     * already this dialect's own operator — so the arm below is the SAME algorithm, resolved through
+     * the same repository method, and not a second implementation of the semantics.
+     *
+     * Async because a relational branch resolves its ids through the related repository, exactly as
+     * the Mongo sibling is.
+     */
+    async constructSearchQuery(searchQuery, searchConfig, fieldsOverride) {
         if (!searchQuery?.trim())
             return {};
         const op = searchConfig;
         const rawSearchableFields = Array.isArray(op.searchableFields) ? op.searchableFields : [];
-        // Relational `searchableFields` descriptors (objects) are resolved only by the
-        // Mongo adapter today, which folds related matches into an `$in` (see
-        // repository-resource.backend.service.ts `findSearchMatchTargetIds`). The
-        // PostgreSQL adapter supports own-column search only, so keep the string
-        // entries and skip descriptors: a relational entry degrades to own-field
-        // search rather than corrupting the query. Parity tracked in
-        // `.claude/plans/generic-relational-search.md` (D4).
-        const allowed = rawSearchableFields.filter((f) => typeof f === 'string');
-        if (allowed.length !== rawSearchableFields.length) {
-            this.logger.warn(`Relational searchableFields descriptors are not yet supported on the PostgreSQL adapter for resource '${String(this.resourceConfiguration.resourceIdentifier)}'; applying own-column search only.`);
-        }
+        // Own-column entries → `$contains` conditions, as before.
+        const ownFields = rawSearchableFields.filter((f) => typeof f === 'string');
         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' } }));
-        return orClauses.length > 0 ? { $or: orClauses } : {};
+            ? fieldsOverride.filter((f) => ownFields.includes(f))
+            : ownFields;
+        const searchConditions = fields.map((f) => ({ [f]: { $contains: searchQuery, $options: 'i' } }));
+        /*
+         * Relational entries → a secondary match on the related resource, folded into an `$in` branch on
+         * this table's join field. Resolved in declared order, matching Mongo.
+         *
+         * A `fieldsOverride` (the caller's `fieldsToSearch`) deliberately does NOT suppress relational
+         * branches: the override names OWN fields to narrow to, and it cannot express a relational
+         * descriptor, so treating it as a filter over descriptors would silently drop them for any caller
+         * that pinned a field subset.
+         */
+        for (const descriptor of rawSearchableFields.filter(isSearchableRelationDescriptor)) {
+            const relationCondition = await this.buildRelationalSearchCondition(searchQuery, descriptor);
+            if (relationCondition)
+                searchConditions.push(relationCondition);
+        }
+        if (searchConditions.length === 0) {
+            /*
+             * Two different situations converge here and they must NOT get the same answer.
+             *
+             * If `searchableFields` was non-empty — relational-only, and every related match resolved to
+             * zero ids — matching everything would return the whole collection for a query that found
+             * nothing, so match NOTHING. Mongo returns `{ _id: { $in: [] } }` for exactly this, and the
+             * same filter is the right one here.
+             *
+             * If it was empty, there is no declared search surface at all, and returning `{}` preserves
+             * this adapter's existing behaviour rather than newly refusing every such search.
+             */
+            return rawSearchableFields.length > 0 ? { _id: { $in: [] } } : {};
+        }
+        return (searchConditions.length > 1 ? { $or: searchConditions } : searchConditions[0]);
+    }
+    /**
+     * Resolve one relational descriptor into a `{ [localField]: { $in: ids } }` branch by running the
+     * related resource's own searchable surface (see `findSearchMatchTargetIds`).
+     *
+     * Returns `null` — contributing no branch — when the related repository cannot be resolved or the
+     * match set is empty. That is the correct fail-safe for a MATCH branch, and the reasoning is the
+     * Mongo sibling's verbatim: it only ever ADDS results within the caller's already scoped and
+     * filtered set, so omitting it can never widen visibility — it merely under-matches.
+     */
+    async buildRelationalSearchCondition(searchQuery, descriptor) {
+        const relatedRepository = this.repositoriesRegistry.getRepository(descriptor.relatedResource);
+        if (!relatedRepository || typeof relatedRepository.findSearchMatchTargetIds !== 'function') {
+            this.logDebug('Relational search branch skipped: related repository unavailable', {
+                relatedResource: descriptor.relatedResource,
+                localField: descriptor.localField,
+            });
+            return null;
+        }
+        const joinField = descriptor.relatedJoinField ?? '_id';
+        const ids = await relatedRepository.findSearchMatchTargetIds(searchQuery, joinField, { fields: descriptor.fields });
+        if (ids.length === 0)
+            return null;
+        return { [descriptor.localField]: { $in: ids } };
     }
     sanitizeRequestFilter(filter, searchConfig) {
         if (!filter || typeof filter !== 'object')