@rapidrest/service-core 1.0.0-rc.7 → 1.0.0

package/dist/lib/models/RepoUtils.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2020-2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
 ////////////////////////////////////////////////////////////////////////////////
 import * as crypto from "crypto";
 import { MongoRepository } from "../database/MongoRepository.js";
@@ -20,15 +21,13 @@ import { BaseEntity } from "../models/BaseEntity.js";
 import { BaseMongoEntity } from "../models/BaseMongoEntity.js";
 import { ApiErrorMessages, ApiErrors } from "../ApiErrors.js";
 import { ApiError, ObjectDecorators, ObjectUtils, UserUtils } from "@rapidrest/core";
-import { DatabaseDecorators } from "../decorators/index.js";
-import { Redis } from "ioredis";
-import { ObjectFactory } from "../ObjectFactory.js";
 import { NotificationUtils } from "../NotificationUtils.js";
 import { RecoverableBaseEntity } from "./RecoverableBaseEntity.js";
 import { ACLAction } from "../security/index.js";
-import { ConnectionManager } from "../database/index.js";
+import { ConnectionManager, RedisCache } from "../database/index.js";
+import { registerRollbackHook, Transactional, transactionContext } from "../decorators/DatabaseDecorators.js";
 const { Config, Init, Inject, Logger } = ObjectDecorators;
-const { RedisConnection } = DatabaseDecorators;
+const _hashCache = new Map();
 /**
  * @author Jean-Philippe Steinmetz
  */
