@rapidrest/service-core 2.0.0 → 2.1.1

package/dist/lib/models/RepoUtils.js

@@ -18,16 +18,55 @@ import { isSqlDataSource } from "../database/ConnectionKinds.js";
 import { resolveCollectionName } from "../database/NamingUtils.js";
 import { ModelUtils } from "../models/ModelUtils.js";
 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 { NotificationUtils } from "../NotificationUtils.js";
 import { RecoverableBaseEntity } from "./RecoverableBaseEntity.js";
-import { ACLAction } from "../security/index.js";
+import { ACLAction, AccessControlListMongo, AccessControlListSQL } from "../security/index.js";
 import { ConnectionManager, RedisCache } from "../database/index.js";
+import { isDuplicateKeyError, isIdentityDuplicate } from "../database/DatabaseErrors.js";
 import { registerRollbackHook, Transactional, transactionContext } from "../decorators/DatabaseDecorators.js";
+import { getColumnMetadata } from "../decorators/PersistenceDecorators.js";
 const { Config, Init, Inject, Logger } = ObjectDecorators;
 const _hashCache = new Map();
+/** Per model class: the `@Column`s holding a date, and whether each is date-only (`"date"`) or a full date/time. */
+const _dateColumnCache = new WeakMap();
+/** `YYYY-MM-DD`. */
+const REGEX_ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** `YYYY-MM-DDTHH:mm[:ss[.fraction]][zone]`, where zone is `Z`, `±HH`, `±HHmm` or `±HH:mm`. */
+const REGEX_ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(\.\d{1,9})?)?(Z|[+-]\d{2}(?::?\d{2})?)?$/i;
+/**
+ * The smallest magnitude accepted for a numeric (epoch milliseconds) date. A smaller number is far more likely to
+ * be epoch *seconds* (which would land in January 1970) than a real date between late 1966 and early 1973.
+ */
+const MIN_EPOCH_MS_MAGNITUDE = 1e11;
+/** 0001-01-01T00:00:00.000Z and 9999-12-31T23:59:59.999Z. */
+const MIN_EPOCH_MS = -62135596800000;
+const MAX_EPOCH_MS = 253402300799999;
+/** The actions `RepoUtils.create()` grants a record's creator on a freshly created per-record ACL. */
+const CREATOR_ACTIONS = [
+    ACLAction.COUNT,
+    ACLAction.CREATE,
+    ACLAction.DELETE,
+    ACLAction.EXISTS,
+    ACLAction.READ,
+    ACLAction.LIST,
+    ACLAction.TRUNCATE,
+    ACLAction.UPDATE,
+];
+/** The explicit `@Column({ type })` values that store a date/time (compared lower-cased). */
+const DATE_COLUMN_TYPES = new Set([
+    "date",
+    "datetime",
+    "datetime2",
+    "datetimeoffset",
+    "smalldatetime",
+    "timestamp",
+    "timestamptz",
+    "timestamp with time zone",
+    "timestamp without time zone",
+    "timestamp with local time zone",
+]);
 /**
  * @author Jean-Philippe Steinmetz
  */
@@ -99,28 +138,91 @@ export class RepoUtils {
         }
     }
     /**
-     * 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.
+     * Retrieves the uids matching the given (already-built) search query, ignoring any pagination `take`/`page`
+     * baked into it by `ModelUtils.buildSearchQuery`, unless `cap` is given.
+     *
+     * Without `cap` the whole matching set is returned. Pass `cap` whenever each uid will cost a per-record ACL check
+     * on behalf of a client that acts on the records (`truncate()` on a `recordACL` model): otherwise a single anonymous
+     * request can trigger unbounded ACL work, and on MongoDB a `distinct` over enough uids exceeds the 16MB reply limit.
+     * `count()` must report the true total, so it never uses this - see `countPermittedUids()`.
+     *
+     * @param cap The maximum number of uids to return.
      */
