@web-ts-toolkit/access-router 0.45.0 → 0.47.0

package/index.mjs

@@ -1,9 +1,9 @@
 // src/index.ts
-import { isPlainObject as isPlainObject20, isString as isString10, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject21, isString as isString10, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
 
 // src/middleware.ts
 import JsonRouter2 from "@web-ts-toolkit/express-json-router";
-import { isArray as isArray12, isFunction as isFunction6, isPlainObject as isPlainObject16, isString as isString7 } from "@web-ts-toolkit/utils";
+import { isArray as isArray12, isFunction as isFunction6, isPlainObject as isPlainObject17, isString as isString7 } from "@web-ts-toolkit/utils";
 
 // src/core.ts
 import {
@@ -31,7 +31,8 @@ import {
   isNil as isNil2,
   isPlainObject as isPlainObject10,
   isString as isString4,
-  keys
+  keys,
+  normalizeUrlPath
 } from "@web-ts-toolkit/utils";
 
 // src/helpers/collection.ts
@@ -65,8 +66,12 @@ var mapWithConcurrencyLimit = async (items, limit, iteratee) => {
 };
 var RequestConcurrencyScheduler = class {
   constructor(limit) {
+    this.activeWork = 0;
+    this.waiters = [];
     this.limit = Math.max(1, limit);
   }
+  // Each map bounds its own orchestration workers. Recursive maps never hold
+  // shared work permits while awaiting descendants (including at limit 1).
   async map(items, iteratee) {
     return mapWithConcurrencyLimit(items, this.limit, (item, index) => iteratee(item, index, true));
   }
@@ -74,6 +79,23 @@ var RequestConcurrencyScheduler = class {
     const [result] = await this.map([void 0], () => iteratee(true));
     return result;
   }
+  // Only leaf persistence operations belong here, not service/hook callbacks.
+  // All work calls on this scheduler share a FIFO admission ceiling.
+  async work(operation) {
+    if (this.activeWork >= this.limit) {
+      await new Promise((resolve) => this.waiters.push(resolve));
+    } else {
+      this.activeWork += 1;
+    }
+    try {
+      return await operation();
+    } finally {
+      const next = this.waiters.shift();
+      if (next)
+        next();
+      else this.activeWork -= 1;
+    }
+  }
 };
 
 // src/helpers/document.ts
@@ -298,6 +320,41 @@ function normalizeSortForOrderBy(sort) {
     orders: normalized.fields.map(({ direction }) => direction)
   };
 }
+function sanitizeSortFields(sort, allowedFields) {
+  const { fields, errors } = normalizeSort(sort);
+  if (errors.length > 0) return { sort: void 0, stripped: [], errors };
+  const allowedSet = new Set(allowedFields.concat(["id", "_id"]));
+  const kept = fields.filter(({ field }) => allowedSet.has(field));
+  const stripped = fields.filter(({ field }) => !allowedSet.has(field)).map(({ field }) => field);
+  if (stripped.length === 0) return { sort, stripped, errors: [] };
+  if (kept.length === 0) return { sort: void 0, stripped, errors: [] };
+  if (typeof sort === "string") {
+    return {
+      sort: kept.map(({ field, direction }) => direction === "desc" ? `-${field}` : field).join(" "),
+      stripped,
+      errors: []
+    };
+  }
+  if (sort instanceof Map) {
+    return {
+      sort: new Map(kept.map(({ field, direction }) => [field, direction])),
+      stripped,
+      errors: []
+    };
+  }
+  if (Array.isArray(sort)) {
+    return {
+      sort: kept.map(({ field, direction }) => [field, direction]),
+      stripped,
+      errors: []
+    };
+  }
+  return {
+    sort: Object.fromEntries(kept.map(({ field, direction }) => [field, direction])),
+    stripped,
+    errors: []
+  };
+}
 
 // src/helpers/index.ts
 import { forEach, isArray as isArray2, isEmpty, isObject, isPlainObject as isPlainObject4, isString as isString3 } from "@web-ts-toolkit/utils";
@@ -1165,6 +1222,7 @@ var AccessRuntime = class {
     this.modelAtts = {};
     this.modelInstances = {};
     this.openApiRegistry = new OpenApiRegistry();
+    this.openApiPathPrefix = "";
     this.allowGlobalModelLookup = options.allowGlobalModelLookup ?? false;
     ensureMongooseJsonSchemaInitialized();
   }
@@ -1193,7 +1251,24 @@ var AccessRuntime = class {
     return global;
   }
   registerOpenApiRoute(route) {
-    this.openApiRegistry.register(route);
+    this.openApiRegistry.register(
+      this.openApiPathPrefix ? { ...route, path: normalizeUrlPath(`${this.openApiPathPrefix}/${route.path}`) } : route
+    );
+  }
+  /**
+   * Compose OpenAPI paths while synchronously constructing mounted routers.
+   * Prefixes apply before collision checks; prior descriptors and Express paths
+   * are unchanged. Nested calls compose and the prior scope is restored even on
+   * failure. The callback must finish registration synchronously (no async work).
+   */
+  withOpenApiPathPrefix(prefix, build) {
+    const previous = this.openApiPathPrefix;
+    this.openApiPathPrefix = normalizeUrlPath(`${previous}/${prefix}`);
+    try {
+      return build();
+    } finally {
+      this.openApiPathPrefix = previous;
+    }
   }
   /**
    * Enable strict OpenAPI collision detection for the remainder of this
@@ -1567,6 +1642,7 @@ import {
   get as get4,
   isArray as isArray7,
   isPlainObject as isPlainObject12,
+  set as set3,
   uniq
 } from "@web-ts-toolkit/utils";
 
@@ -1878,7 +1954,8 @@ function resolveValueNode(template, parent, bare) {
     if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
       throw new CorrelatedReferenceError('Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }');
     }
-    return literalParentRefObject(inner.$parent);
+    const literal = literalParentRefObject(inner.$parent);
+    return bare ? { $eq: literal } : literal;
   }
   if (isParentRefMarker(template)) {
     const path = template.$parent;
@@ -2007,8 +2084,28 @@ function isCorrelatedInclude(value) {
   return isPlainObject11(value) && value.mode === "correlated";
 }
 
+// src/helpers/request-work.ts
+var states = /* @__PURE__ */ new WeakMap();
+function getRequestWorkState(req, runtime) {
+  let owners = states.get(req);
+  if (!owners) {
+    owners = /* @__PURE__ */ new WeakMap();
+    states.set(req, owners);
+  }
+  let state = owners.get(runtime);
+  if (!state) {
+    state = {
+      totalQueries: 0,
+      scheduler: new RequestConcurrencyScheduler(
+        resolveRequestComplexity(runtime.getGlobalOption("requestComplexity")).maxBulkConcurrency
+      )
+    };
+    owners.set(runtime, state);
+  }
+  return state;
+}
+
 // src/services/base.ts
-var correlatedExecStates = /* @__PURE__ */ new WeakMap();
 function getCorrelatedTemplateDepth(includes) {
   let max = 0;
   const visit = (entries, depth) => {
@@ -2058,6 +2155,7 @@ function validateClientFilter(filter2) {
 }
 var Base = class {
   constructor(req, modelName) {
+    this.requestRuntime = getActiveRuntime() ?? defaultRuntime;
     this.req = req;
     this.modelName = modelName;
   }
@@ -2195,6 +2293,7 @@ var Base = class {
       }
       seenCorrelatedPaths.add(entry.path);
     }
+    this.assertIncludeOutputPaths([...legacy, ...correlated]);
     let includeLocalFields = [];
     let includePaths = [];
     forEach3(legacy, (inc) => {
@@ -2211,6 +2310,39 @@ var Base = class {
       correlatedReferenceFields: uniq(compact(correlatedReferenceFields))
     };
   }
+  validateIncludeOutputPath(path, modelName) {
+    const permissionField = getModelOption(modelName, "documentPermissionField");
+    if (get4(set3({}, path, true), permissionField) !== void 0 || get4(set3({}, permissionField, true), path) !== void 0) {
+      this.throwClientRequestError(
+        "bad_request" /* BadRequest */,
+        `Include output path ${path} overlaps document permission field ${permissionField} on model ${modelName}`
+      );
+    }
+  }
+  assertIncludeOutputPaths(include) {
+    const pending = [{ entries: include, modelName: this.modelName }];
+    const visited = /* @__PURE__ */ new WeakMap();
+    while (pending.length > 0) {
+      const { entries, modelName } = pending.pop();
+      if (modelName !== this.modelName && !getModelNames().includes(modelName)) {
+        this.throwClientRequestError("bad_request" /* BadRequest */, `Model ${modelName} not found`);
+      }
+      for (const entry of entries) {
+        if (!isPlainObject12(entry)) continue;
+        const models = visited.get(entry) ?? /* @__PURE__ */ new Set();
+        if (models.has(modelName)) continue;
+        models.add(modelName);
+        visited.set(entry, models);
+        if (typeof entry.path === "string" && entry.path) {
+          this.validateIncludeOutputPath(entry.path, modelName);
+        }
+        if ((entry.op === "read" || entry.op === "list") && typeof entry.model === "string") {
+          const nested = entry.args?.include;
+          if (nested) pending.push({ entries: compact(castArray(nested)), modelName: entry.model });
+        }
+      }
+    }
+  }
   getForeignKeyValues(value) {
     return flatten(castArray(value));
   }
@@ -2345,6 +2477,7 @@ var Base = class {
     const svc = await this.getAuthorizedTargetService(model, "count");
     const localValues = docs.flatMap((doc) => this.getForeignKeyValues(get4(doc, localField)));
     const result = await svc.countByFieldValues(foreignField, localValues, _filters ?? {}, "count");
+    if (!result.success && result.code === "bad_request" /* BadRequest */) throw new ClientRequestError(result);
     if (!result.success) return docs;
     for (let y = 0; y < docs.length; y++) {
       const doc = docs[y];
@@ -2353,16 +2486,7 @@ var Base = class {
     return docs;
   }
   getCorrelatedExecState() {
-    const key = this.req;
-    let state = correlatedExecStates.get(key);
-    if (!state) {
-      state = {
-        totalQueries: 0,
-        scheduler: new RequestConcurrencyScheduler(this.getRequestComplexity().maxBulkConcurrency)
-      };
-      correlatedExecStates.set(key, state);
-    }
-    return state;
+    return getRequestWorkState(this.req, this.requestRuntime);
   }
   claimCorrelatedQuerySlot() {
     const limits = this.getRequestComplexity();
@@ -2761,7 +2885,7 @@ var Base = class {
 // src/services/service.ts
 import {
   castArray as castArray2,
-  cloneDeep as cloneDeep3,
+  cloneDeep as cloneDeep4,
   compact as compact2,
   isArray as isArray8,
   isBoolean as isBoolean3,
@@ -2774,6 +2898,26 @@ import {
 import { diff } from "just-diff";
 
 // src/model.ts
+import { cloneDeep as cloneDeep3 } from "@web-ts-toolkit/utils";
+function admitModelPersistence(adapter, scheduler) {
+  return {
+    modelName: adapter.modelName,
+    mongooseModel: adapter.mongooseModel,
+    new: () => adapter.new(),
+    // Mongoose create(array) otherwise starts all document saves at once. Keep
+    // the adapter's array input/output contract, with one permit per item; all
+    // items are submitted even if one rejects, as with unordered create(array).
+    create: (data) => Array.isArray(data) ? Promise.all(data.map((item) => scheduler.work(async () => (await adapter.create([item]))[0]))) : scheduler.work(() => adapter.create(data)),
+    find: (props) => scheduler.work(() => adapter.find(props)),
+    findOne: (props) => scheduler.work(() => adapter.findOne(props)),
+    exists: (filter2) => scheduler.work(() => adapter.exists(filter2)),
+    countDocuments: (filter2) => scheduler.work(() => adapter.countDocuments(filter2)),
+    distinct: (field, conditions) => scheduler.work(() => adapter.distinct(field, conditions)),
+    aggregate: (pipeline) => scheduler.work(() => adapter.aggregate(pipeline)),
+    // Casting builds no persistence work and must not acquire a recursive permit.
+    ...adapter.castFilter ? { castFilter: (filter2) => adapter.castFilter(filter2) } : {}
+  };
+}
 var Model = class {
   constructor(modelName, runtime) {
     this.modelName = modelName;
@@ -2826,6 +2970,11 @@ var Model = class {
   countDocuments(filter2 = {}) {
     return this.mongooseModel.countDocuments(filter2);
   }
+  /** Cast a copy using this model's query schema/setters, without executing query middleware or persistence. */
+  castFilter(filter2) {
+    const query = this.mongooseModel.countDocuments(cloneDeep3(filter2));
+    return query.cast(this.mongooseModel);
+  }
   // see https://mongoosejs.com/docs/api.html#model_Model.distinct
   distinct(field, conditions = {}) {
     return this.mongooseModel.distinct(field, conditions);
@@ -2836,6 +2985,39 @@ var Model = class {
 };
 var model_default = Model;
 
+// src/helpers/apply-update.ts
+import { isPlainObject as isPlainObject13, set as set4 } from "@web-ts-toolkit/utils";
+function applyUpdate(target, data, allowedFields) {
+  const wholeFields = /* @__PURE__ */ new Set();
+  const partialContainers = /* @__PURE__ */ new Set();
+  const collectBoundary = (shape, prefix = "") => {
+    for (const [key, value] of Object.entries(shape)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (value === true) wholeFields.add(path);
+      else {
+        partialContainers.add(path);
+        collectBoundary(value, path);
+      }
+    }
+  };
+  for (const field of allowedFields) {
+    collectBoundary(set4({}, field, true));
+  }
+  const apply = (values, prefix = "") => {
+    for (const [key, value] of Object.entries(values)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (partialContainers.has(path) && !wholeFields.has(path) && (isPlainObject13(value) || Array.isArray(value))) {
+        apply(value, path);
+      } else if (isDocument2(target)) {
+        target.set(path, value);
+      } else {
+        set4(target, path, value);
+      }
+    }
+  };
+  apply(data ?? {});
+}
+
 // src/logger-helpers.ts
 var SENSITIVE_FILTER_KEYS = /* @__PURE__ */ new Set([
   "password",
@@ -3015,6 +3197,30 @@ var error = (error2) => {
 
 // src/services/model-subdocument-service.ts
 import { forEach as forEach4, get as get5, pick as pick2 } from "@web-ts-toolkit/utils";
+async function visibleMutationRows(service, isAllowed, parentId, sub, rows, response) {
+  const accesses = ["read", `subs.${sub}.read`];
+  if (response === "create") accesses.push(`subs.${sub}.list`);
+  const allowed = await Promise.all(accesses.map(isAllowed));
+  if (allowed.some((value) => !value)) return [];
+  const parentFilter = await service.genFilter("read", { _id: parentId });
+  if (parentFilter === false) return [];
+  const parent = await service.findRawParentDoc({
+    filter: { $and: [{ _id: parentId }, parentFilter] },
+    select: "_id",
+    populate: [],
+    lean: true
+  });
+  if (!parent) return [];
+  const targetFilter = response === "create" ? {} : response === "single" ? { _id: rows[0]?._id } : { _id: { $in: rows.map((row) => row._id) } };
+  const [readFilter, listFilter, select] = await Promise.all([
+    service.genFilter(`subs.${sub}.read`, targetFilter),
+    response === "create" ? service.genFilter(`subs.${sub}.list`) : Promise.resolve({}),
+    service.genQuerySelect("read", null, false, [sub, "sub"])
+  ]);
+  if (readFilter === false || listFilter === false) return [];
+  const visible = filterCollection(filterCollection(rows, listFilter), readFilter);
+  return select ? visible.map((row) => pick2(toObject(row), select.concat("_id"))) : visible;
+}
 async function listSub(service, id, sub, options) {
   const { filter: ft, select } = options ?? {};
   const filterErrors = validateClientFilter(ft);
@@ -3046,25 +3252,24 @@ async function readSub(service, id, sub, subId, options) {
   if (subSelect) subdoc = pick2(toObject(subdoc), subSelect.concat(["_id"]));
   return { success: true, kind: "single", code: "success" /* Success */, data: subdoc };
 }
-async function updateSub(service, id, sub, subId, data) {
+async function updateSub(service, persist, isAllowed, id, sub, subId, data) {
   const parentDoc = await getParentDoc(service, id, sub, null, { access: "update" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   const result = get5(parentDoc, sub);
-  const [subFilter, subReadSelect, subUpdateSelect] = await Promise.all([
+  const [subFilter, subUpdateSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.update`, { _id: subId }),
-    service.genQuerySelect("read", null, false, [sub, "sub"]),
     service.genQuerySelect("update", null, false, [sub, "sub"])
   ]);
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
-  let subdoc = findElement(result, subFilter);
+  const subdoc = findElement(result, subFilter);
   if (!subdoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   const allowedData = pick2(data, subUpdateSelect);
-  Object.assign(subdoc, allowedData);
-  await parentDoc.save();
-  if (subReadSelect) subdoc = pick2(toObject(subdoc), subReadSelect.concat(["_id"]));
-  return { success: true, kind: "single", code: "success" /* Success */, data: subdoc };
+  applyUpdate(subdoc, allowedData, subUpdateSelect);
+  await persist(() => parentDoc.save());
+  const visible = await visibleMutationRows(service, isAllowed, parentDoc._id, sub, [subdoc], "single");
+  return { success: true, kind: "single", code: "success" /* Success */, data: visible[0] ?? null };
 }
-async function bulkUpdateSub(service, id, sub, data) {
+async function bulkUpdateSub(service, persist, isAllowed, id, sub, data) {
   const { maxBulkItems } = service.getRequestComplexity();
   if (data.length > maxBulkItems) {
     return {
@@ -3077,24 +3282,23 @@ async function bulkUpdateSub(service, id, sub, data) {
   const parentDoc = await getParentDoc(service, id, sub, null, { access: "update" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   let result = get5(parentDoc, sub);
-  const [subFilter, subReadSelect, subUpdateSelect] = await Promise.all([
+  const [subFilter, subUpdateSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.update`, { _id: { $in: data.map((v) => v._id) } }),
-    service.genQuerySelect("read", null, false, [sub, "sub"]),
     service.genQuerySelect("update", null, false, [sub, "sub"])
   ]);
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
-  result = filterCollection(result, subFilter);
+  result = filterCollection(result, subFilter).filter((subdoc) => findElementById(data, subdoc._id));
   forEach4(result, (subdoc) => {
     const tdata = findElementById(data, subdoc._id);
     if (!tdata) return;
     const allowedData = pick2(tdata, subUpdateSelect);
-    Object.assign(subdoc, allowedData);
+    applyUpdate(subdoc, allowedData, subUpdateSelect);
   });
-  await parentDoc.save();
-  if (subReadSelect) result = result.map((v) => pick2(toObject(v), subReadSelect.concat(["_id"])));
+  await persist(() => parentDoc.save());
+  result = await visibleMutationRows(service, isAllowed, parentDoc._id, sub, result, "bulk");
   return { success: true, kind: "list", code: "success" /* Success */, data: result, count: result.length };
 }
-async function createSub(service, id, sub, data, options) {
+async function createSub(service, persist, isAllowed, id, sub, data, options) {
   const { addFirst } = options ?? {};
   const { maxBulkItems } = service.getRequestComplexity();
   if (Array.isArray(data) && data.length > maxBulkItems) {
@@ -3108,21 +3312,18 @@ async function createSub(service, id, sub, data, options) {
   const parentDoc = await getParentDoc(service, id, sub, null, { access: "update" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   let result = get5(parentDoc, sub);
-  const [subCreateSelect, subReadSelect] = await Promise.all([
-    service.genQuerySelect("create", null, false, [sub, "sub"]),
-    service.genQuerySelect("read", null, false, [sub, "sub"])
-  ]);
+  const subCreateSelect = await service.genQuerySelect("create", null, false, [sub, "sub"]);
   const allowedData = Array.isArray(data) ? data.map((row) => pick2(row, subCreateSelect)) : pick2(data, subCreateSelect);
   if (Array.isArray(allowedData)) {
     addFirst === true ? result.unshift(...allowedData) : result.push(...allowedData);
   } else {
     addFirst === true ? result.unshift(allowedData) : result.push(allowedData);
   }
-  await parentDoc.save();
-  if (subReadSelect) result = result.map((v) => pick2(toObject(v), subReadSelect.concat(["_id"])));
+  await persist(() => parentDoc.save());
+  result = await visibleMutationRows(service, isAllowed, parentDoc._id, sub, result, "create");
   return { success: true, kind: "list", code: "created" /* Created */, data: result, count: result.length };
 }
-async function deleteSub(service, id, sub, subId) {
+async function deleteSub(service, persist, id, sub, subId) {
   const parentDoc = await getParentDoc(service, id, sub, null, { access: "update" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   const result = get5(parentDoc, sub);
@@ -3131,7 +3332,7 @@ async function deleteSub(service, id, sub, subId) {
   const subdoc = findElement(result, subFilter);
   if (!subdoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
   await ("deleteOne" in subdoc ? subdoc.deleteOne?.() : subdoc.remove?.());
-  await parentDoc.save();
+  await persist(() => parentDoc.save());
   return { success: true, kind: "single", code: "success" /* Success */, data: subdoc._id };
 }
 async function getParentDoc(service, id, sub, args, options) {
@@ -3290,6 +3491,15 @@ var shouldKeepCorrelatedRef = (ref, keep) => {
   return false;
 };
 var Service = class extends Base {
+  constructor(req, modelName) {
+    super(req, modelName);
+    this.persist = (operation) => this.getCorrelatedExecState().scheduler.work(operation);
+    this.model = admitModelPersistence(this.createModelAdapter(modelName), this.getCorrelatedExecState().scheduler);
+    this.options = this.getModelRouterOptions(modelName);
+    this.defaults = this.options.defaults || {};
+    this.baseFields = ["_id"];
+    this.baseFieldsExt = this.baseFields.concat(this.options.documentPermissionField);
+  }
   findRawParentDoc(args) {
     return this.model.findOne({
       ...args,
@@ -3306,6 +3516,10 @@ var Service = class extends Base {
   asServiceHookContext(context) {
     return context;
   }
+  getEffectiveAllowedSortFields(allowedSortFields) {
+    const extra = this.options?.sortableFields ?? [];
+    return extra.length > 0 ? [...allowedSortFields, ...extra] : allowedSortFields;
+  }
   beginOp(op, filter2, extra) {
     const startedAt = Date.now();
     debug({
@@ -3327,14 +3541,6 @@ var Service = class extends Base {
       ...extra ?? {}
     });
   }
-  constructor(req, modelName) {
-    super(req, modelName);
-    this.model = this.createModelAdapter(modelName);
-    this.options = this.getModelRouterOptions(modelName);
-    this.defaults = this.options.defaults || {};
-    this.baseFields = ["_id"];
-    this.baseFieldsExt = this.baseFields.concat(this.options.documentPermissionField);
-  }
   async findOne(filter2, args, options) {
     const filterErrors = this.validateClientFilter(filter2);
     if (filterErrors.length > 0) return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: filterErrors };
@@ -3342,30 +3548,36 @@ var Service = class extends Base {
     const { skim, includePermissions, access, populateAccess, lean } = this.resolveFindOneOptions(options);
     const { filter: overrideFilter, select: overrideSelect, populate: overridePopulate } = overrides ?? {};
     let parsedFilter;
+    let processedInclude;
     try {
-      parsedFilter = await this.parseClientData(filter2);
+      processedInclude = this.processInclude(include);
+      parsedFilter = overrideFilter === false ? false : await this.parseClientData(filter2);
     } catch (error2) {
       const result = this.getClientRequestErrorResult(error2);
       if (result) return result;
       throw error2;
     }
     let [_filter, _select, _populate, allowedSortFields] = await Promise.all([
-      overrideFilter || this.genFilter(access, parsedFilter),
+      overrideFilter ?? this.genFilter(access, parsedFilter),
       overrideSelect || this.genQuerySelect(access, select),
       overridePopulate || this.genPopulate(populateAccess || access, populate),
       this.genAllowedFields({}, access, this.baseFieldsExt)
     ]);
-    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = this.processInclude(include);
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = processedInclude;
     const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
     const finalSelect = normalizeSelect(_select).concat(includeLocalFields, correlatedReferenceFields);
+    const effectiveAllowedSortFields = this.getEffectiveAllowedSortFields(allowedSortFields);
+    const stripDisallowedSort = this.options?.stripDisallowedSort ?? false;
+    const sanitizedSort = stripDisallowedSort ? sanitizeSortFields(sort, effectiveAllowedSortFields) : null;
+    const effectiveSort = stripDisallowedSort ? sanitizedSort?.sort : sort;
     const query = {
       filter: _filter,
       select: finalSelect,
-      sort,
+      sort: effectiveSort,
       populate: _populate
     };
     const startedAt = this.beginOp("findOne", _filter, {
-      sort,
+      sort: effectiveSort,
       selectCount: finalSelect.length,
       populateCount: Array.isArray(_populate) ? _populate.length : _populate ? 1 : 0
     });
@@ -3373,10 +3585,17 @@ var Service = class extends Base {
       this.completeOp("findOne", startedAt, "forbidden" /* Forbidden */, _filter);
       return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query };
     }
-    const sortErrors = validateSortFields(sort, allowedSortFields);
-    if (sortErrors.length > 0) {
-      this.completeOp("findOne", startedAt, "bad_request" /* BadRequest */, _filter);
-      return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sortErrors, query };
+    if (stripDisallowedSort) {
+      if (sanitizedSort && sanitizedSort.errors.length > 0) {
+        this.completeOp("findOne", startedAt, "bad_request" /* BadRequest */, _filter);
+        return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sanitizedSort.errors, query };
+      }
+    } else {
+      const sortErrors = validateSortFields(sort, effectiveAllowedSortFields);
+      if (sortErrors.length > 0) {
+        this.completeOp("findOne", startedAt, "bad_request" /* BadRequest */, _filter);
+        return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sortErrors, query };
+      }
     }
     let doc = await this.model.findOne({ ...query, lean });
     if (!doc) {
@@ -3390,7 +3609,7 @@ var Service = class extends Base {
       originalDocumentSnapshot: toObject(doc),
       resolvedQuery: query
     };
-    const correlatedSnapshots = [cloneDeep3(toObject(doc))];
+    const correlatedSnapshots = [cloneDeep4(toObject(doc))];
     try {
       doc = await this.includeDocs(doc, includes);
       if (correlatedIncludes.length > 0) {
@@ -3437,7 +3656,8 @@ var Service = class extends Base {
     const { select, populate, include, overrides } = this.resolveFindByIdArgs(args);
     const { skim, includePermissions, access, populateAccess, lean } = this.resolveFindByIdOptions(options);
     const { select: overrideSelect, populate: overridePopulate, idFilter: overrideIdFilter } = overrides ?? {};
-    const filter2 = overrideIdFilter || await this.genIDFilter(id);
+    const filter2 = overrideIdFilter ?? await this.genIDFilter(id);
+    if (filter2 === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query: { filter: filter2 } };
     return this.findOne(
       filter2,
       {
@@ -3459,15 +3679,17 @@ var Service = class extends Base {
     const { skim, includePermissions, includeCount, populateAccess, lean } = this.resolveFindOptions(options);
     const { filter: overrideFilter, select: overrideSelect, populate: overridePopulate } = overrides ?? {};
     let parsedFilter;
+    let processedInclude;
     try {
-      parsedFilter = await this.parseClientData(filter2);
+      processedInclude = this.processInclude(include);
+      parsedFilter = overrideFilter === false ? false : await this.parseClientData(filter2);
     } catch (error2) {
       const result = this.getClientRequestErrorResult(error2);
       if (result) return result;
       throw error2;
     }
     const [_filter, _select, _populate, pagination, allowedSortFields] = await Promise.all([
-      overrideFilter || this.genFilter("list", parsedFilter),
+      overrideFilter ?? this.genFilter("list", parsedFilter),
       overrideSelect || this.genQuerySelect("list", select),
       overridePopulate || this.genPopulate(populateAccess, populate),
       genPagination({ skip, limit, page, pageSize }, this.options.listHardLimit),
@@ -3475,17 +3697,21 @@ var Service = class extends Base {
     ]);
     const finalSelect = normalizeSelect(_select);
     const filteredPopulate = isArray8(finalSelect) && isArray8(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
-    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = this.processInclude(include);
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = processedInclude;
     const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
+    const effectiveAllowedSortFields = this.getEffectiveAllowedSortFields(allowedSortFields);
+    const stripDisallowedSort = this.options?.stripDisallowedSort ?? false;
+    const sanitizedSort = stripDisallowedSort ? sanitizeSortFields(sort, effectiveAllowedSortFields) : null;
+    const effectiveSort = stripDisallowedSort ? sanitizedSort?.sort : sort;
     const query = {
       filter: _filter,
       select: finalSelect.concat(includeLocalFields, correlatedReferenceFields),
       populate: filteredPopulate,
-      sort,
+      sort: effectiveSort,
       ...pagination
     };
     const startedAt = this.beginOp("find", _filter, {
-      sort,
+      sort: effectiveSort,
       skip: pagination.skip,
       limit: pagination.limit,
       selectCount: finalSelect.concat(includeLocalFields, correlatedReferenceFields).length,
@@ -3495,10 +3721,17 @@ var Service = class extends Base {
       this.completeOp("find", startedAt, "forbidden" /* Forbidden */, _filter);
       return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query };
     }
-    const sortErrors = validateSortFields(sort, allowedSortFields);
-    if (sortErrors.length > 0) {
-      this.completeOp("find", startedAt, "bad_request" /* BadRequest */, _filter);
-      return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sortErrors, query };
+    if (stripDisallowedSort) {
+      if (sanitizedSort && sanitizedSort.errors.length > 0) {
+        this.completeOp("find", startedAt, "bad_request" /* BadRequest */, _filter);
+        return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sanitizedSort.errors, query };
+      }
+    } else {
+      const sortErrors = validateSortFields(sort, effectiveAllowedSortFields);
+      if (sortErrors.length > 0) {
+        this.completeOp("find", startedAt, "bad_request" /* BadRequest */, _filter);
+        return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: sortErrors, query };
+      }
     }
     let docs = await this.model.find({
       ...query,
@@ -3513,7 +3746,7 @@ var Service = class extends Base {
       resolvedQuery: query
     }));
     const _decorate = isFunction3(decorate) ? decorate : (v) => v;
-    const correlatedSnapshots = docs.map((doc) => cloneDeep3(toObject(doc)));
+    const correlatedSnapshots = docs.map((doc) => cloneDeep4(toObject(doc)));
     try {
       docs = await this.includeDocs(docs, includes);
       if (correlatedIncludes.length > 0) {
@@ -3685,7 +3918,7 @@ var Service = class extends Base {
       }
       if (includeDocPermissions) doc = await this.addDocPermissions(doc, "create", contexts[index]);
       if (includePermissions) doc = await this.addFieldPermissions(doc, "read", contexts[index]);
-      if (resolvedPopulate.length > 0) await populateDoc(doc, resolvedPopulate);
+      if (resolvedPopulate.length > 0) await this.persist(() => populateDoc(doc, resolvedPopulate));
       doc = await this.trimOutputFields(doc, "read", this.baseFieldsExt);
       let outputDoc = await _decorate(doc, contexts[index]);
       if (!includePermissions) outputDoc = this.addEmptyPermissions(outputDoc);
@@ -3741,6 +3974,13 @@ var Service = class extends Base {
       data: doc
     };
   }
+  /**
+   * Update at authorized policy paths: admitted leaves preserve omitted siblings;
+   * whole-authorized objects/arrays replace. Shared by updateById and existing-row
+   * upsert. Validation precedes trusted prepare output (not re-filtered); partial
+   * prepare containers preserve omissions. Transform retains explicit document-setter
+   * replacement authority. Send nested client JSON, not literal dotted update keys.
+   */
   async updateOne(filter2, data, args, options, decorate) {
     const filterErrors = this.validateClientFilter(filter2);
     if (filterErrors.length > 0) return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: filterErrors };
@@ -3748,7 +3988,7 @@ var Service = class extends Base {
     const { skim, includePermissions, populateAccess } = this.resolveUpdateOneOptions(options);
     const { filter: overrideFilter, populate: overridePopulate } = overrides ?? {};
     const [_filter, _populate] = await Promise.all([
-      overrideFilter || this.genFilter("update", filter2),
+      overrideFilter ?? this.genFilter("update", filter2),
       overridePopulate || this.genPopulate(populateAccess, populate)
     ]);
     const query = { filter: _filter, populate: _populate };
@@ -3803,11 +4043,11 @@ var Service = class extends Base {
     }
     const prepared = await this.prepare(allowedData, "update", context);
     context.preparedData = prepared;
-    Object.assign(doc, prepared);
+    applyUpdate(doc, prepared, allowedFields);
     context.modifiedPaths = doc.modifiedPaths();
     doc = assertModelDocument(await this.transform(doc, "update", context), this.modelName, "transform");
     context.currentDocument = doc;
-    doc = await doc.save();
+    doc = await this.persist(() => doc.save());
     const diffExcludeFields = [this.options.documentPermissionField, "__v"];
     this.asServiceHookContext(context).diff = (d) => {
       context.changes = diff(
@@ -3827,7 +4067,7 @@ var Service = class extends Base {
     }
     if (includeDocPermissions) doc = await this.addDocPermissions(doc, "update", context);
     if (includePermissions) doc = await this.addFieldPermissions(doc, "update", context);
-    if (_populate) await populateDoc(doc, _populate);
+    if (_populate) await this.persist(() => populateDoc(doc, _populate));
     doc = await this.trimOutputFields(doc, "read", this.baseFieldsExt);
     let outputDoc = doc;
     if (isFunction3(decorate)) outputDoc = await decorate(outputDoc, context);
@@ -3839,7 +4079,8 @@ var Service = class extends Base {
     const { populate, overrides } = this.resolveUpdateByIdArgs(args);
     const { skim, includePermissions, populateAccess } = this.resolveUpdateByIdOptions(options);
     const { populate: overridePopulate, idFilter: overrideIdFilter } = overrides;
-    const filter2 = overrideIdFilter || await this.genIDFilter(id);
+    const filter2 = overrideIdFilter ?? await this.genIDFilter(id);
+    if (filter2 === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query: { filter: filter2 } };
     return this.updateOne(
       filter2,
       data,
@@ -3859,7 +4100,7 @@ var Service = class extends Base {
     const { populate, overrides } = this.resolveUpsertArgs(args);
     const { skim, includePermissions, populateAccess } = this.resolveUpsertOptions(options);
     const { filter: overrideFilter, populate: overridePopulate } = overrides ?? {};
-    const _filter = await (overrideFilter || this.genFilter("update", filter2));
+    const _filter = await (overrideFilter ?? this.genFilter("update", filter2));
     const query = { filter: _filter };
     const startedAt = this.beginOp("upsert", _filter);
     if (_filter === false) {
@@ -3919,7 +4160,9 @@ var Service = class extends Base {
       resolvedQuery: query
     };
     await this.beforeDelete(doc, context);
-    await ("deleteOne" in doc ? doc.deleteOne() : doc.remove());
+    await this.persist(
+      () => "deleteOne" in doc ? doc.deleteOne() : doc.remove()
+    );
     context.finalDocumentSnapshot = toObject(doc);
     await this.afterDelete(doc, context);
     this.completeOp("delete", startedAt, "success" /* Success */, filter2);
@@ -3930,6 +4173,7 @@ var Service = class extends Base {
     if (filterErrors.length > 0) return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: filterErrors };
     const { access, includeId } = this.resolveExistsOptions(options);
     filter2 = await this.genFilter(access, filter2);
+    if (filter2 === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query: { filter: filter2 } };
     const result = await this.model.exists(filter2);
     return {
       success: true,
@@ -3999,6 +4243,13 @@ var Service = class extends Base {
       query
     };
   }
+  /**
+   * Group target document IDs by original parent-key aliases using one aggregate.
+   * Resolves the requested row policy (legacy count includes pass `count`), casts
+   * authorized filters/foreign operands with the target schema, and deduplicates IDs
+   * independently of pagination. Cast failures return BadRequest; false policy returns
+   * Forbidden. Casting does not execute countDocuments middleware/plugins.
+   */
   async countByFieldValues(foreignField, values, filter2 = {}, access = "list") {
     if (!isValidFieldPath(foreignField)) {
       return {
@@ -4017,7 +4268,25 @@ var Service = class extends Base {
     });
     const query = { filter: filter2 };
     if (filter2 === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query };
-    const matchFilter = filter2;
+    let matchFilter = filter2;
+    let castValues = uniqueValues;
+    try {
+      if (this.model.castFilter) {
+        matchFilter = this.model.castFilter(matchFilter);
+        const foreignFilter = this.model.castFilter({ [foreignField]: { $in: uniqueValues } });
+        castValues = foreignFilter[foreignField]?.$in;
+        if (!Array.isArray(castValues) || castValues.length !== uniqueValues.length) {
+          throw new Error("Foreign field query casting must retain the join operands");
+        }
+      }
+    } catch {
+      return {
+        success: false,
+        kind: "error",
+        code: "bad_request" /* BadRequest */,
+        errors: [{ detail: "Invalid grouped include count filter or foreign-key value" }]
+      };
+    }
     const rows = await this.model.aggregate([
       { $match: matchFilter },
       {
@@ -4028,12 +4297,20 @@ var Service = class extends Base {
         }
       },
       { $unwind: "$foreignValues" },
-      { $match: { foreignValues: { $in: uniqueValues } } },
+      { $match: { foreignValues: { $in: castValues } } },
       { $group: { _id: "$foreignValues", documentIds: { $addToSet: "$_id" } } }
     ]);
-    const counts = /* @__PURE__ */ new Map();
+    const grouped = /* @__PURE__ */ new Map();
     for (const row of rows) {
-      counts.set(String(row._id), new Set(row.documentIds.map((id) => String(id))));
+      const key = String(row._id);
+      const ids = grouped.get(key) ?? /* @__PURE__ */ new Set();
+      for (const id of row.documentIds) ids.add(String(id));
+      grouped.set(key, ids);
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (let i = 0; i < uniqueValues.length; i++) {
+      const ids = grouped.get(String(castValues[i]));
+      if (ids) counts.set(String(uniqueValues[i]), ids);
     }
     return { success: true, kind: "single", code: "success" /* Success */, data: counts, query };
   }
@@ -4112,17 +4389,60 @@ var Service = class extends Base {
   async readSub(id, sub, subId, options) {
     return readSub(this, id, sub, subId, options);
   }
+  /**
+   * Apply authorized policy-path updates, preserving protected siblings, then save.
+   * Output requires post-save parent read and subdocument read operation/row access;
+   * hidden output is successful `data: null` (direct/root-entry 200), not a failed write.
+   * Visible output uses read fields plus `_id`. Do not retry solely for null output.
+   */
   async updateSub(id, sub, subId, data) {
-    return updateSub(this, id, sub, subId, data);
+    return updateSub(
+      this,
+      this.persist,
+      (access) => this.req.macl.isAllowed(this.modelName, access),
+      id,
+      sub,
+      subId,
+      data
+    );
   }
+  /**
+   * Save authorized targeted updates, then return readable targets in stored order.
+   * Requires parent/subdocument read access for output, not subdocument list access;
+   * uses read fields plus `_id`. Hidden output succeeds with `data: [], count: 0`
+   * (direct/root-entry 200); count measures visible rows, not all updated rows.
+   */
   async bulkUpdateSub(id, sub, data) {
-    return bulkUpdateSub(this, id, sub, castArray2(data));
+    return bulkUpdateSub(
+      this,
+      this.persist,
+      (access) => this.req.macl.isAllowed(this.modelName, access),
+      id,
+      sub,
+      castArray2(data)
+    );
   }
+  /**
+   * Append/prepend admitted rows, then return the visible full array (including when
+   * input is empty). Output requires post-save parent read and subdocument list AND
+   * read guards/row filters; fields use read projection plus `_id`.
+   * Hidden output succeeds with code `created`, `data: [], count: 0`
+   * (direct/root-entry 201). Visible count/order follow filtered stored rows.
+   * Empty output does not mean the write failed; addFirst is a service option.
+   */
   async createSub(id, sub, data, options) {
-    return createSub(this, id, sub, data, options);
+    return createSub(
+      this,
+      this.persist,
+      (access) => this.req.macl.isAllowed(this.modelName, access),
+      id,
+      sub,
+      data,
+      options
+    );
   }
   async deleteSub(id, sub, subId) {
-    return deleteSub(this, id, sub, subId);
+    return deleteSub(this, this.persist, id, sub, subId);
   }
   async getParentDoc(id, sub, args, options) {
     return getParentDoc(this, id, sub, args, options);
@@ -4196,6 +4516,7 @@ var PublicService = class extends Service {
       },
       { skim, includePermissions, access, populateAccess, lean }
     );
+    if (!result.success && (result.code === "bad_request" /* BadRequest */ || result.code === "forbidden" /* Forbidden */)) return result;
     if (tryList && (!result.success || !result.data)) {
       const listAllowed = await this.req.macl.isAllowed(this.modelName, "list");
       if (!listAllowed) {
@@ -4236,6 +4557,7 @@ var PublicService = class extends Service {
       },
       { skim, includePermissions, access, populateAccess, lean }
     );
+    if (!result.success && (result.code === "bad_request" /* BadRequest */ || result.code === "forbidden" /* Forbidden */)) return result;
     if (tryList && (!result.success || !result.data)) {
       const listAllowed = await this.req.macl.isAllowed(this.modelName, "list");
       if (!listAllowed) {
@@ -4284,6 +4606,11 @@ var PublicService = class extends Service {
     }
     return result;
   }
+  /**
+   * With an _id, check update-policy existence then update: terminal denial returns
+   * Forbidden, an allowed miss remains Unauthorized, and neither creates a row.
+   * Without an _id, use the create path.
+   */
   async _upsert(data, args, options) {
     const idKey = this.getIdentifier();
     if (idKey !== "_id") {
@@ -4514,7 +4841,7 @@ var DataService = class {
 };
 
 // src/processors.ts
-import { cloneDeep as cloneDeep4, forEach as forEach6, get as get7, hasOwn, isArray as isArray9, isPlainObject as isPlainObject14, map, set as set5 } from "@web-ts-toolkit/utils";
+import { cloneDeep as cloneDeep5, forEach as forEach6, get as get7, hasOwn, isArray as isArray9, isPlainObject as isPlainObject15, map, set as set6 } from "@web-ts-toolkit/utils";
 var UNSAFE_PATH_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 var DEFAULT_MAX_SLICE = 1e3;
 var DEFAULT_MASK_REPLACEMENT = "***";
@@ -4549,7 +4876,7 @@ function resolveLeafParents(obj, src) {
   for (let ind = 0; ind < segs.length - 1; ind += 1) {
     const seg = segs[ind];
     targets = targets.reduce((ret, target) => {
-      if (!isPlainObject14(target)) return ret;
+      if (!isPlainObject15(target)) return ret;
       const targetObject = target;
       const next = targetObject[seg];
       if (isArray9(next)) {
@@ -4563,7 +4890,7 @@ function resolveLeafParents(obj, src) {
   const leaf = segs[segs.length - 1];
   const pairs = [];
   forEach6(targets, (target) => {
-    if (!isPlainObject14(target)) return;
+    if (!isPlainObject15(target)) return;
     pairs.push({ parent: target, leaf });
   });
   return pairs;
@@ -4571,7 +4898,7 @@ function resolveLeafParents(obj, src) {
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
   const mutable = options.mutable !== false;
   const idField = options.idField ?? "_id";
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
@@ -4584,7 +4911,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
     forEach6(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
         forEach6(targets, (target) => {
-          if (!isPlainObject14(target)) return;
+          if (!isPlainObject15(target)) return;
           const targetObject = target;
           const leaf = targetObject[seg];
           const sourceForDest = leaf;
@@ -4592,7 +4919,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
           if (isArray9(leaf)) {
             if (leaf.length === 0) {
               depopulated = [];
-            } else if (leaf.every((item) => isPlainObject14(item))) {
+            } else if (leaf.every((item) => isPlainObject15(item))) {
               depopulated = map(leaf, idField).map((id, i) => {
                 if (id === void 0) {
                   failMissingId(`${src}[${i}]`);
@@ -4602,7 +4929,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
             } else {
               return;
             }
-          } else if (isPlainObject14(leaf)) {
+          } else if (isPlainObject15(leaf)) {
             const id = get7(leaf, idField);
             if (id === void 0) {
               failMissingId(src);
@@ -4611,12 +4938,12 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
           } else {
             return;
           }
-          set5(targetObject, dest, sourceForDest);
-          set5(targetObject, seg, depopulated);
+          set6(targetObject, dest, sourceForDest);
+          set6(targetObject, seg, depopulated);
         });
       } else {
         targets = targets.reduce((ret, target) => {
-          if (!isPlainObject14(target)) return ret;
+          if (!isPlainObject15(target)) return ret;
           const targetObject = target;
           const next = targetObject[seg];
           if (isArray9(next)) {
@@ -4633,7 +4960,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
 };
 var copyPaths = (docObject, operations, options = { mutable: true }) => {
   const mutable = options.mutable !== false;
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
@@ -4644,14 +4971,14 @@ var copyPaths = (docObject, operations, options = { mutable: true }) => {
     if (src === dest) return;
     forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
       if (!hasOwn(parent, leaf)) return;
-      set5(parent, dest, cloneDeep4(parent[leaf]));
+      set6(parent, dest, cloneDeep5(parent[leaf]));
     });
   });
   return obj;
 };
 var movePaths = (docObject, operations, options = { mutable: true }) => {
   const mutable = options.mutable !== false;
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
@@ -4662,8 +4989,8 @@ var movePaths = (docObject, operations, options = { mutable: true }) => {
     if (src === dest) return;
     forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
       if (!hasOwn(parent, leaf)) return;
-      const value = cloneDeep4(parent[leaf]);
-      set5(parent, dest, value);
+      const value = cloneDeep5(parent[leaf]);
+      set6(parent, dest, value);
       if (dest === leaf || dest.startsWith(`${leaf}.`)) return;
       delete parent[leaf];
     });
@@ -4674,7 +5001,7 @@ var sliceArrays = (docObject, operations, options = { mutable: true, maxSlice: D
   const mutable = options.mutable !== false;
   const maxSlice = options.maxSlice ?? DEFAULT_MAX_SLICE;
   assertNonNegativeSafeInteger(maxSlice, "maxSlice", "sliceArrays");
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string") return;
     const src = op.src;
@@ -4698,9 +5025,9 @@ var sliceArrays = (docObject, operations, options = { mutable: true, maxSlice: D
       const end = typeof limit === "undefined" ? void 0 : skip + limit;
       const window = leafValue.slice(skip, end);
       if (typeof rawDest === "undefined") {
-        set5(parent, leaf, window);
+        set6(parent, leaf, window);
       } else {
-        set5(parent, rawDest, window);
+        set6(parent, rawDest, window);
       }
     });
   });
@@ -4708,7 +5035,7 @@ var sliceArrays = (docObject, operations, options = { mutable: true, maxSlice: D
 };
 var countPaths = (docObject, operations, options = { mutable: true }) => {
   const mutable = options.mutable !== false;
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
@@ -4722,21 +5049,21 @@ var countPaths = (docObject, operations, options = { mutable: true }) => {
       let count;
       if (isArray9(leafValue)) {
         count = leafValue.length;
-      } else if (isPlainObject14(leafValue)) {
+      } else if (isPlainObject15(leafValue)) {
         count = Object.keys(leafValue).length;
       } else if (leafValue === null || typeof leafValue === "undefined") {
         count = 0;
       } else {
         count = 1;
       }
-      set5(parent, dest, count);
+      set6(parent, dest, count);
     });
   });
   return obj;
 };
 var maskPaths = (docObject, operations, options = { mutable: true }) => {
   const mutable = options.mutable !== false;
-  const obj = mutable ? docObject : cloneDeep4(docObject);
+  const obj = mutable ? docObject : cloneDeep5(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string") return;
     const src = op.src;
@@ -4745,7 +5072,7 @@ var maskPaths = (docObject, operations, options = { mutable: true }) => {
     const replacement = Object.prototype.hasOwnProperty.call(op, "replacement") ? op.replacement : DEFAULT_MASK_REPLACEMENT;
     forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
       if (!hasOwn(parent, leaf)) return;
-      set5(parent, leaf, replacement);
+      set6(parent, leaf, replacement);
     });
   });
   return obj;
@@ -4798,7 +5125,7 @@ import {
   isEmpty as isEmpty2,
   isEqual,
   isFunction as isFunction4,
-  isPlainObject as isPlainObject15,
+  isPlainObject as isPlainObject16,
   isString as isString5
 } from "@web-ts-toolkit/utils";
 
@@ -4839,10 +5166,10 @@ var permission_default = Permission;
 
 // src/core-shared.ts
 function isAndFilter(filter2) {
-  return !!filter2 && isPlainObject15(filter2) && Object.keys(filter2).length === 1 && isArray10(filter2.$and);
+  return !!filter2 && isPlainObject16(filter2) && Object.keys(filter2).length === 1 && isArray10(filter2.$and);
 }
 function isMergeableClause(filter2) {
-  return !!filter2 && isPlainObject15(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
+  return !!filter2 && isPlainObject16(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
 }
 function optimizeAndFilter(clausesInput) {
   const clauses = [];
@@ -4860,7 +5187,7 @@ function optimizeAndFilter(clausesInput) {
     if (isArray10(value)) {
       return `[${value.map(dedupeKey).join(",")}]`;
     }
-    if (isPlainObject15(value)) {
+    if (isPlainObject16(value)) {
       return `{${Object.keys(value).sort().map((key) => `${key}:${dedupeKey(value[key])}`).join(",")}}`;
     }
     return JSON.stringify(value);
@@ -4902,7 +5229,7 @@ function optimizeAndFilter(clausesInput) {
 }
 function normalizeFilter(filter2) {
   if (filter2 === false) return false;
-  if (!filter2 || !isPlainObject15(filter2) || isEmpty2(filter2)) return null;
+  if (!filter2 || !isPlainObject16(filter2) || isEmpty2(filter2)) return null;
   if (!isAndFilter(filter2)) {
     return filter2;
   }
@@ -4969,7 +5296,7 @@ async function setRequestPermissions(req) {
   const globalPermissions = getGlobalOption("globalPermissions");
   if (!isFunction4(globalPermissions)) return;
   const permissions = await globalPermissions.call(req, req);
-  if (isPlainObject15(permissions)) req[requestPermissionField] = permissions;
+  if (isPlainObject16(permissions)) req[requestPermissionField] = permissions;
   else if (isArray10(permissions)) req[requestPermissionField] = arrayToRecord(permissions);
   else if (isString5(permissions)) req[requestPermissionField] = { [permissions]: true };
   owners.set(requestPermissionField, activeRuntime);
@@ -5189,6 +5516,7 @@ async function resolveSelectForRequest({
 }
 
 // src/core.ts
+var emptyPermissionLeaf = () => ({ $: "_" });
 var Core = class {
   constructor(req) {
     this.cachedPermissions = null;
@@ -5392,7 +5720,7 @@ var Core = class {
   }
   addEmptyPermissions(modelName, doc) {
     const docPermissionField = getModelOption(modelName, "documentPermissionField");
-    setDocValue(doc, docPermissionField, { _view: { $: "_" }, _edit: { $: "_" } });
+    setDocValue(doc, docPermissionField, { _view: emptyPermissionLeaf(), _edit: emptyPermissionLeaf() });
     return doc;
   }
   async addDocPermissions(modelName, doc, access, context) {
@@ -5442,8 +5770,8 @@ var Core = class {
       },
       {}
     );
-    setDocValue(doc, `${docPermissionField}._view`, viewObj);
-    setDocValue(doc, `${docPermissionField}._edit`, editObj);
+    setDocValue(doc, `${docPermissionField}._view`, Object.keys(viewObj).length > 0 ? viewObj : emptyPermissionLeaf());
+    setDocValue(doc, `${docPermissionField}._edit`, Object.keys(editObj).length > 0 ? editObj : emptyPermissionLeaf());
     return doc;
   }
   async decorate(modelName, doc, access, context) {
@@ -5582,12 +5910,12 @@ function guard(condition) {
     const permissions = req[PERMISSIONS];
     let cond = condition;
     let phas = (key) => permissions.has(key);
-    if (isPlainObject16(condition)) {
+    if (isPlainObject17(condition)) {
       const { modelName, id, condition: _cond } = condition;
       const svc = req.macl.getPublicService(modelName);
       const select = getModelOption(modelName, `alwaysSelectFields.read`, void 0);
       let _id = isString7(id) ? id : null;
-      if (isPlainObject16(id)) {
+      if (isPlainObject17(id)) {
         const { type = "param", key } = id;
         if (type === "param") {
           const paramValue = req.params[key];
@@ -5629,7 +5957,7 @@ import express2 from "express";
 
 // src/routers/model-router.ts
 import JsonRouter5 from "@web-ts-toolkit/express-json-router";
-import { forEach as forEach8, isPlainObject as isPlainObject18, isString as isString8, isUndefined as isUndefined2, normalizeUrlPath as normalizeUrlPath2, padEnd } from "@web-ts-toolkit/utils";
+import { forEach as forEach8, isPlainObject as isPlainObject19, isString as isString8, isUndefined as isUndefined2, normalizeUrlPath as normalizeUrlPath3, padEnd } from "@web-ts-toolkit/utils";
 
 // src/routers/router-mutation.ts
 var MODEL_BUILD_TIME_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -5758,7 +6086,7 @@ import JsonRouter4 from "@web-ts-toolkit/express-json-router";
 
 // src/validation/common.ts
 import { z as z2 } from "zod";
-import { isPlainObject as isPlainObject17 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject18 } from "@web-ts-toolkit/utils";
 var stringOrStringArray = z2.union([z2.string(), z2.array(z2.string())]);
 var safeIntegerString = (min, message) => z2.string().regex(/^\d+$/, message).refine((value) => Number.isSafeInteger(Number(value)), "Expected a safe integer").refine((value) => Number(value) >= min, message);
 var queryBooleanString = z2.enum(["true", "false"]);
@@ -5858,7 +6186,7 @@ var correlatedFilterSchema = z2.record(z2.string(), z2.unknown()).superRefine((f
   }
 });
 var correlatedEmptyOptionsSchema = z2.unknown().refine(
-  (value) => value === void 0 || isPlainObject17(value) && Object.keys(value).length === 0,
+  (value) => value === void 0 || isPlainObject18(value) && Object.keys(value).length === 0,
   "Correlated include options must be absent or empty"
 ).optional();
 var correlatedPathSchema = z2.string().min(1).superRefine((path, ctx) => {
@@ -5895,7 +6223,7 @@ var correlatedListArgsSchema = z2.object({
   include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
 }).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
 var correlatedCountArgsSchema = z2.unknown().refine(
-  (value) => value === void 0 || isPlainObject17(value) && Object.keys(value).length === 0,
+  (value) => value === void 0 || isPlainObject18(value) && Object.keys(value).length === 0,
   "Count includes accept no args"
 ).optional();
 var correlatedReadByIdSchema = z2.object({
@@ -5945,7 +6273,7 @@ var correlatedNestedIncludeSchema = z2.union([includeItemSchema, z2.array(includ
 var rejectDuplicateCorrelatedPaths = (items, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   items.forEach((item, index) => {
-    if (isPlainObject17(item) && item.mode === "correlated" && typeof item.path === "string") {
+    if (isPlainObject18(item) && item.mode === "correlated" && typeof item.path === "string") {
       if (seen.has(item.path)) {
         ctx.addIssue({
           code: z2.ZodIssueCode.custom,
@@ -6144,19 +6472,12 @@ function fromJoi(schema) {
 }
 function fromAjv(validator) {
   return async (value) => {
-    const outcome = validator(value);
-    if (isThenable(outcome)) {
+    if (validator.$async === true) {
       try {
-        const data = await outcome;
-        if (data === false) {
-          return {
-            success: false,
-            issues: normalizeAjvIssues(validator.errors ?? [])
-          };
-        }
+        const data = await validator(value);
         return {
           success: true,
-          data: data === true ? value : data
+          data
         };
       } catch (error2) {
         if (!isAjvValidationError(error2)) {
@@ -6164,11 +6485,21 @@ function fromAjv(validator) {
         }
         return {
           success: false,
-          issues: normalizeAjvIssues(error2.errors ?? [])
+          issues: normalizeAjvIssues(error2.errors)
         };
       }
     }
-    const errorsSnapshot = validator.errors ? [...validator.errors] : [];
+    const outcome = validator(value);
+    if (isThenable(outcome)) {
+      void Promise.resolve(outcome).catch(() => {
+      });
+      throw new TypeError(
+        "fromAjv: promise/thenable validators must declare $async: true and resolve with validated data"
+      );
+    }
+    if (typeof outcome !== "boolean") {
+      throw new TypeError("fromAjv: synchronous validators must return a boolean verdict");
+    }
     if (outcome) {
       return {
         success: true,
@@ -6177,7 +6508,9 @@ function fromAjv(validator) {
     }
     return {
       success: false,
-      issues: normalizeAjvIssues(errorsSnapshot)
+      // Normalize immediately, copying message/path before another call can
+      // replace the errors array or mutate its entries.
+      issues: normalizeAjvIssues(validator.errors ?? [])
     };
   };
 }
@@ -6407,14 +6740,14 @@ function isArkTypeErrors(value) {
   return record.arkKind === "errors" || record[" arkKind"] === "errors";
 }
 function isThenable(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+  return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";
 }
 function isAjvValidationError(error2) {
   if (typeof error2 !== "object" || error2 === null || !("errors" in error2)) {
     return false;
   }
-  const errors = error2.errors;
-  return errors == null || Array.isArray(errors);
+  const candidate = error2;
+  return candidate.ajv === true && candidate.validation === true && Array.isArray(candidate.errors);
 }
 function isVineValidationError(error2) {
   if (typeof error2 !== "object" || error2 === null || !("messages" in error2)) {
@@ -7507,11 +7840,11 @@ function setModelSubDocumentRoutes(context) {
 }
 
 // src/openapi/route-registration.ts
-import { normalizeUrlPath } from "@web-ts-toolkit/utils";
+import { normalizeUrlPath as normalizeUrlPath2 } from "@web-ts-toolkit/utils";
 function registerOpenApiRoute(runtime, basePath, defaultTag, route) {
   runtime.registerOpenApiRoute({
     ...route,
-    path: normalizeUrlPath(basePath + route.path),
+    path: normalizeUrlPath2(basePath + route.path),
     tags: route.tags ?? [defaultTag]
   });
 }
@@ -7682,7 +8015,7 @@ var ModelRouter = class _ModelRouter {
     this.runtime = runtime;
     this.runtime.setModelOptions(modelName, initialOptions);
     this.options = this.runtime.getModelOptions(modelName);
-    this.fullBasePath = normalizeUrlPath2(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = normalizeUrlPath3(this.options.parentPath + this.options.basePath);
     this.modelName = modelName;
     this.router = new JsonRouter5(this.options.basePath, createSetCore(this.runtime), accessRouterResponseHandler);
     this.model = new model_default(modelName, this.runtime);
@@ -7763,7 +8096,7 @@ var ModelRouter = class _ModelRouter {
   logEndpoints() {
     runWithRuntime(this.runtime, () => {
       forEach8(this.router.getEndpoints(), ({ method, path }) => {
-        logInfoMessage(`${padEnd(method, 6)} ${normalizeUrlPath2(this.options.parentPath + path)}`);
+        logInfoMessage(`${padEnd(method, 6)} ${normalizeUrlPath3(this.options.parentPath + path)}`);
       });
     });
   }
@@ -7776,7 +8109,7 @@ var ModelRouter = class _ModelRouter {
         value
       );
     }
-    if (arguments.length === 1 && isPlainObject18(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject19(keyOrOptions)) {
       assertMutableRouterOptions("model", keyOrOptions);
       this.runtime.setModelOptions(this.modelName, keyOrOptions);
     }
@@ -7799,7 +8132,7 @@ var ModelRouter = class _ModelRouter {
 
 // src/routers/root-router.ts
 import JsonRouter6 from "@web-ts-toolkit/express-json-router";
-import { isNumber as _isNumber, normalizeUrlPath as normalizeUrlPath3, orderBy as _orderBy } from "@web-ts-toolkit/utils";
+import { isNumber as _isNumber, normalizeUrlPath as normalizeUrlPath4, orderBy as _orderBy } from "@web-ts-toolkit/utils";
 
 // src/core-data.ts
 var DataCore = class {
@@ -8065,7 +8398,7 @@ var RootRouter = class {
     this.setRoutes();
   }
   registerOpenApiRoute(route) {
-    registerOpenApiRoute(this.runtime, normalizeUrlPath3(this.basename), "root", route);
+    registerOpenApiRoute(this.runtime, normalizeUrlPath4(this.basename), "root", route);
   }
   wrapResult(index, item, result) {
     return {
@@ -8215,7 +8548,7 @@ var RootRouter = class {
 
 // src/routers/data-router.ts
 import JsonRouter7 from "@web-ts-toolkit/express-json-router";
-import { isPlainObject as isPlainObject19, isString as isString9, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath4 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject20, isString as isString9, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath5 } from "@web-ts-toolkit/utils";
 var clientErrors4 = JsonRouter7.clientErrors;
 function setOption2(parentKey, optionKey, option) {
   const key = isUndefined3(option) ? parentKey : `${parentKey}.${optionKey}`;
@@ -8260,7 +8593,7 @@ var DataRouter = class {
     this.runtime = runtime;
     this.runtime.setDataOptions(dataName, initialOptions);
     this.options = this.runtime.getDataOptions(dataName);
-    this.fullBasePath = normalizeUrlPath4(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = normalizeUrlPath5(this.options.parentPath + this.options.basePath);
     this.dataName = dataName;
     this.router = new JsonRouter7(this.options.basePath, createSetDataCore(this.runtime), accessRouterResponseHandler);
     this.setCollectionRoutes();
@@ -8416,7 +8749,7 @@ var DataRouter = class {
       assertMutableRouterOption("data", keyOrOptions);
       this.runtime.setDataOption(this.dataName, keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject19(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject20(keyOrOptions)) {
       assertMutableRouterOptions("data", keyOrOptions);
       this.runtime.setDataOptions(this.dataName, keyOrOptions);
     }
@@ -8563,7 +8896,7 @@ function createRuntimeApi(runtime) {
     if (arguments.length === 2 && isString10(keyOrOptions)) {
       return runtime.setGlobalOption(keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject20(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject21(keyOrOptions)) {
       return runtime.setGlobalOptions(keyOrOptions);
     }
   };