@memberjunction/core 6.1.0-edge.5 → 6.1.0-edge.7

package/dist/generic/entityInfo.js

@@ -3,8 +3,26 @@ import { Metadata } from "./metadata.js";
 import { TypeScriptTypeFromSQLType, SQLFullType, SQLMaxLength, FormatValue, CodeNameFromString } from "./util.js";
 import { IsFixedWidthStringSQLType } from "@memberjunction/sql-dialect";
 import { LogError } from "./logging.js";
-import { WarningManager, SafeJSONParse, UUIDsEqual } from "@memberjunction/global";
+import { WarningManager, SafeJSONParse, UUIDsEqual, ordinalCompare } from "@memberjunction/global";
 import { ReadRelationshipJoinFields, } from "./entityConfiguration.js";
+/**
+ * Runtime domain for {@link EntityFieldInfo.ExtendedType}. This array is the single source of
+ * truth; {@link EntityFieldExtendedType} is derived from it. CodeGen validates LLM suggestions
+ * against {@link EntityFieldInfo.ExtendedTypes} rather than duplicating the list.
+ *
+ * `Image` — the value is an image URL, a `data:image/...` URI, or raw image base64. UI surfaces
+ * render a thumbnail and (in edit mode) allow replacing it with an upload capped at the field's
+ * MaxLength.
+ * `Color` — the value is a CSS color (hex / rgb / hsl).
+ * `JSON` — the value is a JSON document; validated on save and pretty-printed in forms.
+ */
+export const EntityFieldExtendedTypes = [
+    'Code', 'Color', 'Email', 'FaceTime', 'Geo',
+    'GeoLatitude', 'GeoLongitude', 'GeoCountry', 'GeoStateProvince',
+    'GeoCity', 'GeoPostalCode', 'GeoAddress',
+    'HTML', 'Icon', 'Image', 'JSON', 'Markdown',
+    'MSTeams', 'Other', 'SIP', 'SMS', 'Skype', 'Tel', 'URL', 'WhatsApp', 'ZoomMtg',
+];
 /**
  * The possible status values for a record change
  */