-    async findAllUids(searchQuery, options) {
+    async findAllUids(searchQuery, options, cap) {
         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 match = Array.isArray(searchQuery)
+                ? searchQuery[0].$match
+                : searchQuery["$match"]
+                    ? searchQuery["$match"]
+                    : searchQuery;
+            // Plain `distinct()` + a client-side slice: no aggregation pipelines (see NOTES.md).
+            const uids = await this.repo.distinct("uid", match, { session: txInfo?.session });
+            return cap !== undefined ? uids.slice(0, cap) : uids;
+        }
+        // Only the uid column is needed, and pagination must not clip the result set here unless capped.
         const uidQuery = { ...searchQuery, select: { uid: true } };
         delete uidQuery.take;
         delete uidQuery.page;
+        if (cap !== undefined) {
+            uidQuery.take = cap;
+        }
         const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
         const rows = (await repo.find(uidQuery));
-        return rows.map((obj) => obj.uid);
+        // A trackChanges table holds one row per version, so the same uid can appear more than once.
+        return Array.from(new Set(rows.map((obj) => obj.uid)));
+    }
+    /**
+     * Returns the maximum number of records a client request may have checked individually against record-level
+     * ACLs: the `take` that `ModelUtils.buildSearchQuerySQL()` already resolved onto the built SQL query. A MongoDB
+     * query carries no `take`, so the same rule is read from `ModelUtils.resolvePagination()`, the helper that
+     * documents it for MongoDB callers.
+     */
+    recordACLCap(searchQuery, query) {
+        // Only `truncate()` uses this; `count()` is never capped.
+        if (typeof searchQuery?.take === "number") {
+            return searchQuery.take;
+        }
+        return ModelUtils.resolvePagination(query).take;
+    }
+    /**
+     * Determines whether a built search query can match soft-deleted records: every OR branch must pin `deleted` to
+     * exactly `false` for it not to. Decided from the compiled query rather than the raw client value, so any
+     * spelling of the filter (`true`, `eq(true)`, `in(true,false)`, `ne(false)`, a repeated parameter, a `$or`
+     * branch) is recognized. Always `false` for a model that isn't recoverable.
+     */
+    queryIncludesDeleted(searchQuery) {
+        if (!(this.modelClass?.prototype instanceof RecoverableBaseEntity)) {
+            return false;
+        }
+        const isFalse = (value) => {
+            if (value === false) {
+                return true;
+            }
+            if (value && typeof value === "object") {
+                // TypeORM FindOperator: Equal(false), or an And(...) that contains one.
+                if (value.type === "equal") {
+                    return value.value === false;
+                }
+                if (value.type === "and" && Array.isArray(value.value)) {
+                    return value.value.some(isFalse);
+                }
+                // MongoDB: { $eq: false }.
+                return Object.keys(value).length === 1 && value.$eq === false;
+            }
+            return false;
+        };
+        if (this.repo instanceof MongoRepository) {
+            const excludes = (match) => !!match &&
+                (isFalse(match.deleted) ||
+                    (Array.isArray(match.$or) && match.$or.length > 0 && match.$or.every(excludes)) ||
+                    (Array.isArray(match.$and) && match.$and.some(excludes)));
+            const match = Array.isArray(searchQuery) ? searchQuery[0]?.$match : (searchQuery?.$match ?? searchQuery);
+            return !excludes(match);
+        }
+        // `buildSearchQuerySQL()` always compiles `where` to an array of OR branches (or omits it: no conditions at all).
+        const where = searchQuery?.where;
+        return !Array.isArray(where) || where.length === 0 || !where.every((branch) => isFalse(branch?.deleted));
     }
     /**
      * Filters the given uids down to those the user has `action` permission for, checking in bounded-size
@@ -141,6 +243,62 @@ export class RepoUtils {
         }
         return permitted;
     }
+    /**
+     * Counts the records matched by an (already-built) search query that the caller holds the given permission(s) on,
+     * for a `recordACL` model. Unlike `findAllUids()` this is never capped - a count must be the true total - but it
+     * never holds the whole matching set either: MongoDB streams uids from a projected cursor instead of a `distinct`
+     * (whose single reply is limited to 16MB), and permissions are checked in bounded batches as the uids arrive.
+     *
+     * @param actions Every action the caller must hold on a record for it to be counted.
+     */
+    async countPermittedUids(searchQuery, actions, options) {
+        const txInfo = this.getTransaction(options);
+        const batchSize = 100;
+        // A trackChanges collection holds one row per version, so the same uid can appear more than once.
+        const seen = this.modelClass.trackChanges ? new Set() : undefined;
+        let batch = [];
+        let total = 0;
+        const flush = async () => {
+            let permitted = batch;
+            for (const action of actions) {
+                permitted = await this.filterPermittedUids(permitted, action, options);
+            }
+            total += permitted.length;
+            batch = [];
+        };
+        const add = async (uid) => {
+            if (seen) {
+                if (seen.has(uid)) {
+                    return;
+                }
+                seen.add(uid);
+            }
+            batch.push(uid);
+            if (batch.length >= batchSize) {
+                await flush();
+            }
+        };
+        if (this.repo instanceof MongoRepository) {
+            const match = Array.isArray(searchQuery)
+                ? searchQuery[0].$match
+                : searchQuery["$match"]
+                    ? searchQuery["$match"]
+                    : searchQuery;
+            const cursor = this.repo.find(match, { projection: { uid: 1 }, session: txInfo?.session });
+            for await (const doc of cursor) {
+                await add(doc.uid);
+            }
+        }
+        else {
+            for (const uid of await this.findAllUids(searchQuery, options)) {
+                await add(uid);
+            }
+        }
+        if (batch.length > 0) {
+            await flush();
+        }
+        return total;
+    }
     async count(query, options) {
         if (!this.repo) {
             throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
@@ -156,18 +314,19 @@ export class RepoUtils {
                 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";
+        let searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, query, true, options?.user);
+        // A client-supplied `deleted` filter (in any form: `true`, `eq(true)`, `ne(false)`, a repeated parameter, a
+        // `$or` branch, ...) overrides `buildSearchQuery()`'s default exclusion of soft-deleted rows. Counting a
+        // matched soft-deleted row requires the DELETE+UPDATE permissions, so this is decided from the built query.
+        const clientRequestsDeleted = this.queryIncludesDeleted(searchQuery);
         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;
+                // A top-level `deleted: false` is ANDed with every other condition (including any `$or` branch's own
+                // `deleted`) on both backends, so no soft-deleted row can match.
+                searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, { ...query, deleted: false }, true, options?.user);
             }
         }
