@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

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';
@@ -17,6 +17,7 @@ import { PostgreSQLFilterBackendService } from '../../../databases/services/post
 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 { materializeSeedInsertRowDefaults } from './seed-row-default-materialization.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';
@@ -293,7 +294,82 @@ export class PostgreSQLResourceRepositoryBackendService {
      * today.
      */
     toSqlWriteRow(data, inheritanceDefinition) {
-        return this.serializeJsonbColumns(this.sqlPlanner.transformForSqlWrite(this.foldSurrogatePrimaryKey(data), inheritanceDefinition, this.declaredBaseFieldNames()));
+        return this.serializeJsonbColumns(this.projectOntoPlannedColumns(this.sqlPlanner.transformForSqlWrite(this.foldSurrogatePrimaryKey(data), inheritanceDefinition, this.declaredBaseFieldNames())));
+    }
+    /**
+     * Keep only the keys this table HAS A COLUMN FOR — the SQL twin of the mongoose schema's own
+     * projection, and the third site of the `plannedFieldNames` gate the two guarded-write sites
+     * already apply.
+     *
+     * ## Why the payload legitimately carries a key that is not a column
+     *
+     * A repository does not receive "the row to write". It receives the OPERATION'S VALIDATED
+     * REQUEST — `validateRepositoryWriteData` parses the payload against the operation's own
+     * `requestDto` — and a custom operation's request DTO declares the ARGUMENTS the operation
+     * takes, not the columns it writes. `claimDomain` takes `{ domain }`, a DNS name being claimed;
+     * its PREFIX hook computes the `domains` block from it and that block is what persists. `domain`
+     * itself was never a field of the resource.
+     *
+     * That is not one operation's quirk. Surveyed over the whole engine catalogue, **43 write
+     * operations declare 63 such request keys** — `reason`, `justification`, `notifyMembers`,
+     * `newParentUnitId`, `featureId`, `cancelImmediately`, `requestedDurationMinutes`, and so on.
+     * The normal case for a custom write verb is to take arguments.
+     *
+     * ## The divergence this closes
+     *
+     * MongoDB projects the payload onto the persisted shape and always has: `SCHEMA_DEFAULT_OPTIONS`
+     * sets `strict: true`, so mongoose drops a path its schema does not declare and the write
+     * succeeds. Here the same key reached the statement and PostgreSQL refused the whole UPDATE with
+     * `column "domain" of relation "organizationssoconfig" does not exist` — measured over HTTP on
+     * 2026-09-09 (issue #573). So the projection existed on one adapter as an accident of the ODM and
+     * on the other not at all, which is the adapter divergence, not the tolerance.
+     *
+     * ## Drop, not refuse — decided rather than inherited
+     *
+     * Refusing a payload key with no column reads like the stricter answer and is not equivalent: it
+     * would refuse all 43 operations above, every one of which is correctly authored and works on
+     * MongoDB today. A refusal is a NEW contract, it would have to be applied to BOTH adapters to
+     * mean anything (a refusal on one adapter only is the very divergence being closed), and its
+     * natural home is a startup-time check over DECLARATIONS — beside the `authoritativeFields`
+     * validator — never a runtime refusal on a live request. The two `plannedFieldNames` gates in
+     * this file already chose to drop, for the same no-op-parity reason.
+     *
+     * A per-operation `requestOnly` DECLARATION was considered as the "state it rather than infer
+     * it" alternative, and rejected: the plan already decides which keys are columns, so a second
+     * declaration would state the same fact twice and let the two disagree
+     * (`.claude/rules/derive-before-you-ask.md` — name what already decides it before adding a
+     * declaration a human maintains).
+     *
+     * ## Why `plannedFieldNames`, and not `planPhysicalColumnNames`
+     *
+     * `plannedFieldNames` is the PERMISSIVE set: for a hybrid-inheritance resource it also contains
+     * the variant-only names `transformForSqlWrite` sweeps into `variantConfig`. Running after that
+     * sweep, those keys are already gone, so the extra members cannot admit anything — while gating
+     * on the narrower physical set would newly DROP a variant field the sweep failed to move, turning
+     * today's loud failure into a silent one. Permissive here is deliberate: this projection removes
+     * an adapter divergence and must not quietly change any other outcome.
+     *
+     * Dropped names are logged at debug rather than warned, matching `cleanInputData`'s report of
+     * what it removed. A warning on the normal case teaches a reader to skim the warnings that matter.
+     */
+    projectOntoPlannedColumns(row) {
+        if (!row || typeof row !== 'object' || Array.isArray(row))
+            return row;
+        const record = row;
+        const unplanned = Object.keys(record).filter((field) => !this.plannedFieldNames.has(field));
+        if (unplanned.length === 0)
+            return row;
+        const projected = {};
+        for (const [field, value] of Object.entries(record)) {
+            if (!this.plannedFieldNames.has(field))
+                continue;
+            projected[field] = value;
+        }
+        this.logDebug('Dropped payload keys with no planned column', {
+            table: this.tableName,
+            droppedFields: unplanned,
+        });
+        return projected;
     }
     /**
      * Render every JSONB-backed column's value as JSON TEXT, so PostgreSQL parses it as `jsonb`.
@@ -952,6 +1028,13 @@ export class PostgreSQLResourceRepositoryBackendService {
         for (const [path, delta] of Object.entries(mutation.increment ?? {})) {
             const segments = path.split('.');
             if (segments.length === 1) {
+                // An increment targeting a field with NO PLANNED COLUMN is dropped, for the same reason the
+                // `clear` case below drops one: mongoose's `strict: true` schema removes an `$inc` on a path
+                // it does not declare, so the counter does not move there — while here the same path would
+                // be `column "x" does not exist` and would fail the WHOLE mutation, including the parts that
+                // are legal. Same third-site gate as `toSqlWriteRow`'s projection.
+                if (!this.plannedFieldNames.has(path))
+                    continue;
                 // `COALESCE(col, 0)` is parity, not defensiveness: MongoDB's `$inc` treats a missing field
                 // as 0 and sets it to `delta`, whereas SQL `NULL + delta` is NULL — without it a first
                 // increment on a nullable column would silently blank the counter instead of starting it.
@@ -973,6 +1056,11 @@ export class PostgreSQLResourceRepositoryBackendService {
             const [root, ...rest] = segments;
             this.assertJsonbPathRoot(root, addition.path, 'array addition');
             if (rest.length === 0) {
+                // Unplanned roots cannot reach here: `assertJsonbPathRoot` above refuses any root that is
+                // not jsonb-backed, and every jsonb root IS a planned column — so this branch needs no
+                // `plannedFieldNames` gate of its own, unlike the increment and clear cases. Stated so the
+                // absence reads as an enumeration result rather than as the third site being forgotten.
+                //
                 // The array IS the column, so it coalesces to an empty ARRAY rather than an empty object.
                 columnAssignments.set(root, this.buildJsonbArrayAddition(this.currentColumnExpression(columnAssignments, root, ARRAY_JSONB_LITERAL), addition));
                 continue;
@@ -1286,8 +1374,13 @@ export class PostgreSQLResourceRepositoryBackendService {
                 continue;
             callerAuthoredPayload[key] = payload[key];
         }
+        // A seed payload is written verbatim by this path — it never meets the request-DTO parse that
+        // materialises schema defaults for every ordinary CREATE. The engine's own configuration seeds
+        // are authored expecting that parse (`{ domains: {}, enforcement: {}, … }`), so without this the
+        // row lands holding empty objects and only an INTERNAL reader ever sees it; see the helper.
+        const materializedPayload = materializeSeedInsertRowDefaults(this.resourceConfiguration.mainSchema, callerAuthoredPayload);
         const writePayload = {
-            ...callerAuthoredPayload,
+            ...materializedPayload,
             [DATA_SEED_ROW_METADATA_FIELD_KEY]: seedMetadata,
         };
         const trackedPayload = this.addUserTrackingAndTimestamps(writePayload, executionContext, existing ? CoreResourceOperation.UPDATE : CoreResourceOperation.CREATE);
@@ -2069,6 +2162,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;
@@ -2127,7 +2232,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);
@@ -2233,6 +2338,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).
      *
@@ -2702,27 +2887,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')