@memberjunction/core 5.42.0 → 5.44.0

package/dist/generic/BaseEntitySaveQueue.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Entity-aware façade over {@link KeyedSerialTaskQueue} for the fire-and-forget save
+ * pattern. Captures the `Save()` calls, `IgnoreDirtyState` force-persist, and error extraction that
+ * the agent-step / action-log / prompt-run logging sites otherwise hand-roll. The key correctness
+ * property is structural: `Update`'s mutation runs *inside* the post-INSERT task, so it can never be
+ * reverted by the INSERT's `finalizeSave` reload (the "stuck at Running" race becomes impossible).
+ * @module @memberjunction/core
+ */
+import { SerialTaskFlushResult } from '@memberjunction/global';
+import { BaseEntity } from './baseEntity.js';
+/**
+ * A per-entity-instance serial save queue. INSERT and UPDATE of the same `BaseEntity` instance are
+ * serialized (the UPDATE waits for the INSERT to land); different entities save concurrently. All
+ * saves are fire-and-forget and **never throw outward** — a failed `Save()` (returned `false` or a
+ * thrown error) is logged and counted; call {@link Flush} at a run/goal boundary to await them and
+ * surface the failure count.
+ */
+export declare class BaseEntitySaveQueue {
+    private readonly queue;
+    private readonly onError?;
+    /**
+     * @param opts.onError Optional handler for a failed save's diagnostic message. Defaults to the
+     *   global `LogError`. Consumers with structured logging (e.g. a category/metadata logger) pass
+     *   their own so failures stay in their log stream.
+     */
+    constructor(opts?: {
+        onError?: (message: string) => void;
+    });
+    /**
+     * Fire-and-forget INSERT of a freshly `NewRecord()`'d entity. The entity instance is the
+     * serialization key, so a subsequent {@link Update} of the same instance waits for this to land.
+     */
+    Insert(entity: BaseEntity): void;
+    /**
+     * Fire-and-forget INSERT that waits for `dependency`'s pending tasks to settle first. Use this for
+     * self-referencing foreign keys: a child entity whose FK points at `dependency` must not INSERT
+     * until the dependency's own INSERT has landed in the database.
+     */
+    InsertAfter(entity: BaseEntity, dependency: BaseEntity): void;
+    /**
+     * Fire-and-forget UPDATE chained after the entity's INSERT. `applyMutation` (if given) runs INSIDE
+     * the post-INSERT task — after `finalizeSave`'s reload — so its values always survive; the save is
+     * force-persisted with `IgnoreDirtyState`. Pass no mutation only when the fields are already set
+     * AND cannot race an in-flight INSERT.
+     */
+    Update(entity: BaseEntity, applyMutation?: (entity: BaseEntity) => void): void;
+    /** Awaits all pending saves and returns failure diagnostics. Call at the run/goal finalize boundary. */
+    Flush(): Promise<SerialTaskFlushResult>;
+    /**
+     * Applies the optional mutation, saves, and returns success — logging and swallowing both a
+     * `false` result and a thrown error so a fire-and-forget save can never surface as an unhandled
+     * rejection (failures are counted via the queue's `isOk`).
+     */
+    private runSave;
+    /** Routes a failure message to the caller-supplied handler, or the global `LogError` by default. */
+    private logFailure;
+    private labelFor;
+    private saveError;
+}
+//# sourceMappingURL=BaseEntitySaveQueue.d.ts.map

package/dist/generic/BaseEntitySaveQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEntitySaveQueue.d.ts","sourceRoot":"","sources":["../../src/generic/BaseEntitySaveQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAwB,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA4B;IAErD;;;;OAIG;gBACS,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE;IAI1D;;;OAGG;IACI,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKvC;;;;OAIG;IACI,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAKpE;;;;;OAKG;IACI,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI;IAOrF,wGAAwG;IACjG,KAAK,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAI9C;;;;OAIG;YACW,OAAO;IAgBrB,oGAAoG;IACpG,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,SAAS;CAGpB"}

