@memberjunction/core 6.1.0-edge.2 → 6.1.0-edge.3

package/dist/generic/entityInfo.js

@@ -4,6 +4,7 @@ import { TypeScriptTypeFromSQLType, SQLFullType, SQLMaxLength, FormatValue, Code
 import { IsFixedWidthStringSQLType } from "@memberjunction/sql-dialect";
 import { LogError } from "./logging.js";
 import { WarningManager, SafeJSONParse, UUIDsEqual } from "@memberjunction/global";
+import { ReadRelationshipJoinFields, } from "./entityConfiguration.js";
 /**
  * The possible status values for a record change
  */
@@ -47,6 +48,41 @@ export class RecordChange extends BaseInfo {
  * Defines foreign key relationships and how they should be represented in the user interface.
  */
 export class EntityRelationshipInfo extends BaseInfo {
+    /**
+     * Optional JSON configuration bag (shape = {@link IEntityRelationshipConfiguration}).
+     * Nested `UI.inclusion` is Primary, More, or None (omit = Auto ranker).
+     * `UI.FormRole` is an accepted alias (`Detail` = More). Distinct from
+     * RelatedRecordCollection, DisplayComponentConfiguration, and AdditionalFieldsToInclude.
+     * Parsed lazily on first access and cached using {@link SafeJSONParse}.
+     *
+     * @see packages/MJCore/src/generic/entityConfiguration.ts
+     */
+    get Configuration() {
+        if (this._configurationObject === undefined) {
+            this._configurationObject = this._configuration ? SafeJSONParse(this._configuration, false) : null;
+        }
+        return this._configurationObject;
+    }
+    set Configuration(value) {
+        if (typeof value === 'string') {
+            this._configuration = value;
+            this._configurationObject = undefined;
+        }
+        else if (value && typeof value === 'object') {
+            this._configurationObject = value;
+            this._configuration = JSON.stringify(value);
+        }
+        else {
+            this._configuration = null;
+            this._configurationObject = null;
+        }
+    }
+    /**
+     * Parsed {@link Configuration}. Null when the column is empty or not valid JSON.
+     */
+    get ConfigurationObject() {
+        return this.Configuration;
+    }
     constructor(initData) {
         super();
         this.ID = null;
@@ -79,6 +115,14 @@ export class EntityRelationshipInfo extends BaseInfo {
         * * Description: Indicates whether this relationship should be automatically updated by CodeGen. When set to 0, the record will not be modified by CodeGen. Defaults to true.
         */
         this.AutoUpdateFromSchema = true;
+        /**
+         * Comma-delimited list of extra related-entity fields to project in base views.
+         */
+        this.AdditionalFieldsToInclude = null;
+        /**
+         * Whether CodeGen automatically updates AdditionalFieldsToInclude from schema metadata.
+         */
+        this.AutoUpdateAdditionalFieldsToInclude = true;
         /**
         * * Field Name: RelatedRecordCollection
         * * SQL Data Type: nvarchar(MAX), nullable
@@ -100,6 +144,11 @@ export class EntityRelationshipInfo extends BaseInfo {
         * @see guides/TRANSACTIONS_AND_BATCHING_GUIDE.md
         */
         this.RelatedRecordCollection = null;
+        /**
+         * Raw string representation of Configuration from metadata.
+         */
+        this._configuration = null;
+        this._configurationObject = undefined;
         // virtual fields - returned by the database VIEW
         this.Entity = null;
         this.EntityBaseTable = null;
@@ -379,6 +428,49 @@ export const GeneratedFormSectionType = {
  * Includes data types, relationships, defaults, and UI display preferences.
  */
 export class EntityFieldInfo extends BaseInfo {
+    /**
+     * Optional JSON configuration bag (shape = {@link IEntityFieldConfiguration}).
+     * Defines field-level configurations such as Hierarchy options (IsHierarchy, MaxDepth).
+     * Parsed lazily on first access and cached using {@link SafeJSONParse}.
+     */
+    get Configuration() {
+        if (this._configurationObject === undefined) {
+            this._configurationObject = this._configuration ? SafeJSONParse(this._configuration, false) : null;
+        }
+        return this._configurationObject;
+    }
+    set Configuration(value) {
+        if (typeof value === 'string') {
+            this._configuration = value;
+            this._configurationObject = undefined;
+        }
+        else if (value && typeof value === 'object') {
+            this._configurationObject = value;
+            this._configuration = JSON.stringify(value);
+        }
+        else {
+            this._configuration = null;
+            this._configurationObject = null;
+        }
+    }
+    /**
+     * Parsed {@link Configuration}. Null when the column is empty or not valid JSON.
+     */
+    get ConfigurationObject() {
+        return this.Configuration;
+    }
+    /**
+     * Returns true if this field is explicitly configured as an intentional recursive tree hierarchy.
+     */
+    get IsHierarchy() {
+        return this.ConfigurationObject?.Hierarchy?.IsHierarchy === true;
+    }
+    /**
+     * Maximum recursion depth configured for this hierarchy field (defaults to 100).
+     */
+    get HierarchyMaxDepth() {
+        return this.ConfigurationObject?.Hierarchy?.MaxDepth ?? 100;
+    }
     /**
      * JSON configuration for additional fields to join from the related entity.
      * Parsed from the RelatedEntityJoinFields column. Uses lazy initialization and caching
@@ -432,6 +524,233 @@ export class EntityFieldInfo extends BaseInfo {
             }
         }
     }
+    /**
+     * Upper bound on how many legal values a validation message enumerates before it truncates.
+     * A long list would otherwise produce an error message no user can read.
+     */
+    static { this.MaxValueListValuesInErrorMessage = 25; }
+    /**
+     * Normalizes a value for comparison against a value list: stringified, trimmed, lower-cased.
+     *
+     * Each part earns its place, and the reasons are NOT equally strong — stated precisely, because
+     * a future maintainer will use this to decide whether to tighten the comparison:
+     *   * **Lower-casing is load-bearing on MJ core itself.** Not merely defensive: the default-value
+     *     path puts a field's SQL default into a new record (`EntityField`'s constructor assigns
+     *     `DefaultValue` when no value is supplied), and two MJ core fields have a default that
+     *     matches their value list by CASE ALONE — `MJ: Entity AI Actions`.TriggerEvent defaults to
+     *     `'After Save'` against a list of `before save | after save`, and its OutputType defaults to
+     *     `'FIeld'` against `entity | field`. Under a case-sensitive comparison, creating either
+     *     record at its database default would fail validation. Separately, SQL Server's default
+     *     collation is case-insensitive, so `Status = 'active'` is accepted by
+     *     `CHECK (Status IN ('Active', ...))` and refusing it here would turn a save that succeeds
+     *     today into a failure. (PostgreSQL IS case-sensitive, so on PG a case variant is still
+     *     refused — by its CHECK, not by this rung.)
+     *   * **Stringifying is required.** `EntityFieldValue.Value` is always a string in metadata while
+     *     the field's runtime value may be a number, so a strict `===` would reject every legal value
+     *     on a numeric list. It is not lossless: `String(1.0)` is `'1'`, so a metadata value written
+     *     as `'1.0'` would fail closed. No numeric value lists exist today (CodeGen cannot produce
+     *     one — see the note in ValueIsPermittedByValueList), so this is recorded rather than solved.
+     *   * **Trimming is cheap insurance, NOT the load-bearing rule it was first documented as.** An
+     *     earlier version of this comment claimed an untrimmed comparison would reject 9,301 existing
+     *     rows in fixed-width `nchar` columns (`MJ: Action Params`.Type, `MJ: Record Changes`.Status
+     *     and others). That measurement was taken over RAW SQL ROWS and does not describe this code
+     *     path: `EntityField`'s value setter already strips trailing padding on fixed-width columns
+     *     (see `FixedWidthColumn`), and hydration assigns through that setter, so the padding is gone
+     *     before `Validate()` ever reads the value. Trimming is kept because it still covers LEADING
+     *     whitespace, stray spaces on the metadata side, and any caller that assigns a padded value
+     *     directly — none of which the setter handles.
+     */
+    static NormalizeValueListValue(value) {
+        return String(value).trim().toLowerCase();
+    }
+    /**
+     * Whether `value` is permitted by this field's exhaustive value list (MJ issue #3969).
+     *
+     * A field whose `ValueListType` is `List` carries an exhaustive set of legal values in
+     * `__mj.EntityFieldValue`, and for an `IN (...)` CHECK constraint that list is the ONLY runtime
+     * representation CodeGen produces — `ParseCheckConstraints` emits the value list rather than a
+     * generated `Validate()` method, since the list is also what the UI needs to render a dropdown.
+     * So this is the only place such a constraint can be caught before the database refuses it as a
+     * raw violation attributed to no field.
+     *
+     * The normalized set is built ONCE per field and reused, because it derives from metadata that
+     * is immutable after load and is shared by every `EntityField` instance of this field — at
+     * import scale (thousands to millions of rows) rebuilding it per record is pure waste.
+     *
+     * Four boundaries keep the rule safe to apply everywhere:
+     *   * `ListOrUserEntry` is never checked — that mode exists precisely to permit values outside
+     *     the list, so validating it would break every field that opted into free text.
+     *   * A `List` field with no `EntityFieldValue` rows permits everything. Strictly it describes
+     *     a field where nothing is legal, which should never exist; it means the metadata is
+     *     broken, not that every value is wrong, so this logs loudly (once per EntityFieldInfo
+     *     instance, which means it re-arms after a metadata refresh rather than being once ever)
+     *     and permits rather than failing every save on the field.
+     *   * Null/undefined is the nullability check's job, so one mistake never produces two errors.
+     *     An EMPTY or whitespace-only string is NOT absence: SQL Server pads on comparison, so
+     *     `''` and `'   '` are the same value to a CHECK constraint and it refuses both. Skipping
+     *     them would leave a hole exactly where a blanked-out field lands.
+     *   * Only string and number values are checked, and the gate fails OPEN — an unsupported type
+     *     skips validation rather than manufacturing a failure. Nothing in the schema restricts
+     *     which columns may carry a value list (`CK_EntityField_ValueListType_New` constrains the
+     *     mode, not the column type), but in practice every one is a string column: measured on a
+     *     current 6.x instance, 455 nvarchar + 7 nchar and nothing else, which follows from
+     *     CodeGen's constraint parser only ever extracting quoted literals. `number` is admitted
+     *     because the generated union type anticipates a non-quoted list via `NeedsQuotes`.
+     *     Booleans and Dates are excluded deliberately: a bit column carrying a `'1'`/`'0'` list
+     *     would see `String(true) === 'true'` and reject every legal value, and a Date has no sane
+     *     string form to compare — so guessing there would break saves rather than guard them.
+     *
+     * TWO PRODUCERS, ONE OF WHICH HAS NO DATABASE FLOOR. A CHECK-derived list is safe by
+     * construction: the database refuses anything this rung refuses, so validating can only move a
+     * failure earlier. The other producer is `applyValueListConfig` in CodeGen, which applies
+     * DBAutoDoc's LLM enum detection from `additionalSchemaInfo` — those fields have NO CHECK
+     * constraint, so for them this rung converts a sampled, confidence-scored guess into a hard save
+     * refusal for any value the model did not see. It is opt-in (the config must exist) and arguably
+     * the intended reading of `List` as a closed set, with `ListOrUserEntry` available when unsure —
+     * but it means "MJ never refuses what the database would accept" holds for the first producer
+     * only.
+     *
+     * @param value the field's current runtime value
+     * @returns true when the value is permitted, INCLUDING when the rule does not apply
+     */
+    ValueIsPermittedByValueList(value) {
+        if (this.ValueListTypeEnum !== EntityFieldValueListType.List) {
+            return true;
+        }
+        if (this._normalizedValueListValues === undefined) {
+            const values = this.EntityFieldValues ?? [];
+            this._normalizedValueListValues = new Set(values.map(v => EntityFieldInfo.NormalizeValueListValue(v.Value)));
+        }
+        // The broken-metadata report comes FIRST, before the null and type gates, so that it is
+        // value-independent: a `List` field with no values whose column happens to hold null (or a
+        // boolean) would otherwise never report at all, making "loud" mean "loud if someone happens
+        // to set a string". The cost is building one memoized set on a field that would build it
+        // anyway.
+        if (this._normalizedValueListValues.size === 0) {
+            if (!this._loggedEmptyValueList) {
+                this._loggedEmptyValueList = true; // latched: one report per field, not per row
+                LogError(`Entity field ${this.Entity}.${this.Name} has ValueListType='List' but no EntityFieldValue rows. ` +
+                    `That describes a field where no value is legal, which is broken metadata rather than a rule, ` +
+                    `so value-list validation is being SKIPPED for this field. Re-run CodeGen for the entity, or ` +
+                    `set ValueListType='None' if the field is not meant to be constrained.`);
+            }
+            return true;
+        }
+        if (value === null || value === undefined) {
+            return true; // an unset nullable field or a new record — the nullability check's business
+        }
+        // Dates are compared on the calendar date rather than the string form — see
+        // dateValueIsPermittedByValueList. A `date` column CAN carry a value list: SQL Server stores
+        // `CHECK (D IN ('2026-01-01','2026-07-01'))` as quoted literals, which is exactly the shape
+        // CodeGen's parser captures, so this is a reachable case rather than a hypothetical one.
+        if (value instanceof Date) {
+            return this.dateValueIsPermittedByValueList(value);
+        }
+        if (typeof value !== 'string' && typeof value !== 'number') {
+            // The rule cannot be applied to this type at all, and that is a mismatch rather than a
+            // state to absorb: either the field should not declare a value list (one on a bit column
+            // — which CodeGen never produces, since SQL Server renders `IN (0,1)` as unquoted
+            // `([B]=(1) OR [B]=(0))`, the same reason no NUMERIC list exists either; see MJ #3978)
+            // or a caller assigned the wrong type. Skipping it silently would
+            // leave the caller believing a guard is on when it is not, which is the exact failure
+            // mode this rung was added to fix — so it is reported, once per field.
+            this.reportUnsupportedValueListValue(`a ${typeof value} value (SQL type ${this.SQLFullType})`, 'value-list validation compares strings, numbers and dates only — comparing anything ' +
+                'else would reject legal values rather than guard them');
+            return true;
+        }
+        return this._normalizedValueListValues.has(EntityFieldInfo.NormalizeValueListValue(value));
+    }
+    /**
+     * Value-list membership for a `Date` runtime value, compared on the CALENDAR DATE rather than
+     * the instant.
+     *
+     * Only `date` columns are compared. A column carrying a time component is deliberately skipped:
+     * the metadata value has no timezone, so deciding whether `'2026-01-01T00:00:00'` is the same
+     * instant as the value read back would mean guessing the database's interpretation, and guessing
+     * wrong rejects a legal value.
+     *
+     * For a `date` column the comparison accepts EITHER the value's UTC calendar date or its LOCAL
+     * one. That asymmetry is deliberate: a value read back from SQL Server arrives as UTC midnight,
+     * while application code that builds a date with `new Date(2026, 6, 1)` produces LOCAL midnight —
+     * whose UTC calendar date is the previous day west of Greenwich. Insisting on one representation
+     * would refuse legal values for half the world, so a date is in the list if either reading of it
+     * is. The cost is that an adjacent day can slip through when both days are in the list, which is
+     * a far better trade than a false failure.
+     */
+    dateValueIsPermittedByValueList(value) {
+        if (this._valueListDateKeys === undefined) {
+            this._valueListDateKeys = this.buildValueListDateKeys();
+        }
+        if (this._valueListDateKeys === null) {
+            this.reportUnsupportedValueListValue(`a Date value (SQL type ${this.SQLFullType})`, 'only a `date` column whose value list is entirely yyyy-mm-dd literals can be ' +
+                'compared — anything else would require guessing how the database interprets a ' +
+                'time-zone-less literal');
+            return true;
+        }
+        if (Number.isNaN(value.getTime())) {
+            return true; // an Invalid Date is not an out-of-list value; leave it to the date check
+        }
+        return this._valueListDateKeys.has(value.toISOString().slice(0, 10)) ||
+            this._valueListDateKeys.has(EntityFieldInfo.LocalCalendarDate(value));
+    }
+    /**
+     * Builds the set of yyyy-mm-dd keys for a `date` field's value list, or null when the field is
+     * not a plain `date` column or any of its values is not a yyyy-mm-dd literal. Reads the already
+     * normalized values, so it costs no extra pass over the metadata (lower-casing cannot affect a
+     * numeric date literal).
+     */
+    buildValueListDateKeys() {
+        if ((this.Type ?? '').trim().toLowerCase() !== 'date') {
+            return null;
+        }
+        const keys = new Set();
+        for (const normalized of this._normalizedValueListValues ?? []) {
+            const match = /^(\d{4}-\d{2}-\d{2})$/.exec(normalized);
+            if (!match) {
+                return null; // not a date list — refuse to guess rather than reject legal values
+            }
+            keys.add(match[1]);
+        }
+        return keys.size > 0 ? keys : null;
+    }
+    /** The Date's LOCAL calendar date as yyyy-mm-dd (its UTC one is `toISOString().slice(0, 10)`). */
+    static LocalCalendarDate(value) {
+        const pad = (n) => String(n).padStart(2, '0');
+        return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
+    }
+    /**
+     * Reports, once per field, that a value could not be checked against the field's value list.
+     * Latched because the metadata is shared by every record: a bulk load would otherwise emit the
+     * same line per row, which is the noise the memoization elsewhere in this class exists to avoid.
+     */
+    reportUnsupportedValueListValue(received, reason) {
+        if (this._loggedUnsupportedValueListType) {
+            return;
+        }
+        this._loggedUnsupportedValueListType = true;
+        LogError(`Entity field ${this.Entity}.${this.Name} has ValueListType='List' but was given ${received}: ` +
+            `${reason}, so value-list validation is being SKIPPED for this field. Either the field's ` +
+            `metadata should not declare a value list, or the caller is assigning the wrong type.`);
+    }
+    /**
+     * This field's legal values formatted for a validation message, truncated past
+     * {@link MaxValueListValuesInErrorMessage}. Memoized — a bad bulk load fails on the same field
+     * repeatedly, and the string never changes.
+     */
+    get ValueListValuesForDisplay() {
+        if (this._valueListDisplayCache !== undefined) {
+            return this._valueListDisplayCache;
+        }
+        // De-duplicated: EntityFieldValue rows are not unique in practice (`MJ: Action Params`.ValueType
+        // carries repeats today), and listing the same value twice — or double-counting it in the
+        // "(N total)" tail — makes the message look like a bug in the message.
+        const values = [...new Set((this.EntityFieldValues ?? []).map(v => v.Value))];
+        const max = EntityFieldInfo.MaxValueListValuesInErrorMessage;
+        this._valueListDisplayCache = values.length > max ?
+            `${values.slice(0, max).join(', ')}, ... (${values.length} total)` :
+            values.join(', ');
+        return this._valueListDisplayCache;
+    }
     get GeneratedFormSectionType() {
         return GeneratedFormSectionType[this.GeneratedFormSection];
     }
@@ -753,6 +1072,18 @@ export class EntityFieldInfo extends BaseInfo {
          */
         this.DisplayName = null;
         this.Description = null;
+        /**
+         * Whether CodeGen automatically updates Description from the underlying schema object.
+         */
+        this.AutoUpdateDescription = true;
+        /**
+         * Whether CodeGen automatically updates UserSearchPredicateAPI from schema heuristics.
+         */
+        this.AutoUpdateUserSearchPredicate = true;
+        /**
+         * Whether CodeGen automatically updates FullTextSearchEnabled from schema indexes.
+         */
+        this.AutoUpdateFullTextSearch = true;
         /**
          * If true, the field is the primary key for the entity. There must be one primary key field per entity.
          */
@@ -824,6 +1155,22 @@ export class EntityFieldInfo extends BaseInfo {
          * Parsed from the RelatedEntityJoinFields column.
          */
         this.RelatedEntityJoinFields = null;
+        /**
+         * Optional JSON policy object declaring this foreign-key field as a first-class
+         * **embedded record** — a 1:1 peer that loads, validates and persists as one
+         * unit with its owner. Shape is `IEmbeddedRecordConfig` (`OnClear`, `LoadNested`).
+         *
+         * `RelatedEntityID` and this field's `Name` are the join; they are deliberately
+         * not repeated inside the JSON. `AllowsNull` on this same field decides whether
+         * `GetEntityObject` provisions the object (required FK) or the caller uses
+         * `{FieldName}_EnsureObject()` (nullable FK).
+         *
+         * `null` (the default, and every pre-feature row) means the field is an ordinary
+         * FK: nothing is generated and nothing is constructed at `GetEntityObject` time.
+         *
+         * @see packages/MJCore/docs/embedded-records.md
+         */
+        this.EmbeddedRecord = null;
         /**
          * The name of the TypeScript interface/type for this JSON field.
          * When set, CodeGen will emit a strongly-typed getter/setter using this type
@@ -841,6 +1188,11 @@ export class EntityFieldInfo extends BaseInfo {
          * Can include imports, multiple types, or any valid TypeScript.
          */
         this.JSONTypeDefinition = null;
+        /**
+         * Raw string representation of Configuration from metadata.
+         */
+        this._configuration = null;
+        this._configurationObject = undefined;
         this.RelatedEntityDisplayType = null;
         this.EntityIDFieldName = null;
         this.__mj_CreatedAt = null;
@@ -1040,6 +1392,24 @@ export class EntityFieldInfo extends BaseInfo {
         this.RelatedEntityClassName = null;
         this._rawEntityFieldValues = null;
         this._entityFieldValuesConstructed = false;
+        /**
+         * Memoized state for value-list validation. NOTE THE NAMES: none of these may be the getter's
+         * name minus its underscore. `BaseInfo.toJSON` walks own keys, and for a `_`-prefixed one it
+         * looks for a public getter of the matching PascalCase name and serializes THROUGH it. A memo
+         * called `_valueListValuesForDisplay` would therefore add `ValueListValuesForDisplay` to every
+         * serialized field — including the ~5,700 MJ core fields with no value list — bloating the
+         * browser metadata cache and forcing EntityFieldValues hydration purely to serialize a string
+         * that only ever appears in an error message. Hence `_valueListDisplayCache`.
+         */
+        this._normalizedValueListValues = undefined;
+        /** Memoized message form of the value list, built on first validation failure. */
+        this._valueListDisplayCache = undefined;
+        /** Latches the broken-metadata error so a bulk load cannot emit it once per row. */
+        this._loggedEmptyValueList = false;
+        /** Latches the unsupported-value-type error for the same reason. */
+        this._loggedUnsupportedValueListType = false;
+        /** Memoized yyyy-mm-dd keys for a `date` field's value list; null when it cannot be compared. */
+        this._valueListDateKeys = undefined;
         /**
          * Cached parsed RelatedEntityJoinFieldsConfig to avoid repeated JSON.parse calls.
          * Lazy-initialized on first access.
@@ -1207,6 +1577,40 @@ export class EntityInfo extends BaseInfo {
         const layered = this.GeneratedBaseViewName?.trim();
         return !!layered && layered.toLowerCase() !== (this.BaseView ?? '').toLowerCase();
     }
+    /**
+     * Optional JSON configuration bag (shape = {@link IEntityConfiguration}).
+     * Nested `UI.Form` holds generated-form chrome: layout, auto left-nav
+     * threshold, related-role policy, and the Primary related budget.
+     * Parsed lazily on first access and cached using {@link SafeJSONParse}.
+     *
+     * @see packages/MJCore/src/generic/entityConfiguration.ts
+     */
+    get Configuration() {
+        if (this._configurationObject === undefined) {
+            this._configurationObject = this._configuration ? SafeJSONParse(this._configuration, false) : null;
+        }
+        return this._configurationObject;
+    }
+    set Configuration(value) {
+        if (typeof value === 'string') {
+            this._configuration = value;
+            this._configurationObject = undefined;
+        }
+        else if (value && typeof value === 'object') {
+            this._configurationObject = value;
+            this._configuration = JSON.stringify(value);
+        }
+        else {
+            this._configuration = null;
+            this._configurationObject = null;
+        }
+    }
+    /**
+     * Parsed {@link Configuration}. Null when the column is empty or not valid JSON.
+     */
+    get ConfigurationObject() {
+        return this.Configuration;
+    }
     /**
      * O(1) case-insensitive field lookup by name. Use this instead of `Fields.find(f => f.Name === name)`
      * on hot paths — it builds a lowercased+trimmed `Map` once (lazily) and reuses it.
@@ -1784,6 +2188,16 @@ export class EntityInfo extends BaseInfo {
      * @returns
      */
     static BuildRelationshipViewParams(record, relationship, filter, maxRecords) {
+        const joinFields = ReadRelationshipJoinFields(relationship.Configuration);
+        if (joinFields && joinFields.length > 1) {
+            const multi = EntityInfo.BuildRelationshipViewParamsForJoinFields(record, relationship.RelatedEntity, joinFields);
+            if (filter && filter.length > 0 && multi.ExtraFilter) {
+                multi.ExtraFilter = `(${multi.ExtraFilter}) AND (${filter})`;
+            }
+            if (maxRecords && maxRecords > 0)
+                multi.MaxRows = maxRecords;
+            return multi;
+        }
         const params = {};
         let quotes = '';
         let keyValue = '';
@@ -1821,20 +2235,72 @@ export class EntityInfo extends BaseInfo {
         return params;
     }
     /**
-     * Builds a simple javascript object that will pre-populate a new record in the related entity with values that link back to the specified record.
-     * This is useful, for example, when creating a new contact from an account, we want to pre-populate the account ID in the new contact record
+     * One related-entity grid over several join fields (Bill-To OR Ship-To).
+     */
+    static BuildRelationshipViewParamsForJoinFields(record, relatedEntityName, joinFields) {
+        const fields = joinFields.map((f) => f.trim()).filter((f) => f.length > 0);
+        if (fields.length === 0)
+            return { EntityName: relatedEntityName };
+        if (fields.length === 1) {
+            const rel = record.EntityInfo.RelatedEntities.find((r) => r.RelatedEntity.trim().toLowerCase() === relatedEntityName.trim().toLowerCase()
+                && r.RelatedEntityJoinField.trim().toLowerCase() === fields[0].toLowerCase());
+            if (rel)
+                return EntityInfo.BuildRelationshipViewParams(record, rel);
+        }
+        const firstKey = record.FirstPrimaryKey;
+        const keyValue = firstKey.Value;
+        const quotes = keyValue && firstKey.NeedsQuotes ? "'" : '';
+        const clauses = fields.map((field) => `[${field}] = ${quotes}${keyValue}${quotes}`);
+        return {
+            EntityName: relatedEntityName,
+            ExtraFilter: clauses.join(' OR '),
+        };
+    }
+    /**
+     * Default field values for a new related record so it links back to `record`.
+     * When the relationship's Configuration declares `UI.join.fields`, every
+     * listed FK is set (Bill-To AND Ship-To). Otherwise only
+     * `RelatedEntityJoinField` is set.
      */
     static BuildRelationshipNewRecordValues(record, relationship) {
-        // we want to build a simple javascript object that will pre-populate a new record in the related entity with values that link
-        // abck to the current record. This is useful for example when creating a new contact from an account, we want to pre-populate the
-        // account ID in the new contact record
+        if (!record || !relationship)
+            return {};
+        const joinFields = ReadRelationshipJoinFields(relationship.Configuration);
+        if (joinFields && joinFields.length > 0) {
+            return EntityInfo.BuildRelationshipNewRecordValuesForJoinFields(record, joinFields, relationship);
+        }
+        const joinField = (relationship.RelatedEntityJoinField ?? '').trim();
+        if (!joinField)
+            return {};
+        return { [joinField]: EntityInfo.resolveRelationshipKeyValue(record, relationship) };
+    }
+    /**
+     * Default field values for a new related record, setting every listed join
+     * field to the parent key. Use this when one grid filters on several FKs
+     * (Bill-To OR Ship-To) so "New" still auto-links the child to this parent.
+     */
+    static BuildRelationshipNewRecordValuesForJoinFields(record, joinFields, relationship) {
+        if (!record)
+            return {};
+        const fields = joinFields.map((f) => f.trim()).filter((f) => f.length > 0);
+        if (fields.length === 0)
+            return {};
+        const keyValue = EntityInfo.resolveRelationshipKeyValue(record, relationship);
         const obj = {};
-        if (record && relationship) {
-            const keyField = relationship.EntityKeyField && relationship.EntityKeyField.trim().length > 0 ? relationship.EntityKeyField : record.FirstPrimaryKey.Name;
-            obj[relationship.RelatedEntityJoinField] = record.Get(keyField);
+        for (const field of fields) {
+            obj[field] = keyValue;
         }
         return obj;
     }
+    static resolveRelationshipKeyValue(record, relationship) {
+        const explicit = relationship?.EntityKeyField?.trim();
+        if (explicit)
+            return record.Get(explicit);
+        const first = record.FirstPrimaryKey;
+        if (first?.Name)
+            return record.Get(first.Name);
+        return first?.Value;
+    }
     /**
      * Returns a RunViewParams object configured to query the related entity matched via an organic key.
      * Supports both direct field matching and transitive matching via SQL views/tables.
@@ -1946,8 +2412,11 @@ export class EntityInfo extends BaseInfo {
                     // Fall back to exact match if no custom expression defined
                     return `${fieldExpression} = '${escapedValue}'`;
                 }
-                const normalizedField = expr.replace(/\{\{FieldName\}\}/g, fieldExpression);
-                const normalizedValue = expr.replace(/\{\{FieldName\}\}/g, `'${escapedValue}'`);
+                // Replacement functions: `escapedValue` is a data value, so `$&`/`` $` ``/
+                // `$'`/`$$` in it would otherwise splice the custom expression's own text
+                // into the SQL literal. See issue #3171.
+                const normalizedField = expr.replace(/\{\{FieldName\}\}/g, () => fieldExpression);
+                const normalizedValue = expr.replace(/\{\{FieldName\}\}/g, () => `'${escapedValue}'`);
                 return `${normalizedField} = ${normalizedValue}`;
             }
             default:
@@ -1976,7 +2445,8 @@ export class EntityInfo extends BaseInfo {
                 const expr = organicKey.CustomNormalizationExpression;
                 if (!expr)
                     return fieldExpression;
-                return expr.replace(/\{\{FieldName\}\}/g, fieldExpression);
+                // Replacement function — see WrapWithNormalization (#3171).
+                return expr.replace(/\{\{FieldName\}\}/g, () => fieldExpression);
             }
             default: return fieldExpression;
         }
@@ -1991,7 +2461,8 @@ export class EntityInfo extends BaseInfo {
                 const expr = organicKey.CustomNormalizationExpression;
                 if (!expr)
                     return `'${escapedValue}'`;
-                return expr.replace(/\{\{FieldName\}\}/g, `'${escapedValue}'`);
+                // Replacement function — see WrapWithNormalization (#3171).
+                return expr.replace(/\{\{FieldName\}\}/g, () => `'${escapedValue}'`);
             }
             default: return `'${escapedValue}'`;
         }
@@ -2200,9 +2671,21 @@ export class EntityInfo extends BaseInfo {
          */
         this.AllowUserSearchAPI = false;
         /**
-         * Whether full-text search is enabled for this entity
+         * Whether full text search is enabled for this entity
          */
-        this.FullTextSearchEnabled = false;
+        this.FullTextSearchEnabled = null;
+        /**
+         * Whether CodeGen automatically updates FullTextSearchEnabled from database catalog/index availability.
+         */
+        this.AutoUpdateFullTextSearch = true;
+        /**
+         * Whether CodeGen automatically updates AllowUserSearchAPI from schema rules.
+         */
+        this.AutoUpdateAllowUserSearchAPI = true;
+        /**
+         * Whether external changes to records are detected.
+         */
+        this.DetectExternalChanges = false;
         /**
          * Name of the SQL Server full-text catalog used for searching
          */
@@ -2306,6 +2789,11 @@ export class EntityInfo extends BaseInfo {
          * CSS class or icon identifier for displaying this entity in the UI
          */
         this.Icon = null;
+        /**
+         * Raw string representation of Configuration from metadata.
+         */
+        this._configuration = null;
+        this._configurationObject = undefined;
         /**
          * Date and time when this entity was created
          */