@web-ts-toolkit/access-router 0.44.0 → 0.46.0

package/index.mjs

@@ -1,16 +1,16 @@
 // src/index.ts
-import { isPlainObject as isPlainObject18, 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 isArray11, isFunction as isFunction6, isPlainObject as isPlainObject15, 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 {
   castArray as castArray4,
   compact as compact3,
   forEach as forEach7,
-  isArray as isArray10,
+  isArray as isArray11,
   isBoolean as isBoolean5,
   isFunction as isFunction5,
   isString as isString6,
@@ -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
@@ -943,7 +965,9 @@ var defaultRequestComplexity = {
   maxIncludeCount: 10,
   maxSubQueryCount: 10,
   maxBulkConcurrency: 10,
-  maxHookConcurrency: 10
+  maxHookConcurrency: 10,
+  maxCorrelatedQueries: 100,
+  maxCorrelatedDepth: 5
 };
 var normalizePositiveInteger = (value, fallback) => {
   return Number.isSafeInteger(value) && Number(value) > 0 ? Number(value) : fallback;
@@ -963,6 +987,14 @@ var resolveRequestComplexity = (options) => ({
   maxHookConcurrency: normalizePositiveInteger(
     options?.maxHookConcurrency,
     defaultRequestComplexity.maxHookConcurrency
+  ),
+  maxCorrelatedQueries: normalizePositiveInteger(
+    options?.maxCorrelatedQueries,
+    defaultRequestComplexity.maxCorrelatedQueries
+  ),
+  maxCorrelatedDepth: normalizePositiveInteger(
+    options?.maxCorrelatedDepth,
+    defaultRequestComplexity.maxCorrelatedDepth
   )
 });
 function validateRequestComplexity(value, options, scope = "request") {
@@ -1155,6 +1187,7 @@ var AccessRuntime = class {
     this.modelAtts = {};
     this.modelInstances = {};
     this.openApiRegistry = new OpenApiRegistry();
+    this.openApiPathPrefix = "";
     this.allowGlobalModelLookup = options.allowGlobalModelLookup ?? false;
     ensureMongooseJsonSchemaInitialized();
   }
@@ -1183,7 +1216,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
@@ -1550,14 +1600,493 @@ var getModelRef = (modelName, refPath) => {
 // src/services/base.ts
 import {
   castArray,
+  cloneDeep as cloneDeep2,
   compact,
   flatten,
   forEach as forEach3,
   get as get4,
-  isArray as isArray6,
-  isPlainObject as isPlainObject11,
+  isArray as isArray7,
+  isPlainObject as isPlainObject12,
+  set as set3,
   uniq
 } from "@web-ts-toolkit/utils";
+
+// src/correlated-includes.ts
+import { cloneDeep, isArray as isArray6, isPlainObject as isPlainObject11 } from "@web-ts-toolkit/utils";
+var PARENT_MARKER_KEY = "$parent";
+var ESCAPE_WRAPPER_KEY = "$escape";
+var SUBQUERY_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["$$sq", "$$date"]);
+var MARKER_FORBIDDEN_OPERATOR_KEYS = /* @__PURE__ */ new Set(["$text", "$where", "$comment"]);
+var LOGICAL_CLAUSE_KEYS = /* @__PURE__ */ new Set(["$and", "$or", "$nor"]);
+var DANGEROUS_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var FIELD_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var ARRAY_INDEX_SEGMENT_PATTERN = /^(0|[1-9]\d*)$/;
+var ownKeys = (value) => Object.keys(value);
+function isParentRefMarker(value) {
+  return isPlainObject11(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
+}
+function isEscapedParentRef(value) {
+  return isPlainObject11(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === ESCAPE_WRAPPER_KEY;
+}
+function hasMarkerKey(value) {
+  return ownKeys(value).includes(PARENT_MARKER_KEY) || ownKeys(value).includes(ESCAPE_WRAPPER_KEY);
+}
+function isValidParentRefPath(path) {
+  if (typeof path !== "string" || path.length === 0) return false;
+  const segments = path.split(".");
+  return segments.every(
+    (segment) => (FIELD_SEGMENT_PATTERN.test(segment) || ARRAY_INDEX_SEGMENT_PATTERN.test(segment)) && !DANGEROUS_PATH_SEGMENTS.has(segment)
+  );
+}
+function isValidCorrelatedOutputPath(path) {
+  return typeof path === "string" && path.length > 0 && isValidFieldPath(path) && path !== "_id" && !path.startsWith("$");
+}
+function containsParentMarkerShape(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (current) => {
+    if (isParentRefMarker(current) || isEscapedParentRef(current)) return true;
+    if (isArray6(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      return current.some(visit);
+    }
+    if (isPlainObject11(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      if (hasMarkerKey(current)) return true;
+      return Object.values(current).some(visit);
+    }
+    return false;
+  };
+  return visit(value);
+}
+function scanTemplateValueNode(value, path, issues) {
+  if (isEscapedParentRef(value)) {
+    const inner = value.$escape;
+    if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
+      issues.push({
+        message: 'Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }',
+        path
+      });
+    }
+    return;
+  }
+  if (isParentRefMarker(value)) {
+    if (!isValidParentRefPath(value.$parent)) {
+      issues.push({
+        message: `Invalid $parent reference path at ${path.length === 0 ? "#" : path.join(".")}`,
+        path
+      });
+    }
+    return;
+  }
+  if (isPlainObject11(value)) {
+    if (hasMarkerKey(value)) {
+      issues.push({
+        message: 'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }',
+        path
+      });
+      return;
+    }
+    scanTemplateObjectEntries(value, path, issues);
+    return;
+  }
+  if (isArray6(value)) {
+    value.forEach((item, index) => scanTemplateValueNode(item, [...path, index], issues));
+  }
+}
+function scanTemplateObjectEntries(obj, basePath, issues) {
+  for (const [key, child] of Object.entries(obj)) {
+    const childPath = [...basePath, key];
+    if (key === PARENT_MARKER_KEY) {
+      issues.push({ message: "$parent is never a field name in correlated templates", path: childPath });
+      continue;
+    }
+    if (SUBQUERY_PAYLOAD_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in subquery payloads`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in ${key} values`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (key === "$elemMatch") {
+      if (isParentRefMarker(child) || isEscapedParentRef(child)) {
+        issues.push({
+          message: "Unsupported $parent reference as a direct $elemMatch value",
+          path: childPath
+        });
+        continue;
+      }
+      scanTemplateValueNode(child, childPath, issues);
+      continue;
+    }
+    if (LOGICAL_CLAUSE_KEYS.has(key)) {
+      if (!isArray6(child)) {
+        scanTemplateValueNode(child, childPath, issues);
+        continue;
+      }
+      child.forEach((clause, index) => {
+        const clausePath = [...childPath, index];
+        if (isParentRefMarker(clause) || isEscapedParentRef(clause)) {
+          issues.push({
+            message: `Unsupported $parent reference as a direct ${key} clause: clauses must be filter objects`,
+            path: clausePath
+          });
+          return;
+        }
+        if (isPlainObject11(clause)) {
+          scanTemplateObjectEntries(clause, clausePath, issues);
+        }
+      });
+      continue;
+    }
+    scanTemplateValueNode(child, childPath, issues);
+  }
+}
+function validateCorrelatedFilterTemplate(filter2) {
+  const issues = [];
+  if (!isPlainObject11(filter2)) {
+    issues.push({ message: "Correlated include filter must be an object", path: [] });
+    return issues;
+  }
+  if (isParentRefMarker(filter2) || isEscapedParentRef(filter2)) {
+    issues.push({ message: "Correlated include filter must not itself be a $parent reference", path: [] });
+    return issues;
+  }
+  scanTemplateObjectEntries(filter2, [], issues);
+  return issues;
+}
+function validateCorrelatedIdTemplate(id) {
+  if (typeof id === "string") {
+    return id.length > 0 ? [] : [{ message: "Correlated include id must be a non-empty string or $parent reference", path: [] }];
+  }
+  if (isEscapedParentRef(id)) {
+    return [{ message: "Unsupported $escape as a correlated include id", path: [] }];
+  }
+  if (isParentRefMarker(id)) {
+    return isValidParentRefPath(id.$parent) ? [] : [{ message: "Invalid $parent reference path in correlated include id", path: [] }];
+  }
+  return [{ message: "Correlated include id must be a string or $parent reference", path: [] }];
+}
+function findArgsMarkerIssue(value, where) {
+  if (value !== void 0 && containsParentMarkerShape(value)) {
+    return {
+      message: `Unsupported $parent reference in ${where}: references are only supported in filter and id positions`,
+      path: []
+    };
+  }
+  return null;
+}
+function collectFilterReferencePaths(filter2) {
+  const paths = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visitValue = (value) => {
+    if (isParentRefMarker(value)) {
+      if (typeof value.$parent === "string") {
+        paths.push(value.$parent);
+      }
+      return;
+    }
+    if (isEscapedParentRef(value)) return;
+    if (isArray6(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
+      value.forEach(visitValue);
+      return;
+    }
+    if (isPlainObject11(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
+      for (const [key, child] of Object.entries(value)) {
+        if (SUBQUERY_PAYLOAD_KEYS.has(key) || MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) continue;
+        visitValue(child);
+      }
+    }
+  };
+  visitValue(filter2);
+  return paths;
+}
+function collectCorrelatedReferencePaths(include) {
+  const paths = [];
+  if (isParentRefMarker(include.id) && typeof include.id !== "string") {
+    const ref = include.id;
+    if (typeof ref.$parent === "string") paths.push(ref.$parent);
+  } else if (typeof include.id === "string") {
+  }
+  const filter2 = include.filter;
+  if (filter2 !== void 0) {
+    paths.push(...collectFilterReferencePaths(filter2));
+  }
+  return [...new Set(paths)];
+}
+var CorrelatedReferenceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CorrelatedReferenceError";
+  }
+};
+var UNRESOLVABLE = /* @__PURE__ */ Symbol("correlated-include-unresolvable");
+function getOwnPathValue(parent, path) {
+  const segments = path.split(".");
+  let current = parent;
+  for (const segment of segments) {
+    if (DANGEROUS_PATH_SEGMENTS.has(segment)) {
+      throw new CorrelatedReferenceError(`Invalid $parent reference path: ${path}`);
+    }
+    if (typeof current !== "object" || current === null) return void 0;
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function cloneSubstitutedValue(value) {
+  if (isPlainObject11(value) || isArray6(value)) return cloneDeep(value);
+  return value;
+}
+function literalParentRefObject(path) {
+  const literal = {};
+  Object.defineProperty(literal, PARENT_MARKER_KEY, {
+    value: path,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+  return literal;
+}
+function resolveObjectEntries(obj, parent) {
+  const out = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === PARENT_MARKER_KEY) {
+      throw new CorrelatedReferenceError("$parent is never a field name in correlated templates");
+    }
+    if (SUBQUERY_PAYLOAD_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        throw new CorrelatedReferenceError(`Unsupported $parent reference inside ${key}`);
+      }
+      out[key] = cloneSubstitutedValue(child);
+      continue;
+    }
+    if (MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        throw new CorrelatedReferenceError(`Unsupported $parent reference inside ${key}`);
+      }
+      out[key] = cloneSubstitutedValue(child);
+      continue;
+    }
+    if (key === "$elemMatch") {
+      if (isParentRefMarker(child) || isEscapedParentRef(child)) {
+        throw new CorrelatedReferenceError("Unsupported $parent reference as a direct $elemMatch value");
+      }
+      out[key] = resolveValueNode(child, parent, false);
+      continue;
+    }
+    if (LOGICAL_CLAUSE_KEYS.has(key)) {
+      if (!isArray6(child)) {
+        out[key] = resolveValueNode(child, parent, false);
+        continue;
+      }
+      out[key] = child.map((clause) => {
+        if (isParentRefMarker(clause) || isEscapedParentRef(clause)) {
+          throw new CorrelatedReferenceError(`Unsupported $parent reference as a direct ${key} clause`);
+        }
+        if (!isPlainObject11(clause)) return cloneSubstitutedValue(clause);
+        return resolveObjectEntries(clause, parent);
+      });
+      continue;
+    }
+    if (key.startsWith("$")) {
+      out[key] = resolveValueNode(child, parent, false);
+      continue;
+    }
+    out[key] = resolveValueNode(child, parent, true);
+  }
+  return out;
+}
+function resolveValueNode(template, parent, bare) {
+  if (isEscapedParentRef(template)) {
+    const inner = template.$escape;
+    if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
+      throw new CorrelatedReferenceError('Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }');
+    }
+    const literal = literalParentRefObject(inner.$parent);
+    return bare ? { $eq: literal } : literal;
+  }
+  if (isParentRefMarker(template)) {
+    const path = template.$parent;
+    if (!isValidParentRefPath(path)) {
+      throw new CorrelatedReferenceError(`Invalid $parent reference path: ${String(path)}`);
+    }
+    const value = getOwnPathValue(parent, path);
+    if (value === void 0 || value === null) throw UNRESOLVABLE;
+    if (bare && isPlainObject11(value)) return { $eq: cloneDeep(value) };
+    return cloneSubstitutedValue(value);
+  }
+  if (isPlainObject11(template)) {
+    if (hasMarkerKey(template)) {
+      throw new CorrelatedReferenceError(
+        'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }'
+      );
+    }
+    return resolveObjectEntries(template, parent);
+  }
+  if (isArray6(template)) {
+    return template.map((item) => resolveValueNode(item, parent, false));
+  }
+  return template;
+}
+function isUnresolvableSignal(error2) {
+  return error2 === UNRESOLVABLE;
+}
+function resolveCorrelatedIdTemplate(id, parent) {
+  try {
+    if (typeof id === "string") {
+      if (id.length === 0) throw new CorrelatedReferenceError("Correlated include id must be a non-empty string");
+      return { status: "resolved", id };
+    }
+    if (isParentRefMarker(id)) {
+      const path = id.$parent;
+      if (!isValidParentRefPath(path)) {
+        throw new CorrelatedReferenceError(`Invalid $parent reference path: ${String(path)}`);
+      }
+      const value = getOwnPathValue(parent, path);
+      if (typeof value === "string") return { status: "resolved", id: value };
+      if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return { status: "resolved", id: String(value) };
+      }
+      throw UNRESOLVABLE;
+    }
+    throw new CorrelatedReferenceError("Correlated include id must be a string or $parent reference");
+  } catch (error2) {
+    if (isUnresolvableSignal(error2)) return { status: "unresolvable" };
+    throw error2;
+  }
+}
+function resolveCorrelatedFilterTemplate(filter2, parent) {
+  try {
+    if (!isPlainObject11(filter2) || isParentRefMarker(filter2) || isEscapedParentRef(filter2)) {
+      throw new CorrelatedReferenceError("Correlated include filter must be an object");
+    }
+    return { status: "resolved", filter: resolveObjectEntries(filter2, parent) };
+  } catch (error2) {
+    if (isUnresolvableSignal(error2)) return { status: "unresolvable" };
+    throw error2;
+  }
+}
+function validateExpandedCorrelatedOperands(expanded, limits) {
+  return validateRequestComplexity(expanded, limits ?? null, "filter");
+}
+var MAX_NESTED_INCLUDE_DEPTH = 10;
+function validateCorrelatedArgsShape(args, op, depth) {
+  if (args === void 0) return [];
+  if (!isPlainObject11(args)) return ["Correlated include args must be an object"];
+  const record = args;
+  const allowed = op === "list" ? /* @__PURE__ */ new Set(["select", "sort", "skip", "limit", "page", "pageSize", "include"]) : /* @__PURE__ */ new Set(["select", "sort", "include"]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) return [`Unsupported correlated include arg: ${key}`];
+  }
+  if (op === "count" && Object.keys(record).length > 0) return ["Count includes accept no args"];
+  const selectIssue = findArgsMarkerIssue(record.select, "args.select");
+  if (selectIssue) return [selectIssue.message];
+  const sortIssue = findArgsMarkerIssue(record.sort, "args.sort");
+  if (sortIssue) return [sortIssue.message];
+  if (record.include !== void 0) {
+    if (depth >= MAX_NESTED_INCLUDE_DEPTH) return ["Correlated include nesting exceeds the supported depth"];
+    const nested = Array.isArray(record.include) ? record.include : [record.include];
+    for (const entry of nested) {
+      const errors = validateCorrelatedIncludeShape(entry, depth + 1);
+      if (errors.length > 0) return errors;
+    }
+  }
+  return [];
+}
+function validateCorrelatedIncludeShape(entry, depth = 0) {
+  if (!isPlainObject11(entry)) return ["Correlated include must be an object"];
+  const record = entry;
+  if (record.mode !== "correlated") return ['Correlated include mode must be "correlated"'];
+  if (typeof record.model !== "string" || record.model.length === 0)
+    return ["Correlated include model must be a non-empty string"];
+  if (record.op !== "list" && record.op !== "read" && record.op !== "count") {
+    return ['Correlated include op must be one of "list", "read", or "count"'];
+  }
+  if (!isValidCorrelatedOutputPath(record.path))
+    return [`Invalid correlated include output path: ${String(record.path)}`];
+  if ("localField" in record || "foreignField" in record) {
+    return ["Correlated includes must not carry localField or foreignField"];
+  }
+  if (record.options !== void 0 && !(isPlainObject11(record.options) && Object.keys(record.options).length === 0)) {
+    return ["Correlated include options must be absent or empty"];
+  }
+  const hasId = record.id !== void 0;
+  const hasFilter = record.filter !== void 0;
+  if (record.op === "read") {
+    if (hasId === hasFilter) return ['Correlated read includes require exactly one of "id" or "filter"'];
+    if (hasId) {
+      const issues = validateCorrelatedIdTemplate(record.id);
+      if (issues.length > 0) return [issues[0].message];
+    } else {
+      const issues = validateCorrelatedFilterTemplate(record.filter);
+      if (issues.length > 0) return [issues[0].message];
+    }
+  } else {
+    if (!hasFilter || hasId) return [`Correlated ${record.op} includes require a filter and no id`];
+    const issues = validateCorrelatedFilterTemplate(record.filter);
+    if (issues.length > 0) return [issues[0].message];
+  }
+  return validateCorrelatedArgsShape(record.args, record.op, depth);
+}
+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
+function getCorrelatedTemplateDepth(includes) {
+  let max = 0;
+  const visit = (entries, depth) => {
+    const list = castArray(entries).filter(Boolean);
+    for (const entry of list) {
+      if (!isPlainObject12(entry)) continue;
+      max = Math.max(max, depth);
+      const nested = entry.args?.include;
+      if (nested !== void 0) {
+        visit(nested, depth + 1);
+      }
+    }
+  };
+  if (includes.length > 0) visit(includes, 1);
+  return max;
+}
 var ClientRequestError = class extends Error {
   constructor(result) {
     super(String(result.code));
@@ -1572,11 +2101,11 @@ function validateClientFilter(filter2) {
   }
   const blockedOperators = /* @__PURE__ */ new Set(["$where", "$expr", "$function", "$accumulator"]);
   const visit = (value, path) => {
-    if (isArray6(value)) {
+    if (isArray7(value)) {
       value.forEach((item, index) => visit(item, `${path}[${index}]`));
       return;
     }
-    if (!isPlainObject11(value)) return;
+    if (!isPlainObject12(value)) return;
     Object.entries(value).forEach(([key, child]) => {
       const nextPath = path ? `${path}.${key}` : key;
       if (blockedOperators.has(key)) {
@@ -1591,6 +2120,7 @@ function validateClientFilter(filter2) {
 }
 var Base = class {
   constructor(req, modelName) {
+    this.requestRuntime = getActiveRuntime() ?? defaultRuntime;
     this.req = req;
     this.modelName = modelName;
   }
@@ -1696,23 +2226,88 @@ var Base = class {
     return this.req.macl.getPublicService(modelName);
   }
   processInclude(include) {
-    const includes = compact(castArray(include)).filter(({ model, op, path, localField, foreignField }) => {
-      return model && op && path && localField && foreignField;
-    });
+    const items = compact(castArray(include));
+    const legacy = [];
+    const correlated = [];
+    const correlatedReferenceFields = [];
+    for (const entry of items) {
+      if (isCorrelatedInclude(entry)) {
+        const shapeErrors = validateCorrelatedIncludeShape(entry);
+        if (shapeErrors.length > 0) {
+          this.throwClientRequestError("bad_request" /* BadRequest */, shapeErrors[0]);
+        }
+        correlated.push(entry);
+        correlatedReferenceFields.push(...collectCorrelatedReferencePaths(entry));
+        continue;
+      }
+      if (containsParentMarkerShape(entry)) {
+        this.throwClientRequestError(
+          "bad_request" /* BadRequest */,
+          'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")'
+        );
+      }
+      const candidate = entry;
+      if (candidate.model && candidate.op && candidate.path && candidate.localField && candidate.foreignField) {
+        legacy.push(entry);
+      }
+    }
+    const seenCorrelatedPaths = /* @__PURE__ */ new Set();
+    for (const entry of correlated) {
+      if (seenCorrelatedPaths.has(entry.path)) {
+        this.throwClientRequestError("bad_request" /* BadRequest */, `Duplicate correlated include output path: ${entry.path}`);
+      }
+      seenCorrelatedPaths.add(entry.path);
+    }
+    this.assertIncludeOutputPaths([...legacy, ...correlated]);
     let includeLocalFields = [];
     let includePaths = [];
-    forEach3(includes, (inc) => {
+    forEach3(legacy, (inc) => {
       includeLocalFields.push(inc.localField);
       includePaths.push(inc.path);
     });
     includeLocalFields = uniq(compact(includeLocalFields));
     includePaths = uniq(compact(includePaths));
     return {
-      includes,
+      includes: legacy,
+      correlatedIncludes: correlated,
       includeLocalFields,
-      includePaths
+      includePaths,
+      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));
   }
@@ -1753,7 +2348,7 @@ var Base = class {
     return ids.size;
   }
   sanitizeIncludeArgs(args) {
-    if (!isPlainObject11(args)) return {};
+    if (!isPlainObject12(args)) return {};
     const { overrides: _clientOverrides, ...trustedArgs } = args;
     return trustedArgs;
   }
@@ -1766,10 +2361,16 @@ var Base = class {
     if (!include) return docs;
     const includes = compact(castArray(include));
     if (includes.length === 0) return docs;
-    const isSingle = !isArray6(docs);
+    const isSingle = !isArray7(docs);
     let docList = isSingle ? [docs] : docs;
     for (let x = 0; x < includes.length; x++) {
       const include2 = includes[x];
+      if (isCorrelatedInclude(include2)) {
+        this.throwClientRequestError(
+          "bad_request" /* BadRequest */,
+          "Correlated includes are not supported by the legacy include executor"
+        );
+      }
       this.assertIncludeForeignField(include2);
       switch (include2.op) {
         case "count":
@@ -1819,34 +2420,376 @@ var Base = class {
       overrides: {
         filter: authorizedFilter
       }
-    };
-    const trustedOptions = {
-      ...options,
-      lean: true,
-      includePermissions: false,
-      includeCount: false
-    };
-    const trustedResult = await svc.find(filter2, trustedArgs, trustedOptions);
-    if (!trustedResult.success) return docs;
-    const index = this.buildForeignKeyIndex(trustedResult.data, foreignField);
-    for (let y = 0; y < docs.length; y++) {
-      const doc = docs[y];
-      const matches = this.getIndexedMatches(index, get4(doc, localField));
-      setDocValue(doc, path, op === "list" ? matches : matches[0]);
-    }
-    return docs;
-  }
-  async includeDocsCount(docs, include) {
-    const { model, path, localField, foreignField, filter: _filters } = include;
-    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) return docs;
-    for (let y = 0; y < docs.length; y++) {
-      const doc = docs[y];
-      setDocValue(doc, path, this.getIndexedCount(result.data, get4(doc, localField)));
-    }
-    return docs;
+    };
+    const trustedOptions = {
+      ...options,
+      lean: true,
+      includePermissions: false,
+      includeCount: false
+    };
+    const trustedResult = await svc.find(filter2, trustedArgs, trustedOptions);
+    if (!trustedResult.success) return docs;
+    const index = this.buildForeignKeyIndex(trustedResult.data, foreignField);
+    for (let y = 0; y < docs.length; y++) {
+      const doc = docs[y];
+      const matches = this.getIndexedMatches(index, get4(doc, localField));
+      setDocValue(doc, path, op === "list" ? matches : matches[0]);
+    }
+    return docs;
+  }
+  async includeDocsCount(docs, include) {
+    const { model, path, localField, foreignField, filter: _filters } = include;
+    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];
+      setDocValue(doc, path, this.getIndexedCount(result.data, get4(doc, localField)));
+    }
+    return docs;
+  }
+  getCorrelatedExecState() {
+    return getRequestWorkState(this.req, this.requestRuntime);
+  }
+  claimCorrelatedQuerySlot() {
+    const limits = this.getRequestComplexity();
+    const state = this.getCorrelatedExecState();
+    if (state.totalQueries >= limits.maxCorrelatedQueries) {
+      this.throwClientRequestError(
+        "bad_request" /* BadRequest */,
+        `Correlated include query budget exceeded (max ${limits.maxCorrelatedQueries})`
+      );
+    }
+    state.totalQueries += 1;
+  }
+  sanitizeCorrelatedArgs(include) {
+    const args = include.args ?? {};
+    if (include.op === "list") {
+      const { select: select2, sort: sort2, skip, limit, page, pageSize, include: nestedInclude2 } = args;
+      return { select: select2, sort: sort2, skip, limit, page, pageSize, nestedInclude: nestedInclude2 };
+    }
+    const { select, sort, include: nestedInclude } = args;
+    return { select, sort, nestedInclude };
+  }
+  async includeCorrelatedDocs(docs, correlatedIncludes, snapshots, depth = 0) {
+    if (correlatedIncludes.length === 0) return docs;
+    const limits = this.getRequestComplexity();
+    const templateDepth = getCorrelatedTemplateDepth(correlatedIncludes);
+    if (depth + templateDepth > limits.maxCorrelatedDepth) {
+      this.throwClientRequestError(
+        "bad_request" /* BadRequest */,
+        `Correlated include depth exceeded (max ${limits.maxCorrelatedDepth})`
+      );
+    }
+    const state = this.getCorrelatedExecState();
+    const resolvedSnapshots = snapshots ?? docs.map((doc) => cloneDeep2(toObject(doc)));
+    for (const include of correlatedIncludes) {
+      switch (include.op) {
+        case "read":
+          await this.includeCorrelatedRead(docs, include, resolvedSnapshots, state, depth);
+          break;
+        case "list":
+          await this.includeCorrelatedList(docs, include, resolvedSnapshots, state, depth);
+          break;
+        case "count":
+          await this.includeCorrelatedCount(docs, include, resolvedSnapshots, state, depth);
+          break;
+        default:
+          this.throwClientRequestError(
+            "bad_request" /* BadRequest */,
+            `Unsupported correlated include op: ${include.op}`
+          );
+      }
+    }
+    return docs;
+  }
+  async includeCorrelatedRead(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "read");
+    const { select, sort, nestedInclude } = this.sanitizeCorrelatedArgs(include);
+    const hasId = include.id !== void 0;
+    if (hasId) {
+      const idTemplate = include.id;
+      const tasks2 = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+      await state.scheduler.map(tasks2, async ({ index, snapshot }) => {
+        let resolution;
+        try {
+          resolution = resolveCorrelatedIdTemplate(idTemplate, snapshot);
+        } catch (error2) {
+          if (error2 instanceof CorrelatedReferenceError) {
+            throw new ClientRequestError({
+              success: false,
+              kind: "error",
+              code: "bad_request" /* BadRequest */,
+              errors: [{ detail: error2.message }]
+            });
+          }
+          throw error2;
+        }
+        if (resolution.status === "unresolvable") {
+          setDocValue(docs[index], include.path, null);
+          return;
+        }
+        const resolvedId = resolution.id;
+        let idFilter;
+        try {
+          idFilter = await svc.genIDFilter(resolvedId);
+        } catch (error2) {
+          const clientResult = this.getClientRequestErrorResult(error2);
+          if (clientResult) throw new ClientRequestError(clientResult);
+          throw error2;
+        }
+        const authorized = await svc.genFilter("read", idFilter);
+        if (authorized === false) {
+          throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+        }
+        this.claimCorrelatedQuerySlot();
+        let result;
+        try {
+          result = await svc.findOne(
+            {},
+            {
+              select,
+              sort,
+              include: nestedInclude,
+              overrides: { filter: authorized }
+            },
+            { access: "read", lean: true, includePermissions: false }
+          );
+        } catch (error2) {
+          const clientResult = this.getClientRequestErrorResult(error2);
+          if (clientResult) throw new ClientRequestError(clientResult);
+          throw error2;
+        }
+        if (result.success) {
+          setDocValue(docs[index], include.path, result.data);
+        } else if (result.code === "not_found" /* NotFound */) {
+          setDocValue(docs[index], include.path, null);
+        } else {
+          throw new ClientRequestError(result);
+        }
+      });
+      return;
+    }
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    let parsedTemplate;
+    try {
+      parsedTemplate = await this.parseClientData(
+        filterTemplate,
+        state.scheduler
+      );
+    } catch (error2) {
+      const clientResult = this.getClientRequestErrorResult(error2);
+      if (clientResult) throw new ClientRequestError(clientResult);
+      throw error2;
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(parsedTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, null);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("read", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.findOne(
+          {},
+          {
+            select,
+            sort,
+            include: nestedInclude,
+            overrides: { filter: authorized }
+          },
+          { access: "read", lean: true, includePermissions: false }
+        );
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else if (result.code === "not_found" /* NotFound */) {
+        setDocValue(docs[index], include.path, null);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
+  }
+  async includeCorrelatedList(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "list");
+    const { select, sort, skip, limit, page, pageSize, nestedInclude } = this.sanitizeCorrelatedArgs(include);
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    let parsedTemplate;
+    try {
+      parsedTemplate = await this.parseClientData(
+        filterTemplate,
+        state.scheduler
+      );
+    } catch (error2) {
+      const clientResult = this.getClientRequestErrorResult(error2);
+      if (clientResult) throw new ClientRequestError(clientResult);
+      throw error2;
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(parsedTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, []);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("list", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.find(
+          {},
+          {
+            select,
+            sort,
+            skip,
+            limit,
+            page,
+            pageSize,
+            include: nestedInclude,
+            overrides: { filter: authorized }
+          },
+          { includeCount: false, lean: true, includePermissions: false }
+        );
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
+  }
+  async includeCorrelatedCount(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "count");
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(filterTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, 0);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("count", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.countTrusted(authorized);
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
   }
   async parseClientData(filter2, scheduler = new RequestConcurrencyScheduler(this.getRequestComplexity().maxBulkConcurrency), scheduled = false) {
     const result = await iterateQuery(
@@ -1890,7 +2833,7 @@ var Base = class {
     }
     let ret = result.data;
     if (sqOptions.path) {
-      ret = isArray6(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
+      ret = isArray7(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
     }
     if (sqOptions.compact) {
       ret = compact(castArray(ret));
@@ -1907,8 +2850,9 @@ var Base = class {
 // src/services/service.ts
 import {
   castArray as castArray2,
+  cloneDeep as cloneDeep4,
   compact as compact2,
-  isArray as isArray7,
+  isArray as isArray8,
   isBoolean as isBoolean3,
   isFunction as isFunction3,
   omit,
@@ -1919,6 +2863,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;
@@ -1971,6 +2935,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);
@@ -1981,6 +2950,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",
@@ -2160,6 +3162,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);
@@ -2191,25 +3217,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 {
@@ -2222,24 +3247,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) {
@@ -2253,21 +3277,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);
@@ -2276,7 +3297,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) {
@@ -2411,7 +3432,39 @@ var assertModelDocument = (value, modelName, hookName) => {
   }
   throw new Error(`${hookName} hook for model=${modelName} must return a Mongoose document instance`);
 };
+var unsetDocPath = (doc, path) => {
+  const segments = path.split(".");
+  let current = doc;
+  const unwrap = (value) => value != null && typeof value === "object" && "_doc" in value ? value._doc : value;
+  current = unwrap(current);
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (current == null || typeof current !== "object") return;
+    if (!Object.prototype.hasOwnProperty.call(current, segments[i])) return;
+    current = unwrap(current[segments[i]]);
+  }
+  if (current != null && typeof current === "object") {
+    delete current[segments[segments.length - 1]];
+  }
+};
+var shouldKeepCorrelatedRef = (ref, keep) => {
+  if (keep.has(ref)) return true;
+  const top = ref.split(".")[0];
+  if (keep.has(top)) return true;
+  for (const kept of keep) {
+    if (kept === ref || kept.startsWith(`${ref}.`) || ref.startsWith(`${kept}.`)) return true;
+  }
+  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,
@@ -2449,14 +3502,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 };
@@ -2464,21 +3509,24 @@ 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, includeLocalFields, includePaths } = this.processInclude(include);
-    const finalSelect = normalizeSelect(_select).concat(includeLocalFields);
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = processedInclude;
+    const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
+    const finalSelect = normalizeSelect(_select).concat(includeLocalFields, correlatedReferenceFields);
     const query = {
       filter: _filter,
       select: finalSelect,
@@ -2511,8 +3559,14 @@ var Service = class extends Base {
       originalDocumentSnapshot: toObject(doc),
       resolvedQuery: query
     };
+    const correlatedSnapshots = [cloneDeep4(toObject(doc))];
     try {
       doc = await this.includeDocs(doc, includes);
+      if (correlatedIncludes.length > 0) {
+        const docList = [doc];
+        await this.includeCorrelatedDocs(docList, correlatedIncludes, correlatedSnapshots);
+        doc = docList[0];
+      }
     } catch (error2) {
       const result = this.getClientRequestErrorResult(error2);
       if (result) {
@@ -2530,8 +3584,20 @@ var Service = class extends Base {
     doc = await this.trimOutputFields(
       doc,
       access,
-      this.baseFieldsExt.concat(includePaths, normalizeSelect(overrideSelect))
+      this.baseFieldsExt.concat(includePaths, correlatedOutputPaths, normalizeSelect(overrideSelect))
     );
+    if (correlatedReferenceFields.length > 0) {
+      const keep = /* @__PURE__ */ new Set([
+        ...normalizeSelect(_select),
+        ...normalizeSelect(overrideSelect),
+        ...this.baseFieldsExt,
+        ...includePaths,
+        ...correlatedOutputPaths
+      ]);
+      for (const ref of correlatedReferenceFields) {
+        if (!shouldKeepCorrelatedRef(ref, keep)) unsetDocPath(doc, ref);
+      }
+    }
     if (!includePermissions) doc = this.addEmptyPermissions(doc);
     this.completeOp("findOne", startedAt, "success" /* Success */, _filter);
     return { success: true, kind: "single", code: "success" /* Success */, data: doc, query, context };
@@ -2540,7 +3606,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,
       {
@@ -2562,26 +3629,29 @@ 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),
       this.genAllowedFields({}, "list", this.baseFieldsExt)
     ]);
     const finalSelect = normalizeSelect(_select);
-    const filteredPopulate = isArray7(finalSelect) && isArray7(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
-    const { includes, includeLocalFields, includePaths } = this.processInclude(include);
+    const filteredPopulate = isArray8(finalSelect) && isArray8(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = processedInclude;
+    const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
     const query = {
       filter: _filter,
-      select: finalSelect.concat(includeLocalFields),
+      select: finalSelect.concat(includeLocalFields, correlatedReferenceFields),
       populate: filteredPopulate,
       sort,
       ...pagination
@@ -2590,7 +3660,7 @@ var Service = class extends Base {
       sort,
       skip: pagination.skip,
       limit: pagination.limit,
-      selectCount: finalSelect.concat(includeLocalFields).length,
+      selectCount: finalSelect.concat(includeLocalFields, correlatedReferenceFields).length,
       populateCount: Array.isArray(filteredPopulate) ? filteredPopulate.length : filteredPopulate ? 1 : 0
     });
     if (_filter === false) {
@@ -2615,8 +3685,12 @@ var Service = class extends Base {
       resolvedQuery: query
     }));
     const _decorate = isFunction3(decorate) ? decorate : (v) => v;
+    const correlatedSnapshots = docs.map((doc) => cloneDeep4(toObject(doc)));
     try {
       docs = await this.includeDocs(docs, includes);
+      if (correlatedIncludes.length > 0) {
+        docs = await this.includeCorrelatedDocs(docs, correlatedIncludes, correlatedSnapshots);
+      }
     } catch (error2) {
       const result = this.getClientRequestErrorResult(error2);
       if (result) {
@@ -2638,8 +3712,20 @@ var Service = class extends Base {
         doc = await this.trimOutputFields(
           doc,
           "list",
-          this.baseFieldsExt.concat(includePaths, normalizeSelect(overrideSelect))
+          this.baseFieldsExt.concat(includePaths, correlatedOutputPaths, normalizeSelect(overrideSelect))
         );
+        if (correlatedReferenceFields.length > 0) {
+          const keep = /* @__PURE__ */ new Set([
+            ...normalizeSelect(_select),
+            ...normalizeSelect(overrideSelect),
+            ...this.baseFieldsExt,
+            ...includePaths,
+            ...correlatedOutputPaths
+          ]);
+          for (const ref of correlatedReferenceFields) {
+            if (!shouldKeepCorrelatedRef(ref, keep)) unsetDocPath(doc, ref);
+          }
+        }
         doc = await _decorate(doc, contexts[i]);
         if (!includePermissions) doc = this.addEmptyPermissions(doc);
         return doc;
@@ -2724,7 +3810,7 @@ var Service = class extends Base {
           validationErrors.push({ index, errors: [] });
           return void 0;
         }
-      } else if (isArray7(validated)) {
+      } else if (isArray8(validated)) {
         if (validated.length > 0) {
           validationErrors.push({
             index,
@@ -2771,7 +3857,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);
@@ -2827,6 +3913,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 };
@@ -2834,7 +3927,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 };
@@ -2881,7 +3974,7 @@ var Service = class extends Base {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */ };
       }
-    } else if (isArray7(validated)) {
+    } else if (isArray8(validated)) {
       if (validated.length > 0) {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: validated };
@@ -2889,11 +3982,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(
@@ -2913,7 +4006,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);
@@ -2925,7 +4018,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,
@@ -2945,7 +4039,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) {
@@ -3005,7 +4099,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);
@@ -3016,6 +4112,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,
@@ -3068,6 +4165,30 @@ var Service = class extends Base {
     if (filter2 === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query };
     return { success: true, kind: "single", code: "success" /* Success */, data: await this.model.countDocuments(filter2), query };
   }
+  /**
+   * Trusted count for correlated includes (ACI-03): the caller already
+   * resolved parent references, revalidated expanded operands, and applied
+   * explicit `count` access via `genFilter`. This skips client-filter
+   * validation and subquery parsing so substituted parent data stays inert.
+   */
+  async countTrusted(authorizedFilter) {
+    const query = { filter: authorizedFilter };
+    if (authorizedFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */, query };
+    return {
+      success: true,
+      kind: "single",
+      code: "success" /* Success */,
+      data: await this.model.countDocuments(authorizedFilter),
+      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 {
@@ -3086,7 +4207,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 },
       {
@@ -3097,12 +4236,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 };
   }
@@ -3181,17 +4328,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);
@@ -3265,6 +4455,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) {
@@ -3305,6 +4496,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) {
@@ -3353,6 +4545,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") {
@@ -3583,29 +4780,64 @@ var DataService = class {
 };
 
 // src/processors.ts
-import { cloneDeep, forEach as forEach6, get as get7, isArray as isArray8, isPlainObject as isPlainObject13, 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"]);
-function failUnsafeSegment(path) {
+var DEFAULT_MAX_SLICE = 1e3;
+var DEFAULT_MASK_REPLACEMENT = "***";
+function failUnsafeSegment(path, fn = "copyAndDepopulate") {
   throw new Error(
-    `copyAndDepopulate: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
+    `${fn}: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
   );
 }
 function failMissingId(path) {
   throw new Error(`copyAndDepopulate: path '${path}' resolved to a record missing the configured id field.`);
 }
-function assertSafePath(path) {
+function failInvalidSlice(value, field, fn) {
+  throw new Error(`${fn}: '${field}' must be a non-negative safe integer, received ${String(value)}.`);
+}
+function assertSafePath(path, fn = "copyAndDepopulate") {
   const segs = path.split(".");
   for (const seg of segs) {
     if (seg.length === 0) continue;
     if (UNSAFE_PATH_KEYS.has(seg)) {
-      failUnsafeSegment(path);
+      failUnsafeSegment(path, fn);
     }
   }
 }
+function assertNonNegativeSafeInteger(value, field, fn) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    failInvalidSlice(value, field, fn);
+  }
+}
+function resolveLeafParents(obj, src) {
+  const segs = src.split(".");
+  let targets = [obj];
+  for (let ind = 0; ind < segs.length - 1; ind += 1) {
+    const seg = segs[ind];
+    targets = targets.reduce((ret, target) => {
+      if (!isPlainObject15(target)) return ret;
+      const targetObject = target;
+      const next = targetObject[seg];
+      if (isArray9(next)) {
+        for (const item of next) {
+          ret.push(item);
+        }
+      } else if (next !== null && next !== void 0) ret.push(next);
+      return ret;
+    }, []);
+  }
+  const leaf = segs[segs.length - 1];
+  const pairs = [];
+  forEach6(targets, (target) => {
+    if (!isPlainObject15(target)) return;
+    pairs.push({ parent: target, leaf });
+  });
+  return pairs;
+}
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
   const mutable = options.mutable !== false;
   const idField = options.idField ?? "_id";
-  const obj = mutable ? docObject : cloneDeep(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;
@@ -3618,15 +4850,15 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
     forEach6(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
         forEach6(targets, (target) => {
-          if (!isPlainObject13(target)) return;
+          if (!isPlainObject15(target)) return;
           const targetObject = target;
           const leaf = targetObject[seg];
           const sourceForDest = leaf;
           let depopulated;
-          if (isArray8(leaf)) {
+          if (isArray9(leaf)) {
             if (leaf.length === 0) {
               depopulated = [];
-            } else if (leaf.every((item) => isPlainObject13(item))) {
+            } else if (leaf.every((item) => isPlainObject15(item))) {
               depopulated = map(leaf, idField).map((id, i) => {
                 if (id === void 0) {
                   failMissingId(`${src}[${i}]`);
@@ -3636,7 +4868,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
             } else {
               return;
             }
-          } else if (isPlainObject13(leaf)) {
+          } else if (isPlainObject15(leaf)) {
             const id = get7(leaf, idField);
             if (id === void 0) {
               failMissingId(src);
@@ -3645,15 +4877,15 @@ 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 (!isPlainObject13(target)) return ret;
+          if (!isPlainObject15(target)) return ret;
           const targetObject = target;
           const next = targetObject[seg];
-          if (isArray8(next)) {
+          if (isArray9(next)) {
             for (const item of next) {
               ret.push(item);
             }
@@ -3665,6 +4897,125 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
   });
   return obj;
 };
+var copyPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  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;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "copyPaths");
+    assertSafePath(dest, "copyPaths");
+    if (src === dest) return;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      set6(parent, dest, cloneDeep5(parent[leaf]));
+    });
+  });
+  return obj;
+};
+var movePaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  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;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "movePaths");
+    assertSafePath(dest, "movePaths");
+    if (src === dest) return;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      const value = cloneDeep5(parent[leaf]);
+      set6(parent, dest, value);
+      if (dest === leaf || dest.startsWith(`${leaf}.`)) return;
+      delete parent[leaf];
+    });
+  });
+  return obj;
+};
+var sliceArrays = (docObject, operations, options = { mutable: true, maxSlice: DEFAULT_MAX_SLICE }) => {
+  const mutable = options.mutable !== false;
+  const maxSlice = options.maxSlice ?? DEFAULT_MAX_SLICE;
+  assertNonNegativeSafeInteger(maxSlice, "maxSlice", "sliceArrays");
+  const obj = mutable ? docObject : cloneDeep5(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "sliceArrays");
+    const rawDest = typeof op.dest === "undefined" ? void 0 : op.dest;
+    if (typeof rawDest !== "undefined") {
+      if (typeof rawDest !== "string" || rawDest.length === 0) return;
+      assertSafePath(rawDest, "sliceArrays");
+    }
+    const skip = op.skip ?? 0;
+    assertNonNegativeSafeInteger(skip, "skip", "sliceArrays");
+    let limit;
+    if (typeof op.limit !== "undefined") {
+      assertNonNegativeSafeInteger(op.limit, "limit", "sliceArrays");
+      limit = Math.min(op.limit, maxSlice);
+    }
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      const leafValue = parent[leaf];
+      if (!isArray9(leafValue)) return;
+      const end = typeof limit === "undefined" ? void 0 : skip + limit;
+      const window = leafValue.slice(skip, end);
+      if (typeof rawDest === "undefined") {
+        set6(parent, leaf, window);
+      } else {
+        set6(parent, rawDest, window);
+      }
+    });
+  });
+  return obj;
+};
+var countPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  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;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "countPaths");
+    assertSafePath(dest, "countPaths");
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      const leafValue = parent[leaf];
+      let count;
+      if (isArray9(leafValue)) {
+        count = leafValue.length;
+      } else if (isPlainObject15(leafValue)) {
+        count = Object.keys(leafValue).length;
+      } else if (leafValue === null || typeof leafValue === "undefined") {
+        count = 0;
+      } else {
+        count = 1;
+      }
+      set6(parent, dest, count);
+    });
+  });
+  return obj;
+};
+var maskPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : cloneDeep5(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "maskPaths");
+    const replacement = Object.prototype.hasOwnProperty.call(op, "replacement") ? op.replacement : DEFAULT_MASK_REPLACEMENT;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      set6(parent, leaf, replacement);
+    });
+  });
+  return obj;
+};
 
 // src/symbols.ts
 var MIDDLEWARE = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/access-router/middleware");
@@ -3707,18 +5058,18 @@ var Cache = class {
 import {
   castArray as castArray3,
   arrayToRecord,
-  hasOwn as hasOwn2,
-  isArray as isArray9,
+  hasOwn as hasOwn3,
+  isArray as isArray10,
   isBoolean as isBoolean4,
   isEmpty as isEmpty2,
   isEqual,
   isFunction as isFunction4,
-  isPlainObject as isPlainObject14,
+  isPlainObject as isPlainObject16,
   isString as isString5
 } from "@web-ts-toolkit/utils";
 
 // src/permission.ts
-import { hasOwn } from "@web-ts-toolkit/utils";
+import { hasOwn as hasOwn2 } from "@web-ts-toolkit/utils";
 var Permission = class {
   constructor(permissions) {
     this.permissions = { ...permissions };
@@ -3734,7 +5085,7 @@ var Permission = class {
     return [permissionOrPermissions].concat(permissions);
   }
   hasKey(permission) {
-    return hasOwn(this.permissions, permission);
+    return hasOwn2(this.permissions, permission);
   }
   has(permission) {
     return this.permissions[permission] === true;
@@ -3754,10 +5105,10 @@ var permission_default = Permission;
 
 // src/core-shared.ts
 function isAndFilter(filter2) {
-  return !!filter2 && isPlainObject14(filter2) && Object.keys(filter2).length === 1 && isArray9(filter2.$and);
+  return !!filter2 && isPlainObject16(filter2) && Object.keys(filter2).length === 1 && isArray10(filter2.$and);
 }
 function isMergeableClause(filter2) {
-  return !!filter2 && isPlainObject14(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
+  return !!filter2 && isPlainObject16(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
 }
 function optimizeAndFilter(clausesInput) {
   const clauses = [];
@@ -3772,10 +5123,10 @@ function optimizeAndFilter(clausesInput) {
     }
   }
   const dedupeKey = (value) => {
-    if (isArray9(value)) {
+    if (isArray10(value)) {
       return `[${value.map(dedupeKey).join(",")}]`;
     }
-    if (isPlainObject14(value)) {
+    if (isPlainObject16(value)) {
       return `{${Object.keys(value).sort().map((key) => `${key}:${dedupeKey(value[key])}`).join(",")}}`;
     }
     return JSON.stringify(value);
@@ -3799,7 +5150,7 @@ function optimizeAndFilter(clausesInput) {
     }
     let canMerge = true;
     for (const [key, value] of Object.entries(clause)) {
-      if (hasOwn2(mergedClause, key) && !isEqual(mergedClause[key], value)) {
+      if (hasOwn3(mergedClause, key) && !isEqual(mergedClause[key], value)) {
         canMerge = false;
         break;
       }
@@ -3817,7 +5168,7 @@ function optimizeAndFilter(clausesInput) {
 }
 function normalizeFilter(filter2) {
   if (filter2 === false) return false;
-  if (!filter2 || !isPlainObject14(filter2) || isEmpty2(filter2)) return null;
+  if (!filter2 || !isPlainObject16(filter2) || isEmpty2(filter2)) return null;
   if (!isAndFilter(filter2)) {
     return filter2;
   }
@@ -3884,8 +5235,8 @@ async function setRequestPermissions(req) {
   const globalPermissions = getGlobalOption("globalPermissions");
   if (!isFunction4(globalPermissions)) return;
   const permissions = await globalPermissions.call(req, req);
-  if (isPlainObject14(permissions)) req[requestPermissionField] = permissions;
-  else if (isArray9(permissions)) req[requestPermissionField] = arrayToRecord(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);
 }
@@ -3898,7 +5249,7 @@ async function evaluateRouteGuard(req, permissions, routeGuard) {
   if (isString5(routeGuard)) {
     return stringHandler(routeGuard);
   }
-  if (isArray9(routeGuard)) {
+  if (isArray10(routeGuard)) {
     return arrayHandler(routeGuard);
   }
   if (isFunction4(routeGuard)) {
@@ -3936,7 +5287,7 @@ async function collectSchemaFields({
       if (value) fields.push(key);
     } else if (isString5(value)) {
       if (stringHandler(value)) fields.push(key);
-    } else if (isArray9(value)) {
+    } else if (isArray10(value)) {
       if (arrayHandler(value)) fields.push(key);
     } else if (isFunction4(value)) {
       if (await value.call(req, ...functionArgs)) fields.push(key);
@@ -4241,7 +5592,7 @@ var Core = class {
     if (isFunction5(validate)) {
       const permissions = this.getGlobalPermissions();
       return validate.call(this.req, allowedData, permissions, context);
-    } else if (isBoolean5(validate) || isArray10(validate)) {
+    } else if (isBoolean5(validate) || isArray11(validate)) {
       return validate;
     } else {
       return true;
@@ -4385,6 +5736,41 @@ var Core = class {
             options
           );
           break;
+        case "COPY":
+          docObject = copyPaths(
+            docObject,
+            args,
+            options
+          );
+          break;
+        case "MOVE":
+          docObject = movePaths(
+            docObject,
+            args,
+            options
+          );
+          break;
+        case "SLICE":
+          docObject = sliceArrays(
+            docObject,
+            args,
+            options
+          );
+          break;
+        case "COUNT":
+          docObject = countPaths(
+            docObject,
+            args,
+            options
+          );
+          break;
+        case "MASK":
+          docObject = maskPaths(
+            docObject,
+            args,
+            options
+          );
+          break;
       }
     });
     return docObject;
@@ -4462,19 +5848,19 @@ function guard(condition) {
     const permissions = req[PERMISSIONS];
     let cond = condition;
     let phas = (key) => permissions.has(key);
-    if (isPlainObject15(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 (isPlainObject15(id)) {
+      if (isPlainObject17(id)) {
         const { type = "param", key } = id;
         if (type === "param") {
           const paramValue = req.params[key];
-          _id = isArray11(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
+          _id = isArray12(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
         } else if (type === "query") {
           const _qval = req.query[key];
-          if (isArray11(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
+          if (isArray12(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
           else _id = _qval;
         } else {
           _id = null;
@@ -4494,7 +5880,7 @@ function guard(condition) {
     const { stringHandler, arrayHandler } = createValidator(phas);
     if (isString7(cond)) {
       if (stringHandler(cond)) return next();
-    } else if (isArray11(cond)) {
+    } else if (isArray12(cond)) {
       if (arrayHandler(cond)) return next();
     } else if (isFunction6(cond)) {
       const result = await cond.call(req, permissions);
@@ -4509,7 +5895,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 isPlainObject16, 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([
@@ -4638,6 +6024,7 @@ import JsonRouter4 from "@web-ts-toolkit/express-json-router";
 
 // src/validation/common.ts
 import { z as z2 } from "zod";
+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"]);
@@ -4698,7 +6085,8 @@ var subPopulateSchema = z2.union([
     select: projectionSchema.optional()
   }).passthrough()
 ]);
-var includeItemSchema = z2.object({
+var legacyIncludeItemSchema = z2.object({
+  mode: z2.enum(["legacy"]).optional(),
   model: z2.string().min(1),
   op: z2.enum(["list", "read", "count"]),
   path: z2.string().min(1),
@@ -4707,8 +6095,139 @@ var includeItemSchema = z2.object({
   foreignField: z2.string().min(1),
   args: z2.unknown().optional().describe("Forwarded to list/read includes. Count includes ignore pagination fields so counts remain exact."),
   options: z2.unknown().optional()
-}).passthrough();
-var includeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+}).passthrough().superRefine((entry, ctx) => {
+  if (entry.filter !== void 0 && containsParentMarkerShape(entry.filter)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: 'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")',
+      path: ["filter"]
+    });
+  }
+});
+var parentRefSchema = z2.object({ $parent: z2.string().min(1) }).strict().superRefine((value, ctx) => {
+  if (!isValidParentRefPath(value.$parent)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid $parent reference path: ${value.$parent}`,
+      path: ["$parent"]
+    });
+  }
+});
+var correlatedIdSchema = z2.union([z2.string().min(1), parentRefSchema]);
+var correlatedFilterSchema = z2.record(z2.string(), z2.unknown()).superRefine((filter2, ctx) => {
+  for (const issue of validateCorrelatedFilterTemplate(filter2)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: issue.message,
+      path: issue.path.map(String)
+    });
+  }
+});
+var correlatedEmptyOptionsSchema = z2.unknown().refine(
+  (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) => {
+  if (!isValidCorrelatedOutputPath(path)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid correlated include output path: ${path}`,
+      path: []
+    });
+  }
+});
+var checkArgsMarkers = (select, sort, ctx) => {
+  const selectIssue = findArgsMarkerIssue(select, "args.select");
+  if (selectIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: selectIssue.message, path: ["select"] });
+  }
+  const sortIssue = findArgsMarkerIssue(sort, "args.sort");
+  if (sortIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: sortIssue.message, path: ["sort"] });
+  }
+};
+var correlatedReadArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedListArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  skip: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  limit: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  page: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  pageSize: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedCountArgsSchema = z2.unknown().refine(
+  (value) => value === void 0 || isPlainObject18(value) && Object.keys(value).length === 0,
+  "Count includes accept no args"
+).optional();
+var correlatedReadByIdSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  id: correlatedIdSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedReadByFilterSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedListSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("list"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedListArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedCountSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("count"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedCountArgsSchema,
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var includeItemSchema = z2.union([
+  legacyIncludeItemSchema,
+  correlatedReadByIdSchema,
+  correlatedReadByFilterSchema,
+  correlatedListSchema,
+  correlatedCountSchema
+]);
+var correlatedNestedIncludeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+var rejectDuplicateCorrelatedPaths = (items, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if (isPlainObject18(item) && item.mode === "correlated" && typeof item.path === "string") {
+      if (seen.has(item.path)) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `Duplicate correlated include output path: ${item.path}`,
+          path: [index, "path"]
+        });
+      } else {
+        seen.add(item.path);
+      }
+    }
+  });
+};
+var includeSchema = z2.union([
+  includeItemSchema,
+  z2.array(includeItemSchema).superRefine(rejectDuplicateCorrelatedPaths)
+]);
 var fieldsSchema = z2.array(z2.string().min(1));
 var taskSchema = z2.object({
   type: z2.string().min(1),
@@ -4891,19 +6410,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)) {
@@ -4911,11 +6423,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,
@@ -4924,7 +6446,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 ?? [])
     };
   };
 }
@@ -5154,14 +6678,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)) {
@@ -5245,7 +6769,7 @@ var listBodySchema = z3.object({
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
 var countBodySchema = z3.object({
   filter: objectOrArraySchema.optional()
-}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options"]));
+}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options", "include"]));
 var readFilterBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
@@ -6254,11 +7778,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]
   });
 }
@@ -6429,7 +7953,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);
@@ -6510,7 +8034,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)}`);
       });
     });
   }
@@ -6523,7 +8047,7 @@ var ModelRouter = class _ModelRouter {
         value
       );
     }
-    if (arguments.length === 1 && isPlainObject16(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject19(keyOrOptions)) {
       assertMutableRouterOptions("model", keyOrOptions);
       this.runtime.setModelOptions(this.modelName, keyOrOptions);
     }
@@ -6546,7 +8070,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 {
@@ -6812,7 +8336,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 {
@@ -6962,7 +8486,7 @@ var RootRouter = class {
 
 // src/routers/data-router.ts
 import JsonRouter7 from "@web-ts-toolkit/express-json-router";
-import { isPlainObject as isPlainObject17, 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}`;
@@ -7007,7 +8531,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();
@@ -7163,7 +8687,7 @@ var DataRouter = class {
       assertMutableRouterOption("data", keyOrOptions);
       this.runtime.setDataOption(this.dataName, keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject17(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject20(keyOrOptions)) {
       assertMutableRouterOptions("data", keyOrOptions);
       this.runtime.setDataOptions(this.dataName, keyOrOptions);
     }
@@ -7310,7 +8834,7 @@ function createRuntimeApi(runtime) {
     if (arguments.length === 2 && isString10(keyOrOptions)) {
       return runtime.setGlobalOption(keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject18(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject21(keyOrOptions)) {
       return runtime.setGlobalOptions(keyOrOptions);
     }
   };