package/dist/generic/BaseEntitySaveQueue.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Entity-aware façade over {@link KeyedSerialTaskQueue} for the fire-and-forget save
+ * pattern. Captures the `Save()` calls, `IgnoreDirtyState` force-persist, and error extraction that
+ * the agent-step / action-log / prompt-run logging sites otherwise hand-roll. The key correctness
+ * property is structural: `Update`'s mutation runs *inside* the post-INSERT task, so it can never be
+ * reverted by the INSERT's `finalizeSave` reload (the "stuck at Running" race becomes impossible).
+ * @module @memberjunction/core
+ */
+import { KeyedSerialTaskQueue } from '@memberjunction/global';
+import { EntitySaveOptions } from './interfaces.js';
+import { LogError } from './logging.js';
+/**
+ * A per-entity-instance serial save queue. INSERT and UPDATE of the same `BaseEntity` instance are
+ * serialized (the UPDATE waits for the INSERT to land); different entities save concurrently. All
+ * saves are fire-and-forget and **never throw outward** — a failed `Save()` (returned `false` or a
+ * thrown error) is logged and counted; call {@link Flush} at a run/goal boundary to await them and
+ * surface the failure count.
+ */
+export class BaseEntitySaveQueue {
+    /**
+     * @param opts.onError Optional handler for a failed save's diagnostic message. Defaults to the
+     *   global `LogError`. Consumers with structured logging (e.g. a category/metadata logger) pass
+     *   their own so failures stay in their log stream.
+     */
+    constructor(opts) {
+        this.queue = new KeyedSerialTaskQueue();
+        this.onError = opts?.onError;
+    }
+    /**
+     * Fire-and-forget INSERT of a freshly `NewRecord()`'d entity. The entity instance is the
+     * serialization key, so a subsequent {@link Update} of the same instance waits for this to land.
+     */
+    Insert(entity) {
+        const label = this.labelFor('Insert', entity);
+        void this.queue.enqueue(entity, () => this.runSave(entity, label), { isOk: (ok) => ok === true, label });
+    }
+    /**
+     * Fire-and-forget INSERT that waits for `dependency`'s pending tasks to settle first. Use this for
+     * self-referencing foreign keys: a child entity whose FK points at `dependency` must not INSERT
+     * until the dependency's own INSERT has landed in the database.
+     */
+    InsertAfter(entity, dependency) {
+        const label = this.labelFor('Insert', entity);
+        void this.queue.enqueue(entity, () => this.runSave(entity, label), { isOk: (ok) => ok === true, label, after: dependency });
+    }
+    /**
+     * Fire-and-forget UPDATE chained after the entity's INSERT. `applyMutation` (if given) runs INSIDE
+     * the post-INSERT task — after `finalizeSave`'s reload — so its values always survive; the save is
+     * force-persisted with `IgnoreDirtyState`. Pass no mutation only when the fields are already set
+     * AND cannot race an in-flight INSERT.
+     */
+    Update(entity, applyMutation) {
+        const label = this.labelFor('Update', entity);
+        const options = new EntitySaveOptions();
+        options.IgnoreDirtyState = true;
+        void this.queue.enqueue(entity, () => this.runSave(entity, label, options, applyMutation), { isOk: (ok) => ok === true, label });
+    }
+    /** Awaits all pending saves and returns failure diagnostics. Call at the run/goal finalize boundary. */
+    Flush() {
+        return this.queue.flush();
+    }
+    /**
+     * Applies the optional mutation, saves, and returns success — logging and swallowing both a
+     * `false` result and a thrown error so a fire-and-forget save can never surface as an unhandled
+     * rejection (failures are counted via the queue's `isOk`).
+     */
+    async runSave(entity, label, options, applyMutation) {
+        try {
+            if (applyMutation) {
+                applyMutation(entity);
+            }
+            const ok = await entity.Save(options);
+            if (!ok) {
+                this.logFailure(`${label} failed: ${this.saveError(entity)}`);
+            }
+            return ok;
+        }
+        catch (e) {
+            this.logFailure(`${label} threw: ${e instanceof Error ? e.message : String(e)}`);
+            return false;
+        }
+    }
+    /** Routes a failure message to the caller-supplied handler, or the global `LogError` by default. */
+    logFailure(message) {
+        if (this.onError) {
+            this.onError(message);
+        }
+        else {
+            LogError(message);
+        }
+    }
+    labelFor(op, entity) {
+        let name = 'entity';
+        try {
+            name = entity.EntityInfo?.Name ?? 'entity';
+        }
+        catch {
+            /* EntityInfo unavailable (e.g. a bare mock) — fall back to the generic label */
+        }
+        return `BaseEntitySaveQueue.${op}(${name})`;
+    }
+    saveError(entity) {
+        return entity.LatestResult?.CompleteMessage ?? 'Save returned false';
+    }
+}
+//# sourceMappingURL=BaseEntitySaveQueue.js.map

