@memberjunction/core 5.4.1 → 5.6.0

package/dist/generic/databaseProviderBase.d.ts

@@ -1,10 +1,52 @@
 import { ProviderBase } from "./providerBase.js";
 import { UserInfo } from "./securityInfo.js";
+import { EntityDependency, EntityInfo, RecordChange, RecordDependency, RecordMergeRequest, RecordMergeResult } from "./entityInfo.js";
+import { BaseEntity, BaseEntityResult } from "./baseEntity.js";
+import { EntitySaveOptions, EntityDeleteOptions, EntityMergeOptions, PotentialDuplicateRequest, PotentialDuplicateResponse } from "./interfaces.js";
+import { CompositeKey } from "./compositeKey.js";
+import { AggregateResult, EntityRecordNameInput, EntityRecordNameResult, RunReportResult } from "./interfaces.js";
+import { RunReportParams } from "./runReport.js";
+export { DatabasePlatform, PlatformSQL, IsPlatformSQL } from "./platformSQL.js";
+import { DatabasePlatform } from "./platformSQL.js";
+/**
+ * Represents a single field change in the DiffObjects comparison result
+ */
+export type FieldChange = {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+};
+/**
+ * Result of save SQL generation. Subclasses populate this from their dialect-specific
+ * SQL generators (stored procedure calls, function calls, etc.).
+ */
+export interface SaveSQLResult {
+    /** The complete SQL to execute (may include record-change tracking, temp tables, etc.) */
+    fullSQL: string;
+    /** Simpler SQL without record-change wrapping, used for logging/migration replay */
+    simpleSQL?: string;
+    /** Parameterized query values (e.g. [$1,$2] for PG). Null/undefined for inline SQL. */
+    parameters?: unknown[] | null;
+    /** Provider-specific extra data (e.g. overlapping-change data for ISA propagation) */
+    extraData?: Record<string, unknown>;
+}
+/**
+ * Result of delete SQL generation.
+ */
+export interface DeleteSQLResult {
+    fullSQL: string;
+    simpleSQL?: string;
+    parameters?: unknown[] | null;
+}
 /**
  * This class is a generic server-side provider class to abstract database operations
  * on any database system and therefore be usable by server-side components that need to
  * do database operations but do not want close coupling with a specific database provider
  * like @see @memberjunction/sqlserver-dataprovider
+ *
+ * It contains DB-agnostic business logic (record change tracking, favorites, ISA hierarchy,
+ * record dependencies, diffing, etc.) that is shared across all database providers.
+ * Subclasses implement abstract methods for DB-specific SQL dialect generation.
  */
 export declare abstract class DatabaseProviderBase extends ProviderBase {
     /**
@@ -16,7 +58,7 @@ export declare abstract class DatabaseProviderBase extends ProviderBase {
      * @param T - The type of the result set
      * @returns A promise that resolves to an array of results of type T
      */
-    abstract ExecuteSQL<T>(query: string, parameters?: any[], options?: ExecuteSQLOptions, contextUser?: UserInfo): Promise<Array<T>>;
+    abstract ExecuteSQL<T>(query: string, parameters?: unknown[], options?: ExecuteSQLOptions, contextUser?: UserInfo): Promise<Array<T>>;
     /**
      * Begins a transaction for the current database connection.
      */
@@ -29,6 +71,616 @@ export declare abstract class DatabaseProviderBase extends ProviderBase {
      * Rolls back the current transaction.
      */
     abstract RollbackTransaction(): Promise<void>;
+    /**
+     * Returns the database platform key for this provider.
+     * Override in subclasses. Defaults to 'sqlserver' for backward compatibility.
+     * Inherited from ProviderBase; redeclared here for DatabaseProviderBase consumers.
+     */
+    get PlatformKey(): DatabasePlatform;
+    /**
+     * Gets the MemberJunction core schema name (e.g. '__mj').
+     * Subclasses should override if they have a different way to resolve this.
+     * Defaults to the value from ConfigData.
+     */
+    get MJCoreSchemaName(): string;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Quotes a database identifier (table, column, view name) using the provider's
+     * dialect convention. SQL Server uses [brackets], PostgreSQL uses "double quotes".
+     * @param name The identifier to quote
+     */
+    abstract QuoteIdentifier(name: string): string;
+    /**
+     * Quotes a schema-qualified object name (e.g. schema.viewName) using the provider's
+     * dialect convention. SQL Server uses [schema].[view], PostgreSQL uses "schema"."view".
+     * @param schemaName The schema name
+     * @param objectName The object name (table, view, etc.)
+     */
+    abstract QuoteSchemaAndView(schemaName: string, objectName: string): string;
+    /**
+     * Builds a UNION ALL query that checks each child entity's base table for a record
+     * with the given primary key. Used by FindISAChildEntity/FindISAChildEntities.
+     * @param childEntities The child entities to search
+     * @param recordPKValue The primary key value to find
+     */
+    protected abstract BuildChildDiscoverySQL(childEntities: EntityInfo[], recordPKValue: string): string;
+    /**
+     * Builds SQL for hard-link (foreign key) dependency queries.
+     * Returns a UNION ALL query across all dependent entities.
+     * @param entityDependencies The entity-level dependency metadata
+     * @param compositeKey The primary key of the record being checked
+     */
+    protected abstract BuildHardLinkDependencySQL(entityDependencies: EntityDependency[], compositeKey: CompositeKey): string;
+    /**
+     * Builds SQL for soft-link dependency queries (entities using EntityIDFieldName pattern).
+     * Returns a UNION ALL query across all soft-linked entities.
+     * @param entityName The entity name being checked for dependencies
+     * @param compositeKey The primary key of the record
+     */
+    protected abstract BuildSoftLinkDependencySQL(entityName: string, compositeKey: CompositeKey): string;
+    /**
+     * Generates the SQL (and optional parameters) for a Save (Create or Update) operation.
+     * Each provider produces its own dialect: SQL Server generates T-SQL EXEC statements,
+     * PostgreSQL generates SELECT FROM function(...) calls, etc.
+     *
+     * @param entity The entity being saved
+     * @param isNew  True for INSERT / Create, false for UPDATE
+     * @param user   The acting user (needed for encryption, audit columns, etc.)
+     */
+    protected abstract GenerateSaveSQL(entity: BaseEntity, isNew: boolean, user: UserInfo): Promise<SaveSQLResult>;
+    /**
+     * Generates the SQL (and optional parameters) for a Delete operation.
+     */
+    protected abstract GenerateDeleteSQL(entity: BaseEntity, user: UserInfo): DeleteSQLResult;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Regex pattern matching known database UUID/ID generation functions for this provider's platform.
+     * SQL Server should match NEWID, NEWSEQUENTIALID.
+     * PostgreSQL should match gen_random_uuid, uuid_generate_v4.
+     * Case-insensitive, should match the full string with optional whitespace and parens.
+     */
+    protected abstract get UUIDFunctionPattern(): RegExp;
+    /**
+     * Regex pattern matching known database default-value functions (non-UUID) for this provider's platform.
+     * SQL Server should match GETDATE, GETUTCDATE, SYSDATETIME, etc.
+     * PostgreSQL should match NOW, CURRENT_TIMESTAMP, clock_timestamp, etc.
+     * Case-insensitive, should match the full string with optional whitespace and parens.
+     */
+    protected abstract get DBDefaultFunctionPattern(): RegExp;
+    /**
+     * Combined regex covering UUID functions from ALL platforms.
+     * Used by the static convenience method for code that doesn't have a provider instance.
+     */
+    private static readonly _allPlatformUUIDPattern;
+    /**
+     * Combined regex covering default-value functions from ALL platforms.
+     * Used by the static convenience method for code that doesn't have a provider instance.
+     */
+    private static readonly _allPlatformDefaultPattern;
+    /**
+     * Checks whether a string value looks like a database UUID generation function
+     * for this provider's platform.
+     *
+     * @param value The string value to check
+     * @returns true if the value matches a known UUID generation function pattern
+     */
+    IsUUIDGenerationFunction(value: string): boolean;
+    /**
+     * Checks whether a string value looks like a known database default-value function
+     * that is NOT a UUID generator for this provider's platform.
+     *
+     * @param value The string value to check
+     * @returns true if the value matches a known non-UUID database function pattern
+     */
+    IsNonUUIDDatabaseFunction(value: string): boolean;
+    /**
+     * Static convenience: checks all platforms' UUID generation functions.
+     * Prefer the instance method when you have a provider reference.
+     */
+    static IsUUIDGenerationFunctionAllPlatforms(value: string): boolean;
+    /**
+     * Static convenience: checks all platforms' default-value functions.
+     * Prefer the instance method when you have a provider reference.
+     */
+    static IsNonUUIDDatabaseFunctionAllPlatforms(value: string): boolean;
+    /**
+     * Generates a new UUID suitable for use as a primary key or unique identifier.
+     * Uses uuidv4() from @memberjunction/global. Subclasses may override to provide
+     * platform-specific ID generation if needed.
+     *
+     * @returns A new UUID string
+     */
+    GenerateNewID(): string;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Creates a changes object by comparing two JavaScript objects, identifying fields that have different values.
+     * Each property in the returned object represents a changed field, with the field name as the key.
+     *
+     * @param oldData - The original data object to compare from
+     * @param newData - The new data object to compare to
+     * @param entityInfo - Entity metadata used to validate fields and determine comparison logic
+     * @param quoteToEscape - The quote character to escape in string values (typically "'")
+     * @returns A Record mapping field names to FieldChange objects, or null if either input is null/undefined.
+     *          Only includes fields that have actually changed and are not read-only.
+     */
+    DiffObjects(oldData: Record<string, unknown>, newData: Record<string, unknown>, entityInfo: EntityInfo, quoteToEscape: string): Record<string, FieldChange> | null;
+    /**
+     * Determines whether a specific field value has changed between old and new data.
+     */
+    private isFieldDifferent;
+    /**
+     * Escapes a value for use in diff output, handling strings and nested objects.
+     */
+    private escapeValueForDiff;
+    /**
+     * Converts a diff/changes object into a human-readable description of what changed.
+     * @param changesObject The output of DiffObjects()
+     * @param maxValueLength Maximum length for displayed values before truncation
+     * @param cutOffText Text to append when values are truncated
+     */
+    CreateUserDescriptionOfChanges(changesObject: Record<string, FieldChange>, maxValueLength?: number, cutOffText?: string): string;
+    /**
+     * Truncates a string value to a maximum length, appending trailing characters if truncated.
+     */
+    protected TrimString(value: unknown, maxLength: number, trailingChars: string): unknown;
+    /**
+     * Recursively escapes the specified quote character in all string properties of an object or array.
+     * Essential for preparing data to be embedded in SQL strings.
+     *
+     * @param obj - The object, array, or primitive value to process
+     * @param quoteToEscape - The quote character to escape (typically single quote "'")
+     * @returns A new object/array with all string values having quotes properly escaped
+     */
+    protected EscapeQuotesInProperties(obj: unknown, quoteToEscape: string): unknown;
+    /**
+     * Transforms a transaction result row into a list of field/value pairs.
+     */
+    protected MapTransactionResultToNewValues(transactionResult: Record<string, unknown>): {
+        FieldName: string;
+        Value: unknown;
+    }[];
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Discovers which IS-A child entity, if any, has a record with the given primary key.
+     * Executes a single UNION ALL query across all child entity tables for maximum efficiency.
+     *
+     * @param entityInfo The parent entity whose children to search
+     * @param recordPKValue The primary key value to find in child tables
+     * @param contextUser Optional context user for audit/permission purposes
+     * @returns The child entity name if found, or null if no child record exists
+     */
+    FindISAChildEntity(entityInfo: EntityInfo, recordPKValue: string, contextUser?: UserInfo): Promise<{
+        ChildEntityName: string;
+    } | null>;
+    /**
+     * Discovers ALL IS-A child entities that have records with the given primary key.
+     * Used for overlapping subtype parents (AllowMultipleSubtypes = true) where multiple
+     * children can coexist.
+     *
+     * @param entityInfo The parent entity whose children to search
+     * @param recordPKValue The primary key value to find in child tables
+     * @param contextUser Optional context user for audit/permission purposes
+     * @returns Array of child entity names found (empty if none)
+     */
+    FindISAChildEntities(entityInfo: EntityInfo, recordPKValue: string, contextUser?: UserInfo): Promise<{
+        ChildEntityName: string;
+    }[]>;
+    /**
+     * Checks whether a given entity matches the target name, or is an ancestor
+     * of the target (i.e., the target is somewhere in its descendant sub-tree).
+     * Used to identify and skip the active branch during sibling propagation.
+     */
+    protected IsEntityOrAncestorOf(entityInfo: EntityInfo, targetName: string): boolean;
+    /**
+     * Recursively enumerates an entity's entire sub-tree from metadata.
+     * No DB queries — uses EntityInfo.ChildEntities which is populated from metadata.
+     */
+    protected GetFullSubTree(entityInfo: EntityInfo): EntityInfo[];
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Retrieves the change history for a specific record.
+     * Uses the vwRecordChanges view which exists in both SQL Server and PostgreSQL.
+     *
+     * @param entityName The entity name
+     * @param compositeKey The record's composite primary key
+     * @param contextUser Optional context user
+     */
+    GetRecordChanges(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<RecordChange[]>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Checks if a record is marked as a favorite for a given user.
+     */
+    GetRecordFavoriteStatus(userId: string, entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<boolean>;
+    /**
+     * Gets the favorite record ID if the record is a favorite for the given user, null otherwise.
+     */
+    GetRecordFavoriteID(userId: string, entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<string | null>;
+    /**
+     * Creates or deletes a user favorite record for the specified entity record.
+     * Uses GetEntityObject and BaseEntity CRUD methods (no entity-specific type imports needed).
+     */
+    SetRecordFavoriteStatus(userId: string, entityName: string, compositeKey: CompositeKey, isFavorite: boolean, contextUser: UserInfo): Promise<void>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Returns a list of record-level dependencies — records in other entities linked to
+     * the specified entity/record via foreign keys (hard links) or EntityIDFieldName
+     * soft links. Uses abstract SQL builders for dialect-specific query generation.
+     *
+     * @param entityName The entity name to check
+     * @param compositeKey The primary key(s) of the record
+     * @param contextUser Optional context user
+     */
+    GetRecordDependencies(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<RecordDependency[]>;
+    /**
+     * Parses raw SQL results from dependency queries into RecordDependency objects.
+     */
+    private parseRecordDependencyResults;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Called during Save before any SQL is executed to run validation-type entity actions.
+     * Return a non-empty string to abort the save with that message; return null to proceed.
+     * SQL Server overrides this to delegate to HandleEntityActions('validate', ...).
+     */
+    protected OnValidateBeforeSave(_entity: BaseEntity, _user: UserInfo): Promise<string | null>;
+    /**
+     * Called before the save SQL is executed.
+     * SQL Server overrides this to fire before-save entity actions and AI actions.
+     */
+    protected OnBeforeSaveExecute(_entity: BaseEntity, _user: UserInfo, _options: EntitySaveOptions): Promise<void>;
+    /**
+     * Called after a successful save (both direct and transaction-callback paths).
+     * Intentionally synchronous (fire-and-forget) — SQL Server overrides to dispatch
+     * after-save entity actions and AI actions without awaiting.
+     */
+    protected OnAfterSaveExecute(_entity: BaseEntity, _user: UserInfo, _options: EntitySaveOptions): void;
+    /**
+     * Called before the delete SQL is executed.
+     * SQL Server overrides to fire before-delete entity actions and AI actions.
+     */
+    protected OnBeforeDeleteExecute(_entity: BaseEntity, _user: UserInfo, _options: EntityDeleteOptions): Promise<void>;
+    /**
+     * Called after a successful delete.
+     * Intentionally synchronous — see OnAfterSaveExecute.
+     */
+    protected OnAfterDeleteExecute(_entity: BaseEntity, _user: UserInfo, _options: EntityDeleteOptions): void;
+    /**
+     * Post-processes rows returned by a save/load SQL operation.
+     * SQL Server overrides to handle datetimeoffset conversion and field decryption.
+     * Default: returns rows unchanged.
+     */
+    protected PostProcessRows(rows: Record<string, unknown>[], _entityInfo: EntityInfo, _user: UserInfo): Promise<Record<string, unknown>[]>;
+    /**
+     * Called after a direct (non-transaction) save succeeds, before returning.
+     * SQL Server overrides to propagate record-change entries to IS-A sibling branches.
+     */
+    protected OnSaveCompleted(_entity: BaseEntity, _saveSQLResult: SaveSQLResult, _user: UserInfo, _options: EntitySaveOptions): Promise<void>;
+    /**
+     * Called before starting a save/delete SQL operation to pause background metadata refresh.
+     * SQL Server overrides to set _bAllowRefresh = false.
+     */
+    protected OnSuspendRefresh(): void;
+    /**
+     * Called after a save/delete SQL operation completes (success or failure) to resume refresh.
+     */
+    protected OnResumeRefresh(): void;
+    /**
+     * Returns provider-specific extra data to attach to a TransactionItem.
+     * SQL Server overrides to include { dataSource: this._pool }.
+     */
+    protected GetTransactionExtraData(_entity: BaseEntity): Record<string, unknown>;
+    /**
+     * Builds the ExecuteSQLOptions for a Save operation.
+     * SQL Server overrides to add connectionSource for IS-A shared transactions.
+     */
+    protected BuildSaveExecuteOptions(entity: BaseEntity, sqlDetails: SaveSQLResult): ExecuteSQLOptions;
+    /**
+     * Builds the ExecuteSQLOptions for a Delete operation.
+     */
+    protected BuildDeleteExecuteOptions(entity: BaseEntity, sqlDetails: DeleteSQLResult): ExecuteSQLOptions;
+    /**
+     * Validates the result of a delete SQL execution by checking that the returned
+     * primary keys match the entity being deleted.
+     * SQL Server overrides to handle the multi-result-set case (CASCADE deletes).
+     */
+    protected ValidateDeleteResult(entity: BaseEntity, rawResult: Record<string, unknown>[], entityResult: BaseEntityResult): boolean;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Validates a user-provided SQL clause (WHERE, ORDER BY, etc.) to prevent SQL injection.
+     * Checks for forbidden keywords (INSERT, UPDATE, DELETE, EXEC, DROP, UNION, CAST, etc.)
+     * and dangerous patterns (comments, semicolons, xp_ prefix).
+     * String literals are stripped before validation to avoid false positives.
+     *
+     * @param clause The SQL clause to validate
+     * @returns true if the clause is safe, false if it contains forbidden patterns
+     */
+    protected ValidateUserProvidedSQLClause(clause: string): boolean;
+    /**
+     * Checks that the given user has read permissions on the specified entity.
+     * Throws if the user lacks CanRead permission.
+     *
+     * @param entityName The entity to check permissions for
+     * @param contextUser The user whose permissions to check
+     * @throws Error if contextUser is null, entity is not found, or user lacks read permission
+     */
+    protected CheckUserReadPermissions(entityName: string, contextUser: UserInfo): void;
+    /**
+     * Builds and validates an aggregate SQL query from the provided aggregate expressions.
+     * Uses SQLExpressionValidator from @memberjunction/global for injection prevention.
+     * Uses QuoteIdentifier/QuoteSchemaAndView for dialect-neutral SQL generation.
+     *
+     * @param aggregates Array of aggregate expressions to validate and build
+     * @param entityInfo Entity metadata for field reference validation
+     * @param schemaName Schema name for the entity
+     * @param baseView Base view name for the entity
+     * @param whereSQL WHERE clause to apply (without the WHERE keyword)
+     * @returns Object with aggregateSQL string and any validation errors
+     */
+    protected BuildAggregateSQL(aggregates: {
+        expression: string;
+        alias?: string;
+    }[], entityInfo: EntityInfo, schemaName: string, baseView: string, whereSQL: string): {
+        aggregateSQL: string | null;
+        validationErrors: AggregateResult[];
+    };
+    /**
+     * Executes an aggregate query and maps results back to the original expressions.
+     *
+     * @param aggregateSQL The SQL query to execute (from BuildAggregateSQL)
+     * @param aggregates Original aggregate expression definitions
+     * @param validationErrors Any validation errors from BuildAggregateSQL
+     * @param contextUser User context for query execution
+     * @returns Array of AggregateResult objects with execution time
+     */
+    protected ExecuteAggregateQuery(aggregateSQL: string | null, aggregates: {
+        expression: string;
+        alias?: string;
+    }[], validationErrors: AggregateResult[], contextUser?: UserInfo): Promise<{
+        results: AggregateResult[];
+        executionTime: number;
+    }>;
+    /**
+     * Builds the SQL to retrieve the "name" field value for a specific entity record.
+     * Uses QuoteIdentifier/QuoteSchemaAndView for dialect-neutral SQL generation.
+     *
+     * @param entityName The entity name
+     * @param compositeKey The record's primary key
+     * @returns The SQL query string, or null if the entity has no name field
+     */
+    protected BuildEntityRecordNameSQL(entityName: string, compositeKey: CompositeKey): string | null;
+    /**
+     * Retrieves the display name for a single entity record.
+     * Uses BuildEntityRecordNameSQL for dialect-neutral SQL generation.
+     */
+    protected InternalGetEntityRecordName(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<string>;
+    /**
+     * Retrieves display names for multiple entity records.
+     */
+    protected InternalGetEntityRecordNames(info: EntityRecordNameInput[], contextUser?: UserInfo): Promise<EntityRecordNameResult[]>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Saves an entity record — the full orchestration flow shared by all DB providers.
+     *
+     * 1. Permission & dirty-state checks
+     * 2. Validation via OnValidateBeforeSave hook
+     * 3. Before-save actions via OnBeforeSaveExecute hook
+     * 4. SQL generation via GenerateSaveSQL (abstract, provider-specific)
+     * 5. Execute via TransactionGroup or directly
+     * 6. After-save actions via OnAfterSaveExecute hook
+     * 7. Post-save cleanup via OnSaveCompleted hook (ISA propagation, etc.)
+     */
+    Save(entity: BaseEntity, user: UserInfo, options: EntitySaveOptions): Promise<{}>;
+    /**
+     * Deletes an entity record — the full orchestration flow shared by all DB providers.
+     *
+     * 1. Permission checks & replay handling
+     * 2. SQL generation via GenerateDeleteSQL (abstract, provider-specific)
+     * 3. Before-delete actions via OnBeforeDeleteExecute hook
+     * 4. Execute via TransactionGroup or directly
+     * 5. Validate delete result (PK match check)
+     * 6. After-delete actions via OnAfterDeleteExecute hook
+     */
+    Delete(entity: BaseEntity, options: EntityDeleteOptions, user: UserInfo): Promise<boolean>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Creates an audit log record in the MJ: Audit Logs entity.
+     * Uses BaseEntity with .Set() calls (no typed entity subclass imports needed - can't use those from MJCore anyway).
+     * Callers typically fire-and-forget.
+     *
+     * @param user The user performing the action
+     * @param authorizationName Optional authorization name to look up
+     * @param auditLogTypeName The audit log type name (must exist in metadata)
+     * @param status 'Success' or 'Failed'
+     * @param details Optional details (JSON string, description, etc.)
+     * @param entityId The entity ID being audited
+     * @param recordId Optional record ID being audited
+     * @param auditLogDescription Optional description for the audit log
+     * @param saveOptions Save options to pass to the entity Save() call
+     * @returns The saved audit log BaseEntity, or null on error
+     */
+    CreateAuditLogRecord(user: UserInfo, authorizationName: string | null, auditLogTypeName: string, status: string, details: string | null, entityId: string, recordId: string | null, auditLogDescription: string | null, saveOptions: EntitySaveOptions | null): Promise<BaseEntity | null>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Handles entity actions (non-AI) for save, delete, or validate operations.
+     * Override in subclasses that have access to EntityActionEngineServer.
+     * Default: no-op, returns empty array.
+     *
+     * @param entity The entity being saved/deleted/validated
+     * @param baseType The operation type
+     * @param before True for before-hooks, false for after-hooks
+     * @param user The acting user
+     * @returns Array of action results (empty by default)
+     */
+    protected HandleEntityActions(_entity: BaseEntity, _baseType: 'save' | 'delete' | 'validate', _before: boolean, _user: UserInfo): Promise<{
+        Success: boolean;
+        Message?: string;
+    }[]>;
+    /**
+     * Handles AI-specific entity actions for save or delete operations.
+     * Override in subclasses that have access to AIEngine.
+     * Default: no-op.
+     */
+    protected HandleEntityAIActions(_entity: BaseEntity, _baseType: 'save' | 'delete', _before: boolean, _user: UserInfo): Promise<void>;
+    /**
+     * Returns AI actions configured for the given entity and timing.
+     * Override in subclasses that have access to AIEngine.
+     * Default: returns empty array.
+     */
+    protected GetEntityAIActions(_entityInfo: EntityInfo, _before: boolean): {
+        ID: string;
+        EntityID: string;
+        TriggerEvent: string;
+        AIActionID: string;
+        AIModelID: string;
+    }[];
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Returns the stored procedure / function name for a Create or Update operation.
+     * Pure metadata lookup — no SQL execution needed.
+     * SQL Server uses spCreate/spUpdate naming, PostgreSQL uses the same pattern.
+     *
+     * @param entity The entity being saved
+     * @param bNewRecord True for Create, false for Update
+     * @returns The SP/function name
+     */
+    GetCreateUpdateSPName(entity: BaseEntity, bNewRecord: boolean): string;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Logs a record change entry by diffing old/new data and executing
+     * provider-specific SQL to insert the record change.
+     * Concrete orchestration; SQL generation is delegated to BuildRecordChangeSQL.
+     *
+     * @param newData The new record data (null for deletes)
+     * @param oldData The old record data (null for creates)
+     * @param entityName The entity name
+     * @param recordID The record ID (CompositeKey string)
+     * @param entityInfo The entity metadata
+     * @param type The change type
+     * @param user The acting user
+     */
+    protected LogRecordChange(newData: Record<string, unknown> | null, oldData: Record<string, unknown> | null, entityName: string, recordID: string, entityInfo: EntityInfo, type: 'Create' | 'Update' | 'Delete', user: UserInfo): Promise<unknown[] | undefined>;
+    /**
+     * Builds the SQL (and optional parameters) for inserting a record change entry.
+     * Each provider generates its own dialect: SQL Server uses EXEC spCreateRecordChange_Internal,
+     * PostgreSQL uses INSERT INTO "RecordChange" with parameterized values.
+     *
+     * Returns null if there are no changes to log.
+     */
+    protected abstract BuildRecordChangeSQL(newData: Record<string, unknown> | null, oldData: Record<string, unknown> | null, entityName: string, recordID: string, entityInfo: EntityInfo, type: 'Create' | 'Update' | 'Delete', user: UserInfo): {
+        sql: string;
+        parameters?: unknown[];
+    } | null;
+    /**
+     * Propagates record change entries to sibling branches of an IS-A hierarchy.
+     * Called after saving an entity with AllowMultipleSubtypes (overlapping subtypes).
+     * Collects SQL from BuildSiblingRecordChangeSQL for each sibling and executes as a batch.
+     *
+     * @param parentInfo The parent entity info
+     * @param changeData The changes JSON and description
+     * @param pkValue The primary key value
+     * @param userId The acting user ID
+     * @param activeChildEntityName The child entity that initiated the save (to skip)
+     * @param extraExecOptions Optional provider-specific execution options (e.g. connectionSource for SQL Server transactions)
+     */
+    protected PropagateRecordChangesToSiblings(parentInfo: EntityInfo, changeData: {
+        changesJSON: string;
+        changesDescription: string;
+    }, pkValue: string, userId: string, activeChildEntityName: string | undefined, extraExecOptions?: Record<string, unknown>): Promise<void>;
+    /**
+     * Builds the SQL for a single sibling entity's record change entry in the propagation batch.
+     * SQL Server uses FOR JSON PATH + spCreateRecordChange_Internal.
+     * PostgreSQL uses json_build_object + INSERT INTO "RecordChange".
+     */
+    protected abstract BuildSiblingRecordChangeSQL(varName: string, entityInfo: EntityInfo, safeChangesJSON: string, safeChangesDesc: string, safePKValue: string, safeUserId: string): string;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Initiates duplicate detection for a list of records.
+     * Uses BaseEntity to create a Duplicate Run record.
+     * Subclasses may override to provide additional functionality.
+     *
+     * @param params The duplicate detection request parameters
+     * @param contextUser The acting user
+     * @returns A response indicating the duplicate detection status
+     */
+    GetRecordDuplicates(params: PotentialDuplicateRequest, contextUser?: UserInfo): Promise<PotentialDuplicateResponse>;
+    /**
+     * Merges multiple records into a single surviving record.
+     * Full orchestration: transaction, field map update, dependency re-pointing,
+     * deletion, and merge logging.
+     *
+     * @param request The merge request with surviving record and records to merge
+     * @param contextUser The acting user
+     * @param _options Optional merge options
+     * @returns The merge result
+     */
+    MergeRecords(request: RecordMergeRequest, contextUser?: UserInfo, _options?: EntityMergeOptions): Promise<RecordMergeResult>;
+    /**
+     * Creates the initial merge log record at the start of a merge operation.
+     * Uses BaseEntity with .Set() calls (no typed entity subclass imports available in MJCore).
+     */
+    protected StartMergeLogging(request: RecordMergeRequest, result: RecordMergeResult, contextUser?: UserInfo): Promise<BaseEntity>;
+    /**
+     * Finalizes merge logging by updating the log record with completion status
+     * and creating deletion detail records.
+     * Uses BaseEntity with .Set() calls (no typed entity subclass imports).
+     */
+    protected CompleteMergeLogging(recordMergeLog: BaseEntity, result: RecordMergeResult, contextUser?: UserInfo): Promise<void>;
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**************************************************************************/
+    /**
+     * Runs a report by looking up its SQL definition from vwReports and executing it.
+     * Both SQL Server and PostgreSQL share this logic — the only dialect difference
+     * is identifier quoting, handled by QuoteIdentifier/QuoteSchemaAndView.
+     *
+     * @param params Report parameters including ReportID
+     * @param contextUser Optional context user for permission/audit purposes
+     * @deprecated Reports are no longer supported and will eventually be removed. Interactive Components and Artifacts are replacements
+     */
+    RunReport(params: RunReportParams, contextUser?: UserInfo): Promise<RunReportResult>;
 }
 /**
  * Configuration options for SQL execution with logging support