-        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) {
@@ -186,19 +345,10 @@ export class RepoUtils {
         // 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;
+            // Never capped: a count is the true total of matching records the caller may see. When the query can
+            // match soft-deleted records, conservatively apply the restore bar (DELETE+UPDATE) to every matched record
+            // rather than the ordinary `action`.
+            return await this.countPermittedUids(searchQuery, clientRequestsDeleted ? [ACLAction.DELETE, ACLAction.UPDATE] : [action], options);
         }
         if (this.repo instanceof MongoRepository) {
             if (Array.isArray(searchQuery)) {
@@ -316,6 +466,13 @@ export class RepoUtils {
         const clazz = this.getClassType(obj);
         const newObj = obj instanceof clazz ? obj : this.instantiateObject(obj, clazz);
         const repo = this.repo;
+        // A create must never let its input pick an existing document. A caller-supplied `_id` would otherwise make
+        // `MongoRepository.save()` replace (upsert) whichever document owns that `_id` - any record, of any owner.
+        if (!options?.preserveId && newObj._id !== undefined) {
+            delete newObj._id;
+        }
+        // JSON has no date type - store Date-typed properties as real dates, not strings.
+        this.coerceDateProperties(newObj, clazz);
         // Make sure an existing object doesn't already exist with the same identifiers
         const ids = [];
         const idProps = ModelUtils.getIdPropertyNames(clazz);
@@ -325,10 +482,7 @@ export class RepoUtils {
                 ids.push(val);
             }
         }
-        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);
+        const count = await this.countById(ids, txInfo, clazz);
         if (!this.modelClass.trackChanges && count > 0) {
             throw new ApiError(ApiErrors.IDENTIFIER_EXISTS, 400, ApiErrorMessages.IDENTIFIER_EXISTS);
         }
@@ -347,7 +501,8 @@ export class RepoUtils {
             // must always run.
             throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
         }
-        // Override the date and version fields with their defaults
+        // Override the date and version fields with their defaults. Whatever the caller supplied for these is
+        // discarded, so a create can't forge a record's history or optimistic-lock state.
         if (newObj instanceof BaseEntity) {
             newObj.dateCreated = new Date();
             newObj.dateModified = new Date();
@@ -357,90 +512,72 @@ export class RepoUtils {
         if (newObj instanceof BaseEntity && this.modelClass.trackChanges === 0) {
             newObj.version = 0;
         }
+        // Resolve the record-level ACL *before* the record is written, so that a create which isn't entitled to its
+        // uid's ACL never writes a record at all (not even one that a transaction rollback would have to undo).
+        const freshAclUid = this.aclUtils?.enabled && this.modelClass.recordACL
+            ? await this.claimRecordACL(newObj.uid, count, options)
+            : undefined;
         // 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);
+        try {
+            if (this.repo instanceof MongoRepository) {
+                // `insertOnly`: a create always inserts, even when trusted code preserved an `_id` (`preserveId`).
+                saved = await this.repo.save(newObj, { session: txInfo?.session, insertOnly: true });
+            }
+            else {
+                const repo = txInfo?.entityManager
+                    ? txInfo.entityManager.getRepository(this.modelClass)
+                    : this.repo;
+                // `insert()` rather than `save()`: TypeORM's `save()` becomes an UPDATE of the existing row when a
+                // concurrent create of the same identifier lands between the count check above and this write.
+                // `insert()` merges generated columns back into `newObj`.
+                await repo.insert(newObj);
+                saved = newObj;
+            }
         }
-        const result = this.instantiateObject(saved);
-        if (this.aclUtils?.enabled && this.modelClass.recordACL) {
-            // 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. We only search the immediate ACL
-            // and not the parent chain and we perform an exact match.
-            let found = !!this.aclUtils.getRecord(acl, options?.user, { maxDepth: 0, specificity: "exact" });
-            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,
-                    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);
-                    }
-                });
+        catch (err) {
+            // Don't leave the ACL claimed above behind for a record that was never written. This can't be left to a
+            // rollback hook alone: without transaction support there is no rollback to run one.
+            if (freshAclUid) {
+                try {
+                    await this.aclUtils.removeACL(freshAclUid);
+                }
+                catch (removeErr) {
+                    this.logger?.warn(`RepoUtils: Failed to remove ACL ${freshAclUid} after a failed create().`);
+                    this.logger?.debug(removeErr);
+                }
             }
-            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.`);
-                });
+            // A duplicate key (a concurrent create of the same identifier, a preserved `_id` that's already taken, or a
+            // value of some other unique column) is an identifier conflict, not an internal error.
+            if (isDuplicateKeyError(err)) {
+                throw new ApiError(ApiErrors.IDENTIFIER_EXISTS, 400, ApiErrorMessages.IDENTIFIER_EXISTS);
             }
+            throw err;
         }
-        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));
+        const result = this.instantiateObject(saved);
+        // `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 (freshAclUid) {
+            registerRollbackHook(async () => {
+                try {
+                    await this.aclUtils.removeACL(freshAclUid);
+                }
+                catch (err) {
+                    this.logger?.warn(`RepoUtils: Failed to roll back orphaned ACL ${freshAclUid} after a failed create().`);
+                    this.logger?.debug(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.
+        // Cache the object for faster retrieval (a copy, so stripping scoped fields below can't alter the cached one).
+        this.cacheRecord(result);
+        // An ACL document written through the ACL routes must not be shadowed by a stale ACLUtils cache entry.
+        await this.invalidateACLCache([result.uid]);
+        // Broadcast to push subscribers, then remove the properties scoped with @RequiresScope that the user does not
+        // have access to from what is returned.
+        this.publish([result.uid], "create", result, options);
         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);
-        }
         return result;
     }
     async delete(uid, options) {
@@ -459,6 +596,8 @@ export class RepoUtils {
         // 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);
+        // The cache keys of every stored version of this record, collected before the rows go away.
+        const versionKeys = await this.versionCacheKeys([uid], options);
         // 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) {
@@ -469,14 +608,19 @@ export class RepoUtils {
                 const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
                 await repo.delete(query.where);
             }
-            if (this.aclUtils?.enabled && this.modelClass.recordACL) {
+            // Purging a single version of a trackChanges record leaves the record (and so its ACL) in place.
+            const recordRemains = !!options.version && (await this.countById(uid, txInfo)) > 0;
+            if (this.aclUtils?.enabled && this.modelClass.recordACL && !recordRemains) {
                 // `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);
+                // `unlessProtected`: a record that shares the uid of a class/route/default ACL must never remove it.
+                const removedAcl = await this.aclUtils.removeACL(uid, {
+                    unlessProtected: true,
+                });
                 if (removedAcl) {
                     registerRollbackHook(async () => {
                         try {
@@ -505,21 +649,11 @@ export class RepoUtils {
                 });
             }
         }
-        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 || []);
-            this.notificationUtils?.sendMessage(channels, this.modelClass.name, "delete", {
-                uid,
-                version: options.version,
-            });
-        }
+        // Delete the object from cache (list results read their records through these same keys).
+        this.uncacheRecords([uid], versionKeys);
+        // An ACL document removed through the ACL routes must stop granting anything right away.
+        await this.invalidateACLCache([uid]);
+        this.publish([uid], "delete", { uid, version: options.version }, options);
     }
     /**
      * Retrieves an array of objects from the datasource matching the given search query. This function will first
@@ -545,23 +679,21 @@ export class RepoUtils {
         const limit = options?.limit ? Math.min(options?.limit, 1000) : 100;
         const page = options?.page ? Number(options?.page) : 0;
         let results = [];
-        // When we hash the seach query we need to ensure we're including the pagination information to preserve
-        // like queries and results.
-        const searchQueryHash = this.hashQuery({
-            ...query,
-            limit,
-            page,
+        // Build (and so validate) the query before consulting the cache: a query that must be rejected (e.g. a forged
+        // `$literal` key, or `me` without a user) is rejected even when an equivalent query's results are cached.
+        const searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, query, true, options?.user);
+        // The cache key covers the pagination, and the requesting user whenever the query can refer to them via `me`
+        // (substituted by `buildSearchQuery()`), since the same raw query then means something different per user.
+        const queryKey = this.queryCacheKey({
+            query: { ...query, limit, page },
+            user: RepoUtils.REGEX_ME.test(JSON.stringify(query) ?? "") ? (options?.user?.uid ?? null) : undefined,
         });
         // Pull from the cache if available
         if (!options?.skipCache && this.cache) {
-            const cached = await this.cache.loadSet(searchQueryHash);
-            if (cached) {
-                results = cached.filter((obj) => obj !== undefined);
-            }
+            results = await this.loadCachedResults(queryKey);
         }
         // 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(searchQuery)) {
@@ -591,10 +723,7 @@ export class RepoUtils {
             }
             // Cache the results for future requests. Don't bother if there were no results.
             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));
+                this.cacheResults(queryKey, results);
             }
         }
         // Record-level ACLs aren't reflected in the query itself (nor in cached results, which are shared across
@@ -619,7 +748,8 @@ export class RepoUtils {
             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.
+        // does not have access to. Done on copies: the cache holds (and keeps serving) the objects themselves.
+        results = results.map((obj) => this.copyRecord(obj));
         ObjectUtils.deleteScopedProps(results, options?.user, this.modelClass);
         return results;
     }
@@ -637,12 +767,17 @@ export class RepoUtils {
         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.
+        // a key shared with create()/update()/find()'s cache-seeding, all of which also cache regardless of the
+        // deleted state. 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.cache) {
-            existing = await this.cache.load(this.hashQuery(query));
+        const version = this.parseVersion(options?.version);
+        // `undefined` when this lookup can't be cached (a specific version of a model whose versions aren't kept).
+        const cacheKey = this.cache ? this.recordCacheKey(id, version) : undefined;
+        if (!options?.skipCache && cacheKey) {
+            const cached = await this.cache.load(cacheKey);
+            // Only accept an entry that really is the record asked for.
+            existing = cached && this.matchesId(cached, id, version) ? cached : undefined;
         }
         if (!existing) {
             if (this.repo instanceof MongoRepository) {
@@ -676,9 +811,9 @@ export class RepoUtils {
             existing = null;
         }
         if (existing) {
-            if (this.cache) {
+            if (cacheKey) {
                 // Cache the object for faster retrieval
-                this.cache.save(this.hashQuery(query), existing).catch((err) => this.logCacheError("save", err));
+                this.cache.save(cacheKey, existing).catch((err) => this.logCacheError("save", err));
             }
             // Check user permissions
             if (this.aclUtils?.enabled && !options?.ignoreACL) {
@@ -698,6 +833,7 @@ export class RepoUtils {
                 }
             }
         }
+        // A new object, so stripping it below never alters the cached one.
         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.
@@ -707,6 +843,202 @@ export class RepoUtils {
         // Make sure we return the correct data type
         return result;
     }
+    /**
+     * Resolves the per-record ACL for a record about to be created by `create()` under `uid`. Returns `uid` when a
+     * fresh ACL was created for it (so the caller can clean it up if the create fails), or `undefined` when an
+     * existing ACL is legitimately reused as-is.
+     *
+     * ACLs live in one global collection keyed only by uid, shared by every model and by the class/route ACLs, and a
+     * create's uid can come from the client. An ACL that already exists at `uid` may guard a record of another model,
+     * a whole model or route, or have been planted there by another user ahead of time - adopting it would hand
+     * whoever holds rights on it the new record, or hand the creator whatever it protects. So:
+     * - a code-defined ACL uid (a class, route or endpoint ACL, or any `default_*` uid; see
+     * `ACLUtils.isReservedUid()`/`isProtectedACL()`) is never claimed or reused, whoever the caller is;
+     * - an existing ACL is reused, unchanged, only for a trackChanges "new version" of an existing record
+     * (`count > 0`; `create()` has already verified the caller's UPDATE right on that record), or when trusted
+     * server code passed `allowExistingACL`. Neither a trusted role nor already holding rights on it is enough.
+     *
+     * Otherwise the create is refused with `IDENTIFIER_EXISTS`, the same error as a record identifier collision.
+     * A genuinely orphaned ACL can't be reliably told apart from one guarding another model's record, so no attempt
+     * is made to replace it. A fresh ACL is claimed with `saveACL()`'s `createOnly` mode, so two concurrent creates
+     * (of the same or of different models) can't both claim the same uid either.
+     */
+    async claimRecordACL(uid, count, options) {
+        const aclUtils = this.aclUtils;
+        const refuse = () => new ApiError(ApiErrors.IDENTIFIER_EXISTS, 400, ApiErrorMessages.IDENTIFIER_EXISTS);
+        if (aclUtils.isReservedUid(uid)) {
+            throw refuse();
+        }
+        // Bypass the cache: this is an authorization decision about the ACL's current state. Only the ACL itself is
+        // inspected, so its parent chain isn't loaded.
+        const existingAcl = await aclUtils.findACL(uid, [], {
+            skipCache: true,
+            skipParents: true,
+        });
+        if (existingAcl) {
+            if (aclUtils.isProtectedACL(existingAcl) || !(count > 0 || options?.allowExistingACL)) {
+                throw refuse();
+            }
+            return undefined;
+        }
+        const acl = {
+            uid,
+            parentUid: options?.acl?.parentUid || this.defaultACLUid,
+            records: [...(options?.acl?.records || [])],
+        };
+        // Look for an existing record for the creator. We only search the immediate ACL
+        // and not the parent chain and we perform an exact match.
+        const found = !!aclUtils.getRecord(acl, options?.user, { maxDepth: 0, specificity: "exact" });
+        // 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, actions: [...CREATOR_ACTIONS] });
+        }
+        await aclUtils.saveACL(acl, { createOnly: true });
+        return uid;
+    }
+    /**
+     * Converts every `Date`-typed property of `obj` that holds a string or number (e.g. an ISO 8601 string from a
+     * JSON request body) to a real `Date`, in place. Without this a MongoDB document stores the string itself, and
+     * date range queries (which compare against `Date` operands) never match it.
+     *
+     * A property counts as `Date`-typed when its `@Column` declares an explicit date/time `type`, or otherwise when
+     * TypeScript's emitted `design:type` is `Date`. TypeScript reflects a union-typed property (e.g. `Date | null`)
+     * as `Object`, so such a property is only converted when its `@Column` sets `type` explicitly. Properties that
+     * aren't `@Column`s are never touched.
+     *
+     * Accepted values (anything else, including a `Date` column holding a boolean or an object, is a 400):
+     * - an ISO 8601 date (`YYYY-MM-DD`) or date-time (`YYYY-MM-DDTHH:mm[:ss[.fff]]`, `T` or a space), with a zone
+     * designator of `Z`, `±HH`, `±HHmm` or `±HH:mm`. A date-time without a zone is read as UTC, never as the server's
+     * local time;
+     * - a finite number of epoch milliseconds between years 1 and 9999 whose magnitude is at least `1e11` (a smaller
+     * number is ambiguous with epoch seconds). Numeric strings are not accepted;
+     * - a `Date`, `null` or `undefined`, which are left as they are.
+     *
+     * A SQL date-only column (`@Column({ type: "date" })`) is validated as a `YYYY-MM-DD` string but kept as that
+     * string: TypeORM writes a `Date` into such a column using the server's local calendar date, so converting it
+     * would store the previous day on any server west of UTC. On MongoDB, which has no date-only type, it is
+     * converted to midnight UTC like any other date.
+     *
+     * @param obj The object whose properties to convert.
+     * @param clazz The model class describing `obj`.
+     * @throws ApiError `INVALID_REQUEST` (400) when a value isn't a valid date.
+     */
+    coerceDateProperties(obj, clazz) {
+        if (!obj || typeof obj !== "object" || !clazz) {
+            return;
+        }
+        const isSql = !(this.repo instanceof MongoRepository);
+        for (const column of RepoUtils.getDateColumns(clazz)) {
+            const value = obj[column.propertyName];
+            if (value === undefined || value === null || value instanceof Date) {
+                continue;
+            }
+            const invalid = () => new ApiError(ApiErrors.INVALID_REQUEST, 400, `Property ${column.propertyName} is invalid. Expected a valid ${column.dateOnly && isSql ? "YYYY-MM-DD date" : "date"}.`);
+            if (column.dateOnly && isSql) {
+                if (typeof value !== "string" || !RepoUtils.parseISODate(value, true)) {
+                    throw invalid();
+                }
+                continue;
+            }
+            const date = RepoUtils.parseDateInput(value);
+            if (!date) {
+                throw invalid();
+            }
+            obj[column.propertyName] = date;
+        }
+    }
+    /**
+     * Returns the date-typed `@Column`s of `clazz` (see `coerceDateProperties()`), computed once per class.
+     */
+    static getDateColumns(clazz) {
+        let columns = _dateColumnCache.get(clazz);
+        if (!columns) {
+            columns = [];
+            for (const column of getColumnMetadata(clazz)) {
+                const type = column.options.type ?? column.designType;
+                const typeName = typeof type === "string" ? type.toLowerCase() : undefined;
+                if (type === Date || (typeName && DATE_COLUMN_TYPES.has(typeName))) {
+                    columns.push({ propertyName: column.propertyName, dateOnly: typeName === "date" });
+                }
+            }
+            _dateColumnCache.set(clazz, columns);
+        }
+        return columns;
+    }
+    /**
+     * Parses a client-supplied date value: an ISO 8601 string or a number of epoch milliseconds (see
+     * `coerceDateProperties()` for the exact rules). Returns `undefined` for anything else.
+     */
+    static parseDateInput(value) {
+        if (typeof value === "number") {
+            const ok = Number.isFinite(value) &&
+                value >= MIN_EPOCH_MS &&
+                value <= MAX_EPOCH_MS &&
+                Math.abs(value) >= MIN_EPOCH_MS_MAGNITUDE;
+            return ok ? new Date(value) : undefined;
+        }
+        return typeof value === "string" ? RepoUtils.parseISODate(value, false) : undefined;
+    }
+    /**
+     * Strictly parses an ISO 8601 date (`YYYY-MM-DD`) or, unless `dateOnly`, date-time string, rejecting impossible
+     * calendar values (e.g. `2026-02-30`) that `new Date()` would silently roll over. A date-time without a zone is
+     * read as UTC.
+     */
+    static parseISODate(value, dateOnly) {
+        const dateMatch = value.match(REGEX_ISO_DATE);
+        const match = dateMatch ?? (dateOnly ? null : value.match(REGEX_ISO_DATE_TIME));
+        if (!match) {
+            return undefined;
+        }
+        const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+        const [hour, minute, second] = [Number(match[4] ?? 0), Number(match[5] ?? 0), Number(match[6] ?? 0)];
+        if (hour > 23 || minute > 59 || second > 59) {
+            return undefined;
+        }
+        const calendar = new Date(Date.UTC(year, month - 1, day));
+        calendar.setUTCFullYear(year); // Date.UTC() maps years 0-99 to 1900-1999
+        if (calendar.getUTCFullYear() !== year || calendar.getUTCMonth() !== month - 1 || calendar.getUTCDate() !== day) {
+            return undefined;
+        }
+        if (dateMatch) {
+            return calendar;
+        }
+        // Normalize the zone (none means UTC; `±HH` and `±HHmm` become `±HH:mm`) so `Date` parses it unambiguously.
+        let zone = (match[8] ?? "Z").toUpperCase();
+        if (zone !== "Z") {
+            // The pattern only admits 2 or 4 digits here.
+            const digits = zone.slice(1).replace(":", "");
+            zone = `${zone[0]}${digits.slice(0, 2)}:${digits.length === 4 ? digits.slice(2) : "00"}`;
+        }
+        const pad = (n, width = 2) => String(n).padStart(width, "0");
+        const fraction = match[7] ? match[7].slice(0, 4).padEnd(4, "0") : "";
+        const date = new Date(`${pad(year, 4)}-${pad(month)}-${pad(day)}T${pad(hour)}:${pad(minute)}:${pad(second)}${fraction}${zone}`);
+        return isNaN(date.getTime()) ? undefined : date;
+    }
+    /**
+     * Rejects update input with a top-level key that MongoDB would interpret as something other than a plain field
+     * name: a dotted path (`"aliases.3"`, which writes a nested element) or an operator (`"$inc"`). Such a key
+     * bypasses route/model validation (which only knows the model's real property names), so it is refused on
+     * every backend rather than passed through.
+     *
+     * @throws ApiError `INVALID_REQUEST` (400) naming the first offending key.
+     */
+    assertPlainPropertyNames(obj) {
+        for (const key of Object.keys(obj ?? {})) {
+            if (key.includes(".") || key.startsWith("$")) {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, `Property ${key} is invalid. Property names cannot contain '.' or start with '$'.`);
+            }
+        }
+    }
+    /**
+     * Determines whether `existing` is under optimistic locking: a `BaseEntity` instance or - for a `BaseEntity`
+     * model - any object carrying a numeric `version`, such as a plain document read straight from a
+     * `MongoRepository` (whose `find()`/`findOne()` return plain documents, not model instances).
+     */
+    isVersioned(existing) {
+        return (existing instanceof BaseEntity ||
+            (typeof existing?.version === "number" && this.modelClass?.prototype instanceof BaseEntity));
+    }
     /**
      * Returns the default access control list governing the model type. Returning a value of `undefined` will grant
      * full acccess to any user (including unauthenticated anonymous users).
@@ -831,7 +1163,10 @@ export class RepoUtils {
         }
         try {
             const searchQuery = ModelUtils.buildSearchQuery(this.modelClass, this.repo, query, true, options?.user);
-            const uids = await this.findAllUids(searchQuery, options);
+            // When every matched record costs a per-record ACL check (a recordACL model, for any caller including an
+            // anonymous one), the work is bounded by the query's page size, so one request removes at most one page.
+            const checksRecordACLs = !!(this.aclUtils?.enabled && this.modelClass.recordACL && !options.ignoreACL);
+            const uids = await this.findAllUids(searchQuery, options, checksRecordACLs ? this.recordACLCap(searchQuery, query) : undefined);
             if (uids.length > 0) {
                 let finalUids = uids;
                 // Check if this class uses record level ACLs. If so, we need to check the perms of
@@ -848,6 +1183,7 @@ export class RepoUtils {
                     }
                 }
                 const cleansUpRecordACLs = !!(this.aclUtils?.enabled && this.modelClass.recordACL);
+                const versionKeys = await this.versionCacheKeys(finalUids, options);
                 // Now delete all records that were found
                 if (this.repo instanceof MongoRepository) {
                     await this.repo.deleteMany({ uid: { $in: finalUids } }, {
@@ -872,7 +1208,10 @@ export class RepoUtils {
                     // 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);
+                    // `unlessProtected`: a record that shares the uid of a class/route/default ACL must never remove it.
+                    const removedAcls = await this.aclUtils.removeACLs(finalUids, {
+                        unlessProtected: true,
+                    });
                     if (removedAcls.length > 0) {
                         registerRollbackHook(async () => {
                             try {
@@ -885,6 +1224,10 @@ export class RepoUtils {
                         });
                     }
                 }
+                // Drop the removed records from the cache (cached lists read their records through these keys), and
+                // the removed ACLs from ACLUtils' cache when this is the ACL model itself.
+                this.uncacheRecords(finalUids, versionKeys);
+                await this.invalidateACLCache(finalUids);
                 if (!options?.skipPush) {
                     let channels = options?.pushChannels || [];
                     for (const uid of finalUids) {
@@ -915,8 +1258,14 @@ export class RepoUtils {
                 throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
             }
         }
-        // Enforce optimistic locking when applicable
-        if (existing instanceof BaseEntity) {
+        // A dotted (`"aliases.3"`) or `$`-prefixed top-level key would write a nested path (or an operator) that
+        // route/model validation never saw. `update()` itself never needs one, so it's refused outright.
+        this.assertPlainPropertyNames(obj);
+        // Enforce optimistic locking when applicable. Keyed on the record actually carrying a version, not on its
+        // prototype: a plain document read straight from a `MongoRepository` is just as versioned as a model
+        // instance, and silently skipping the check (and the version bump below) for it lost concurrent writes.
+        const versioned = this.isVersioned(existing);
+        if (versioned) {
             if (existing.version !== obj.version) {
                 throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
             }
@@ -925,30 +1274,58 @@ export class RepoUtils {
         if (existing.uid !== obj.uid) {
             throw new ApiError(ApiErrors.OBJECT_ID_MISMATCH, 400, ApiErrorMessages.OBJECT_ID_MISMATCH);
         }
+        // JSON has no date type - store Date-typed properties as real dates, not strings.
+        this.coerceDateProperties(obj, this.getClassType(obj));
         // 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) {
+        // didn't send) for them. `dateCreated` is always protected, with no bypass - there is never a
+        // legitimate reason to change it via update(). `@ReadOnly`-decorated properties are an app-level
+        // opt-in for anything else (roles, ownership fields, etc.) that must never be client-settable, but
+        // trusted server-side code may pass `allowReadOnly: true` to write them anyway - see that option's
+        // own doc comment on `RepoUpdateOptions`.
+        const keepPrevious = !!this.modelClass.trackChanges;
+        if (versioned) {
             obj.dateCreated = existing.dateCreated;
         }
-        for (const prop of ModelUtils.getReadOnlyPropertyNames(this.modelClass)) {
-            obj[prop] = existing[prop];
+        if (!options?.allowReadOnly) {
+            const readOnlyProps = ModelUtils.getReadOnlyPropertyNames(this.modelClass);
+            const hasOwn = (target, prop) => Object.prototype.hasOwnProperty.call(target, prop);
+            // `existing` usually comes from `findOne()`, which removes the @RequiresScope fields the requesting user
+            // can't see. Copying such a field from it would erase the stored value, so a missing field is instead left
+            // out of the write (an in-place update then keeps the stored value), or, for a trackChanges model whose
+            // update writes a whole new version, taken from the stored record itself.
+            let source = existing;
+            if (keepPrevious && readOnlyProps.some((prop) => !hasOwn(existing, prop))) {
+                source = (await this.loadStoredRecord(existing, options)) ?? existing;
+            }
+            for (const prop of readOnlyProps) {
+                if (hasOwn(source, prop)) {
+                    obj[prop] = source[prop];
+                }
+                else {
+                    delete obj[prop];
+                }
+            }
         }
-        // When using MongoDB we need to copy the _id property in order to prevent duplicate entries
-        if (existing instanceof BaseMongoEntity) {
+        // `_id` always comes from the stored record, never from the input. On MongoDB this also prevents duplicate
+        // entries when saving; an input `_id` is never allowed to select (or be written over) some other document.
+        if (existing._id !== undefined && existing._id !== null) {
             obj._id = existing._id;
         }
-        const keepPrevious = !!this.modelClass.trackChanges;
+        else {
+            delete obj._id;
+        }
         let query = this.searchIdQuery(existing.uid, options?.version || obj.version);
         let result = null;
-        if (this.repo instanceof MongoRepository) {
-            if (existing instanceof BaseEntity) {
-                if (keepPrevious) {
-                    // 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 {
+        // A duplicate key raised by any of the writes below is mapped by `mapUpdateWriteError()`: 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 write version + 1, and the database rejects the loser - is
+        // reported as a lost optimistic-lock race (409); a clash on any other unique column is a 400.
+        try {
+            if (this.repo instanceof MongoRepository) {
+                // The fields to `$set` in place - never `_id`, which is immutable and already identifies the document.
+                const { _id, ...fields } = obj;
+                if (versioned) {
+                    if (keepPrevious) {
                         result = this.instantiateObject(await this.repo.save({
                             ...obj,
                             _id: undefined, // Ensure we save a new document
@@ -956,104 +1333,92 @@ export class RepoUtils {
                             version: obj.version + 1,
                         }, { session: txInfo?.session }));
                     }
-                    catch (err) {
-                        if (err?.code === 11000) {
+                    else {
+                        // One atomic, version-conditioned find-and-modify that returns this call's own write. A separate
+                        // `updateOne()` followed by a `findOne(version + 1)` read-back could miss when a concurrent writer
+                        // bumped the version again in between, failing a write that had actually succeeded.
+                        result = await this.repo.findOneAndUpdate({ uid: obj.uid, version: obj.version }, {
+                            $set: {
+                                ...fields,
+                                dateModified: new Date(),
+                                version: obj.version + 1,
+                            },
+                        }, { session: txInfo?.session, returnDocument: "after" });
+                        // No match means a concurrent writer already advanced this record past `obj.version` (or removed
+                        // it): a lost optimistic-lock race, reported as such rather than silently overwriting.
+                        if (!result) {
                             throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
                         }
-                        throw err;
                     }
                 }
-                else {
-                    const updateResult = await this.repo.updateOne({ uid: obj.uid, version: obj.version }, {
-                        $set: {
-                            ...obj,
-                            dateModified: new Date(),
-                            version: obj.version + 1,
-                        },
-                    }, {
-                        session: txInfo?.session,
-                    });
-                    // `updateOne()` doesn't throw when its filter (including `version`) matches nothing - a
-                    // concurrent writer that already advanced this row past `obj.version` leaves this call
-                    // matching zero documents. Without this check, the fallback `findOne(version + 1)` below
-                    // would silently find THAT concurrent writer's row and return it as if it were this call's
-                    // own successful update - a genuine version conflict lost instead of reported.
-                    if (updateResult?.matchedCount === 0) {
-                        throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
-                    }
-                }
-            }
-            else if (obj.uid) {
-                if (keepPrevious) {
-                    try {
+                else if (obj.uid) {
+                    if (keepPrevious) {
                         result = this.instantiateObject(await this.repo.save({
                             ...obj,
+                            _id: undefined, // Ensure we save a new document
                             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);
+                    else {
+                        result = await this.repo.findOneAndUpdate({ uid: obj.uid }, { $set: fields }, { session: txInfo?.session, returnDocument: "after" });
+                        // The record was removed after `existing` was read.
+                        if (!result) {
+                            throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
                         }
-                        throw err;
                     }
                 }
                 else {
-                    await this.repo.updateOne({ uid: obj.uid }, {
-                        $set: {
-                            ...obj,
-                        },
-                    }, { session: txInfo?.session });
-                }
-            }
-            else {
-                const toSave = obj;
-                if (keepPrevious) {
-                    toSave.version += 1;
-                }
-                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 repo.insert({
-                        ...obj,
-                        dateModified: new Date(),
-                        version: obj.version + 1,
-                    });
-                }
-                else {
-                    const updateResult = await repo.update(query.where, {
-                        ...obj,
-                        dateModified: new Date(),
-                        version: obj.version + 1,
-                    });
-                    // Same silent-conflict hazard as the Mongo branch above: `repo.update()` doesn't throw when
-                    // its WHERE clause (including `version`) matches nothing, it just reports 0 affected rows.
-                    // Only checked when the driver actually reports a number (some don't, e.g. `affected` stays
-                    // `undefined`) - never throw on ambiguous ignorance of the true row count.
-                    if (updateResult.affected === 0) {
-                        throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
+                    const toSave = obj;
+                    if (keepPrevious) {
+                        toSave.version += 1;
                     }
+                    result = await this.repo.save(toSave, { session: txInfo?.session });
                 }
             }
             else {
-                const toSave = obj;
-                if (keepPrevious) {
-                    toSave.version += 1;
-                    // 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);
+                const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+                if (versioned) {
+                    if (keepPrevious) {
+                        await repo.insert({
+                            ...obj,
+                            dateModified: new Date(),
+                            version: obj.version + 1,
+                        });
+                    }
+                    else {
+                        const updateResult = await repo.update(query.where, {
+                            ...obj,
+                            dateModified: new Date(),
+                            version: obj.version + 1,
+                        });
+                        // Same silent-conflict hazard as the Mongo branch above: `repo.update()` doesn't throw when
+                        // its WHERE clause (including `version`) matches nothing, it just reports 0 affected rows.
+                        // Only checked when the driver actually reports a number (some don't, e.g. `affected` stays
+                        // `undefined`) - never throw on ambiguous ignorance of the true row count.
+                        if (updateResult.affected === 0) {
+                            throw new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION);
+                        }
+                    }
                 }
                 else {
-                    await repo.update(query.where, toSave);
+                    const toSave = obj;
+                    if (keepPrevious) {
+                        toSave.version += 1;
+                        // 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 repo.update(query.where, toSave);
+                    }
                 }
             }
         }
-        query = this.searchIdQuery(existing.uid, existing instanceof BaseEntity ? existing.version + 1 : undefined);
+        catch (err) {
+            throw this.mapUpdateWriteError(err, keepPrevious);
+        }
+        query = this.searchIdQuery(existing.uid, versioned ? existing.version + 1 : undefined);
         if (!result) {
             if (this.repo instanceof MongoRepository) {
                 result = await this.repo.findOne(query["$match"] ? query["$match"] : query, {
@@ -1069,23 +1434,253 @@ export class RepoUtils {
             }
         }
         result = this.instantiateObject(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.
+        // Cache the object for faster retrieval: its latest-version entry, which list results read their records
+        // through too, so a cached list reflects the update (a copy, so stripping scoped fields below can't alter it).
+        this.cacheRecord(result);
+        // An ACL document updated through the ACL routes must take effect right away.
+        await this.invalidateACLCache([result.uid]);
+        // Broadcast to push subscribers, then remove the properties scoped with @RequiresScope that the user does not
+        // have access to from what is returned.
+        this.publish([result.uid], "update", result, options);
         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);
-        }
         return result;
     }
+    /**
+     * Maps an error thrown by one of `update()`'s writes: a duplicate key on the record's identity (`_id`/primary key
+     * or `(uid, version)`) is a lost optimistic-lock race (409 `INVALID_OBJECT_VERSION`), and a duplicate value of any
+     * other unique column is a 400 `IDENTIFIER_EXISTS`. Any other error is returned as is.
+     *
+     * @param err The error thrown by the write.
+     * @param versionInsert Whether the write inserted a new version (`trackChanges`), which makes an unidentified
+     * duplicate key most likely a version clash.
+     */
+    mapUpdateWriteError(err, versionInsert) {
+        if (err instanceof ApiError || !isDuplicateKeyError(err)) {
+            return err;
+        }
+        return isIdentityDuplicate(err, versionInsert)
+            ? new ApiError(ApiErrors.INVALID_OBJECT_VERSION, 409, ApiErrorMessages.INVALID_OBJECT_VERSION)
+            : new ApiError(ApiErrors.IDENTIFIER_EXISTS, 400, ApiErrorMessages.IDENTIFIER_EXISTS);
+    }
+    /**
+     * Counts the stored rows/documents (every version, deleted or not) whose identifier matches `id`, ignoring ACLs.
+     *
+     * @param id The identifier, or identifiers, to match.
+     * @param txInfo The active transaction, if any.
+     * @param clazz The model class to build the identifier query for.
+     */
+    async countById(id, txInfo, clazz = this.modelClass) {
+        const query = ModelUtils.buildIdSearchQuery(this.repo, clazz, id, undefined);
+        if (this.repo instanceof MongoRepository) {
+            return await this.repo.count(query, { session: txInfo?.session });
+        }
+        const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+        return await repo.count(query);
+    }
+    /**
+     * Reads the stored version of `existing` straight from the database, without ACL checks, caching or scoped
+     * property removal. Used by `update()` when `existing` lacks fields it must carry over.
+     */
+    async loadStoredRecord(existing, options) {
+        const txInfo = this.getTransaction(options);
+        const query = this.searchIdQuery(existing.uid, typeof existing.version === "number" ? existing.version : undefined);
+        if (this.repo instanceof MongoRepository) {
+            return await this.repo.find(query, { session: txInfo?.session, sort: { version: -1 }, limit: 1 }).next();
+        }
+        const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+        return await repo.findOne({ ...query, order: { version: "DESC" } });
+    }
+    /**
+     * Returns whether this model keeps every version of a record as its own immutable row/document (`trackChanges`),
+     * which is what makes a version-specific cache entry safe to keep until it expires.
+     */
+    get versionsAreImmutable() {
+        return !!this.modelClass?.trackChanges;
+    }
+    /** Parses a `version` option the way `searchIdQuery()` does. */
+    parseVersion(version) {
+        if (version === undefined || version === null || version === "") {
+            return undefined;
+        }
+        return typeof version === "string" ? parseInt(version, 10) : version;
+    }
+    /**
+     * Returns the cache key of a single record: its latest version, or (only for a model whose versions are immutable)
+     * a specific version. Returns `undefined` for a specific version of any other model, which is never cached: its
+     * entry would outlive the in-place update that replaces that version.
+     *
+     * Record keys (`rec:`) and query result keys (`q:`) are distinct namespaces, so no client-chosen uid can ever name
+     * a query result entry (or the other way around).
+     */
+    recordCacheKey(uid, version) {
+        if (version === undefined) {
+            return `rec:latest:${uid}`;
+        }
+        return this.versionsAreImmutable ? `rec:v${version}:${uid}` : undefined;
+    }
+    /** Returns the cache key of a `find()` result for the given (JSON-serializable) key material. */
+    queryCacheKey(material) {
+        return `q:${this.hashQuery(material)}`;
+    }
+    /**
+     * Determines whether a cached record really is the one identified by `id` (and `version`, when given): one of the
+     * model's identifier properties must hold `id`. Guards against a cache entry written under a colliding key.
+     */
+    matchesId(record, id, version) {
+        if (!record || typeof record !== "object") {
+            return false;
+        }
+        if (version !== undefined && record.version !== version) {
+            return false;
+        }
+        return ModelUtils.getIdPropertyNames(this.modelClass).some((prop) => record[prop] === id);
+    }
+    /**
+     * Returns a shallow copy of `record` with the same prototype, for handing out (or stripping) without altering the
+     * object a cache holds.
+     */
+    copyRecord(record) {
+        if (!record || typeof record !== "object") {
+            return record;
+        }
+        return Object.assign(Object.create(Object.getPrototypeOf(record)), record);
+    }
+    /**
+     * Stores a copy of `record` in the cache under its latest-version key, and under its version key when versions are
+     * immutable. Fire-and-forget: a cache failure never fails the write.
+     */
+    cacheRecord(record) {
+        if (!this.cache || !record?.uid) {
+            return;
+        }
+        const copy = this.copyRecord(record);
+        const keys = [this.recordCacheKey(record.uid)];
+        const version = record.version;
+        if (typeof version === "number" && this.versionsAreImmutable) {
+            keys.push(this.recordCacheKey(record.uid, version));
+        }
+        for (const key of keys) {
+            this.cache.save(key, copy).catch((err) => this.logCacheError("save", err));
+        }
+    }
+    /**
+     * Caches a page of `find()` results: each record under its own record key, and the query key as the list of those
+     * records' `[uid, version]` references. A record of a model whose versions are immutable is referenced by its
+     * version (a list may hold past versions); any other record by its latest-version key, which `update()` refreshes
+     * and `delete()` removes, so a cached list never serves a stale or deleted record.
+     */
+    cacheResults(queryKey, results) {
+        const refs = [];
+        const keys = [];
+        const records = [];
+        for (const record of results) {
+            if (!record?.uid) {
+                continue;
+            }
+            const version = record.version;
+            const ref = [
+                record.uid,
+                this.versionsAreImmutable && typeof version === "number" ? version : null,
+            ];
+            refs.push(ref);
+            keys.push(this.recordCacheKey(ref[0], ref[1] ?? undefined));
+            records.push(record);
+        }
+        this.cache.saveMany(keys, records).catch((err) => this.logCacheError("saveMany", err));
+        this.cache.save(queryKey, refs).catch((err) => this.logCacheError("save", err));
+    }
+    /**
+     * Loads a cached page of `find()` results (see `cacheResults()`). Records that have since expired, been deleted, or
+     * whose entry isn't the referenced record are left out; an empty array means nothing usable was cached.
+     */
+    async loadCachedResults(queryKey) {
+        const refs = await this.cache.load(queryKey);
+        if (!Array.isArray(refs) || refs.length === 0) {
+            return [];
+        }
+        const valid = refs.filter((ref) => Array.isArray(ref) && typeof ref[0] === "string");
+        const loaded = await this.cache.loadMany(valid.map((ref) => this.recordCacheKey(ref[0], ref[1] ?? undefined)));
+        return loaded.filter((record, i) => !!record && record.uid === valid[i][0] && (valid[i][1] === null || record.version === valid[i][1]));
+    }
+    /**
+     * Returns the version-specific cache keys of every stored version of the given records (only for a model whose
+     * versions are cached individually; otherwise none). Must be called before the records are removed.
+     */
+    async versionCacheKeys(uids, options) {
+        if (!this.cache || !this.versionsAreImmutable || uids.length === 0) {
+            return [];
+        }
+        const txInfo = this.getTransaction(options);
+        let rows;
+        if (this.repo instanceof MongoRepository) {
+            rows = await this.repo
+                .find({ uid: { $in: uids } }, { session: txInfo?.session, projection: { uid: 1, version: 1 } })
+                .toArray();
+        }
+        else {
+            const { In } = ModelUtils.orm;
+            const repo = txInfo?.entityManager ? txInfo.entityManager.getRepository(this.modelClass) : this.repo;
+            rows = await repo.find({ where: { uid: In(uids) }, select: { uid: true, version: true } });
+        }
+        return rows
+            .filter((row) => typeof row?.version === "number")
+            .map((row) => this.recordCacheKey(row.uid, row.version));
+    }
+    /**
+     * Removes the cached entries of the given records: their latest-version keys plus `versionKeys` (see
+     * `versionCacheKeys()`). Fire-and-forget: a cache failure never fails the write.
+     */
+    uncacheRecords(uids, versionKeys = []) {
+        if (!this.cache || uids.length === 0) {
+            return;
+        }
+        const keys = uids.map((uid) => this.recordCacheKey(uid)).concat(versionKeys);
+        this.cache.deleteMany(keys).catch((err) => this.logCacheError("deleteMany", err));
+    }
+    /**
+     * Returns whether this is the ACL model itself (served by e.g. a `BaseACLRoute`), whose documents `ACLUtils`
+     * caches separately under their uids.
+     */
+    get isACLModel() {
+        const clazz = this.modelClass;
+        return (!!clazz &&
+            (clazz === AccessControlListMongo ||
+                clazz === AccessControlListSQL ||
+                clazz.prototype instanceof AccessControlListMongo ||
+                clazz.prototype instanceof AccessControlListSQL));
+    }
+    /**
+     * After a write to the ACL model, drops `ACLUtils`' cached copies of the written ACLs so permission checks see the
+     * change right away (they would otherwise keep using the old ACL until its cache entry expired). A failure is
+     * logged rather than failing the write, which has already happened.
+     */
+    async invalidateACLCache(uids) {
+        if (!this.isACLModel || !this.aclUtils || uids.length === 0) {
+            return;
+        }
+        try {
+            await this.aclUtils.invalidateACLs(uids);
+        }
+        catch (err) {
+            this.logger?.warn(`RepoUtils: Failed to invalidate cached ACL(s) ${uids.join(", ")}.`);
+            this.logger?.debug(err);
+        }
+    }
+    /**
+     * Sends a push notification about a write, unless `skipPush` is set. The payload is a copy with every
+     * `@RequiresScope` property removed: subscribers only need READ on the record's channel, and the writer's scopes
+     * say nothing about theirs, so no scoped value is ever published. Consumers that need a scoped value must fetch
+     * the record, which applies their own scopes.
+     */
+    publish(uids, action, payload, options) {
+        if (options?.skipPush || !this.notificationUtils) {
+            return;
+        }
+        const message = this.copyRecord(payload);
+        ObjectUtils.deleteScopedProps(message, undefined, this.modelClass);
+        const channels = uids.concat(options?.pushChannels || []);
+        this.notificationUtils.sendMessage(channels, this.modelClass.name, action, message);
+    }
     /**
      * Performs validation on the object(s) provided. This function first calls `ObjectUtils.validate()` to check
      * any class level defined validation functions. Second, it scans for any properties with the `@Reference`
@@ -1143,6 +1738,8 @@ export class RepoUtils {
         }
     }
 }
+/** Matches a whole-word `me` anywhere in a serialized query (see `find()`'s cache key). */
+RepoUtils.REGEX_ME = /\bme\b/;
 __decorate([
     Inject("ACLUtils"),
     __metadata("design:type", Function)