package/dist/generic/BaseEntitySaveQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEntitySaveQueue.js","sourceRoot":"","sources":["../../src/generic/BaseEntitySaveQueue.ts"],"names":[],"mappings":"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"}

package/dist/generic/EntityFieldRules.d.ts

@@ -0,0 +1,97 @@
+import type { EntityDocumentResolver, FieldChange, FieldRuleSet, PromptResolver } from '@memberjunction/global';
+import { BaseEntity } from './baseEntity.js';
+import { IMetadataProvider } from './interfaces.js';
+import { UserInfo } from './securityInfo.js';
+/** Result of {@link EntityFieldRules.Validate} — a pre-flight check of a rule set against entity metadata. */
+export interface EntityFieldRulesValidation {
+    /** True when every rule targets an existing, writable field and all source field references resolve. */
+    Valid: boolean;
+    /** Human-readable problems, one per offending rule (empty when Valid). */
+    Errors: string[];
+}
+/** Options controlling a compute/apply pass. */
+export interface EntityFieldRulesOptions {
+    /**
+     * Extra data the rules may reference beyond the entity's own fields (merged on top of the entity's
+     * field map — a `formula` can read `fields.SomeContextKey`, a `condition` can read `SomeContextKey`).
+     * Use for values you already hold: a data context, a query result, an agent's output payload.
+     */
+    Context?: Record<string, unknown>;
+    /** When true, compute the diff but DO NOT write — the returned changes are the preview. */
+    DryRun?: boolean;
+}
+/** Outcome of {@link EntityFieldRules.ApplyToEntity}. */
+export interface EntityFieldRulesResult {
+    /** The per-field diff (old → new) for every rule — the dry-run preview AND the applied record. */
+    Changes: FieldChange[];
+    /** Names of the fields that were (or, in dry-run, would be) written. */
+    AppliedFields: string[];
+    /** True when the entity was saved (always false in dry-run, on error, or when nothing changed). */
+    Saved: boolean;
+    /** True when this was a dry-run (no write attempted). */
+    DryRun: boolean;
+    /** Per-rule evaluation errors (condition/source/transform), if any. No write happens when present. */
+    Errors: string[];
+    /** Save error detail, when a real apply failed to persist. */
+    SaveError?: string;
+}
+/**
+ * Metadata-aware application of a {@link FieldRuleSet} to MJ entity records. Instantiate once per bulk
+ * run and reuse across records so the underlying expression cache is shared. Holds an acting user for
+ * the built-in lookup resolver.
+ */
+export declare class EntityFieldRules {
+    private readonly contextUser?;
+    private readonly evaluator;
+    /**
+     * @param contextUser - The acting user, used by the built-in `RunView`-backed lookup resolver
+     *   (required server-side; client-side may omit it).
+     * @param promptResolver - Optional resolver for `prompt` rule sources. Core does not depend on the AI
+     *   stack, so this is injected by a higher layer that has an `AIPromptRunner` (the bulk-update
+     *   processor supplies one). Omit it and any `prompt` rule reports a clear error instead of running.
+     * @param entityDocumentResolver - Optional resolver for `entityDocument` rule sources. Core does not
+     *   depend on the templates/AI stack, so this is injected by a higher layer that can render an Entity
+     *   Document (the processor supplies one). Omit it and any `entityDocument` rule reports a clear error.
+     */
+    constructor(contextUser?: UserInfo, promptResolver?: PromptResolver, entityDocumentResolver?: EntityDocumentResolver);
+    /**
+     * Pre-flight validation of a rule set against an entity's metadata. Pure + synchronous — safe to run
+     * in a UX on every edit. Checks each rule's target field exists and is writable, and that any `field`
+     * source reference resolves to a real field.
+     *
+     * @param entityName - The target entity.
+     * @param ruleSet - The rules to validate.
+     * @param provider - Metadata provider to resolve the entity (defaults to the global provider). Pass
+     *   the owning provider in multi-provider contexts.
+     */
+    static Validate(entityName: string, ruleSet: FieldRuleSet, provider?: IMetadataProvider): EntityFieldRulesValidation;
+    /**
+     * Computes the per-field changes for a loaded entity — WITHOUT mutating it — coercing each new value
+     * to the target field's type. This is the dry-run primitive.
+     *
+     * @param entity - A loaded entity (its current values are the "old" side of the diff).
+     * @param ruleSet - The rules to evaluate.
+     * @param context - Optional extra data the rules may reference (merged over the entity's fields).
+     */
+    ComputeForEntity(entity: BaseEntity, ruleSet: FieldRuleSet, context?: Record<string, unknown>): Promise<FieldChange[]>;
+    /**
+     * Computes and (unless `DryRun`) writes the rule results onto the entity, then `Save()`s it — so MJ
+     * Record Changes versioning captures the before/after. No write occurs if any rule errored or nothing
+     * changed.
+     *
+     * @param entity - A loaded entity to update.
+     * @param ruleSet - The rules to apply.
+     * @param options - {@link EntityFieldRulesOptions} (context + dry-run).
+     */
+    ApplyToEntity(entity: BaseEntity, ruleSet: FieldRuleSet, options?: EntityFieldRulesOptions): Promise<EntityFieldRulesResult>;
+    /** Coerces a computed change's NewValue to the target field's TS type (no-op for un-applied/errored). */
+    private coerceChange;
+    /** Aligns a raw value to an entity field's TS type. Leaves the value untouched when it can't convert. */
+    private static coerceToType;
+    private static equal;
+    /** A `RunView`-backed resolver for `lookup` rule sources (match one row, return one field). */
+    private buildLookupResolver;
+    /** Minimal SQL literal rendering for the lookup filter (escapes string quotes; numbers/bools inline). */
+    private static sqlLiteral;
+}
+//# sourceMappingURL=EntityFieldRules.d.ts.map