@@ -43,18 +42,25 @@ export class RepoUtils {
     async init() {
         // Retrieve the repository based on the modelClass that was passed in to the constructor
         if (!this.repo) {
-            if (!this.modelClass.datastore) {
+            if (!this.modelClass.datasource) {
                 throw new Error(`Cannot initialize RepoUtils. Did you forget to add @DataStore() to ${this.modelClass.name}?`);
             }
             if (!this.connectionManager) {
                 throw new Error("Cannot initialize RepoUtils. Failed to retrieve ConnectionManager.");
             }
-            const ds = this.connectionManager.connections.get(this.modelClass.datastore);
+            const ds = this.connectionManager.connections.get(this.modelClass.datasource);
             if (!ds) {
-                throw new Error(`Cannot initialize RepoUtils. No connection found for datastore '${this.modelClass.datastore}'`);
+                throw new Error(`Cannot initialize RepoUtils. No connection found for datasource '${this.modelClass.datasource}'`);
             }
             this.repo = ds.getRepository(this.modelClass);
         }
+        // Create the cache store if caching is enabled for this entity type
+        if (!this.cache && this.modelClass.cacheTTL) {
+            this.cache = await this._objectFactory?.newInstance(RedisCache, {
+                name: this.modelClass.fqn ?? this.modelClass.name,
+                args: [this.modelClass],
+            });
+        }
         if (!this.repo) {
             throw new Error(`Cannot initialize RepoUtils. No repository found for class ${this.modelClass.name}.`);
         }
@@ -68,11 +74,11 @@ export class RepoUtils {
         // Does the model specify a MongoDB shard configuration?
         const shardConfig = Reflect.getMetadata("rrst:shardConfig", this.modelClass);
         if (shardConfig && this.repo instanceof MongoRepository) {
-            const conn = this.connectionManager?.connections.get(this.modelClass.datastore);
+            const conn = this.connectionManager?.connections.get(this.modelClass.datasource);
             const admin = conn?.admin();
             if (admin) {
                 const collectionName = resolveCollectionName(this.modelClass);
-                const dbName = this.config.get(`datastores:${this.modelClass.datastore}:database`);
+                const dbName = this.config.get(`datastores:${this.modelClass.datasource}:database`);
                 try {
                     this.logger.info(`Configuring sharding for: collection=${dbName}.${collectionName}, key=${JSON.stringify(shardConfig.key)}, unique=${shardConfig.unique}, options=${JSON.stringify(shardConfig.options)})`);
                     const result = await admin.command({
@@ -93,39 +99,203 @@ export class RepoUtils {
         }
     }
     /**
-     * The base key used to get or set data in the cache.
+     * Retrieves every uid matching the given (already-built) search query, ignoring any pagination `take`/`page`
+     * baked into it by `ModelUtils.buildSearchQuery`. Used by `count`/`exists`/`truncate`, which must narrow by
+     * record-level ACLs against the *entire* matching set rather than a single page of it — applying the default
+     * `take` here would silently undercount, under-check existence for, or under-delete a large result set.
      */
-    get baseCacheKey() {
-        return "db.cache." + this.modelClass.name;
+    async findAllUids(searchQuery, options) {
+        const txInfo = this.getTransaction(options);
+        if (this.repo instanceof MongoRepository) {
+            if (Array.isArray(searchQuery)) {
+                return await this.repo.distinct("uid", searchQuery[0].$match, { session: txInfo?.session });
+            }
+            return await this.repo.distinct("uid", searchQuery["$match"] ? searchQuery["$match"] : searchQuery, {
+                session: txInfo?.session,
+            });
+        }
+        // Only the uid column is needed, and pagination must not clip the result set here.
+        const uidQuery = { ...searchQuery, select: { uid: true } };
+        delete uidQuery.take;
+        delete uidQuery.page;
+        const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+        const rows = (await repo.find(uidQuery));
+        return rows.map((obj) => obj.uid);
+    }
+    /**
+     * Filters the given uids down to those the user has `action` permission for, checking in bounded-size
+     * batches rather than a single unbounded `Promise.all` so a large matching set can't fire an unbounded
+     * number of concurrent permission-check round trips at once.
+     */
+    async filterPermittedUids(uids, action, options) {
+        const batchSize = 100;
+        const permitted = [];
+        for (let i = 0; i < uids.length; i += batchSize) {
+            const batch = uids.slice(i, i + batchSize);
+            const results = await Promise.all(batch.map((uid) => this.aclUtils.hasPermission(options?.user, uid, action)));
+            for (let j = 0; j < batch.length; j++) {
+                if (results[j]) {
+                    permitted.push(batch[j]);
+                }
+            }
+        }
+        return permitted;
     }
     async count(query, options) {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
         let count = 0;
-        // Check user permissions
+        const action = options?.action ?? ACLAction.COUNT;
+        const txInfo = this.getTransaction(options);
+        // Check user permissions against the class-level ACL. This is a fast-fail gate for users with no
+        // legitimate access to the resource type at all; per-record narrowing (below) is an additional layer
+        // on top of this, not a replacement for it.
         if (this.aclUtils?.enabled && !options?.ignoreACL) {
-            if (!(await this.aclUtils.hasPermission(options?.user, this.defaultACLUid, ACLAction.READ))) {
+            if (!(await this.aclUtils.hasPermission(options?.user, this.defaultACLUid, action))) {
                 throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
             }
         }
+        // A client-supplied `?deleted=true` filter overrides `buildSearchQuery()`'s default exclusion of
+        // soft-deleted rows. Counting a matched soft-deleted row requires the DELETE+UPDATE permissions.
+        const clientRequestsDeleted = query?.deleted === true || query?.deleted === "true";
+        const recordACL = !!this.modelClass.recordACL;
+        let effectiveQuery = query;
+        if (clientRequestsDeleted && this.aclUtils?.enabled && !options?.ignoreACL && !recordACL) {
+            if (!(await this.canViewDeleted(options?.user, this.defaultACLUid))) {
+                effectiveQuery = { ...query };
+                delete effectiveQuery.deleted;
+            }
+        }
+        const searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, effectiveQuery, true, options?.user);
+        // `buildSearchQuery()` auto-excludes soft-deleted rows for a RecoverableBaseEntity by default. We strip
+        // that out of the query rather than trying to influence the exclusion via the input `query` object.
+        if (options?.includeDeleted) {
+            if (Array.isArray(searchQuery)) {
+                delete searchQuery[0]?.$match?.deleted;
+            }
+            else if (searchQuery?.$match) {
+                delete searchQuery.$match.deleted;
+            }
+            else if (Array.isArray(searchQuery?.where)) {
+                for (const w of searchQuery.where) {
+                    delete w.deleted;
+                }
+            }
+        }
+        // Record-level ACLs aren't reflected in the query itself, so the matched uids must be checked
+        // individually and counted rather than delegating the count to the database.
+        if (this.aclUtils?.enabled && !options?.ignoreACL && recordACL) {
+            const uids = await this.findAllUids(searchQuery, options);
+            let permitted;
+            if (clientRequestsDeleted) {
+                // Every uid this query matched is, by construction, a soft-deleted record - check the restore
+                // bar per-record rather than the ordinary `action`.
+                const deleteOk = new Set(await this.filterPermittedUids(uids, ACLAction.DELETE, options));
+                const updateOk = await this.filterPermittedUids(uids, ACLAction.UPDATE, options);
+                permitted = updateOk.filter((uid) => deleteOk.has(uid));
+            }
+            else {
+                permitted = await this.filterPermittedUids(uids, action, options);
+            }
+            return permitted.length;
+        }
         if (this.repo instanceof MongoRepository) {
-            if (Array.isArray(query)) {
-                query.push({ $count: "count" });
-                const result = await this.repo.aggregate(query).next();
+            if (Array.isArray(searchQuery)) {
+                searchQuery.push({ $count: "count" });
+                const result = await this.repo.aggregate(searchQuery, { session: txInfo?.session }).next();
                 count = result ? result.count : count;
             }
             else {
-                count = await this.repo.count(query["$match"] ? query["$match"] : query);
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                count = await repo.count(searchQuery["$match"] ? searchQuery["$match"] : searchQuery, {
+                    session: txInfo?.session,
+                });
             }
         }
         else {
-            count = await this.repo.count(query);
+            const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+            count = await repo.count(searchQuery);
         }
         return count;
     }
     /**
-     * Stores a new record of the provided object in the datastore. Performs pre-processing, permission checks against
+     * Determines whether an object with the given unique identifier (and, optionally, a specific version) exists
+     * in the datasource. Respects record-level ACLs the same way `count()` does.
+     *
+     * @param id The unique identifier of the object to check for.
+     * @param options The additional options to consider, such as `version` and the requesting `user`.
+     */
+    async exists(id, options) {
+        if (!this.repo) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const action = options?.action ?? ACLAction.EXISTS;
+        // Check user permissions against the class-level ACL. This is a fast-fail gate for users with no
+        // legitimate access to the resource type at all; per-record narrowing (below) is an additional layer
+        // on top of this, not a replacement for it.
+        if (this.aclUtils?.enabled && !options?.ignoreACL) {
+            if (!(await this.aclUtils.hasPermission(options?.user, this.defaultACLUid, action))) {
+                throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+            }
+        }
+        // Ordinary (live-record) existence check, respecting `action`/record-level ACLs exactly as before.
+        let count = await this.existsQuery(id, options, false, action);
+        // A soft-deleted record only counts as "existing" for a caller with both DELETE and UPDATE permission.
+        if (count === 0 && options?.includeDeleted) {
+            let canRestore = true;
+            if (this.aclUtils?.enabled && !options?.ignoreACL) {
+                const restoreAclUid = this.modelClass.recordACL ? id : this.defaultACLUid;
+                canRestore = await this.canViewDeleted(options?.user, restoreAclUid);
+            }
+            if (canRestore) {
+                // Permission for the deleted record was already established above, so this pass runs as a raw
+                // existence check rather than re-deriving/re-checking `action` (which the record's ACL may not
+                // grant even to someone who can restore it).
+                count = await this.existsQuery(id, options, true, null);
+            }
+        }
+        return count;
+    }
+    /**
+     * Runs the actual existence check/count for `exists()`, deduped by uid and clamped to at most 1. Split out
+     * so `exists()` can run it twice — once for a live record, once (gated on DELETE+UPDATE permission) for a
+     * soft-deleted one — without duplicating the Mongo/SQL/record-ACL branching.
+     *
+     * @param id The unique identifier of the object to check for.
+     * @param options The additional options to consider, such as `version`.
+     * @param includeDeleted Whether to match a soft-deleted record.
+     * @param enforceAction The ACL action to check per matched record on a `recordACL` model, or `null` to skip
+     * that check (used for the second, already-authorized `includeDeleted` pass).
+     */
+    async existsQuery(id, options, includeDeleted, enforceAction) {
+        if (!this.repo) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const txInfo = this.getTransaction(options);
+        // Without an explicit version, `query` matches every historical row sharing this uid on a trackChanges
+        // entity - existence is still a yes/no question about the uid itself, so results are deduped by uid and
+        // the final count clamped to at most 1, rather than reporting the number of matching version rows.
+        const query = this.searchIdQuery(id, options?.version, includeDeleted);
+        // Record-level ACLs aren't reflected in the query itself, so the matched uids must be checked
+        // individually and counted rather than delegating the count to the database.
+        if (enforceAction && this.aclUtils?.enabled && !options?.ignoreACL && this.modelClass.recordACL) {
+            const uids = await this.findAllUids(query);
+            const permitted = await this.filterPermittedUids(uids, enforceAction, options);
+            return permitted.length > 0 ? 1 : 0;
+        }
+        let count;
+        if (this.repo instanceof MongoRepository) {
+            count = await this.repo.count(query, { session: txInfo?.session });
+        }
+        else {
+            const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+            count = await repo.count(query);
+        }
+        return Math.min(count, 1);
+    }
+    /**
+     * Stores a new record of the provided object in the datasource. Performs pre-processing, permission checks against
      * the class ACL, cache seeding, telemetry recording and push notifications.
      *
      * @param obj The object to store.
@@ -135,6 +305,7 @@ export class RepoUtils {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
+        const txInfo = this.getTransaction(options);
         // Verify the user's permission to create objects
         if (this.aclUtils?.enabled &&
             !options?.ignoreACL &&
@@ -144,6 +315,7 @@ export class RepoUtils {
         // Instantiate the object if not already done
         const clazz = this.getClassType(obj);
         const newObj = obj instanceof clazz ? obj : this.instantiateObject(obj, clazz);
+        const repo = this.repo;
         // Make sure an existing object doesn't already exist with the same identifiers
         const ids = [];
         const idProps = ModelUtils.getIdPropertyNames(clazz);
@@ -153,11 +325,28 @@ export class RepoUtils {
                 ids.push(val);
             }
         }
-        const query = ModelUtils.buildIdSearchQuery(this.repo, clazz, ids, undefined);
-        const count = await this.repo.count(query);
+        const query = ModelUtils.buildIdSearchQuery(repo, clazz, ids, undefined);
+        const count = this.repo instanceof MongoRepository
+            ? await this.repo.count(query, { session: txInfo?.session })
+            : await (txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo).count(query);
         if (!this.modelClass.trackChanges && count > 0) {
             throw new ApiError(ApiErrors.IDENTIFIER_EXISTS, 400, ApiErrorMessages.IDENTIFIER_EXISTS);
         }
+        else if (this.modelClass.trackChanges &&
+            count > 0 &&
+            this.modelClass.recordACL &&
+            this.aclUtils?.enabled &&
+            !(await this.aclUtils.hasPermission(options?.user, newObj.uid, ACLAction.UPDATE))) {
+            // A trackChanges + recordACL model is being "re-created" under an existing uid (i.e. a new
+            // version). That's only legitimate for someone who already has update rights on the
+            // existing record — generic class-level CREATE permission isn't enough, otherwise any
+            // creator could inject a new "latest version" of another user's record. Deliberately NOT
+            // gated on `options.ignoreACL`: that flag exists so ModelRoute.doCreate() can skip
+            // re-doing the class-level CREATE check it already performed upstream — it says nothing
+            // about this distinct, additional per-record check, which has no upstream equivalent and
+            // must always run.
+            throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+        }
         // Override the date and version fields with their defaults
         if (newObj instanceof BaseEntity) {
             newObj.dateCreated = new Date();
@@ -168,38 +357,85 @@ export class RepoUtils {
         if (newObj instanceof BaseEntity && this.modelClass.trackChanges === 0) {
             newObj.version = 0;
         }
-        // HAX We shouldn't be casting obj to any here but this is the only way to get it to compile since T
-        // extends BaseEntity.
-        const result = this.instantiateObject(await this.repo.save(newObj));
-        if (this.cacheClient && this.modelClass.cacheTTL) {
-            // Cache the object for faster retrieval
-            const query = this.searchIdQuery(newObj.uid);
-            const cacheKey = `${this.baseCacheKey}.${this.hashQuery(query)}`;
-            void this.cacheClient.setex(cacheKey, this.modelClass.cacheTTL, JSON.stringify(result));
+        // HAX We shouldn't be casting obj to any here but this is the only way to get it to compile
+        // since T extends BaseEntity.
+        let saved;
+        if (this.repo instanceof MongoRepository) {
+            saved = await this.repo.save(newObj, { session: txInfo?.session });
+        }
+        else {
+            const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+            saved = await repo.save(newObj);
         }
+        const result = this.instantiateObject(saved);
         if (this.aclUtils?.enabled && this.modelClass.recordACL) {
-            // If ACLs are enabled but no ACL was given create one
-            const acl = {
+            // Reuse the existing ACL if this is a legitimate trackChanges "new version" rather than building a fresh,
+            // version-less object from scratch. Building fresh here would let saveACL()'s optimistic-lock version
+            // check pass by coincidence (a never-updated ACL is also version 0), silently discarding the real records.
+            const existingAcl = await this.aclUtils.findACL(result.uid);
+            const isFreshAcl = !existingAcl;
+            const acl = existingAcl ?? {
                 uid: result.uid,
                 parentUid: options?.acl?.parentUid || this.defaultACLUid,
                 records: options?.acl?.records || [],
             };
             // Look for an existing record for the creator
             let found = !!this.aclUtils.getRecord(acl, options?.user);
+            let modifiedExistingAcl = false;
             // Always grant the creator CRUD access, unless the user is a superuser.
             if (!found && options?.user && !UserUtils.hasRoles(options?.user, this.trustedRoles)) {
                 acl.records.push({
                     userOrRoleId: options.user.uid,
-                    create: true,
-                    read: true,
-                    update: true,
-                    delete: true,
-                    special: false,
-                    full: false,
+                    actions: [
+                        ACLAction.COUNT,
+                        ACLAction.CREATE,
+                        ACLAction.DELETE,
+                        ACLAction.EXISTS,
+                        ACLAction.READ,
+                        ACLAction.LIST,
+                        ACLAction.TRUNCATE,
+                        ACLAction.UPDATE,
+                    ],
                 });
+                modifiedExistingAcl = !isFreshAcl;
             }
             await this.aclUtils.saveACL(acl);
+            // `saveACL()` commits independently, on the `acl` connection's own transaction (see its doc
+            // comment). That means it can't be rolled back by this (the entity-side) transaction's own abort if this
+            // transaction fails later. Register a compensating action so a later failure doesn't leave an orphaned
+            // ACL behind.
+            if (isFreshAcl) {
+                const newAclUid = acl.uid;
+                registerRollbackHook(async () => {
+                    try {
+                        await this.aclUtils.removeACL(newAclUid);
+                    }
+                    catch (err) {
+                        this.logger?.warn(`RepoUtils: Failed to roll back orphaned ACL ${newAclUid} after a failed create().`);
+                        this.logger?.debug(err);
+                    }
+                });
+            }
+            else if (modifiedExistingAcl) {
+                // Reverting a change to an already-existing ACL isn't well-defined in general (it may carry
+                // other, unrelated state) — log loudly instead so this is visible for manual reconciliation.
+                const modifiedAclUid = acl.uid;
+                registerRollbackHook(async () => {
+                    this.logger?.warn(`RepoUtils: create() failed after modifying existing ACL ${modifiedAclUid} — that change was not automatically reverted.`);
+                });
+            }
+        }
+        if (this.cache) {
+            // Cache the object for faster retrieval.
+            const query = this.searchIdQuery(newObj.uid);
+            const cacheKey = this.hashQuery(query);
+            this.cache.save(cacheKey, result).catch((err) => this.logCacheError("save", err));
+            this.cache.save(result.uid, result).catch((err) => this.logCacheError("save", err));
         }
+        // Process the result to remove any properties that have been scoped with @RequiresScope that the user
+        // does not have access to. Done after caching (the cache must retain the full object for other
+        // requests) but before the result is returned or broadcast to push subscribers.
+        ObjectUtils.deleteScopedProps(result, options?.user, this.modelClass);
         if (!options?.skipPush) {
             let channels = [result.uid].concat(options?.pushChannels || []);
             this.notificationUtils?.sendMessage(channels, this.modelClass.name, "create", result);
@@ -210,6 +446,7 @@ export class RepoUtils {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
+        const txInfo = this.getTransaction(options);
         if (this.aclUtils?.enabled && !options.ignoreACL) {
             const acl = await this.aclUtils.findACL(uid);
             if (!(await this.aclUtils.hasPermission(options.user, acl ? acl : this.defaultACLUid, ACLAction.DELETE))) {
@@ -218,18 +455,38 @@ export class RepoUtils {
         }
         const isRecoverable = this.instantiateObject({}) instanceof RecoverableBaseEntity;
         const isPurge = isRecoverable ? options.purge || false : true;
+        // Delete must be able to target a record regardless of its current `deleted` state (the default) —
+        // otherwise an already soft-deleted record could never be purged, nor a soft-delete repeated idempotently.
         const query = ModelUtils.buildIdSearchQuery(this.repo, this.modelClass, uid, options.version ? Number(options.version) : undefined);
         // If the object(s) are being permenantly removed from the database do so and then clear the accompanying
         // ACL(s). If the class type is recoverable and purge isn't desired, simply mark the object(s) as deleted.
         if (isPurge) {
             if (this.repo instanceof MongoRepository) {
-                await this.repo.deleteMany(query);
+                await this.repo.deleteMany(query, { session: txInfo?.session });
             }
             else {
-                await this.repo.delete(query.where);
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                await repo.delete(query.where);
             }
             if (this.aclUtils?.enabled && this.modelClass.recordACL) {
-                await this.aclUtils.removeACL(uid);
+                // `removeACL()` returns the exact document it deleted (captured atomically, not via a separate
+                // earlier read - see its doc comment) - used as the restore snapshot below. `removeACL()`
+                // commits independently, on the `acl` connection's own transaction; if this (the entity-side)
+                // transaction later fails, its own abort can't undo that removal, so the rollback hook restores
+                // the snapshot in that case. `preserveVersion` restores its exact prior version instead of
+                // bumping it, and refuses (rather than clobbers) if something already exists at this uid.
+                const removedAcl = await this.aclUtils.removeACL(uid);
+                if (removedAcl) {
+                    registerRollbackHook(async () => {
+                        try {
+                            await this.aclUtils.saveACL(removedAcl, { preserveVersion: true });
+                        }
+                        catch (err) {
+                            this.logger?.warn(`RepoUtils: Failed to restore ACL ${uid} after a failed delete().`);
+                            this.logger?.debug(err);
+                        }
+                    });
+                }
             }
         }
         else {
@@ -238,18 +495,22 @@ export class RepoUtils {
                     $set: {
                         deleted: true,
                     },
-                });
+                }, { session: txInfo?.session });
             }
             else {
-                await this.repo.update(query.where, {
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                await repo.update(query.where, {
                     deleted: true,
                 });
             }
         }
-        if (this.cacheClient && this.modelClass.cacheTTL) {
-            // Delete the object from cache
-            void this.cacheClient.del(`${this.baseCacheKey}.${this.hashQuery(query)}`);
-            void this.cacheClient.del(`${this.baseCacheKey}.${this.hashQuery(this.searchIdQuery(uid))}`);
+        if (this.cache) {
+            // Delete the object from cache.
+            this.cache.delete(uid).catch((err) => this.logCacheError("delete", err));
+            this.cache.delete(this.hashQuery(query)).catch((err) => this.logCacheError("delete", err));
+            this.cache
+                .delete(this.hashQuery(this.searchIdQuery(uid)))
+                .catch((err) => this.logCacheError("delete", err));
         }
         if (!options?.skipPush) {
             let channels = [uid].concat(options?.pushChannels || []);
@@ -260,7 +521,7 @@ export class RepoUtils {
         }
     }
     /**
-     * Retrieves an array of objects from the datastore matching the given search query. This function will first
+     * Retrieves an array of objects from the datasource matching the given search query. This function will first
      * attempt to look up the results in the cache. Also checks ACLs for READ permission.
      *
      * @param query The constructed search query to run.
@@ -270,9 +531,13 @@ export class RepoUtils {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
-        // Check user permissions
+        const action = options?.action ?? ACLAction.LIST;
+        const txInfo = this.getTransaction(options);
+        // Check user permissions against the class-level ACL. This is a fast-fail gate for users with no
+        // legitimate access to the resource type at all; per-record narrowing (below, right before the
+        // results are returned) is an additional layer on top of this, not a replacement for it.
         if (this.aclUtils?.enabled && !options?.ignoreACL) {
-            if (!(await this.aclUtils.hasPermission(options?.user, this.defaultACLUid, ACLAction.READ))) {
+            if (!(await this.aclUtils.hasPermission(options?.user, this.defaultACLUid, action))) {
                 throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
             }
         }
@@ -287,88 +552,74 @@ export class RepoUtils {
             page,
         });
         // Pull from the cache if available
-        if (!options?.skipCache && this.cacheClient && this.modelClass.cacheTTL) {
-            const json = await this.cacheClient.get(`${this.baseCacheKey}.${searchQueryHash}`);
-            if (json) {
-                try {
-                    const uids = JSON.parse(json);
-                    // Attempt to retrieve as many objects from the cache simultaneously
-                    const keys = uids.map((uid) => `${this.baseCacheKey}.${this.hashQuery(this.searchIdQuery(uid))}`);
-                    // Retrieve all objects from the cache (if possible)
-                    const cresults = await this.cacheClient.mget(...keys);
-                    // Check for any missing objects that weren't in the cache. Build a list of missing
-                    // items that we can retrieve from the database directly.
-                    const missingUids = [];
-                    for (let i = 0; i < cresults.length; i++) {
-                        if (cresults[i] === null) {
-                            missingUids.push(cresults[i]);
-                        }
-                    }
-                    // Now pull all missing items from the database
-                    let missing = [];
-                    if (missingUids.length > 0) {
-                        if (this.repo instanceof MongoRepository) {
-                            missing = await this.repo.find({ uid: { $in: missingUids } }).toArray();
-                        }
-                        else {
-                            const { In } = ModelUtils.orm;
-                            missing = await this.repo.find({ where: { uid: In(missingUids) } });
-                        }
-                    }
-                    // Merge the results back into the results array. We iterate through cresults to preserve
-                    // the order of the original query.
-                    for (let i = 0; i < cresults.length; i++) {
-                        if (cresults[i] !== null) {
-                            results.push(JSON.parse(cresults[i]));
-                        }
-                        else {
-                            // Find the desired object in the missing array
-                            for (const obj of missing) {
-                                if (obj.uid === missingUids[i]) {
-                                    results.push(obj);
-                                    break;
-                                }
-                            }
-                        }
-                    }
-                    // Populate the cache with all missing objects
-                    for (const obj of missing) {
-                        const query = this.searchIdQuery(obj.uid);
-                        const cacheKey = `${this.baseCacheKey}.${this.hashQuery(query)}`;
-                        void this.cacheClient.setex(cacheKey, this.modelClass.cacheTTL, JSON.stringify(obj));
-                    }
-                }
-                catch (err) {
-                    // It doesn't matter if this fails
-                }
+        if (!options?.skipCache && this.cache) {
+            const cached = await this.cache.loadSet(searchQueryHash);
+            if (cached) {
+                results = cached.filter((obj) => obj !== undefined);
             }
         }
         // If the query wasn't cached retrieve from the database
         if (results.length === 0) {
+            const searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, query, true, options?.user);
             if (this.repo instanceof MongoRepository) {
                 const skip = page * limit;
-                if (Array.isArray(query)) {
-                    results = await this.repo.aggregate(query).skip(skip).limit(limit).toArray();
+                if (Array.isArray(searchQuery)) {
+                    results = await this.repo
+                        .aggregate(searchQuery, { session: txInfo?.session })
+                        .skip(skip)
+                        .limit(limit)
+                        .toArray();
                 }
                 else {
                     results = await this.repo
-                        .find(query["$match"] ? query["$match"] : query, {
+                        .find(searchQuery["$match"] ? searchQuery["$match"] : searchQuery, {
                         limit,
+                        session: txInfo?.session,
                         skip,
-                        sort: query["$sort"],
+                        sort: searchQuery["$sort"],
                     })
                         .toArray();
                 }
             }
             else {
-                results = await this.repo.find(query);
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                // `searchQuery.page` (set by `buildSearchQuerySQL`) isn't a TypeORM find option and is silently
+                // ignored by `repo.find()` - it must be translated to `skip` here, the same way the Mongo branch
+                // above translates `page` into its own `skip`, or every SQL page request returns page 0.
+                results = (await repo.find({ ...searchQuery, skip: page * limit }));
             }
             // Cache the results for future requests. Don't bother if there were no results.
-            if (results.length > 0 && this.cacheClient && this.modelClass.cacheTTL) {
-                const uids = results.map((obj) => obj.uid);
-                void this.cacheClient.setex(`${this.baseCacheKey}.${searchQueryHash}`, this.modelClass.cacheTTL, JSON.stringify(uids));
+            if (results.length > 0 && this.cache) {
+                this.cache.saveSet(searchQueryHash, results).catch((err) => this.logCacheError("saveSet", err));
+                // Also seed each individual object's own cache entry.
+                const ids = results.map((obj) => this.hashQuery(this.searchIdQuery(obj.uid)));
+                this.cache.saveMany(ids, results).catch((err) => this.logCacheError("saveMany", err));
             }
         }
+        // Record-level ACLs aren't reflected in the query itself (nor in cached results, which are shared across
+        // users), so each matched record must be checked individually before it's returned to the caller. The
+        // checks are run concurrently, and share a request-scoped ACL cache, so that a page of N results costs
+        // at most one round trip per *distinct* ACL uid (typically just the shared parent, since per-record
+        // ACLs are rarely warm in Redis) instead of N sequential round trips.
+        //
+        // A soft-deleted row can appear in `results` despite `buildSearchQuery()`'s default exclusion via a client
+        // supplying its own `deleted` query param, which the query builder honors as-is. Such a row needs the
+        // same DELETE+UPDATE permission.
+        if (this.aclUtils?.enabled && !options?.ignoreACL) {
+            const recordACL = !!this.modelClass.recordACL;
+            const permitted = await Promise.all(results.map((obj) => {
+                if (obj.deleted === true) {
+                    return this.canViewDeleted(options?.user, recordACL ? obj.uid : this.defaultACLUid);
+                }
+                return recordACL
+                    ? this.aclUtils.hasPermission(options?.user, obj.uid, action)
+                    : Promise.resolve(true);
+            }));
+            results = results.filter((_obj, i) => permitted[i]);
+        }
+        // Process the results to remove any properties that have been scoped with @RequiresScope that the user
+        // does not have access to.
+        ObjectUtils.deleteScopedProps(results, options?.user, this.modelClass);
         return results;
     }
     /**
@@ -382,39 +633,78 @@ export class RepoUtils {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
+        let existing = undefined;
+        const txInfo = this.getTransaction(options);
+        // Deliberately uses the default (includeDeleted: true) query shape here — this result is cached under
+        // a key shared with create()/update()/find()'s cache-seeding, all of which also use the default shape,
+        // so changing it here alone would desync this read from what those write. Soft-deleted records are
+        // filtered out below instead, after the cache/DB read, regardless of which one produced the result.
         const query = this.searchIdQuery(id, options?.version);
-        if (!options?.skipCache && this.cacheClient && this.modelClass.cacheTTL) {
-            // First attempt to retrieve the object from the cache
-            const json = await this.cacheClient.get(`${this.baseCacheKey}.${this.hashQuery(query)}`);
-            if (json) {
-                try {
-                    const existing = JSON.parse(json);
-                    if (existing) {
-                        return existing;
+        if (!options?.skipCache && this.cache) {
+            existing = await this.cache.load(this.hashQuery(query));
+        }
+        if (!existing) {
+            if (this.repo instanceof MongoRepository) {
+                existing = await this.repo
+                    .find(query["$match"] ? query["$match"] : query, {
+                    session: txInfo?.session,
+                    sort: { version: -1 },
+                })
+                    .next();
+            }
+            else if (this.modelClass.prototype instanceof BaseEntity) {
+                // Without an explicit version, `query` matches every row sharing this uid (all historical
+                // versions, for a trackChanges entity). Order by version desc so the newest one wins, the same
+                // way the Mongo branch above does - otherwise TypeORM's `findOne()` returns whichever matching
+                // row it encounters first, which isn't guaranteed to be the latest. `SimpleEntity` has no
+                // `version` column to order by, so this only applies to `BaseEntity` subclasses.
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                existing = (await repo.findOne({ ...query, order: { version: "DESC" } }));
+            }
+            else {
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                existing = (await repo.findOne(query));
+            }
+        }
+        // Never surface a soft-deleted record via an id-based lookup by default — matches the default the
+        // list/search endpoint already applies. `includeDeleted` opts back in (e.g. an admin history/restore
+        // view fetching a specific past version by id). Checked here (after cache or DB resolution) rather
+        // than by filtering `deleted` into the query above, so a cache entry that predates a delete, or was
+        // seeded by an explicit `?deleted=true` list request, is filtered consistently either way.
+        if (existing && existing.deleted === true && !options?.includeDeleted) {
+            existing = null;
+        }
+        if (existing) {
+            if (this.cache) {
+                // Cache the object for faster retrieval
+                this.cache.save(this.hashQuery(query), existing).catch((err) => this.logCacheError("save", err));
+            }
+            // Check user permissions
+            if (this.aclUtils?.enabled && !options?.ignoreACL) {
+                const acl = await this.aclUtils.findACL(existing.uid);
+                if (existing.deleted === true) {
+                    // Viewing a soft-deleted record (opted into via `includeDeleted`) requires both DELETE and UPDATE
+                    // permission, the two actions actually needed to restore the record.
+                    if (!(await this.canViewDeleted(options?.user, acl ? acl : this.defaultACLUid))) {
+                        existing = null;
                     }
                 }
-                catch (err) {
-                    // It doesn't matter if this fails
+                else {
+                    const action = options?.action ?? ACLAction.READ;
+                    if (!(await this.aclUtils.hasPermission(options?.user, acl ? acl : this.defaultACLUid, action))) {
+                        throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+                    }
                 }
             }
         }
-        let existing = null;
-        if (this.repo instanceof MongoRepository) {
-            existing = await this.repo
-                .find(query["$match"] ? query["$match"] : query, {
-                sort: { version: -1 },
-            })
-                .next();
-        }
-        else {
-            existing = await this.repo.findOne(query);
-        }
-        if (existing && this.cacheClient && this.modelClass.cacheTTL) {
-            // Cache the object for faster retrieval
-            void this.cacheClient.setex(`${this.baseCacheKey}.${this.hashQuery(query)}`, this.modelClass.cacheTTL, JSON.stringify(existing));
+        const result = existing ? this.instantiateObject(existing) : undefined;
+        // Process the result to remove any properties that have been scoped with @RequiresScope that the user
+        // does not have access to.
+        if (result) {
+            ObjectUtils.deleteScopedProps(result, options?.user, this.modelClass);
         }
         // Make sure we return the correct data type
-        return existing ? this.instantiateObject(existing) : undefined;
+        return result;
     }
     /**
      * Returns the default access control list governing the model type. Returning a value of `undefined` will grant
@@ -432,13 +722,47 @@ export class RepoUtils {
         }
         return result;
     }
+    /**
+     * Checks whether the caller has both `DELETE` and `UPDATE` permission against the given ACL (or ACL uid).
+     * Ordinary READ/LIST/EXISTS permission on a record says nothing about whether its owner
+     * consented to its "deleted" state being visible, so those two actions (the ones actually needed to
+     * restore the record) are required instead.
+     *
+     * @param user The user to check.
+     * @param acl The ACL (or ACL uid) governing the record.
+     */
+    async canViewDeleted(user, acl) {
+        return ((await this.aclUtils.hasPermission(user, acl, ACLAction.DELETE)) &&
+            (await this.aclUtils.hasPermission(user, acl, ACLAction.UPDATE)));
+    }
+    /**
+     * Logs a swallowed error from a fire-and-forget cache operation. Cache reads/writes are best-effort and
+     * must never propagate into (and thus fail/retry) the write they're attached to.
+     * @param op The cache operation that failed (e.g. "save", "delete").
+     * @param err The error thrown by the cache operation.
+     */
+    logCacheError(op, err) {
+        this.logger?.warn(`RepoUtils: Cache ${op} failed for ${this.modelClass?.name}.`);
+        this.logger?.debug(err);
+    }
     /**
      * Hashes the given query object to a unique string.
      * @param query The query object to hash.
      */
     hashQuery(query) {
         const queryStr = JSON.stringify(query);
-        return crypto.createHash("md5").update(queryStr).digest("hex");
+        let hash = _hashCache.get(queryStr);
+        if (hash === undefined) {
+            // Hash the query string
+            hash = crypto.createHash("md5").update(queryStr).digest("hex");
+            // Clear the hash cache if it grows too big to prevent runaway memory usage
+            if (_hashCache.size >= 10000) {
+                _hashCache.clear();
+            }
+            // Store the hashed query string for faster lookup next time
+            _hashCache.set(queryStr, hash);
+        }
+        return hash;
     }
     /**
      * Returns the class type (constructor) for the given object. This uses the `_fqn` or `_type` property of `obj` to
@@ -449,14 +773,28 @@ export class RepoUtils {
      */
     getClassType(obj) {
         const className = obj._fqn || obj._type;
-        if (this.objectFactory) {
+        if (this._objectFactory) {
             if (className && typeof className === "string") {
-                const clazz = this.objectFactory.classes.get(className) || this.objectFactory.classes.get(`models.${className}`);
-                return clazz;
+                const clazz = this._objectFactory.classes.get(className) ||
+                    this._objectFactory.classes.get(`models.${className}`);
+                // Only accept the resolved class if it's actually this route's model or a subtype of it (e.g. a
+                // @ChildEntity()). `objectFactory.classes` contains every registered model in the app, so without
+                // this check a client could point `_type`/`_fqn` at an unrelated model to have its payload
+                // instantiated/validated against that other model's (possibly much looser) rules while still
+                // being persisted through this route's own datasource/collection.
+                if (clazz && (clazz === this.modelClass || clazz.prototype instanceof this.modelClass)) {
+                    return clazz;
+                }
             }
         }
         return this.modelClass;
     }
+    /**
+     * Returns the current transactional session information, if present.
+     */
+    getTransaction(options) {
+        return options?.transaction ?? transactionContext.getStore();
+    }
     /**
      * Creates a new instance of obj scoped to the correct model class or sub-class.
      */
@@ -470,55 +808,81 @@ export class RepoUtils {
      * Search for existing object based on passed in id and version and product uid.
      *
      * The result of this function is compatible with all `Repository.find()` functions.
+     *
+     * @param includeDeleted Set to false to exclude soft-deleted `RecoverableBaseEntity` records from matching.
+     * Defaults to true; pass false when the result is exposed directly to an API client (e.g. `findOne`, `exists`)
+     * so a soft-deleted record isn't returned as if it still existed.
      */
-    searchIdQuery(id, version) {
-        return ModelUtils.buildIdSearchQuery(this.repo, this.modelClass, id, typeof version === "string" ? parseInt(version, 10) : version);
+    searchIdQuery(id, version, includeDeleted = true) {
+        return ModelUtils.buildIdSearchQuery(this.repo, this.modelClass, id, typeof version === "string" ? parseInt(version, 10) : version, includeDeleted);
     }
     async truncate(query, options) {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
+        const txInfo = this.getTransaction(options);
         // Check user permissions. Don't check if record-level ACLs are used as this will be done
         // per record later.
         if (this.aclUtils?.enabled && !options.ignoreACL && !this.modelClass.recordACL) {
-            if (!(await this.aclUtils.hasPermission(options.user, this.defaultACLUid, ACLAction.DELETE))) {
+            if (!(await this.aclUtils.hasPermission(options.user, this.defaultACLUid, ACLAction.TRUNCATE))) {
                 throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
             }
         }
         try {
-            let uids = [];
-            if (this.repo instanceof MongoRepository) {
-                if (Array.isArray(query)) {
-                    uids = await this.repo.distinct("uid", query[0].$match);
-                }
-                else {
-                    uids = await this.repo.distinct("uid", query["$match"] ? query["$match"] : query);
-                }
-            }
-            else {
-                (await this.repo.find(query)).forEach((obj) => uids.push(obj.uid));
-            }
+            const searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, query, true, options?.user);
+            const uids = await this.findAllUids(searchQuery, options);
             if (uids.length > 0) {
                 let finalUids = uids;
                 // Check if this class uses record level ACLs. If so, we need to check the perms of
                 // each one. We will remove any from our list that the user does not have permission to
-                // delete.
+                // truncate.
                 if (this.aclUtils?.enabled && this.modelClass.recordACL) {
-                    finalUids = [];
-                    for (const uid of uids) {
-                        if (!options.ignoreACL) {
-                            if (await this.aclUtils.hasPermission(options.user, uid, ACLAction.DELETE)) {
-                                finalUids.push(uid);
-                            }
-                        }
+                    if (options.ignoreACL) {
+                        // Caller has already authorized this truncate; skip the per-record permission
+                        // narrowing entirely rather than defaulting to an empty (i.e. no-op) delete set.
+                        finalUids = uids;
+                    }
+                    else {
+                        finalUids = await this.filterPermittedUids(uids, ACLAction.TRUNCATE, options);
                     }
                 }
+                const cleansUpRecordACLs = !!(this.aclUtils?.enabled && this.modelClass.recordACL);
                 // Now delete all records that were found
                 if (this.repo instanceof MongoRepository) {
-                    await this.repo.deleteMany({ uid: { $in: finalUids } });
+                    await this.repo.deleteMany({ uid: { $in: finalUids } }, {
+                        session: txInfo?.session,
+                    });
                 }
                 else {
-                    await this.repo.delete(finalUids);
+                    const repo = txInfo?.entityManager
+                        ? txInfo.entityManager.getRepository(this.modelClass)
+                        : this.repo;
+                    // A plain array of ids only maps to a WHERE ... IN clause when the primary key is a single
+                    // column — for a trackChanges entity the SQL primary key is the composite (uid, version),
+                    // so an explicit In() on the uid column is used instead of relying on that implicit form.
+                    const { In } = ModelUtils.orm;
+                    await repo.delete({ uid: In(finalUids) });
+                }
+                if (cleansUpRecordACLs && finalUids.length > 0) {
+                    // `removeACLs()` returns exactly what it deleted (captured atomically, not via a separate
+                    // earlier read - see `removeACL()`'s doc comment) - used directly as the restore snapshot.
+                    // It commits independently, on the `acl` connection's own transaction; if this (entity-side)
+                    // transaction later fails, its own abort can't undo that removal, so the rollback hook
+                    // restores the snapshot in that case. `saveACLs()` restores each ACL's exact prior version
+                    // (see `saveACL()`'s `preserveVersion` option) and refuses — rather than clobbers — any of
+                    // these uids that already has something at it again by the time the restore runs.
+                    const removedAcls = await this.aclUtils.removeACLs(finalUids);
+                    if (removedAcls.length > 0) {
+                        registerRollbackHook(async () => {
+                            try {
+                                await this.aclUtils.saveACLs(removedAcls);
+                            }
+                            catch (err) {
+                                this.logger?.warn(`RepoUtils: Failed to restore ${removedAcls.length} ACL(s) after a failed truncate().`);
+                                this.logger?.debug(err);
+                            }
+                        });
+                    }
                 }
                 if (!options?.skipPush) {
                     let channels = options?.pushChannels || [];
@@ -543,6 +907,7 @@ export class RepoUtils {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
         }
+        const txInfo = this.getTransaction(options);
         if (this.aclUtils?.enabled && !options?.ignoreACL) {
             const acl = await this.aclUtils.findACL(existing.uid);
             if (!(await this.aclUtils.hasPermission(options?.user, acl ? acl : this.defaultACLUid, ACLAction.UPDATE))) {
@@ -559,6 +924,15 @@ export class RepoUtils {
         if (existing.uid !== obj.uid) {
             throw new ApiError(ApiErrors.OBJECT_ID_MISMATCH, 400, ApiErrorMessages.OBJECT_ID_MISMATCH);
         }
+        // Force system-managed fields back to their persisted value, discarding whatever the client sent (or
+        // didn't send) for them. `dateCreated` is always protected; `@ReadOnly`-decorated properties are an
+        // app-level opt-in for anything else (roles, ownership fields, etc.) that must never be client-settable.
+        if (existing instanceof BaseEntity) {
+            obj.dateCreated = existing.dateCreated;
+        }
+        for (const prop of ModelUtils.getReadOnlyPropertyNames(this.modelClass)) {
+            obj[prop] = existing[prop];
+        }
         // When using MongoDB we need to copy the _id property in order to prevent duplicate entries
         if (existing instanceof BaseMongoEntity) {
             obj._id = existing._id;
@@ -569,12 +943,24 @@ export class RepoUtils {
         if (this.repo instanceof MongoRepository) {
             if (existing instanceof BaseEntity) {
                 if (keepPrevious) {
-                    result = this.instantiateObject(await this.repo.save({
-                        ...obj,
-                        _id: undefined, // Ensure we save a new document
-                        dateModified: new Date(),
-                        version: obj.version + 1,
-                    }));
+                    // Same (uid, version) unique index race as RepoUtils.create(): two concurrent updates of
+                    // the same version can both pass the optimistic-lock check above and both attempt to
+                    // insert (uid, version + 1). The database rejects the loser; treat that the same as a
+                    // lost optimistic-lock race rather than letting the raw duplicate-key error escape.
+                    try {
+                        result = this.instantiateObject(await this.repo.save({
+                            ...obj,
+                            _id: undefined, // Ensure we save a new document
+                            dateModified: new Date(),
+                            version: obj.version + 1,
+                        }, { session: txInfo?.session }));
+                    }
+                    catch (err) {
+                        if (err?.code === 11000) {
+                            throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
+                        }
+                        throw err;
+                    }
                 }
                 else {
                     await this.repo.updateOne({ uid: obj.uid, version: obj.version }, {
@@ -583,22 +969,32 @@ export class RepoUtils {
                             dateModified: new Date(),
                             version: obj.version + 1,
                         },
+                    }, {
+                        session: txInfo?.session,
                     });
                 }
             }
             else if (obj.uid) {
                 if (keepPrevious) {
-                    result = this.instantiateObject(await this.repo.save({
-                        ...obj,
-                        version: obj.version + 1,
-                    }));
+                    try {
+                        result = this.instantiateObject(await this.repo.save({
+                            ...obj,
+                            version: obj.version + 1,
+                        }, { session: txInfo?.session }));
+                    }
+                    catch (err) {
+                        if (err?.code === 11000) {
+                            throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
+                        }
+                        throw err;
+                    }
                 }
                 else {
                     await this.repo.updateOne({ uid: obj.uid }, {
                         $set: {
                             ...obj,
                         },
-                    });
+                    }, { session: txInfo?.session });
                 }
             }
             else {
@@ -606,20 +1002,21 @@ export class RepoUtils {
                 if (keepPrevious) {
                     toSave.version += 1;
                 }
-                result = await this.repo.save(toSave);
+                result = await this.repo.save(toSave, { session: txInfo?.session });
             }
         }
         else {
+            const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
             if (existing instanceof BaseEntity) {
                 if (keepPrevious) {
-                    await this.repo.insert({
+                    await repo.insert({
                         ...obj,
                         dateModified: new Date(),
                         version: obj.version + 1,
                     });
                 }
                 else {
-                    await this.repo.update(query.where, {
+                    await repo.update(query.where, {
                         ...obj,
                         dateModified: new Date(),
                         version: obj.version + 1,
@@ -630,31 +1027,43 @@ export class RepoUtils {
                 const toSave = obj;
                 if (keepPrevious) {
                     toSave.version += 1;
-                    result = await this.repo.save(toSave);
+                    // TypeORM's overloaded Repository.save() can't be resolved against `repo`'s inferred
+                    // `EntityManager | Repository<T>` union type — same class of friction as the "HAX" cast
+                    // above.
+                    result = await repo.save(toSave);
                 }
                 else {
-                    await this.repo.update(query.where, toSave);
+                    await repo.update(query.where, toSave);
                 }
             }
         }
-        query = this.searchIdQuery(existing.uid, obj instanceof BaseEntity ? obj.version + 1 : undefined);
+        query = this.searchIdQuery(existing.uid, existing instanceof BaseEntity ? existing.version + 1 : undefined);
         if (!result) {
             if (this.repo instanceof MongoRepository) {
-                result = await this.repo.findOne(query["$match"] ? query["$match"] : query);
+                result = await this.repo.findOne(query["$match"] ? query["$match"] : query, {
+                    session: txInfo?.session,
+                });
             }
             else {
-                result = await this.repo.findOne(query);
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                result = (await repo.findOne(query));
             }
             if (!result) {
                 throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
             }
         }
         result = this.instantiateObject(result);
-        if (result && this.cacheClient && this.modelClass.cacheTTL) {
-            // Cache the object for faster retrieval
-            void this.cacheClient.setex(`${this.baseCacheKey}.${this.hashQuery(query)}`, this.modelClass.cacheTTL, JSON.stringify(result));
-            void this.cacheClient.setex(`${this.baseCacheKey}.${this.hashQuery(this.searchIdQuery(result.uid))}`, this.modelClass.cacheTTL, JSON.stringify(result));
+        if (result && this.cache) {
+            // Cache the object for faster retrieval.
+            this.cache.save(this.hashQuery(query), result).catch((err) => this.logCacheError("save", err));
+            this.cache
+                .save(this.hashQuery(this.searchIdQuery(result.uid)), result)
+                .catch((err) => this.logCacheError("save", err));
         }
+        // Process the result to remove any properties that have been scoped with @RequiresScope that the user
+        // does not have access to. Done after caching (the cache must retain the full object for other
+        // requests) but before the result is returned or broadcast to push subscribers.
+        ObjectUtils.deleteScopedProps(result, options?.user, this.modelClass);
         if (!options?.skipPush) {
             let channels = [result.uid].concat(options?.pushChannels || []);
             this.notificationUtils?.sendMessage(channels, this.modelClass.name, "update", result);
@@ -676,18 +1085,31 @@ export class RepoUtils {
                 // Instantiate the correct object type so that we can perform validation correctly. If we don't do this
                 // then the provided object will be missing all decorators and validation won't work as desired.
                 const metadataObj = this.instantiateObject(obj);
+                // A separate, genuinely bare instance (constructed with no data at all) to source @ReadOnly
+                // defaults from. `metadataObj` isn't safe for this: it's hydrated from the client-supplied
+                // `obj`, and a model constructor that copies a same-named field from its `other` argument
+                // (a common "hydrate from data" pattern) would carry the client's tampered value straight
+                // through to `metadataObj` too, making the "reset to default" below a no-op.
+                const defaultObj = this.instantiateObject(undefined, metadataObj.constructor);
                 ObjectUtils.validate(obj, metadataObj.constructor);
-                // Iterate through all properties and look for `@Reference`
+                // Iterate through all properties
                 for (const member of Object.getOwnPropertyNames(obj)) {
+                    // Reset any @ReadOnly properties, discarding whatever the client supplied.
+                    const isReadOnly = Reflect.getMetadata("rrst:readOnly", metadataObj, member);
+                    if (member in obj && isReadOnly) {
+                        // Override the value from our default object
+                        obj[member] = defaultObj[member];
+                    }
+                    // Check for @Reference
                     const clazz = Reflect.getMetadata("rrst:reference", metadataObj, member);
-                    if (clazz && clazz.datastore && obj[member]) {
+                    if (clazz && clazz.datasource && obj[member]) {
                         // Attempt to grab the repository for this reference type
-                        const conn = this.connectionManager?.connections.get(clazz.datastore);
+                        const conn = this.connectionManager?.connections.get(clazz.datasource);
                         const repo = conn instanceof MongoConnection || isSqlDataSource(conn)
                             ? conn.getRepository(clazz)
                             : undefined;
                         if (repo) {
-                            // Check to see if there are any objects with this UID in the datastore. If the value is an array
+                            // Check to see if there are any objects with this UID in the datasource. If the value is an array
                             // let's make sure that every uid is valid.
                             const uids = Array.isArray(obj[member]) ? obj[member] : [obj[member]];
                             const query = ModelUtils.buildIdSearchQuery(repo, clazz, uids);
@@ -701,7 +1123,7 @@ export class RepoUtils {
             }
         }
         catch (err) {
-            throw new ApiError(ApiErrorMessages.INVALID_REQUEST, 400, err.message);
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, err.message);
         }
     }
 }
@@ -709,10 +1131,6 @@ __decorate([
     Inject("ACLUtils"),
     __metadata("design:type", Function)
 ], RepoUtils.prototype, "aclUtils", void 0);
-__decorate([
-    RedisConnection("cache"),
-    __metadata("design:type", Redis)
-], RepoUtils.prototype, "cacheClient", void 0);
 __decorate([
     Config(),
     __metadata("design:type", Object)
@@ -725,10 +1143,6 @@ __decorate([
     Logger,
     __metadata("design:type", Object)
 ], RepoUtils.prototype, "logger", void 0);
-__decorate([
-    Inject(ObjectFactory),
-    __metadata("design:type", ObjectFactory)
-], RepoUtils.prototype, "objectFactory", void 0);
 __decorate([
     Inject(NotificationUtils),
     __metadata("design:type", NotificationUtils)
@@ -743,4 +1157,28 @@ __decorate([
     __metadata("design:paramtypes", []),
     __metadata("design:returntype", Promise)
 ], RepoUtils.prototype, "init", null);
+__decorate([
+    Transactional(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], RepoUtils.prototype, "create", null);
+__decorate([
+    Transactional(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RepoUtils.prototype, "delete", null);
+__decorate([
+    Transactional(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], RepoUtils.prototype, "truncate", null);
+__decorate([
+    Transactional(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], RepoUtils.prototype, "update", null);
 //# sourceMappingURL=RepoUtils.js.map