@@ -209,7 +227,7 @@ export class EntityOrganicKeyInfo extends BaseInfo {
                 sorted.sort((a, b) => {
                     const aSeq = a.Sequence ?? 999999;
                     const bSeq = b.Sequence ?? 999999;
-                    return aSeq - bSeq;
+                    return (aSeq - bSeq) || ordinalCompare(a.RelatedEntity, b.RelatedEntity) || ordinalCompare(a.ID, b.ID);
                 });
                 for (const item of sorted) {
                     this._RelatedEntities.push(new EntityOrganicKeyRelatedEntityInfo(item));
@@ -305,6 +323,15 @@ export class EntityUserPermissionInfo {
  * Controls which roles can perform create, read, update, and delete operations.
  */
 export class EntityPermissionInfo extends BaseInfo {
+    /**
+     * True when this row is a Deny row (`Type = 'Deny'`, compared case- and whitespace-insensitively;
+     * a null/blank Type — rows created before the column existed — is Allow). On a Deny row a set
+     * `Can*` flag means "deny that operation", so nothing that reads a `Can*` flag as a GRANT may
+     * look at a Deny row: `GetUserPermisions` subtracts these, and the RLS readers skip them.
+     */
+    get IsDeny() {
+        return (this.Type || 'Allow').trim().toLowerCase() === 'deny';
+    }
     get CreateRLSFilterObject() {
         return this.RLSFilter(EntityPermissionType.Create);
     }
@@ -369,6 +396,190 @@ export class EntityPermissionInfo extends BaseInfo {
         this.copyInitData(initData);
     }
 }
+/**
+ * The three states a single field-level permission verb can hold, modelled on SQL Server's
+ * posture:
+ *
+ * - `No Access` — neutral, and the default. Grants nothing and blocks nothing; another role's
+ *   Allow still wins.
+ * - `Allow` — grants the action for this role.
+ * - `Deny` — trumps everything. One Deny across any of the user's roles wins no matter how
+ *   many Allows sit beside it.
+ */
+export const FieldPermissionAccess = {
+    Allow: 'Allow',
+    Deny: 'Deny',
+    NoAccess: 'No Access',
+};
+/**
+ * The transport-only key carrying the server's authoritative answer to "which fields on this
+ * entity may the caller of THIS request read".
+ *
+ * **Why it lists READABLE fields rather than denied ones.** The two carry the same information
+ * only while the client already holds the full permission matrix, which it does today — the
+ * `MJ_Metadata` dataset ships `MJ: Entity Fields` and `MJ: Entity Field Permissions` unfiltered.
+ * That is scheduled to change (MJ issue #3485, metadata filtering for restricted users), and a
+ * payload that named DENIED fields would hand back exactly what such filtering exists to withhold:
+ * the names of columns you are not allowed to know about. A readable list names only fields the
+ * caller may already see, so it discloses nothing under any filtering design.
+ *
+ * **Why it is needed at all.** The server omits denied fields from the response object, but
+ * GraphQL emits every SELECTED field regardless — so a denied field the client asked for arrives
+ * as an explicit `null`, indistinguishable from a genuine one. The client cannot settle that from
+ * its own metadata: in the window after a permission change (and permanently, once metadata is
+ * filtered) the client's copy disagrees with the server's. This key is the server stating it
+ * in-band, for the request that actually ran.
+ *
+ * Suffixed `___` following the established transport-only convention (`OldValues___`,
+ * `RestoreContext___`) so it cannot collide with a real column name.
+ */
+export const ReadableFieldsTransportKey = 'ReadableFields___';
+/**
+ * True when a rule takes access AWAY rather than granting or abstaining.
+ *
+ * `Deny` is the only restricting value *within a single rule*. `No Access` is the aggregation's
+ * identity element: it can leave a role without access, but it can never remove access one of the
+ * user's other roles granted.
+ *
+ * **This answers a question about one rule, not about a change.** Whether a CHANGE restricts a
+ * user is a property of the aggregate across every role they hold — setting each of a user's roles
+ * to `No Access` in turn writes no `Deny` anywhere and still ends with the field denied. So this
+ * is sound for an INSERT, which can only add rules and therefore cannot remove an existing
+ * `Allow`, and is NOT sufficient for an edit or a delete. Those must project the resulting rule
+ * set and aggregate it — see {@link EntityFieldInfo.AggregateFieldRulesForUser}.
+ */
+export function IsRestrictingFieldRule(rule) {
+    return (rule?.ReadAccess === FieldPermissionAccess.Deny ||
+        rule?.UpdateAccess === FieldPermissionAccess.Deny ||
+        rule?.CreateAccess === FieldPermissionAccess.Deny);
+}
+/**
+ * The single wording for "you cannot use this field", modelled on SQL Server's posture of never
+ * disclosing whether an object is missing or merely inaccessible.
+ *
+ * Naming the field is safe — the caller supplied it, so it tells them nothing they did not
+ * already know. Naming the REASON is not: confirming "this field exists and is restricted"
+ * turns any predicate into an oracle for probing which columns a deployment considers
+ * sensitive. The ambiguity also stays correct after
+ * [#3485](https://github.com/MemberJunction/MJ/issues/3485) tiers metadata and restricted fields
+ * stop shipping to clients at all, at which point "does not exist" becomes literally true from
+ * the client's vantage point.
+ *
+ * Lives here rather than on `ProviderBase` so the write path in `BaseEntity` can reach it
+ * without importing the provider layer, which imports `BaseEntity` in turn.
+ */
+export function FieldSecurityDenialMessage(fieldName, entityName) {
+    return `Field '${fieldName}' does not exist on entity '${entityName}' or you do not have access to it.`;
+}
+/**
+ * The wording for "you may not WRITE this field" — used only when the caller can READ it.
+ *
+ * Naming the reason here discloses nothing. The caller can see the field and its values, so
+ * both facts the ambiguous wording withholds — that the column exists, and that it is
+ * restricted for them — are already theirs. All this adds is *which* permission is missing,
+ * which they would learn by trying anyway.
+ *
+ * The two justifications behind {@link FieldSecurityDenialMessage} do not reach this case:
+ * predicate probing is a question about columns the caller cannot READ, and the
+ * [#3485](https://github.com/MemberJunction/MJ/issues/3485) argument — that "does not exist"
+ * becomes literally true once restricted fields stop shipping to clients — is false for a
+ * readable field, which keeps shipping. Ambiguity there does not age into truth; it just tells
+ * someone that a field they are looking at might not exist.
+ *
+ * A field the caller cannot read must still use the ambiguous wording. That is not hypothetical:
+ * `SetMany` deliberately skips the readability assertion (it is the hydration and resolver-apply
+ * path), so server-side code can dirty a read-denied field and reach the update gate.
+ */
+export function FieldSecurityWriteDenialMessage(fieldName, entityName) {
+    return `You do not have permission to update field '${fieldName}' on entity '${entityName}'.`;
+}
+/**
+ * The error thrown when field-level security refuses a request — a caller-authored predicate
+ * naming an unreadable field, a typed accessor touching one, or a save modifying a field the
+ * caller may not write.
+ *
+ * A DISTINCT class because its message is the one security rejection that is deliberately safe
+ * to show a caller: both {@link FieldSecurityDenialMessage} and
+ * {@link FieldSecurityWriteDenialMessage} were designed for exactly that surface and disclose
+ * nothing (see their docs). Transport layers that rightly swallow arbitrary resolver errors
+ * (whose messages can carry SQL text or internal state) recognize this one and let it through,
+ * so the intended wording reaches the wire instead of degenerating into a generic transport
+ * error.
+ *
+ * Recognize it by `name === FieldSecurityError.ErrorName` rather than `instanceof` where
+ * bundling might duplicate the class.
+ */
+export class FieldSecurityError extends Error {
+    static { this.ErrorName = 'FieldSecurityError'; }
+    /**
+     * Defaults to the ambiguous wording, which is correct for every READ denial. Pass `message`
+     * only through a named factory such as {@link FieldSecurityError.WriteDenial}, so the choice
+     * of wording is always a deliberate, reviewable decision rather than an inline string.
+     */
+    constructor(fieldName, entityName, message) {
+        super(message ?? FieldSecurityDenialMessage(fieldName, entityName));
+        this.name = FieldSecurityError.ErrorName;
+    }
+    /**
+     * A write refusal on a field the caller CAN read — names the missing permission instead of
+     * hiding behind "or it does not exist", which would be actively misleading about a field
+     * whose values they are looking at. Callers must confirm readability first; see
+     * {@link FieldSecurityWriteDenialMessage}.
+     */
+    static WriteDenial(fieldName, entityName) {
+        return new FieldSecurityError(fieldName, entityName, FieldSecurityWriteDenialMessage(fieldName, entityName));
+    }
+}
+/**
+ * Field-level (column-level) security settings. Maps an entity FIELD to a role, carrying three
+ * independent trinary verbs — Read, Update and Create. One row per (field, role).
+ *
+ * These rows are only consulted when the parent entity has
+ * {@link EntityInfo.EnableFieldLevelSecurity} set. Aggregation across the roles a user holds,
+ * per verb: `effective = (any matching row Allows) AND NOT (any matching row Denies)`. See
+ * {@link EntityFieldInfo.GetUserFieldPermissions}.
+ */
+export class EntityFieldPermissionInfo extends BaseInfo {
+    /**
+     * @param initData raw metadata row off the wire. `BaseInfo.copyInitData` only ever reads
+     * `Object.keys()` off it, so a plain record is wide enough.
+     */
+    constructor(initData = null) {
+        super();
+        this.ID = null;
+        this.EntityFieldID = null;
+        this.RoleID = null;
+        /**
+         * Whether this role may READ the field's values. The aggregation normalizes defensively and
+         * treats anything unrecognized as `No Access`, so a bad value off the wire fails closed
+         * rather than granting.
+         */
+        this.ReadAccess = FieldPermissionAccess.NoAccess;
+        /**
+         * Whether this role may modify the field's value on an EXISTING record.
+         *
+         * Requires {@link ReadAccess} = Allow — a field a user cannot see is one they cannot
+         * change. Enforced per row by a CHECK constraint, and again after aggregation because the
+         * constraint cannot see across roles.
+         */
+        this.UpdateAccess = FieldPermissionAccess.NoAccess;
+        /**
+         * Whether this role may supply the field's value when INSERTing a record. Requires
+         * {@link ReadAccess} = Allow, on the same two-layer basis as {@link UpdateAccess}.
+         *
+         * A user who may not create a field does not get an error — the supplied value is dropped
+         * and the column takes its default, matching the read path where a denied field is simply
+         * absent.
+         */
+        this.CreateAccess = FieldPermissionAccess.NoAccess;
+        this.__mj_CreatedAt = null;
+        this.__mj_UpdatedAt = null;
+        // virtual fields - returned by the database VIEW
+        this.EntityField = null;
+        this.Role = null;
+        this.copyInitData(initData);
+    }
+}
 export const EntityFieldTSType = {
     String: 'string',
     Number: 'number',
@@ -428,6 +639,10 @@ export const GeneratedFormSectionType = {
  * Includes data types, relationships, defaults, and UI display preferences.
  */
 export class EntityFieldInfo extends BaseInfo {
+    /**
+     * Runtime domain for {@link ExtendedType}. Same array as {@link EntityFieldExtendedTypes}.
+     */
+    static { this.ExtendedTypes = EntityFieldExtendedTypes; }
     /**
      * Optional JSON configuration bag (shape = {@link IEntityFieldConfiguration}).
      * Defines field-level configurations such as Hierarchy options (IsHierarchy, MaxDepth).
@@ -508,6 +723,201 @@ export class EntityFieldInfo extends BaseInfo {
         }
         return this._EntityFieldValues;
     }
+    /**
+     * Field-level (column-level) security records configured for THIS field, across all roles.
+     * Empty for the overwhelming majority of fields — see {@link HasFieldPermissions}.
+     */
+    get FieldPermissions() {
+        return this._FieldPermissions;
+    }
+    /**
+     * True when at least one {@link EntityFieldPermissionInfo} record exists for this field.
+     *
+     * **Not an enforcement gate** — it answers "does any configuration target this field",
+     * which CodeGen's DB-tier emission and the system-user entanglement guard both need. The
+     * access decision is {@link EntityInfo.EnableFieldLevelSecurity} plus the aggregation; on an
+     * enabled entity a field with no records is denied, not open.
+     */
+    get HasFieldPermissions() {
+        return this._FieldPermissions.length > 0;
+    }
+    /**
+     * Entities whose fields can never be restricted by field-level security.
+     *
+     * Two distinct reasons, both amounting to "a configuration that cannot be undone through
+     * the product":
+     *
+     * 1. **The security-configuration surface** (Entities, Entity Fields, Entity Permissions,
+     *    Entity Field Permissions, Roles). Restricting `CanRead` on the Entity Field Permissions
+     *    entity itself would leave the admin screen unable to render the very rows needed to
+     *    reverse the restriction — recovery would require direct SQL against the database.
+     * 2. **The identity surface** (Users, User Roles). Role resolution and the auth path read
+     *    these on every request; restricting a column here degrades far more than one screen.
+     *
+     * Note this is deliberately a guard on WHICH ENTITIES are restrictable, not an exemption for
+     * particular USERS. No user is above a Deny — that would undercut the entire point of the
+     * feature for the confidentiality use cases (compensation, donor giving) that motivate it.
+     *
+     * Stored lowercased; compare with a trimmed, lowercased entity name.
+     */
+    static { this.UnrestrictableEntityNames = new Set([
+        'mj: entities',
+        'mj: entity fields',
+        'mj: entity permissions',
+        'mj: entity field permissions',
+        'mj: roles',
+        'mj: users',
+        'mj: user roles',
+    ]); }
+    /**
+     * True when this field belongs to an entity that field-level security may never restrict.
+     * See {@link EntityFieldInfo.UnrestrictableEntityNames} for the rationale.
+     */
+    get IsOnUnrestrictableEntity() {
+        return EntityFieldInfo.UnrestrictableEntityNames.has((this.Entity ?? '').trim().toLowerCase());
+    }
+    /**
+     * True for fields that must remain readable regardless of any permission record:
+     * primary keys (hard or soft) and `__mj_` system columns.
+     *
+     * Stripping a primary key from a result breaks entity load, {@link CompositeKey}
+     * construction, relationship resolution, and cache fingerprinting — the failure surfaces
+     * far from the permission record that caused it. This is enforced here AND at save time on
+     * the permission record itself, so a row inserted outside the entity path still cannot take
+     * a primary key out of a result set.
+     */
+    get IsUnrestrictableField() {
+        return this.IsPrimaryKey === true || this.IsSoftPrimaryKey === true || (this.Name ?? '').startsWith('__mj_');
+    }
+    /**
+     * Returns the effective field-level access this user has to this field, aggregating the
+     * field's permission records across every role the user holds.
+     *
+     * **PRECONDITION: the caller has already established that the parent entity has
+     * {@link EntityInfo.EnableFieldLevelSecurity} set.** The flag is a required parameter rather
+     * than something this method looks up, because `EntityFieldInfo` holds its entity's NAME and
+     * not a reference to the `EntityInfo` — and a method that silently answered "denied" for a
+     * field on a non-FLS entity would be a trap. Pass `false` and every field comes back fully
+     * open.
+     *
+     * Per verb, across the user's matching roles:
+     * `effective = (any row Allows) AND NOT (any row Denies)`. Deny is absorbing and No Access
+     * is the identity, so three states collapse to that one expression.
+     *
+     * Outcomes:
+     * - **Field security disabled on the entity** → fully open.
+     * - **No records on the field** (enabled) → fully closed. Snapshot initialization creates a
+     *   row for every (field, role) that should have one, so a missing row means reconciliation
+     *   has not run — failing closed makes that visible.
+     * - **Records exist, none match the user's roles** → fully closed, for want of an Allow.
+     *
+     * **There is no exempt user — not even the MJ system user.** Every account, including the
+     * one the server runs its own background work as, gets its access from the rows. The system
+     * user stays working because it holds the standard roles (UI, Developer, Integration),
+     * snapshot initialization writes them `Allow` rows like any other role holding entity read,
+     * and the save-time configuration guards refuse a `Deny` aimed at a role it holds. That is a
+     * constraint on what can be CONFIGURED, which an administrator can see and reason about —
+     * unlike a runtime bypass, which is invisible at the point where access is decided and has
+     * to be trusted rather than checked.
+     *
+     * PERFORMANCE: this is the per-FIELD primitive. Enforcement points must never call it
+     * inside a per-row loop — `MapFieldNamesToCodeNames` runs once per row, so a naive call
+     * site costs `fields x rows` aggregations. Compute the denied-field Set once per
+     * (entity, user) per request and pass it into the row loop.
+     *
+     * @param user the user whose effective access is being resolved
+     * @param entityFieldSecurityEnabled the parent entity's `EnableFieldLevelSecurity` flag
+     */
+    GetUserFieldPermissions(user, entityFieldSecurityEnabled) {
+        if (!entityFieldSecurityEnabled) {
+            return EntityFieldInfo.fullyOpenFieldPermissions();
+        }
+        // Records on an unrestrictable entity are ignored entirely rather than half-applied.
+        // Save-time validation rejects such rows, so reaching here means they were written
+        // outside the entity path.
+        if (this.IsOnUnrestrictableEntity) {
+            return EntityFieldInfo.fullyOpenFieldPermissions();
+        }
+        // Primary keys and __mj_ system columns are forced open BEFORE aggregation rather than
+        // patched afterwards: a half-corrected result (readable but not creatable) would break
+        // inserts on entities whose primary key the caller supplies.
+        if (this.IsUnrestrictableField) {
+            return EntityFieldInfo.fullyOpenFieldPermissions();
+        }
+        return this.aggregateUserFieldPermissions(user);
+    }
+    /**
+     * The "field security does not apply here" answer, named so the policy exits above cannot
+     * drift apart from one another.
+     */
+    static fullyOpenFieldPermissions() {
+        return { CanRead: true, CanUpdate: true, CanCreate: true };
+    }
+    /**
+     * Trinary aggregation across the user's roles. Split out of
+     * {@link GetUserFieldPermissions} so the guards there read as policy and this reads as
+     * arithmetic.
+     */
+    aggregateUserFieldPermissions(user) {
+        return EntityFieldInfo.AggregateFieldRulesForUser(this._FieldPermissions, user);
+    }
+    /**
+     * The same aggregation {@link GetUserFieldPermissions} performs, over a rule list the caller
+     * supplies rather than this field's stored one.
+     *
+     * Exists so save-time guards can evaluate a **prospective** outcome — the rules as they would
+     * stand after a proposed insert, edit or delete — instead of classifying a single row in
+     * isolation. That distinction is load-bearing: whether a change restricts a user is a property
+     * of the AGGREGATE across all the roles they hold, not of any one rule. A rule reading
+     * `No Access` restricts nobody on its own, yet setting every one of a user's roles to
+     * `No Access` leaves no `Allow` standing and denies the field outright.
+     *
+     * @param rules the rules to aggregate — any shape carrying a `RoleID` and the three verbs
+     * @param user the user whose roles select which rules apply
+     */
+    static AggregateFieldRulesForUser(rules, user) {
+        const allow = { CanRead: false, CanUpdate: false, CanCreate: false };
+        const deny = { CanRead: false, CanUpdate: false, CanCreate: false };
+        for (const fp of rules) {
+            const roleMatch = user?.UserRoles?.find((r) => UUIDsEqual(r.RoleID, fp.RoleID));
+            if (!roleMatch) {
+                continue; // user does not hold this role
+            }
+            EntityFieldInfo.applyAccessToBuckets(fp.ReadAccess, allow, deny, 'CanRead');
+            EntityFieldInfo.applyAccessToBuckets(fp.UpdateAccess, allow, deny, 'CanUpdate');
+            EntityFieldInfo.applyAccessToBuckets(fp.CreateAccess, allow, deny, 'CanCreate');
+        }
+        const effective = {
+            CanRead: allow.CanRead && !deny.CanRead,
+            CanUpdate: allow.CanUpdate && !deny.CanUpdate,
+            CanCreate: allow.CanCreate && !deny.CanCreate,
+        };
+        // Read is required for Update and Create. A CHECK constraint enforces this per ROW and
+        // cannot enforce it here: role A granting Read+Update and role B denying Read are each
+        // individually legal, yet a user holding both aggregates to read-denied +
+        // update-allowed. This clamp is what makes that combination unreachable at runtime.
+        if (!effective.CanRead) {
+            effective.CanUpdate = false;
+            effective.CanCreate = false;
+        }
+        return effective;
+    }
+    /**
+     * Folds one trinary verb into the Allow/Deny buckets. Anything unrecognized is treated as
+     * `No Access`, so a value reaching here outside the CHECK constraint grants nothing.
+     */
+    static applyAccessToBuckets(access, allow, deny, verb) {
+        switch ((access ?? '').trim().toLowerCase()) {
+            case 'allow':
+                allow[verb] = true;
+                break;
+            case 'deny':
+                deny[verb] = true;
+                break;
+            default:
+                break; // 'No Access', and anything unrecognized: neutral
+        }
+    }
     /**
      * Returns the ValueListType using the EntityFieldValueListType enum.
      */
@@ -878,6 +1288,42 @@ export class EntityFieldInfo extends BaseInfo {
             this.IsPrimaryKey ||
             this.IsSpecialDateField;
     }
+    /**
+     * True when {@link ExtendedType} is any Geo* tag (`Geo`, `GeoLatitude`, `GeoAddress`, …).
+     * Used by maps, distance, and GeoCodeSyncService. Display-only virtuals still count.
+     */
+    get IsGeoExtendedType() {
+        const t = this.ExtendedType;
+        return typeof t === 'string' && t.startsWith('Geo');
+    }
+    /**
+     * A Geo* field that can be written on Save. GeoCodeSyncService only runs when the
+     * entity has at least one of these. Virtual / AllowUpdateAPI=0 fields (PrimaryAddress*,
+     * `__mj_Latitude`, embedded `__mj_Latitude_{FK}`) are display-only — maps still use them.
+     */
+    get IsWritableGeoField() {
+        return this.IsGeoExtendedType && !this.IsVirtual && !!this.AllowUpdateAPI;
+    }
+    /**
+     * Native (table) latitude column — `ExtendedType=GeoLatitude`, or legacy `Geo` named Latitude.
+     */
+    get IsNativeLatitudeField() {
+        if (this.IsVirtual)
+            return false;
+        if (this.ExtendedType === 'GeoLatitude')
+            return true;
+        return this.ExtendedType === 'Geo' && /^lat(itude)?$/i.test(this.Name);
+    }
+    /**
+     * Native (table) longitude column — `ExtendedType=GeoLongitude`, or legacy `Geo` named Long*.
+     */
+    get IsNativeLongitudeField() {
+        if (this.IsVirtual)
+            return false;
+        if (this.ExtendedType === 'GeoLongitude')
+            return true;
+        return this.ExtendedType === 'Geo' && /^(lng|lon|long|longitude)$/i.test(this.Name);
+    }
     /**
      * Helper method that returns true if the field is one of the special reserved MJ date fields for tracking CreatedAt and UpdatedAt timestamps as well as the DeletedAt timestamp used for entities that
      * have DeleteType=Soft. This is only used when the entity has TrackRecordChanges=1 or for entities where DeleteType=Soft
@@ -1419,6 +1865,7 @@ export class EntityFieldInfo extends BaseInfo {
          * Flag to track if RelatedEntityJoinFieldsConfig parsing failed to avoid repeated parse attempts on bad JSON.
          */
         this._relatedEntityJoinFieldsFailedParsing = false;
+        this._FieldPermissions = [];
         /** Memoized {@link TSType} — `Type` is immutable after metadata load, so the classification never changes. */
         this._tsType = undefined;
         /**
@@ -1441,6 +1888,15 @@ export class EntityFieldInfo extends BaseInfo {
                 this._EntityFieldValues = [];
                 this._entityFieldValuesConstructed = true;
             }
+            // Field-level security records. Constructed eagerly rather than lazily (unlike
+            // EntityFieldValues above) because the array is empty for virtually every field in
+            // every deployment — there is no ~36,000-object construction cost to defer, and
+            // HasFieldPermissions is read on enforcement paths where a lazy hydration check
+            // would cost more than the construction it avoids.
+            const efp = initData.EntityFieldPermissions || initData._FieldPermissions || initData.FieldPermissions;
+            if (efp && efp.length > 0) {
+                this._FieldPermissions = efp.map((p) => new EntityFieldPermissionInfo(p));
+            }
         }
     }
     /**
@@ -1577,6 +2033,40 @@ export class EntityInfo extends BaseInfo {
         const layered = this.GeneratedBaseViewName?.trim();
         return !!layered && layered.toLowerCase() !== (this.BaseView ?? '').toLowerCase();
     }
+    /**
+     * Parsed SubtypeSelector configuration, if configured.
+     */
+    get SubtypeSelectorConfig() {
+        if (this._subtypeSelectorConfig === undefined) {
+            if (this.SubtypeSelector && typeof this.SubtypeSelector === 'string') {
+                try {
+                    const parsed = JSON.parse(this.SubtypeSelector);
+                    if (parsed && typeof parsed['Path'] === 'string' && parsed['Path'].trim().length > 0) {
+                        this._subtypeSelectorConfig = { Path: parsed['Path'].trim() };
+                    }
+                    else {
+                        LogError(`EntityInfo '${this.Name}': SubtypeSelector JSON must contain a non-empty 'Path' string property. Found: ${this.SubtypeSelector}`);
+                        this._subtypeSelectorConfig = null;
+                    }
+                }
+                catch (err) {
+                    LogError(`EntityInfo '${this.Name}': failed to parse SubtypeSelector JSON '${this.SubtypeSelector}': ${err instanceof Error ? err.message : String(err)}`);
+                    this._subtypeSelectorConfig = null;
+                }
+            }
+            else {
+                this._subtypeSelectorConfig = null;
+            }
+        }
+        return this._subtypeSelectorConfig;
+    }
+    /**
+     * True when at least one field is a writable Geo* source (street and/or native lat/lng).
+     * Person/Org PrimaryAddress* are virtual display fields and do **not** count.
+     */
+    get HasWritableGeoSourceFields() {
+        return (this.Fields ?? []).some(f => f.IsWritableGeoField);
+    }
     /**
      * Optional JSON configuration bag (shape = {@link IEntityConfiguration}).
      * Nested `UI.Form` holds generated-form chrome: layout, auto left-nav
@@ -1611,6 +2101,140 @@ export class EntityInfo extends BaseInfo {
     get ConfigurationObject() {
         return this.Configuration;
     }
+    /**
+     * The set of field names this user may NOT READ on this entity — the per-request primitive
+     * every field-security enforcement point is built on.
+     *
+     * Compute this ONCE per (entity, user) per request and pass the Set into any row loop.
+     * `GetUserFieldPermissions` is the per-FIELD primitive; calling it per row costs
+     * `fields x rows` aggregations (40,000 for a 1,000-row x 40-column result), each of which
+     * re-scans `user.UserRoles` and allocates. A Set lookup costs neither.
+     *
+     * Names are lowercased so callers can match case-insensitively, consistent with
+     * {@link ProjectRowsToFields}. Returns an EMPTY set — never null — both when the entity has
+     * field security switched off and when the user is denied nothing, so callers can treat
+     * `size === 0` as the single "nothing to do" condition.
+     */
+    GetDeniedReadFields(user) {
+        return this.getDeniedFields(user, (p) => !p.CanRead);
+    }
+    /**
+     * Whether this user may READ the named field — the single-field question, answered the same
+     * way {@link GetDeniedReadFields} answers it in bulk.
+     *
+     * Exists for **display code that is about to read a value it did not choose**: a form
+     * toolbar rendering the entity's Name field, an FK control rendering the joined display
+     * column, an IS-A card walking a sibling record's fields. `BaseEntity.Get()` throws for a
+     * denied field, so those call sites have to ask before they read or they take out the whole
+     * screen instead of hiding one value.
+     *
+     * This is a PREDICATE, deliberately — not a value accessor that quietly returns nothing.
+     * The caller still decides what to render in place of the value, which is the part that
+     * differs per surface and should not be hidden inside a getter.
+     *
+     * **Fails open** on a missing user, a missing field name, or an entity with field security
+     * switched off — matching `BaseEntity`'s own gate and `MjFormFieldComponent`. The server is
+     * the real boundary; a UI that blanked out fields because no user had resolved yet would be
+     * worse than one that shows them.
+     *
+     * PERFORMANCE: this delegates to {@link GetDeniedReadFields}, which walks every field on the
+     * entity. Fine for the handful of chrome reads it exists for; do NOT call it per row in a
+     * grid loop — compute the denied set once and test against it.
+     *
+     * @param fieldName the field about to be read
+     * @param user the acting user
+     */
+    IsFieldReadableByUser(fieldName, user) {
+        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+            return true;
+        }
+        return !this.GetDeniedReadFields(user).has(fieldName.trim().toLowerCase());
+    }
+    /**
+     * Whether this user may UPDATE the named field. Companion to
+     * {@link IsFieldReadableByUser}, for UI that needs to render a control read-only rather than
+     * let a user type into something the server will reject on save. Fails open on the same
+     * three conditions.
+     */
+    IsFieldUpdatableByUser(fieldName, user) {
+        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+            return true;
+        }
+        return !this.GetDeniedUpdateFields(user).has(fieldName.trim().toLowerCase());
+    }
+    /**
+     * Whether this user may supply a value for the named field when CREATING a record.
+     * Companion to {@link IsFieldReadableByUser}. Fails open on the same three conditions.
+     *
+     * Note the server does not REJECT a create-denied value — it drops it and takes the column
+     * default. So a UI that leaves such a field editable on a new record silently discards what
+     * the user typed, which is the case this exists to prevent.
+     */
+    IsFieldCreatableByUser(fieldName, user) {
+        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+            return true;
+        }
+        return !this.GetDeniedCreateFields(user).has(fieldName.trim().toLowerCase());
+    }
+    /**
+     * The set of field names this user may NOT UPDATE on this entity. Same per-request
+     * precompute contract as {@link GetDeniedReadFields}.
+     *
+     * A field can be readable and not updatable. The reverse cannot happen — Read is required
+     * for Update — so denied-read is always a subset of denied-update, but ask for the set you
+     * actually need rather than relying on that.
+     */
+    GetDeniedUpdateFields(user) {
+        return this.getDeniedFields(user, (p) => !p.CanUpdate);
+    }
+    /**
+     * The set of field names this user may NOT supply a value for when CREATING a record. Same
+     * per-request precompute contract as {@link GetDeniedReadFields}.
+     *
+     * Unlike the update set, this does not drive a rejection: a value supplied for a
+     * create-denied field is dropped and the column takes its default.
+     */
+    GetDeniedCreateFields(user) {
+        return this.getDeniedFields(user, (p) => !p.CanCreate);
+    }
+    /**
+     * Shared walk behind {@link GetDeniedReadFields} / {@link GetDeniedUpdateFields} /
+     * {@link GetDeniedCreateFields}, short-circuiting on {@link EnableFieldLevelSecurity}.
+     *
+     * Every field is aggregated, including those carrying no permission records — on an enabled
+     * entity those are denied. Unrestrictable fields (primary keys, `__mj_` columns) come back
+     * open, decided inside `GetUserFieldPermissions` rather than skipped here.
+     *
+     * **Carries BOTH `Name` and `CodeName`**, because the callers do not all live in the same key
+     * space and a set holding only one of them silently no-ops in the other. `BaseEntity` and the
+     * predicate gate ask about field *Names*; the row projections
+     * (`ProviderBase.OmitFieldsFromRows`, the Record Changes payload projector) match against a
+     * *row's own keys*, and rows are keyed by `CodeName` — `getRunTimeViewFieldString` emits
+     * `[Name] AS [CodeName]` whenever the two differ, and `CodeNameFromString` replaces every
+     * `[^a-zA-Z0-9_]` with `_`. So for a column named `Base Salary` a Name-only set holds
+     * `base salary` while the rows are keyed `Base_Salary`, nothing matches, and the denied values
+     * are returned in full. Every shipped MJ field name is already a valid identifier, so the two
+     * coincide throughout core and no fixture caught this; it needs a customer entity with a
+     * column like `Base Salary` or `Emp #` — which is the population this feature exists for.
+     *
+     * Widening cannot over-deny. The only way an extra entry could catch an innocent field is if a
+     * DENIED field's `CodeName` equalled a different, permitted field's `Name` — but two fields
+     * that collide on `CodeName` already collide on their generated property, which is not a
+     * schema CodeGen can emit.
+     */
+    getDeniedFields(user, isDenied) {
+        const denied = new Set();
+        if (!this.EnableFieldLevelSecurity) {
+            return denied;
+        }
+        for (const field of this._Fields) {
+            if (isDenied(field.GetUserFieldPermissions(user, true))) {
+                denied.add(field.Name.trim().toLowerCase());
+                denied.add(field.CodeName.trim().toLowerCase());
+            }
+        }
+        return denied;
+    }
     /**
      * 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.
@@ -1638,6 +2262,12 @@ export class EntityInfo extends BaseInfo {
     /**
      * Returns the primary key field for the entity. For entities with a composite primary key, use the PrimaryKeys property which returns all.
      * In the case of a composite primary key, the PrimaryKey property will return the first field in the sequence of the primary key fields.
+     *
+     * This is a single-column convenience for the places MJ is single-column *by design* — foreign-key
+     * targets, keyset `ORDER BY`, IS-A shared keys, and the bare-value shorthand `CompositeKey.LoadFromURLSegment`
+     * accepts. Do not use it to *construct* a load key for an arbitrary entity: that silently drops every
+     * column but the first on a composite key. Build keys with `CompositeKey.FromURLSegment(entityInfo, recordId)`
+     * or `CompositeKey.FromEntityRecord(entityInfo, row)`, which honor all of `PrimaryKeys`.
      */
     get FirstPrimaryKey() {
         if (this._firstPrimaryKeyCache === undefined) {
@@ -2063,7 +2693,7 @@ export class EntityInfo extends BaseInfo {
             const allow = { CanCreate: false, CanRead: false, CanUpdate: false, CanDelete: false };
             const deny = { CanCreate: false, CanRead: false, CanUpdate: false, CanDelete: false };
             for (const ep of permissionList) {
-                const isDeny = (ep.Type || 'Allow').trim().toLowerCase() === 'deny';
+                const isDeny = ep.IsDeny;
                 const bucket = isDeny ? deny : allow;
                 bucket.CanCreate = bucket.CanCreate || !!ep.CanCreate;
                 bucket.CanRead = bucket.CanRead || !!ep.CanRead;
@@ -2089,7 +2719,15 @@ export class EntityInfo extends BaseInfo {
         }
     }
     /**
-     * Determines if a given user, for a given permission type, is exempt from RowLevelSecurity or not
+     * Determines if a given user, for a given permission type, is exempt from RowLevelSecurity or not.
+     *
+     * A permission row confers an exemption only for an operation it GRANTS (the matching `Can*`
+     * flag is true) and leaves unfiltered. A row that does not grant the operation has no filter
+     * for it either, and that absence means "not applicable", not "unrestricted" — so it must not
+     * lift a filter that another of the user's roles binds. Without the `Can*` check, a role that
+     * grants only reads (CanCreate=false, hence CreateRLSFilterID=null) made every holder of that
+     * role exempt from CREATE row-level security, which is the shape of the 'UI' role every
+     * authenticated user holds on nearly every entity.
      * @param user
      * @param type
      * @returns
@@ -2097,23 +2735,26 @@ export class EntityInfo extends BaseInfo {
     UserExemptFromRowLevelSecurity(user, type) {
         for (let j = 0; j < this.Permissions.length; j++) {
             const ep = this.Permissions[j];
+            if (ep.IsDeny) {
+                continue; // a Deny row's Can* flags are denials, never grants — it cannot exempt anyone
+            }
             const roleMatch = user.UserRoles?.find((r) => UUIDsEqual(r.RoleID, ep.RoleID));
             if (roleMatch) { // user has this role 
                 switch (type) {
                     case EntityPermissionType.Create:
-                        if (!ep.CreateRLSFilterID)
+                        if (ep.CanCreate && !ep.CreateRLSFilterID)
                             return true;
                         break;
                     case EntityPermissionType.Read:
-                        if (!ep.ReadRLSFilterID)
+                        if (ep.CanRead && !ep.ReadRLSFilterID)
                             return true;
                         break;
                     case EntityPermissionType.Update:
-                        if (!ep.UpdateRLSFilterID)
+                        if (ep.CanUpdate && !ep.UpdateRLSFilterID)
                             return true;
                         break;
                     case EntityPermissionType.Delete:
-                        if (!ep.DeleteRLSFilterID)
+                        if (ep.CanDelete && !ep.DeleteRLSFilterID)
                             return true;
                         break;
                 }
@@ -2122,7 +2763,18 @@ export class EntityInfo extends BaseInfo {
         return false; // if we get here, the user is NOT exempt from RLS for this Permission Type
     }
     /**
-     * Returns RLS security info attributes for a given user and permission type
+     * Returns RLS security info attributes for a given user and permission type.
+     *
+     * Only permission rows that GRANT the operation contribute a filter: an Allow row whose matching
+     * `Can*` flag is true. Deny rows are skipped outright — on a Deny row a set `Can*` flag means
+     * "deny that operation", and a user carrying one fails the permission gate before this runs
+     * (`GetUserPermisions` subtracts Deny from Allow), so reading it as a grant would be wrong even
+     * though it is unreachable. The filters of a user's roles are OR'd together by the caller, so a filter collected
+     * from a row that does not grant the operation would WIDEN the clause: a user granted Create by
+     * role A (bound to filter F1) would create against `F1 OR F2` when role B keeps a leftover
+     * `CreateRLSFilterID = F2` beside `CanCreate = false`. `GetUserPermisions` aggregates the flags
+     * across roles, so such a user passes the permission gate on role A alone; nothing else stops
+     * F2 from applying. A user with no granting row gets no clause here — and no permission either.
      * @param user
      * @param type
      * @returns
@@ -2131,24 +2783,27 @@ export class EntityInfo extends BaseInfo {
         const rlsList = [];
         for (let j = 0; j < this.Permissions.length; j++) {
             const ep = this.Permissions[j];
+            if (ep.IsDeny) {
+                continue; // never a grant — see the doc comment
+            }
             const roleMatch = user.UserRoles?.find((r) => UUIDsEqual(r.RoleID, ep.RoleID));
             if (roleMatch) { // user has this role
                 let matchObject = null;
                 switch (type) {
                     case EntityPermissionType.Create:
-                        if (ep.CreateRLSFilterID)
+                        if (ep.CanCreate && ep.CreateRLSFilterID)
                             matchObject = ep.CreateRLSFilterObject;
                         break;
                     case EntityPermissionType.Read:
-                        if (ep.ReadRLSFilterID)
+                        if (ep.CanRead && ep.ReadRLSFilterID)
                             matchObject = ep.ReadRLSFilterObject;
                         break;
                     case EntityPermissionType.Update:
-                        if (ep.UpdateRLSFilterID)
+                        if (ep.CanUpdate && ep.UpdateRLSFilterID)
                             matchObject = ep.UpdateRLSFilterObject;
                         break;
                     case EntityPermissionType.Delete:
-                        if (ep.DeleteRLSFilterID)
+                        if (ep.CanDelete && ep.DeleteRLSFilterID)
                             matchObject = ep.DeleteRLSFilterObject;
                         break;
                 }
@@ -2284,7 +2939,7 @@ export class EntityInfo extends BaseInfo {
         }
         else {
             // currently we only support a single value for FOREIGN KEYS, so we can just grab the first value in the primary key
-            const firstKey = record.FirstPrimaryKey;
+            const firstKey = record.FirstPrimaryKey; // first-pk-ok: FK target — a relationship's join field references one parent key column
             keyValue = firstKey.Value;
             //When creating a new record, the keyValue is null and the quotes are not needed
             quotes = keyValue && firstKey.NeedsQuotes ? "'" : '';
@@ -2324,7 +2979,7 @@ export class EntityInfo extends BaseInfo {
             if (rel)
                 return EntityInfo.BuildRelationshipViewParams(record, rel);
         }
-        const firstKey = record.FirstPrimaryKey;
+        const firstKey = record.FirstPrimaryKey; // first-pk-ok: FK target — a relationship's join field references one parent key column
         const keyValue = firstKey.Value;
         const quotes = keyValue && firstKey.NeedsQuotes ? "'" : '';
         const clauses = fields.map((field) => `[${field}] = ${quotes}${keyValue}${quotes}`);
@@ -2373,7 +3028,7 @@ export class EntityInfo extends BaseInfo {
         const explicit = relationship?.EntityKeyField?.trim();
         if (explicit)
             return record.Get(explicit);
-        const first = record.FirstPrimaryKey;
+        const first = record.FirstPrimaryKey; // first-pk-ok: FK target — a relationship's join field references one parent key column
         if (first?.Name)
             return record.Get(first.Name);
         return first?.Value;
@@ -2654,6 +3309,12 @@ export class EntityInfo extends BaseInfo {
          * This flag is set on the **parent** entity and controls whether its children are exclusive.
          */
         this.AllowMultipleSubtypes = false;
+        /**
+         * Optional JSON configuration specifying declarative prospective subtype resolution on an entity.
+         * Stored in the SubtypeSelector column of Entity (shape = IEntitySubtypeSelectorConfig).
+         */
+        this.SubtypeSelector = null;
+        this._subtypeSelectorConfig = undefined;
         /**
          * Whether to audit when users access records from this entity
          */
@@ -2678,6 +3339,19 @@ export class EntityInfo extends BaseInfo {
          * client-side IndexedDB cache. Zero overhead on hot save/query paths.
          */
         this.AllowCaching = false;
+        /**
+         * Whether field-level (column-level) security is enforced for this entity.
+         *
+         * This is the single gate every field-security enforcement point checks first, and it is
+         * explicit — never inferred from whether permission rows happen to exist. It is `false` for
+         * nearly every entity in nearly every deployment, so enforcement collapses to one boolean
+         * test: no field iteration, no aggregation, no allocation.
+         *
+         * Turning it on snapshots the entity's existing entity-level permissions into per-field
+         * rows, so enabling changes no behavior until an administrator tightens a field. Turning it
+         * off leaves the rows in place, inactive, so re-enabling does not lose the configuration.
+         */
+        this.EnableFieldLevelSecurity = false;
         /**
          * Whether this entity is available through the GraphQL API
          */
@@ -2788,9 +3462,10 @@ export class EntityInfo extends BaseInfo {
          */
         this.FullTextSearchFunctionGenerated = true;
         /**
-         * When true, this entity supports geocoding — CodeGen generates geo-aware subclass code,
-         * adds __mj_Latitude/__mj_Longitude virtual fields to the base view, and the UI shows
-         * a map view toggle. Auto-set by CodeGen when LLM detects geo-capable fields.
+         * When true, this entity participates in geo **read** features: map view, distance
+         * calculations, and similar. That is independent of whether GeoCodeSyncService runs
+         * on Save — the service only fires when {@link HasWritableGeoSourceFields} is true.
+         * Auto-set by CodeGen when LLM detects geo-capable fields.
          */
         this.SupportsGeoCoding = false;
         /**
@@ -3053,7 +3728,7 @@ export class EntityInfo extends BaseInfo {
                     er.sort((a, b) => {
                         const aSeq = a.Sequence !== null && a.Sequence !== undefined ? a.Sequence : 999999;
                         const bSeq = b.Sequence !== null && b.Sequence !== undefined ? b.Sequence : 999999;
-                        return aSeq - bSeq;
+                        return (aSeq - bSeq) || ordinalCompare(a.RelatedEntity, b.RelatedEntity) || ordinalCompare(a.ID, b.ID);
                     });
                 }
                 // now that we have prepared the er array by sorting it, if needed, let's load up the related entities