package/dist/generic/EntityFieldRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityFieldRules.d.ts","sourceRoot":"","sources":["../../src/generic/EntityFieldRules.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,YAAY,EAAkB,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AAChJ,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,8GAA8G;AAC9G,MAAM,WAAW,0BAA0B;IACvC,wGAAwG;IACxG,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACnC,kGAAkG;IAClG,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,wEAAwE;IACxE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mGAAmG;IACnG,KAAK,EAAE,OAAO,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,sGAAsG;IACtG,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAab,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAZzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAEhD;;;;;;;;;OASG;gBAC0B,WAAW,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,cAAc,EAAE,sBAAsB,CAAC,EAAE,sBAAsB;IAQrI;;;;;;;;;OASG;WACW,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,0BAA0B;IAwB3H;;;;;;;OAOG;IACU,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAMnI;;;;;;;;OAQG;IACU,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmBzI,yGAAyG;IACzG,OAAO,CAAC,YAAY;IAYpB,yGAAyG;IACzG,OAAO,CAAC,MAAM,CAAC,YAAY;IAyB3B,OAAO,CAAC,MAAM,CAAC,KAAK;IAMpB,+FAA+F;IAC/F,OAAO,CAAC,mBAAmB;IAmB3B,yGAAyG;IACzG,OAAO,CAAC,MAAM,CAAC,UAAU;CAM5B"}

package/dist/generic/EntityFieldRules.js

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Metadata-aware field rules for MemberJunction entities — the higher-order sibling of
+ * the pure field-rules engine in `@memberjunction/global`.
+ *
+ * The pure engine ({@link FieldRulesEvaluator} / {@link FieldTransformEngine} in `@memberjunction/global`)
+ * is deliberately metadata-blind: it computes a per-field diff from a plain `Record<string, unknown>`
+ * and an injected lookup resolver, so it can run anywhere (client, server, integration sync — wherever
+ * the "record" came from). {@link EntityFieldRules} layers the things that only make sense when the
+ * **target is a real MJ entity**, and which need the metadata layer in this package:
+ *
+ *  1. **Validation** — does each rule's target field exist on the entity, and is it writable
+ *     (not a primary key / read-only / virtual)? Source `field` references valid? This is a pre-flight
+ *     check a UX can run before anyone presses "Run".
+ *  2. **Type coercion** — a formula that yields the string `"42"` becomes the number `42` for a numeric
+ *     column, using each field's {@link EntityFieldInfo.TSType}. The pure engine produces raw values;
+ *     this aligns them to the entity's actual SQL types.
+ *  3. **Entity lookups** — a built-in `RunView`-backed resolver for `lookup` rule sources.
+ *  4. **Apply** — write the computed values onto a {@link BaseEntity} and `Save()`, so MJ's Record
+ *     Changes versioning captures the before/after automatically. Dry-run returns the diff and writes nothing.
+ *
+ * The **target is always an MJ entity**; the **source** may be the entity's own fields plus an optional
+ * injected `context` (data context, query result, agent output, related-entity lookups) — all data you
+ * already hold. When the *other side* is a live external system (its own protocol, auth, match
+ * resolution, sync direction), that is the domain of `@memberjunction/integration`, which uses the same
+ * pure transform engine for its per-field transforms. One engine, two purpose-built layers.
+ */
+import { FieldRulesEvaluator } from '@memberjunction/global';
+import { EntityFieldTSType } from './entityInfo.js';
+import { Metadata } from './metadata.js';
+import { RunView } from '../views/runView.js';
+/**
+ * Metadata-aware application of a {@link FieldRuleSet} to MJ entity records. Instantiate once per bulk
+ * run and reuse across records so the underlying expression cache is shared. Holds an acting user for
+ * the built-in lookup resolver.
+ */
+export class EntityFieldRules {
+    /**
+     * @param contextUser - The acting user, used by the built-in `RunView`-backed lookup resolver
+     *   (required server-side; client-side may omit it).
+     * @param promptResolver - Optional resolver for `prompt` rule sources. Core does not depend on the AI
+     *   stack, so this is injected by a higher layer that has an `AIPromptRunner` (the bulk-update
+     *   processor supplies one). Omit it and any `prompt` rule reports a clear error instead of running.
+     * @param entityDocumentResolver - Optional resolver for `entityDocument` rule sources. Core does not
+     *   depend on the templates/AI stack, so this is injected by a higher layer that can render an Entity
+     *   Document (the processor supplies one). Omit it and any `entityDocument` rule reports a clear error.
+     */
+    constructor(contextUser, promptResolver, entityDocumentResolver) {
+        this.contextUser = contextUser;
+        this.evaluator = new FieldRulesEvaluator({
+            LookupResolver: this.buildLookupResolver(),
+            PromptResolver: promptResolver,
+            EntityDocumentResolver: entityDocumentResolver,
+        });
+    }
+    /**
+     * Pre-flight validation of a rule set against an entity's metadata. Pure + synchronous — safe to run
+     * in a UX on every edit. Checks each rule's target field exists and is writable, and that any `field`
+     * source reference resolves to a real field.
+     *
+     * @param entityName - The target entity.
+     * @param ruleSet - The rules to validate.
+     * @param provider - Metadata provider to resolve the entity (defaults to the global provider). Pass
+     *   the owning provider in multi-provider contexts.
+     */
+    static Validate(entityName, ruleSet, provider) {
+        const md = provider ?? Metadata.Provider;
+        const entity = md?.EntityByName(entityName);
+        if (!entity) {
+            return { Valid: false, Errors: [`entity '${entityName}' not found in metadata`] };
+        }
+        const field = (name) => entity.FieldByName(name);
+        const errors = [];
+        ruleSet.Rules.forEach((rule, i) => {
+            const target = field(rule.TargetField);
+            if (!target) {
+                errors.push(`rule ${i + 1}: target field '${rule.TargetField}' does not exist on '${entityName}'`);
+            }
+            else if (target.ReadOnly) {
+                errors.push(`rule ${i + 1}: target field '${rule.TargetField}' is read-only and cannot be set`);
+            }
+            if (rule.Source.Kind === 'field' && !field(rule.Source.Field)) {
+                errors.push(`rule ${i + 1}: source field '${rule.Source.Field}' does not exist on '${entityName}'`);
+            }
+        });
+        return { Valid: errors.length === 0, Errors: errors };
+    }
+    /**
+     * Computes the per-field changes for a loaded entity — WITHOUT mutating it — coercing each new value
+     * to the target field's type. This is the dry-run primitive.
+     *
+     * @param entity - A loaded entity (its current values are the "old" side of the diff).
+     * @param ruleSet - The rules to evaluate.
+     * @param context - Optional extra data the rules may reference (merged over the entity's fields).
+     */
+    async ComputeForEntity(entity, ruleSet, context) {
+        const record = context ? { ...entity.GetAll(), ...context } : entity.GetAll();
+        const changes = await this.evaluator.ComputeChanges(record, ruleSet);
+        return changes.map((change) => this.coerceChange(change, entity));
+    }
+    /**
+     * Computes and (unless `DryRun`) writes the rule results onto the entity, then `Save()`s it — so MJ
+     * Record Changes versioning captures the before/after. No write occurs if any rule errored or nothing
+     * changed.
+     *
+     * @param entity - A loaded entity to update.
+     * @param ruleSet - The rules to apply.
+     * @param options - {@link EntityFieldRulesOptions} (context + dry-run).
+     */
+    async ApplyToEntity(entity, ruleSet, options) {
+        const changes = await this.ComputeForEntity(entity, ruleSet, options?.Context);
+        const errors = changes.filter((c) => c.Error).map((c) => `${c.Field}: ${c.Error}`);
+        const toApply = changes.filter((c) => c.Applied && c.Changed && !c.Error);
+        const base = {
+            Changes: changes, AppliedFields: toApply.map((c) => c.Field), Saved: false, DryRun: !!options?.DryRun, Errors: errors,
+        };
+        if (options?.DryRun || errors.length > 0 || toApply.length === 0) {
+            return base;
+        }
+        for (const change of toApply) {
+            // Dynamic, rule-driven field names — the legitimate use of Set() (no compile-time property).
+            entity.Set(change.Field, change.NewValue);
+        }
+        const saved = await entity.Save();
+        return { ...base, Saved: saved, SaveError: saved ? undefined : (entity.LatestResult?.CompleteMessage ?? 'save failed') };
+    }
+    /** Coerces a computed change's NewValue to the target field's TS type (no-op for un-applied/errored). */
+    coerceChange(change, entity) {
+        if (!change.Applied || change.Error || change.NewValue == null) {
+            return change;
+        }
+        const field = entity.EntityInfo.FieldByName(change.Field);
+        if (!field) {
+            return change;
+        }
+        const coerced = EntityFieldRules.coerceToType(change.NewValue, field.TSType);
+        return coerced === change.NewValue ? change : { ...change, NewValue: coerced, Changed: !EntityFieldRules.equal(change.OldValue, coerced) };
+    }
+    /** Aligns a raw value to an entity field's TS type. Leaves the value untouched when it can't convert. */
+    static coerceToType(value, tsType) {
+        switch (tsType) {
+            case EntityFieldTSType.Number: {
+                const n = Number(value);
+                return Number.isFinite(n) ? n : value;
+            }
+            case EntityFieldTSType.Boolean: {
+                if (typeof value === 'boolean')
+                    return value;
+                if (typeof value === 'number')
+                    return value !== 0;
+                const s = String(value).toLowerCase().trim();
+                if (s === 'true' || s === '1' || s === 'yes')
+                    return true;
+                if (s === 'false' || s === '0' || s === 'no')
+                    return false;
+                return value;
+            }
+            case EntityFieldTSType.Date: {
+                const d = value instanceof Date ? value : new Date(String(value));
+                return isNaN(d.getTime()) ? value : d;
+            }
+            case EntityFieldTSType.String:
+                return typeof value === 'string' ? value : String(value);
+            default:
+                return value;
+        }
+    }
+    static equal(a, b) {
+        if (a === b)
+            return true;
+        if (a instanceof Date && b instanceof Date)
+            return a.getTime() === b.getTime();
+        return a == null && b == null;
+    }
+    /** A `RunView`-backed resolver for `lookup` rule sources (match one row, return one field). */
+    buildLookupResolver() {
+        return async (lookup) => {
+            const result = await new RunView().RunView({
+                EntityName: lookup.Entity,
+                ExtraFilter: `[${lookup.MatchField}] = ${EntityFieldRules.sqlLiteral(lookup.MatchValue)}`,
+                Fields: [lookup.ReturnField],
+                MaxRows: 1,
+                ResultType: 'simple',
+            }, this.contextUser);
+            if (!result.Success || !result.Results?.length) {
+                return undefined;
+            }
+            return result.Results[0][lookup.ReturnField];
+        };
+    }
+    /** Minimal SQL literal rendering for the lookup filter (escapes string quotes; numbers/bools inline). */
+    static sqlLiteral(value) {
+        if (value == null)
+            return 'NULL';
+        if (typeof value === 'number' || typeof value === 'bigint')
+            return String(value);
+        if (typeof value === 'boolean')
+            return value ? '1' : '0';
+        return `'${String(value).replace(/'/g, "''")}'`;
+    }
+}
+//# sourceMappingURL=EntityFieldRules.js.map

package/dist/generic/EntityFieldRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityFieldRules.js","sourceRoot":"","sources":["../../src/generic/EntityFieldRules.ts"],"names":[],"mappings":"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"}

package/dist/generic/authTypes.d.ts

@@ -11,6 +11,7 @@ export declare const AUTH_PROVIDER_TYPES: {
     readonly OKTA: "okta";
     readonly COGNITO: "cognito";
     readonly GOOGLE: "google";
+    readonly WORKOS: "workos";
     readonly CUSTOM: "custom";
 };
 /**

package/dist/generic/authTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../src/generic/authTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;CAOtB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}
+{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../src/generic/authTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAQtB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}

package/dist/generic/authTypes.js

@@ -11,6 +11,7 @@ export const AUTH_PROVIDER_TYPES = {
     OKTA: 'okta',
     COGNITO: 'cognito',
     GOOGLE: 'google',
+    WORKOS: 'workos',
     CUSTOM: 'custom'
 };
 //# sourceMappingURL=authTypes.js.map

package/dist/generic/authTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"authTypes.js","sourceRoot":"","sources":["../../src/generic/authTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC"}
+{"version":3,"file":"authTypes.js","sourceRoot":"","sources":["../../src/generic/authTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC"}

package/dist/generic/baseEngine.d.ts

@@ -174,6 +174,26 @@ export interface EngineDataMapEntry {
     data: unknown[];
     loadedSuccessfully: boolean;
     errorMessage?: string;
+    /**
+     * True when this config was skipped because the current user lacks read
+     * permission on its entity. The data array will be empty `[]`.
+     */
+    permissionDenied?: boolean;
+}
+/**
+ * Thrown when engine data is accessed but was never loaded because the
+ * current user lacks read permissions on the underlying entities.
+ *
+ * Consumers that want graceful degradation should check
+ * `engine.IsPermissionConstrained` BEFORE accessing properties.
+ * This exception is the safety net for code paths that forget to check.
+ */
+export declare class PermissionConstrainedError extends Error {
+    /** The engine class name (e.g., 'AIEngineBase', 'QueryEngine') */
+    readonly EngineName: string;
+    /** The entity names that were denied */
+    readonly DeniedEntities: string[];
+    constructor(engineName: string, deniedEntities: string[]);
 }
 export declare abstract class BaseEngine<T> extends BaseSingleton<T> implements IStartupSink {
     private _loaded;
@@ -188,6 +208,8 @@ export declare abstract class BaseEngine<T> extends BaseSingleton<T> implements
     private _dataChange$;
     private _cacheChangeUnsubscribers;
     private _propertySubjects;
+    private _isPermissionConstrained;
+    private _deniedEntityNames;
     /**
      * Returns an Observable for a specific engine array property. Subscribers receive the
      * current array immediately (BehaviorSubject semantics), then re-receive the same array
@@ -238,6 +260,42 @@ export declare abstract class BaseEngine<T> extends BaseSingleton<T> implements
      * @param affectedEntity - For add/update/delete, the entity that was affected
      */
     protected NotifyDataChange(config: BaseEnginePropertyConfig, data: unknown[], changeType?: 'refresh' | 'add' | 'update' | 'delete', affectedEntity?: BaseEntity): void;
+    /**
+     * True when the engine loaded successfully but all entity configs were
+     * skipped because the current user lacks read permissions. Accessor
+     * properties will throw {@link PermissionConstrainedError} if accessed
+     * in this state. Check this flag first to degrade gracefully.
+     */
+    get IsPermissionConstrained(): boolean;
+    /**
+     * Retrieves engine-loaded data for a config property by name. This is the
+     * canonical accessor for engine getter properties — it checks the data map
+     * for permission denial and throws {@link PermissionConstrainedError} with
+     * the specific denied entity name(s) if the config was skipped.
+     *
+     * Subclasses should use this in every getter that exposes engine-loaded data:
+     * ```typescript
+     * public get Models(): MJAIModelEntityExtended[] {
+     *     return this.GetConfigData<MJAIModelEntityExtended>('_models');
+     * }
+     * ```
+     *
+     * @param propertyName - The config property name (e.g., '_models', '_agents'),
+     *   matching the PropertyName used in the engine's Config() params array.
+     * @returns The data array for the property, or an empty array if not yet loaded.
+     * @throws {PermissionConstrainedError} if the property was skipped due to permission denial.
+     */
+    protected GetConfigData<E>(propertyName: string): E[];
+    /**
+     * Check if a specific property was skipped due to permission denial.
+     * Forward-compatible with a future partial-loading approach.
+     */
+    IsPropertyPermissionConstrained(propertyName: string): boolean;
+    /**
+     * List of entity names that were skipped due to permission denial.
+     * Empty if not permission-constrained. Useful for logging/diagnostics.
+     */
+    get PermissionConstrainedEntities(): string[];
     /**
      * Controls the default RunView ResultType for all entity configs loaded by this engine.
      * Override in subclasses to change the default for the entire engine without modifying
@@ -539,6 +597,18 @@ export declare abstract class BaseEngine<T> extends BaseSingleton<T> implements
      *   directly from the database. Passed through from {@link Load} when `forceRefresh` is true (i.e., `Config(true)`).
      */
     protected LoadConfigs(configs: Partial<BaseEnginePropertyConfig>[], contextUser: UserInfo, bypassCache?: boolean): Promise<void>;
+    /**
+     * All-or-nothing permission gate: checks `CanRead` on every entity config. If ANY
+     * entity is denied, ALL configs are skipped — the engine is marked permission-constrained
+     * and its data arrays are set to empty `[]`. This prevents noisy permission-denied errors
+     * and endless retry loops for users with limited permissions (e.g., org-scoped SaaS roles).
+     *
+     * On the server side with a system user (who has all permissions), this method returns
+     * the original configs unchanged — no behavior change for privileged users.
+     *
+     * @returns The original configs array (all permissions pass) or an empty array (any denied)
+     */
+    protected CheckPermissionsOrSkipAll(configs: BaseEnginePropertyConfig[], contextUser: UserInfo): BaseEnginePropertyConfig[];
     /**
      * Loads a single metadata configuration.
      * @param config - The metadata configuration to load