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

package/index.js

@@ -77,14 +77,14 @@ __export(index_exports, {
   setModelOptions: () => setModelOptions
 });
 module.exports = __toCommonJS(index_exports);
-var import_utils28 = require("@web-ts-toolkit/utils");
+var import_utils30 = require("@web-ts-toolkit/utils");
 
 // src/middleware.ts
 var import_express_json_router2 = __toESM(require("@web-ts-toolkit/express-json-router"));
-var import_utils22 = require("@web-ts-toolkit/utils");
+var import_utils23 = require("@web-ts-toolkit/utils");
 
 // src/core.ts
-var import_utils21 = require("@web-ts-toolkit/utils");
+var import_utils22 = require("@web-ts-toolkit/utils");
 
 // src/runtime.ts
 var import_mongoose3 = __toESM(require("mongoose"));
@@ -1000,7 +1000,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;
@@ -1020,6 +1022,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") {
@@ -1605,7 +1615,463 @@ var getModelRef = (modelName, refPath) => {
 };
 
 // src/services/base.ts
+var import_utils13 = require("@web-ts-toolkit/utils");
+
+// src/correlated-includes.ts
 var import_utils12 = require("@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 (0, import_utils12.isPlainObject)(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
+}
+function isEscapedParentRef(value) {
+  return (0, import_utils12.isPlainObject)(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 ((0, import_utils12.isArray)(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      return current.some(visit);
+    }
+    if ((0, import_utils12.isPlainObject)(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 ((0, import_utils12.isPlainObject)(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 ((0, import_utils12.isArray)(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 (!(0, import_utils12.isArray)(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 ((0, import_utils12.isPlainObject)(clause)) {
+          scanTemplateObjectEntries(clause, clausePath, issues);
+        }
+      });
+      continue;
+    }
+    scanTemplateValueNode(child, childPath, issues);
+  }
+}
+function validateCorrelatedFilterTemplate(filter2) {
+  const issues = [];
+  if (!(0, import_utils12.isPlainObject)(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 ((0, import_utils12.isArray)(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
+      value.forEach(visitValue);
+      return;
+    }
+    if ((0, import_utils12.isPlainObject)(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 ((0, import_utils12.isPlainObject)(value) || (0, import_utils12.isArray)(value)) return (0, import_utils12.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 (!(0, import_utils12.isArray)(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 (!(0, import_utils12.isPlainObject)(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>" } }');
+    }
+    return literalParentRefObject(inner.$parent);
+  }
+  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 && (0, import_utils12.isPlainObject)(value)) return { $eq: (0, import_utils12.cloneDeep)(value) };
+    return cloneSubstitutedValue(value);
+  }
+  if ((0, import_utils12.isPlainObject)(template)) {
+    if (hasMarkerKey(template)) {
+      throw new CorrelatedReferenceError(
+        'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }'
+      );
+    }
+    return resolveObjectEntries(template, parent);
+  }
+  if ((0, import_utils12.isArray)(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 (!(0, import_utils12.isPlainObject)(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 (!(0, import_utils12.isPlainObject)(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 (!(0, import_utils12.isPlainObject)(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 && !((0, import_utils12.isPlainObject)(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 (0, import_utils12.isPlainObject)(value) && value.mode === "correlated";
+}
+
+// src/services/base.ts
+var correlatedExecStates = /* @__PURE__ */ new WeakMap();
+function getCorrelatedTemplateDepth(includes) {
+  let max = 0;
+  const visit = (entries, depth) => {
+    const list = (0, import_utils13.castArray)(entries).filter(Boolean);
+    for (const entry of list) {
+      if (!(0, import_utils13.isPlainObject)(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));
@@ -1620,11 +2086,11 @@ function validateClientFilter(filter2) {
   }
   const blockedOperators = /* @__PURE__ */ new Set(["$where", "$expr", "$function", "$accumulator"]);
   const visit = (value, path) => {
-    if ((0, import_utils12.isArray)(value)) {
+    if ((0, import_utils13.isArray)(value)) {
       value.forEach((item, index) => visit(item, `${path}[${index}]`));
       return;
     }
-    if (!(0, import_utils12.isPlainObject)(value)) return;
+    if (!(0, import_utils13.isPlainObject)(value)) return;
     Object.entries(value).forEach(([key, child]) => {
       const nextPath = path ? `${path}.${key}` : key;
       if (blockedOperators.has(key)) {
@@ -1744,25 +2210,56 @@ var Base = class {
     return this.req.macl.getPublicService(modelName);
   }
   processInclude(include) {
-    const includes = (0, import_utils12.compact)((0, import_utils12.castArray)(include)).filter(({ model, op, path, localField, foreignField }) => {
-      return model && op && path && localField && foreignField;
-    });
+    const items = (0, import_utils13.compact)((0, import_utils13.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);
+    }
     let includeLocalFields = [];
     let includePaths = [];
-    (0, import_utils12.forEach)(includes, (inc) => {
+    (0, import_utils13.forEach)(legacy, (inc) => {
       includeLocalFields.push(inc.localField);
       includePaths.push(inc.path);
     });
-    includeLocalFields = (0, import_utils12.uniq)((0, import_utils12.compact)(includeLocalFields));
-    includePaths = (0, import_utils12.uniq)((0, import_utils12.compact)(includePaths));
+    includeLocalFields = (0, import_utils13.uniq)((0, import_utils13.compact)(includeLocalFields));
+    includePaths = (0, import_utils13.uniq)((0, import_utils13.compact)(includePaths));
     return {
-      includes,
+      includes: legacy,
+      correlatedIncludes: correlated,
       includeLocalFields,
-      includePaths
+      includePaths,
+      correlatedReferenceFields: (0, import_utils13.uniq)((0, import_utils13.compact)(correlatedReferenceFields))
     };
   }
   getForeignKeyValues(value) {
-    return (0, import_utils12.flatten)((0, import_utils12.castArray)(value));
+    return (0, import_utils13.flatten)((0, import_utils13.castArray)(value));
   }
   getForeignKey(value) {
     return String(value);
@@ -1770,7 +2267,7 @@ var Base = class {
   buildForeignKeyIndex(rows, foreignField) {
     const index = /* @__PURE__ */ new Map();
     for (const row of rows) {
-      for (const value of this.getForeignKeyValues((0, import_utils12.get)(row, foreignField))) {
+      for (const value of this.getForeignKeyValues((0, import_utils13.get)(row, foreignField))) {
         const key = this.getForeignKey(value);
         const values = index.get(key);
         if (values) values.push(row);
@@ -1801,7 +2298,7 @@ var Base = class {
     return ids.size;
   }
   sanitizeIncludeArgs(args) {
-    if (!(0, import_utils12.isPlainObject)(args)) return {};
+    if (!(0, import_utils13.isPlainObject)(args)) return {};
     const { overrides: _clientOverrides, ...trustedArgs } = args;
     return trustedArgs;
   }
@@ -1812,12 +2309,18 @@ var Base = class {
   }
   async includeDocs(docs, include) {
     if (!include) return docs;
-    const includes = (0, import_utils12.compact)((0, import_utils12.castArray)(include));
+    const includes = (0, import_utils13.compact)((0, import_utils13.castArray)(include));
     if (includes.length === 0) return docs;
-    const isSingle = !(0, import_utils12.isArray)(docs);
+    const isSingle = !(0, import_utils13.isArray)(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":
@@ -1838,7 +2341,7 @@ var Base = class {
     const svc = await this.getAuthorizedTargetService(model, "read");
     for (let y = 0; y < docs.length; y++) {
       const doc = docs[y];
-      const localValue = (0, import_utils12.get)(doc, localField);
+      const localValue = (0, import_utils13.get)(doc, localField);
       const filter2 = { ..._filters ?? {}, [foreignField]: { $in: this.getForeignKeyValues(localValue) } };
       const trustedOptions = {
         ...options,
@@ -1857,10 +2360,10 @@ var Base = class {
     const { model, op, path, localField, foreignField, filter: _filters, args = {}, options = {} } = include;
     const svc = await this.getAuthorizedTargetService(model, op);
     const includeLocalValues = [];
-    (0, import_utils12.forEach)(docs, (doc) => {
-      includeLocalValues.push(...this.getForeignKeyValues((0, import_utils12.get)(doc, localField)));
+    (0, import_utils13.forEach)(docs, (doc) => {
+      includeLocalValues.push(...this.getForeignKeyValues((0, import_utils13.get)(doc, localField)));
     });
-    const filter2 = { ..._filters ?? {}, [foreignField]: { $in: (0, import_utils12.flatten)(includeLocalValues) } };
+    const filter2 = { ..._filters ?? {}, [foreignField]: { $in: (0, import_utils13.flatten)(includeLocalValues) } };
     const authorizedFilter = await svc.genFilter(op, filter2);
     const trustedArgs = {
       ...this.sanitizeIncludeArgs(args),
@@ -1879,7 +2382,7 @@ var Base = class {
     const index = this.buildForeignKeyIndex(trustedResult.data, foreignField);
     for (let y = 0; y < docs.length; y++) {
       const doc = docs[y];
-      const matches = this.getIndexedMatches(index, (0, import_utils12.get)(doc, localField));
+      const matches = this.getIndexedMatches(index, (0, import_utils13.get)(doc, localField));
       setDocValue(doc, path, op === "list" ? matches : matches[0]);
     }
     return docs;
@@ -1887,15 +2390,365 @@ var Base = class {
   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((0, import_utils12.get)(doc, localField)));
+    const localValues = docs.flatMap((doc) => this.getForeignKeyValues((0, import_utils13.get)(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, (0, import_utils12.get)(doc, localField)));
+      setDocValue(doc, path, this.getIndexedCount(result.data, (0, import_utils13.get)(doc, localField)));
+    }
+    return docs;
+  }
+  getCorrelatedExecState() {
+    const key = this.req;
+    let state = correlatedExecStates.get(key);
+    if (!state) {
+      state = {
+        totalQueries: 0,
+        scheduler: new RequestConcurrencyScheduler(this.getRequestComplexity().maxBulkConcurrency)
+      };
+      correlatedExecStates.set(key, state);
+    }
+    return state;
+  }
+  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) => (0, import_utils13.cloneDeep)(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(
       filter2,
@@ -1938,10 +2791,10 @@ var Base = class {
     }
     let ret = result.data;
     if (sqOptions.path) {
-      ret = (0, import_utils12.isArray)(ret) ? (0, import_utils12.flatten)(ret.map((v) => (0, import_utils12.get)(v, sqOptions.path))) : (0, import_utils12.get)(ret, sqOptions.path);
+      ret = (0, import_utils13.isArray)(ret) ? (0, import_utils13.flatten)(ret.map((v) => (0, import_utils13.get)(v, sqOptions.path))) : (0, import_utils13.get)(ret, sqOptions.path);
     }
     if (sqOptions.compact) {
-      ret = (0, import_utils12.compact)((0, import_utils12.castArray)(ret));
+      ret = (0, import_utils13.compact)((0, import_utils13.castArray)(ret));
     }
     return ret;
   }
@@ -1953,7 +2806,7 @@ var Base = class {
 };
 
 // src/services/service.ts
-var import_utils14 = require("@web-ts-toolkit/utils");
+var import_utils15 = require("@web-ts-toolkit/utils");
 var import_just_diff = require("just-diff");
 
 // src/model.ts
@@ -2197,28 +3050,28 @@ var error = (error2) => {
 };
 
 // src/services/model-subdocument-service.ts
-var import_utils13 = require("@web-ts-toolkit/utils");
+var import_utils14 = require("@web-ts-toolkit/utils");
 async function listSub(service, id, sub, options) {
   const { filter: ft, select } = options ?? {};
   const filterErrors = validateClientFilter(ft);
   if (filterErrors.length > 0) return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: filterErrors };
   const parentDoc = await getParentDoc(service, id, sub, null, { access: "read" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
-  let result = (0, import_utils13.get)(parentDoc, sub);
+  let result = (0, import_utils14.get)(parentDoc, sub);
   const [subFilter, subSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.list`, ft),
     service.genQuerySelect("list", select, false, [sub, "sub"])
   ]);
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
   result = filterCollection(result, subFilter);
-  if (subSelect) result = result.map((v) => (0, import_utils13.pick)(toObject(v), subSelect.concat("_id")));
+  if (subSelect) result = result.map((v) => (0, import_utils14.pick)(toObject(v), subSelect.concat("_id")));
   return { success: true, kind: "list", code: "success" /* Success */, data: result, count: result.length };
 }
 async function readSub(service, id, sub, subId, options) {
   const { select, populate } = options ?? {};
   const parentDoc = await getParentDoc(service, id, sub, { populate }, { access: "read" });
   if (!parentDoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
-  const result = (0, import_utils13.get)(parentDoc, sub);
+  const result = (0, import_utils14.get)(parentDoc, sub);
   const [subFilter, subSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.read`, { _id: subId }),
     service.genQuerySelect("read", select, false, [sub, "sub"])
@@ -2226,13 +3079,13 @@ async function readSub(service, id, sub, subId, options) {
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
   let subdoc = findElement(result, subFilter);
   if (!subdoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
-  if (subSelect) subdoc = (0, import_utils13.pick)(toObject(subdoc), subSelect.concat(["_id"]));
+  if (subSelect) subdoc = (0, import_utils14.pick)(toObject(subdoc), subSelect.concat(["_id"]));
   return { success: true, kind: "single", code: "success" /* Success */, data: subdoc };
 }
 async function updateSub(service, 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 = (0, import_utils13.get)(parentDoc, sub);
+  const result = (0, import_utils14.get)(parentDoc, sub);
   const [subFilter, subReadSelect, subUpdateSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.update`, { _id: subId }),
     service.genQuerySelect("read", null, false, [sub, "sub"]),
@@ -2241,10 +3094,10 @@ async function updateSub(service, id, sub, subId, data) {
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
   let subdoc = findElement(result, subFilter);
   if (!subdoc) return { success: false, kind: "error", code: "not_found" /* NotFound */ };
-  const allowedData = (0, import_utils13.pick)(data, subUpdateSelect);
+  const allowedData = (0, import_utils14.pick)(data, subUpdateSelect);
   Object.assign(subdoc, allowedData);
   await parentDoc.save();
-  if (subReadSelect) subdoc = (0, import_utils13.pick)(toObject(subdoc), subReadSelect.concat(["_id"]));
+  if (subReadSelect) subdoc = (0, import_utils14.pick)(toObject(subdoc), subReadSelect.concat(["_id"]));
   return { success: true, kind: "single", code: "success" /* Success */, data: subdoc };
 }
 async function bulkUpdateSub(service, id, sub, data) {
@@ -2259,7 +3112,7 @@ 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 = (0, import_utils13.get)(parentDoc, sub);
+  let result = (0, import_utils14.get)(parentDoc, sub);
   const [subFilter, subReadSelect, subUpdateSelect] = await Promise.all([
     service.genFilter(`subs.${sub}.update`, { _id: { $in: data.map((v) => v._id) } }),
     service.genQuerySelect("read", null, false, [sub, "sub"]),
@@ -2267,14 +3120,14 @@ async function bulkUpdateSub(service, id, sub, data) {
   ]);
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
   result = filterCollection(result, subFilter);
-  (0, import_utils13.forEach)(result, (subdoc) => {
+  (0, import_utils14.forEach)(result, (subdoc) => {
     const tdata = findElementById(data, subdoc._id);
     if (!tdata) return;
-    const allowedData = (0, import_utils13.pick)(tdata, subUpdateSelect);
+    const allowedData = (0, import_utils14.pick)(tdata, subUpdateSelect);
     Object.assign(subdoc, allowedData);
   });
   await parentDoc.save();
-  if (subReadSelect) result = result.map((v) => (0, import_utils13.pick)(toObject(v), subReadSelect.concat(["_id"])));
+  if (subReadSelect) result = result.map((v) => (0, import_utils14.pick)(toObject(v), subReadSelect.concat(["_id"])));
   return { success: true, kind: "list", code: "success" /* Success */, data: result, count: result.length };
 }
 async function createSub(service, id, sub, data, options) {
@@ -2290,25 +3143,25 @@ 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 = (0, import_utils13.get)(parentDoc, sub);
+  let result = (0, import_utils14.get)(parentDoc, sub);
   const [subCreateSelect, subReadSelect] = await Promise.all([
     service.genQuerySelect("create", null, false, [sub, "sub"]),
     service.genQuerySelect("read", null, false, [sub, "sub"])
   ]);
-  const allowedData = Array.isArray(data) ? data.map((row) => (0, import_utils13.pick)(row, subCreateSelect)) : (0, import_utils13.pick)(data, subCreateSelect);
+  const allowedData = Array.isArray(data) ? data.map((row) => (0, import_utils14.pick)(row, subCreateSelect)) : (0, import_utils14.pick)(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) => (0, import_utils13.pick)(toObject(v), subReadSelect.concat(["_id"])));
+  if (subReadSelect) result = result.map((v) => (0, import_utils14.pick)(toObject(v), subReadSelect.concat(["_id"])));
   return { success: true, kind: "list", code: "created" /* Created */, data: result, count: result.length };
 }
 async function deleteSub(service, 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 = (0, import_utils13.get)(parentDoc, sub);
+  const result = (0, import_utils14.get)(parentDoc, sub);
   const subFilter = await service.genFilter(`subs.${sub}.delete`, { _id: subId });
   if (subFilter === false) return { success: false, kind: "error", code: "forbidden" /* Forbidden */ };
   const subdoc = findElement(result, subFilter);
@@ -2449,6 +3302,29 @@ 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 {
   findRawParentDoc(args) {
     return this.model.findOne({
@@ -2515,8 +3391,9 @@ var Service = class extends Base {
       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 } = this.processInclude(include);
+    const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
+    const finalSelect = normalizeSelect(_select).concat(includeLocalFields, correlatedReferenceFields);
     const query = {
       filter: _filter,
       select: finalSelect,
@@ -2549,8 +3426,14 @@ var Service = class extends Base {
       originalDocumentSnapshot: toObject(doc),
       resolvedQuery: query
     };
+    const correlatedSnapshots = [(0, import_utils15.cloneDeep)(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) {
@@ -2568,8 +3451,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 };
@@ -2615,11 +3510,12 @@ var Service = class extends Base {
       this.genAllowedFields({}, "list", this.baseFieldsExt)
     ]);
     const finalSelect = normalizeSelect(_select);
-    const filteredPopulate = (0, import_utils14.isArray)(finalSelect) && (0, import_utils14.isArray)(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
-    const { includes, includeLocalFields, includePaths } = this.processInclude(include);
+    const filteredPopulate = (0, import_utils15.isArray)(finalSelect) && (0, import_utils15.isArray)(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = this.processInclude(include);
+    const correlatedOutputPaths = correlatedIncludes.map((entry) => entry.path);
     const query = {
       filter: _filter,
-      select: finalSelect.concat(includeLocalFields),
+      select: finalSelect.concat(includeLocalFields, correlatedReferenceFields),
       populate: filteredPopulate,
       sort,
       ...pagination
@@ -2628,7 +3524,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) {
@@ -2652,9 +3548,13 @@ var Service = class extends Base {
       originalDocumentSnapshot: toObject(doc),
       resolvedQuery: query
     }));
-    const _decorate = (0, import_utils14.isFunction)(decorate) ? decorate : (v) => v;
+    const _decorate = (0, import_utils15.isFunction)(decorate) ? decorate : (v) => v;
+    const correlatedSnapshots = docs.map((doc) => (0, import_utils15.cloneDeep)(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) {
@@ -2676,8 +3576,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;
@@ -2753,16 +3665,16 @@ var Service = class extends Base {
         resolvedQuery: resolvedPopulate.length > 0 ? { populate: resolvedPopulate } : {}
       };
       const allowedFields = await this.genAllowedFields(item, "create");
-      const allowedData = (0, import_utils14.pick)(item, allowedFields);
+      const allowedData = (0, import_utils15.pick)(item, allowedFields);
       context.allowedFields = allowedFields;
       context.allowedData = allowedData;
       const validated = await this.validate(allowedData, "create", context);
-      if ((0, import_utils14.isBoolean)(validated)) {
+      if ((0, import_utils15.isBoolean)(validated)) {
         if (!validated) {
           validationErrors.push({ index, errors: [] });
           return void 0;
         }
-      } else if ((0, import_utils14.isArray)(validated)) {
+      } else if ((0, import_utils15.isArray)(validated)) {
         if (validated.length > 0) {
           validationErrors.push({
             index,
@@ -2792,7 +3704,7 @@ var Service = class extends Base {
       contexts[index].preparedData = preparedData;
       return preparedData;
     });
-    const _decorate = (0, import_utils14.isFunction)(decorate) ? decorate : (v) => v;
+    const _decorate = (0, import_utils15.isFunction)(decorate) ? decorate : (v) => v;
     const createdDocs = await this.model.create(items);
     const docs = await mapWithConcurrencyLimit(createdDocs, maxBulkConcurrency, async (doc, index) => {
       contexts[index].currentDocument = doc;
@@ -2910,16 +3822,16 @@ var Service = class extends Base {
     context.docPermissions = this.getDocPermissions(doc);
     context.currentDocument = doc;
     const allowedFields = await this.genAllowedFields(doc, "update");
-    const allowedData = (0, import_utils14.pick)(data, allowedFields);
+    const allowedData = (0, import_utils15.pick)(data, allowedFields);
     context.allowedFields = allowedFields;
     context.allowedData = allowedData;
     const validated = await this.validate(allowedData, "update", context);
-    if ((0, import_utils14.isBoolean)(validated)) {
+    if ((0, import_utils15.isBoolean)(validated)) {
       if (!validated) {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */ };
       }
-    } else if ((0, import_utils14.isArray)(validated)) {
+    } else if ((0, import_utils15.isArray)(validated)) {
       if (validated.length > 0) {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: validated };
@@ -2935,10 +3847,10 @@ var Service = class extends Base {
     const diffExcludeFields = [this.options.documentPermissionField, "__v"];
     this.asServiceHookContext(context).diff = (d) => {
       context.changes = (0, import_just_diff.diff)(
-        (0, import_utils14.omit)(context.originalDocumentSnapshot, diffExcludeFields),
-        (0, import_utils14.omit)(d.toObject({ virtuals: false }), diffExcludeFields)
+        (0, import_utils15.omit)(context.originalDocumentSnapshot, diffExcludeFields),
+        (0, import_utils15.omit)(d.toObject({ virtuals: false }), diffExcludeFields)
       ) || [];
-      context.modifiedPaths = (0, import_utils14.uniq)(context.changes.map((di) => di.path.length > 0 ? String(di.path[0]) : ""));
+      context.modifiedPaths = (0, import_utils15.uniq)(context.changes.map((di) => di.path.length > 0 ? String(di.path[0]) : ""));
     };
     doc = assertModelDocument(await this.afterPersist(doc, "update", context), this.modelName, "afterPersist");
     context.currentDocument = doc;
@@ -2954,7 +3866,7 @@ var Service = class extends Base {
     if (_populate) await populateDoc(doc, _populate);
     doc = await this.trimOutputFields(doc, "read", this.baseFieldsExt);
     let outputDoc = doc;
-    if ((0, import_utils14.isFunction)(decorate)) outputDoc = await decorate(outputDoc, context);
+    if ((0, import_utils15.isFunction)(decorate)) outputDoc = await decorate(outputDoc, context);
     if (!includePermissions) outputDoc = this.addEmptyPermissions(outputDoc);
     this.completeOp("updateOne", startedAt, "success" /* Success */, _filter);
     return { success: true, kind: "single", code: "success" /* Success */, data: outputDoc, input: prepared };
@@ -3106,6 +4018,23 @@ 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
+    };
+  }
   async countByFieldValues(foreignField, values, filter2 = {}, access = "list") {
     if (!isValidFieldPath(foreignField)) {
       return {
@@ -3117,7 +4046,7 @@ var Service = class extends Base {
     }
     const filterErrors = this.validateClientFilter(filter2);
     if (filterErrors.length > 0) return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: filterErrors };
-    const uniqueValues = (0, import_utils14.uniqBy)(values, (value) => String(value));
+    const uniqueValues = (0, import_utils15.uniqBy)(values, (value) => String(value));
     filter2 = await this.genFilter(access, {
       ...filter2,
       [foreignField]: { $in: uniqueValues }
@@ -3193,7 +4122,7 @@ var Service = class extends Base {
     return resolveExistsOptions(this, options);
   }
   async getFieldPermissionAccess(ids) {
-    const uniqueIds = (0, import_utils14.compact)((0, import_utils14.uniqBy)(ids, (id) => String(id)).map((id) => String(id)));
+    const uniqueIds = (0, import_utils15.compact)((0, import_utils15.uniqBy)(ids, (id) => String(id)).map((id) => String(id)));
     if (uniqueIds.length === 0) {
       return {
         readIds: /* @__PURE__ */ new Set(),
@@ -3223,7 +4152,7 @@ var Service = class extends Base {
     return updateSub(this, id, sub, subId, data);
   }
   async bulkUpdateSub(id, sub, data) {
-    return bulkUpdateSub(this, id, sub, (0, import_utils14.castArray)(data));
+    return bulkUpdateSub(this, id, sub, (0, import_utils15.castArray)(data));
   }
   async createSub(id, sub, data, options) {
     return createSub(this, id, sub, data, options);
@@ -3237,7 +4166,7 @@ var Service = class extends Base {
 };
 
 // src/services/public-service.ts
-var import_utils15 = require("@web-ts-toolkit/utils");
+var import_utils16 = require("@web-ts-toolkit/utils");
 var PublicService = class extends Service {
   async _list(filter2, args, options) {
     const { select, populate, include, sort, skip, limit, page, pageSize, tasks } = this.resolvePublicListArgs(args);
@@ -3276,7 +4205,7 @@ var PublicService = class extends Service {
         let d = toObject(doc);
         d = await this.decorate(d, "create", context);
         d = this.runTasks(d, tasks);
-        if (select) d = (0, import_utils15.pick)(d, [...normalizeSelect(select), ...this.baseFieldsExt]);
+        if (select) d = (0, import_utils16.pick)(d, [...normalizeSelect(select), ...this.baseFieldsExt]);
         return d;
       }
     );
@@ -3381,8 +4310,8 @@ var PublicService = class extends Service {
         let d = toObject(doc);
         d = await this.decorate(d, "update", context);
         d = this.runTasks(d, tasks);
-        if (select) d = (0, import_utils15.pick)(d, [...normalizeSelect(select), ...this.baseFieldsExt]);
-        else if (!returningAll) d = (0, import_utils15.pick)(d, [...Object.keys(data), "_id"]);
+        if (select) d = (0, import_utils16.pick)(d, [...normalizeSelect(select), ...this.baseFieldsExt]);
+        else if (!returningAll) d = (0, import_utils16.pick)(d, [...Object.keys(data), "_id"]);
         return d;
       }
     );
@@ -3504,7 +4433,7 @@ var PublicService = class extends Service {
 };
 
 // src/services/data-service.ts
-var import_utils16 = require("@web-ts-toolkit/utils");
+var import_utils17 = require("@web-ts-toolkit/utils");
 var DataService = class {
   constructor(req, dataName) {
     this.req = req;
@@ -3526,7 +4455,7 @@ var DataService = class {
     let doc = await findElement(this.data, _filter);
     if (!doc) return { success: false, kind: "error", code: "not_found" /* NotFound */, query };
     doc = await this.trimOutputFields(doc, access);
-    if (_select.length > 0) doc = (0, import_utils16.pick)(doc, _select);
+    if (_select.length > 0) doc = (0, import_utils17.pick)(doc, _select);
     return { success: true, kind: "single", code: "success" /* Success */, data: doc, query };
   }
   async findById(id, args, options) {
@@ -3566,13 +4495,13 @@ var DataService = class {
     const totalCount = docs.length;
     if (sort) {
       const normalizedSort = normalizeSortForOrderBy(sort);
-      docs = (0, import_utils16.orderBy)(docs, normalizedSort.fields, normalizedSort.orders);
+      docs = (0, import_utils17.orderBy)(docs, normalizedSort.fields, normalizedSort.orders);
     }
     const pagedDocs = docs.slice(query.skip, query.limit && query.skip + query.limit);
     const { maxHookConcurrency } = this.getRequestComplexity();
     const trimmed = await mapWithConcurrencyLimit(pagedDocs, maxHookConcurrency, async (doc) => {
       doc = await this.trimOutputFields(doc, "list");
-      if (_select.length > 0) doc = (0, import_utils16.pick)(doc, _select);
+      if (_select.length > 0) doc = (0, import_utils17.pick)(doc, _select);
       return doc;
     });
     if (!hasExplicitLimit && trimmed.length === totalCount) {
@@ -3621,30 +4550,65 @@ var DataService = class {
 };
 
 // src/processors.ts
-var import_utils17 = require("@web-ts-toolkit/utils");
+var import_utils18 = require("@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 (!(0, import_utils18.isPlainObject)(target)) return ret;
+      const targetObject = target;
+      const next = targetObject[seg];
+      if ((0, import_utils18.isArray)(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 = [];
+  (0, import_utils18.forEach)(targets, (target) => {
+    if (!(0, import_utils18.isPlainObject)(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 : (0, import_utils17.cloneDeep)(docObject);
-  (0, import_utils17.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+  const obj = mutable ? docObject : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
     const dest = op.dest;
@@ -3653,19 +4617,19 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
     assertSafePath(dest);
     let targets = [obj];
     const segs = src.split(".");
-    (0, import_utils17.forEach)(segs, (seg, ind) => {
+    (0, import_utils18.forEach)(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
-        (0, import_utils17.forEach)(targets, (target) => {
-          if (!(0, import_utils17.isPlainObject)(target)) return;
+        (0, import_utils18.forEach)(targets, (target) => {
+          if (!(0, import_utils18.isPlainObject)(target)) return;
           const targetObject = target;
           const leaf = targetObject[seg];
           const sourceForDest = leaf;
           let depopulated;
-          if ((0, import_utils17.isArray)(leaf)) {
+          if ((0, import_utils18.isArray)(leaf)) {
             if (leaf.length === 0) {
               depopulated = [];
-            } else if (leaf.every((item) => (0, import_utils17.isPlainObject)(item))) {
-              depopulated = (0, import_utils17.map)(leaf, idField).map((id, i) => {
+            } else if (leaf.every((item) => (0, import_utils18.isPlainObject)(item))) {
+              depopulated = (0, import_utils18.map)(leaf, idField).map((id, i) => {
                 if (id === void 0) {
                   failMissingId(`${src}[${i}]`);
                 }
@@ -3674,8 +4638,8 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
             } else {
               return;
             }
-          } else if ((0, import_utils17.isPlainObject)(leaf)) {
-            const id = (0, import_utils17.get)(leaf, idField);
+          } else if ((0, import_utils18.isPlainObject)(leaf)) {
+            const id = (0, import_utils18.get)(leaf, idField);
             if (id === void 0) {
               failMissingId(src);
             }
@@ -3683,15 +4647,15 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
           } else {
             return;
           }
-          (0, import_utils17.set)(targetObject, dest, sourceForDest);
-          (0, import_utils17.set)(targetObject, seg, depopulated);
+          (0, import_utils18.set)(targetObject, dest, sourceForDest);
+          (0, import_utils18.set)(targetObject, seg, depopulated);
         });
       } else {
         targets = targets.reduce((ret, target) => {
-          if (!(0, import_utils17.isPlainObject)(target)) return ret;
+          if (!(0, import_utils18.isPlainObject)(target)) return ret;
           const targetObject = target;
           const next = targetObject[seg];
-          if ((0, import_utils17.isArray)(next)) {
+          if ((0, import_utils18.isArray)(next)) {
             for (const item of next) {
               ret.push(item);
             }
@@ -3703,6 +4667,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 : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(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;
+    (0, import_utils18.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils18.hasOwn)(parent, leaf)) return;
+      (0, import_utils18.set)(parent, dest, (0, import_utils18.cloneDeep)(parent[leaf]));
+    });
+  });
+  return obj;
+};
+var movePaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(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;
+    (0, import_utils18.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils18.hasOwn)(parent, leaf)) return;
+      const value = (0, import_utils18.cloneDeep)(parent[leaf]);
+      (0, import_utils18.set)(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 : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(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);
+    }
+    (0, import_utils18.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      const leafValue = parent[leaf];
+      if (!(0, import_utils18.isArray)(leafValue)) return;
+      const end = typeof limit === "undefined" ? void 0 : skip + limit;
+      const window = leafValue.slice(skip, end);
+      if (typeof rawDest === "undefined") {
+        (0, import_utils18.set)(parent, leaf, window);
+      } else {
+        (0, import_utils18.set)(parent, rawDest, window);
+      }
+    });
+  });
+  return obj;
+};
+var countPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(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");
+    (0, import_utils18.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils18.hasOwn)(parent, leaf)) return;
+      const leafValue = parent[leaf];
+      let count;
+      if ((0, import_utils18.isArray)(leafValue)) {
+        count = leafValue.length;
+      } else if ((0, import_utils18.isPlainObject)(leafValue)) {
+        count = Object.keys(leafValue).length;
+      } else if (leafValue === null || typeof leafValue === "undefined") {
+        count = 0;
+      } else {
+        count = 1;
+      }
+      (0, import_utils18.set)(parent, dest, count);
+    });
+  });
+  return obj;
+};
+var maskPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils18.cloneDeep)(docObject);
+  (0, import_utils18.forEach)(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;
+    (0, import_utils18.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils18.hasOwn)(parent, leaf)) return;
+      (0, import_utils18.set)(parent, leaf, replacement);
+    });
+  });
+  return obj;
+};
 
 // src/symbols.ts
 var MIDDLEWARE = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/access-router/middleware");
@@ -3742,10 +4825,10 @@ var Cache = class {
 };
 
 // src/core-shared.ts
-var import_utils19 = require("@web-ts-toolkit/utils");
+var import_utils20 = require("@web-ts-toolkit/utils");
 
 // src/permission.ts
-var import_utils18 = require("@web-ts-toolkit/utils");
+var import_utils19 = require("@web-ts-toolkit/utils");
 var Permission = class {
   constructor(permissions) {
     this.permissions = { ...permissions };
@@ -3761,7 +4844,7 @@ var Permission = class {
     return [permissionOrPermissions].concat(permissions);
   }
   hasKey(permission) {
-    return (0, import_utils18.hasOwn)(this.permissions, permission);
+    return (0, import_utils19.hasOwn)(this.permissions, permission);
   }
   has(permission) {
     return this.permissions[permission] === true;
@@ -3781,10 +4864,10 @@ var permission_default = Permission;
 
 // src/core-shared.ts
 function isAndFilter(filter2) {
-  return !!filter2 && (0, import_utils19.isPlainObject)(filter2) && Object.keys(filter2).length === 1 && (0, import_utils19.isArray)(filter2.$and);
+  return !!filter2 && (0, import_utils20.isPlainObject)(filter2) && Object.keys(filter2).length === 1 && (0, import_utils20.isArray)(filter2.$and);
 }
 function isMergeableClause(filter2) {
-  return !!filter2 && (0, import_utils19.isPlainObject)(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
+  return !!filter2 && (0, import_utils20.isPlainObject)(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
 }
 function optimizeAndFilter(clausesInput) {
   const clauses = [];
@@ -3799,10 +4882,10 @@ function optimizeAndFilter(clausesInput) {
     }
   }
   const dedupeKey = (value) => {
-    if ((0, import_utils19.isArray)(value)) {
+    if ((0, import_utils20.isArray)(value)) {
       return `[${value.map(dedupeKey).join(",")}]`;
     }
-    if ((0, import_utils19.isPlainObject)(value)) {
+    if ((0, import_utils20.isPlainObject)(value)) {
       return `{${Object.keys(value).sort().map((key) => `${key}:${dedupeKey(value[key])}`).join(",")}}`;
     }
     return JSON.stringify(value);
@@ -3826,7 +4909,7 @@ function optimizeAndFilter(clausesInput) {
     }
     let canMerge = true;
     for (const [key, value] of Object.entries(clause)) {
-      if ((0, import_utils19.hasOwn)(mergedClause, key) && !(0, import_utils19.isEqual)(mergedClause[key], value)) {
+      if ((0, import_utils20.hasOwn)(mergedClause, key) && !(0, import_utils20.isEqual)(mergedClause[key], value)) {
         canMerge = false;
         break;
       }
@@ -3837,24 +4920,24 @@ function optimizeAndFilter(clausesInput) {
     }
     Object.assign(mergedClause, clause);
   }
-  const finalClauses = (0, import_utils19.isEmpty)(mergedClause) ? remainingClauses : [mergedClause, ...remainingClauses];
+  const finalClauses = (0, import_utils20.isEmpty)(mergedClause) ? remainingClauses : [mergedClause, ...remainingClauses];
   if (finalClauses.length === 0) return null;
   if (finalClauses.length === 1) return finalClauses[0];
   return { $and: finalClauses };
 }
 function normalizeFilter(filter2) {
   if (filter2 === false) return false;
-  if (!filter2 || !(0, import_utils19.isPlainObject)(filter2) || (0, import_utils19.isEmpty)(filter2)) return null;
+  if (!filter2 || !(0, import_utils20.isPlainObject)(filter2) || (0, import_utils20.isEmpty)(filter2)) return null;
   if (!isAndFilter(filter2)) {
     return filter2;
   }
   return optimizeAndFilter(filter2.$and);
 }
 async function resolveIdentifierFilter(req, idField, resolveIdFilter, id) {
-  if ((0, import_utils19.isFunction)(resolveIdFilter)) {
+  if ((0, import_utils20.isFunction)(resolveIdFilter)) {
     return await resolveIdFilter.call(req, id);
   }
-  if ((0, import_utils19.isString)(idField)) {
+  if ((0, import_utils20.isString)(idField)) {
     return { [idField]: id };
   }
   return { _id: id };
@@ -3870,12 +4953,12 @@ async function resolveAccessFilter({
 }) {
   let nextFilter = normalizeFilter(filter2);
   const overrideFilterFn = getOption(`overrideFilter.${access}`, null);
-  if (nextFilter !== false && (0, import_utils19.isFunction)(overrideFilterFn)) {
+  if (nextFilter !== false && (0, import_utils20.isFunction)(overrideFilterFn)) {
     nextFilter = normalizeFilter(await overrideFilterFn.call(req, nextFilter, permissions));
   }
   if (nextFilter === false) return false;
   const baseFilterFn = getOption(`baseFilter.${access}`, null);
-  if (!(0, import_utils19.isFunction)(baseFilterFn)) return nextFilter ?? {};
+  if (!(0, import_utils20.isFunction)(baseFilterFn)) return nextFilter ?? {};
   const baseFilter = normalizeFilter(
     cache.has(cacheKey) ? cache.get(cacheKey) : await baseFilterFn.call(req, permissions)
   );
@@ -3909,34 +4992,34 @@ async function setRequestPermissions(req) {
   if (owner === activeRuntime) return;
   if (hasFieldValue && owner === void 0) return;
   const globalPermissions = getGlobalOption("globalPermissions");
-  if (!(0, import_utils19.isFunction)(globalPermissions)) return;
+  if (!(0, import_utils20.isFunction)(globalPermissions)) return;
   const permissions = await globalPermissions.call(req, req);
-  if ((0, import_utils19.isPlainObject)(permissions)) req[requestPermissionField] = permissions;
-  else if ((0, import_utils19.isArray)(permissions)) req[requestPermissionField] = (0, import_utils19.arrayToRecord)(permissions);
-  else if ((0, import_utils19.isString)(permissions)) req[requestPermissionField] = { [permissions]: true };
+  if ((0, import_utils20.isPlainObject)(permissions)) req[requestPermissionField] = permissions;
+  else if ((0, import_utils20.isArray)(permissions)) req[requestPermissionField] = (0, import_utils20.arrayToRecord)(permissions);
+  else if ((0, import_utils20.isString)(permissions)) req[requestPermissionField] = { [permissions]: true };
   owners.set(requestPermissionField, activeRuntime);
 }
 async function evaluateRouteGuard(req, permissions, routeGuard) {
   const phas = (key) => permissions.has(key);
   const { stringHandler, arrayHandler } = createValidator(phas);
-  if ((0, import_utils19.isBoolean)(routeGuard)) {
+  if ((0, import_utils20.isBoolean)(routeGuard)) {
     return routeGuard === true;
   }
-  if ((0, import_utils19.isString)(routeGuard)) {
+  if ((0, import_utils20.isString)(routeGuard)) {
     return stringHandler(routeGuard);
   }
-  if ((0, import_utils19.isArray)(routeGuard)) {
+  if ((0, import_utils20.isArray)(routeGuard)) {
     return arrayHandler(routeGuard);
   }
-  if ((0, import_utils19.isFunction)(routeGuard)) {
+  if ((0, import_utils20.isFunction)(routeGuard)) {
     return routeGuard.call(req, permissions);
   }
   return false;
 }
 async function callHookChain(req, hook, doc, permissions, context) {
-  const hooks = (0, import_utils19.castArray)(hook);
+  const hooks = (0, import_utils20.castArray)(hook);
   for (let x = 0; x < hooks.length; x++) {
-    if ((0, import_utils19.isFunction)(hooks[x])) {
+    if ((0, import_utils20.isFunction)(hooks[x])) {
       doc = await hooks[x].call(req, doc, permissions, context);
     }
   }
@@ -3959,13 +5042,13 @@ async function collectSchemaFields({
     if (baseFields.includes(key)) continue;
     const val = permissionSchema[key];
     const value = val && val[access] || val;
-    if ((0, import_utils19.isBoolean)(value)) {
+    if ((0, import_utils20.isBoolean)(value)) {
       if (value) fields.push(key);
-    } else if ((0, import_utils19.isString)(value)) {
+    } else if ((0, import_utils20.isString)(value)) {
       if (stringHandler(value)) fields.push(key);
-    } else if ((0, import_utils19.isArray)(value)) {
+    } else if ((0, import_utils20.isArray)(value)) {
       if (arrayHandler(value)) fields.push(key);
-    } else if ((0, import_utils19.isFunction)(value)) {
+    } else if ((0, import_utils20.isFunction)(value)) {
       if (await value.call(req, ...functionArgs)) fields.push(key);
     }
   }
@@ -4051,7 +5134,7 @@ async function runDecorateAllHook({
 }
 
 // src/acl/select-resolution.ts
-var import_utils20 = require("@web-ts-toolkit/utils");
+var import_utils21 = require("@web-ts-toolkit/utils");
 async function collectAllowedFieldsForRequest({
   req,
   permissionSchema,
@@ -4119,15 +5202,15 @@ async function resolveSelectForRequest({
       const excludeall = normalizedSelect.every((v) => v.startsWith("-"));
       if (excludeall) {
         normalizedSelect = normalizedSelect.map((v) => v.substring(1));
-        fields = (0, import_utils20.difference)(fields, normalizedSelect);
+        fields = (0, import_utils21.difference)(fields, normalizedSelect);
         if (excludeid) fields.push("-_id");
       } else {
-        fields = (0, import_utils20.intersection)(normalizedSelect, fields.concat(excludeid ? "-_id" : "_id"));
+        fields = (0, import_utils21.intersection)(normalizedSelect, fields.concat(excludeid ? "-_id" : "_id"));
       }
     }
     return fields.concat(alwaysSelectFields);
   }
-  return (0, import_utils20.intersection)(normalizedSelect, fields);
+  return (0, import_utils21.intersection)(normalizedSelect, fields);
 }
 
 // src/core.ts
@@ -4142,10 +5225,10 @@ var Core = class {
   getIdentifier(modelName) {
     const resolveIdFilter = getModelOption(modelName, "resolveIdFilter");
     const idField = getModelOption(modelName, "idField");
-    if ((0, import_utils21.isFunction)(resolveIdFilter)) {
+    if ((0, import_utils22.isFunction)(resolveIdFilter)) {
       return null;
     }
-    if ((0, import_utils21.isString)(idField)) {
+    if ((0, import_utils22.isString)(idField)) {
       return idField;
     }
     return "_id";
@@ -4223,11 +5306,11 @@ var Core = class {
   async genPopulate(modelName, access = "read", _populate = null, subPaths = []) {
     if (!_populate) return [];
     let populate = Array.isArray(_populate) ? _populate : [_populate];
-    populate = (0, import_utils21.compact)(
+    populate = (0, import_utils22.compact)(
       await Promise.all(
         populate.map(async (p) => {
-          const populateAccess = !(0, import_utils21.isString)(p) && p.access ? p.access : access;
-          const ret = (0, import_utils21.isString)(p) ? { path: p } : {
+          const populateAccess = !(0, import_utils22.isString)(p) && p.access ? p.access : access;
+          const ret = (0, import_utils22.isString)(p) ? { path: p } : {
             path: p.path,
             select: normalizeSelect(p.select)
           };
@@ -4265,10 +5348,10 @@ var Core = class {
   }
   async validate(modelName, allowedData, access, context) {
     const validate = getModelOption(modelName, `validate.${access}`, null);
-    if ((0, import_utils21.isFunction)(validate)) {
+    if ((0, import_utils22.isFunction)(validate)) {
       const permissions = this.getGlobalPermissions();
       return validate.call(this.req, allowedData, permissions, context);
-    } else if ((0, import_utils21.isBoolean)(validate) || (0, import_utils21.isArray)(validate)) {
+    } else if ((0, import_utils22.isBoolean)(validate) || (0, import_utils22.isArray)(validate)) {
       return validate;
     } else {
       return true;
@@ -4293,7 +5376,7 @@ var Core = class {
     const changeOptions = getModelOption(modelName, `onChange`, {});
     for (let x = 0; x < context.modifiedPaths.length; x++) {
       const mpath = context.modifiedPaths[x];
-      if ((0, import_utils21.isFunction)(changeOptions[mpath])) {
+      if ((0, import_utils22.isFunction)(changeOptions[mpath])) {
         await changeOptions[mpath].call(
           this.req,
           context.originalDocumentSnapshot[mpath],
@@ -4317,7 +5400,7 @@ var Core = class {
   async genDocPermissions(modelName, doc, access, context) {
     const docPermissionsFn = getModelOption(modelName, `docPermissions.${access}`, null);
     let docPermissions = {};
-    if ((0, import_utils21.isFunction)(docPermissionsFn)) {
+    if ((0, import_utils22.isFunction)(docPermissionsFn)) {
       const permissions = this.getGlobalPermissions();
       try {
         docPermissions = await docPermissionsFn.call(this.req, doc, permissions, context);
@@ -4368,7 +5451,7 @@ var Core = class {
       readExists ? this.genAllowedFields(modelName, doc, "read") : [],
       updateExists ? this.genAllowedFields(modelName, doc, "update") : []
     ]);
-    const viewObj = (0, import_utils21.reduce)(
+    const viewObj = (0, import_utils22.reduce)(
       views,
       (ret, view) => {
         ret[view] = true;
@@ -4376,7 +5459,7 @@ var Core = class {
       },
       {}
     );
-    const editObj = (0, import_utils21.reduce)(
+    const editObj = (0, import_utils22.reduce)(
       edits,
       (ret, view) => {
         ret[view] = true;
@@ -4400,9 +5483,9 @@ var Core = class {
     return runDecorateAllHook({ req: this.req, hook: decorateAll, docs, permissions, context });
   }
   runTasks(modelName, docObject, task) {
-    const tasks = (0, import_utils21.compact)((0, import_utils21.castArray)(task));
+    const tasks = (0, import_utils22.compact)((0, import_utils22.castArray)(task));
     if (tasks.length === 0) return docObject;
-    (0, import_utils21.forEach)(tasks, (task2) => {
+    (0, import_utils22.forEach)(tasks, (task2) => {
       const { type, args, options } = task2;
       switch (type) {
         case "COPY_AND_DEPOPULATE":
@@ -4412,6 +5495,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;
@@ -4435,9 +5553,9 @@ var Core = class {
       }
       const [, field, op] = keys2;
       const subOption = getExactModelOption(modelName, `operationAccess.${access}`);
-      if ((0, import_utils21.isUndefined)(subOption)) {
+      if ((0, import_utils22.isUndefined)(subOption)) {
         const subFieldOption = getExactModelOption(modelName, `operationAccess.subs.${field}`);
-        if ((0, import_utils21.isUndefined)(subFieldOption)) {
+        if ((0, import_utils22.isUndefined)(subFieldOption)) {
           const opOption = getModelOption(modelName, `operationAccess.${op}`);
           return this.canActivate(opOption);
         }
@@ -4489,25 +5607,25 @@ function guard(condition) {
     const permissions = req[PERMISSIONS];
     let cond = condition;
     let phas = (key) => permissions.has(key);
-    if ((0, import_utils22.isPlainObject)(condition)) {
+    if ((0, import_utils23.isPlainObject)(condition)) {
       const { modelName, id, condition: _cond } = condition;
       const svc = req.macl.getPublicService(modelName);
       const select = getModelOption(modelName, `alwaysSelectFields.read`, void 0);
-      let _id = (0, import_utils22.isString)(id) ? id : null;
-      if ((0, import_utils22.isPlainObject)(id)) {
+      let _id = (0, import_utils23.isString)(id) ? id : null;
+      if ((0, import_utils23.isPlainObject)(id)) {
         const { type = "param", key } = id;
         if (type === "param") {
           const paramValue = req.params[key];
-          _id = (0, import_utils22.isArray)(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
+          _id = (0, import_utils23.isArray)(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
         } else if (type === "query") {
           const _qval = req.query[key];
-          if ((0, import_utils22.isArray)(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
+          if ((0, import_utils23.isArray)(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
           else _id = _qval;
         } else {
           _id = null;
         }
       }
-      if (!(0, import_utils22.isString)(_id) || !_id) {
+      if (!(0, import_utils23.isString)(_id) || !_id) {
         return next(new import_express_json_router2.default.clientErrors.BadRequestError());
       }
       const result = await svc._read(_id, { select });
@@ -4519,11 +5637,11 @@ function guard(condition) {
       cond = _cond;
     }
     const { stringHandler, arrayHandler } = createValidator(phas);
-    if ((0, import_utils22.isString)(cond)) {
+    if ((0, import_utils23.isString)(cond)) {
       if (stringHandler(cond)) return next();
-    } else if ((0, import_utils22.isArray)(cond)) {
+    } else if ((0, import_utils23.isArray)(cond)) {
       if (arrayHandler(cond)) return next();
-    } else if ((0, import_utils22.isFunction)(cond)) {
+    } else if ((0, import_utils23.isFunction)(cond)) {
       const result = await cond.call(req, permissions);
       if (!!result) return next();
     }
@@ -4536,7 +5654,7 @@ var import_express2 = __toESM(require("express"));
 
 // src/routers/model-router.ts
 var import_express_json_router5 = __toESM(require("@web-ts-toolkit/express-json-router"));
-var import_utils25 = require("@web-ts-toolkit/utils");
+var import_utils27 = require("@web-ts-toolkit/utils");
 
 // src/routers/router-mutation.ts
 var MODEL_BUILD_TIME_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -4665,6 +5783,7 @@ var import_express_json_router4 = __toESM(require("@web-ts-toolkit/express-json-
 
 // src/validation/common.ts
 var import_zod2 = require("zod");
+var import_utils24 = require("@web-ts-toolkit/utils");
 var stringOrStringArray = import_zod2.z.union([import_zod2.z.string(), import_zod2.z.array(import_zod2.z.string())]);
 var safeIntegerString = (min, message) => import_zod2.z.string().regex(/^\d+$/, message).refine((value) => Number.isSafeInteger(Number(value)), "Expected a safe integer").refine((value) => Number(value) >= min, message);
 var queryBooleanString = import_zod2.z.enum(["true", "false"]);
@@ -4725,7 +5844,8 @@ var subPopulateSchema = import_zod2.z.union([
     select: projectionSchema.optional()
   }).passthrough()
 ]);
-var includeItemSchema = import_zod2.z.object({
+var legacyIncludeItemSchema = import_zod2.z.object({
+  mode: import_zod2.z.enum(["legacy"]).optional(),
   model: import_zod2.z.string().min(1),
   op: import_zod2.z.enum(["list", "read", "count"]),
   path: import_zod2.z.string().min(1),
@@ -4734,8 +5854,139 @@ var includeItemSchema = import_zod2.z.object({
   foreignField: import_zod2.z.string().min(1),
   args: import_zod2.z.unknown().optional().describe("Forwarded to list/read includes. Count includes ignore pagination fields so counts remain exact."),
   options: import_zod2.z.unknown().optional()
-}).passthrough();
-var includeSchema = import_zod2.z.union([includeItemSchema, import_zod2.z.array(includeItemSchema)]);
+}).passthrough().superRefine((entry, ctx) => {
+  if (entry.filter !== void 0 && containsParentMarkerShape(entry.filter)) {
+    ctx.addIssue({
+      code: import_zod2.z.ZodIssueCode.custom,
+      message: 'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")',
+      path: ["filter"]
+    });
+  }
+});
+var parentRefSchema = import_zod2.z.object({ $parent: import_zod2.z.string().min(1) }).strict().superRefine((value, ctx) => {
+  if (!isValidParentRefPath(value.$parent)) {
+    ctx.addIssue({
+      code: import_zod2.z.ZodIssueCode.custom,
+      message: `Invalid $parent reference path: ${value.$parent}`,
+      path: ["$parent"]
+    });
+  }
+});
+var correlatedIdSchema = import_zod2.z.union([import_zod2.z.string().min(1), parentRefSchema]);
+var correlatedFilterSchema = import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).superRefine((filter2, ctx) => {
+  for (const issue of validateCorrelatedFilterTemplate(filter2)) {
+    ctx.addIssue({
+      code: import_zod2.z.ZodIssueCode.custom,
+      message: issue.message,
+      path: issue.path.map(String)
+    });
+  }
+});
+var correlatedEmptyOptionsSchema = import_zod2.z.unknown().refine(
+  (value) => value === void 0 || (0, import_utils24.isPlainObject)(value) && Object.keys(value).length === 0,
+  "Correlated include options must be absent or empty"
+).optional();
+var correlatedPathSchema = import_zod2.z.string().min(1).superRefine((path, ctx) => {
+  if (!isValidCorrelatedOutputPath(path)) {
+    ctx.addIssue({
+      code: import_zod2.z.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: import_zod2.z.ZodIssueCode.custom, message: selectIssue.message, path: ["select"] });
+  }
+  const sortIssue = findArgsMarkerIssue(sort, "args.sort");
+  if (sortIssue) {
+    ctx.addIssue({ code: import_zod2.z.ZodIssueCode.custom, message: sortIssue.message, path: ["sort"] });
+  }
+};
+var correlatedReadArgsSchema = import_zod2.z.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  include: import_zod2.z.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedListArgsSchema = import_zod2.z.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  skip: import_zod2.z.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  limit: import_zod2.z.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  page: import_zod2.z.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  pageSize: import_zod2.z.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  include: import_zod2.z.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedCountArgsSchema = import_zod2.z.unknown().refine(
+  (value) => value === void 0 || (0, import_utils24.isPlainObject)(value) && Object.keys(value).length === 0,
+  "Count includes accept no args"
+).optional();
+var correlatedReadByIdSchema = import_zod2.z.object({
+  mode: import_zod2.z.literal("correlated"),
+  model: import_zod2.z.string().min(1),
+  op: import_zod2.z.literal("read"),
+  path: correlatedPathSchema,
+  id: correlatedIdSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedReadByFilterSchema = import_zod2.z.object({
+  mode: import_zod2.z.literal("correlated"),
+  model: import_zod2.z.string().min(1),
+  op: import_zod2.z.literal("read"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedListSchema = import_zod2.z.object({
+  mode: import_zod2.z.literal("correlated"),
+  model: import_zod2.z.string().min(1),
+  op: import_zod2.z.literal("list"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedListArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedCountSchema = import_zod2.z.object({
+  mode: import_zod2.z.literal("correlated"),
+  model: import_zod2.z.string().min(1),
+  op: import_zod2.z.literal("count"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedCountArgsSchema,
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var includeItemSchema = import_zod2.z.union([
+  legacyIncludeItemSchema,
+  correlatedReadByIdSchema,
+  correlatedReadByFilterSchema,
+  correlatedListSchema,
+  correlatedCountSchema
+]);
+var correlatedNestedIncludeSchema = import_zod2.z.union([includeItemSchema, import_zod2.z.array(includeItemSchema)]);
+var rejectDuplicateCorrelatedPaths = (items, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if ((0, import_utils24.isPlainObject)(item) && item.mode === "correlated" && typeof item.path === "string") {
+      if (seen.has(item.path)) {
+        ctx.addIssue({
+          code: import_zod2.z.ZodIssueCode.custom,
+          message: `Duplicate correlated include output path: ${item.path}`,
+          path: [index, "path"]
+        });
+      } else {
+        seen.add(item.path);
+      }
+    }
+  });
+};
+var includeSchema = import_zod2.z.union([
+  includeItemSchema,
+  import_zod2.z.array(includeItemSchema).superRefine(rejectDuplicateCorrelatedPaths)
+]);
 var fieldsSchema = import_zod2.z.array(import_zod2.z.string().min(1));
 var taskSchema = import_zod2.z.object({
   type: import_zod2.z.string().min(1),
@@ -5272,7 +6523,7 @@ var listBodySchema = import_zod3.z.object({
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
 var countBodySchema = import_zod3.z.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 = import_zod3.z.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
@@ -5627,7 +6878,7 @@ var rootDataQueryEntrySchema = import_zod5.z.union([
 var rootQuerySchema = import_zod5.z.array(import_zod5.z.union([rootModelQueryEntrySchema, rootDataQueryEntrySchema]));
 
 // src/routers/shared.ts
-var import_utils23 = require("@web-ts-toolkit/utils");
+var import_utils25 = require("@web-ts-toolkit/utils");
 
 // src/routers/model-router-collection-routes.ts
 function setModelCollectionRoutes(context) {
@@ -5645,14 +6896,14 @@ function setModelCollectionRoutes(context) {
     await context.assertAllowed(req, "list");
     const { skip, limit, page, page_size, skim, include_permissions, include_count, include_extra_headers } = parseQuery(requestSchemas.listQuery, req.query);
     const svc = context.getPublicService(req);
-    const includeCount = (0, import_utils23.parseBooleanString)(include_count);
-    const includeExtraHeaders = (0, import_utils23.parseBooleanString)(include_extra_headers);
+    const includeCount = (0, import_utils25.parseBooleanString)(include_count);
+    const includeExtraHeaders = (0, import_utils25.parseBooleanString)(include_extra_headers);
     const result = await svc._list(
       {},
       { skip, limit, page, pageSize: page_size },
       {
-        skim: (0, import_utils23.parseBooleanString)(skim),
-        includePermissions: (0, import_utils23.parseBooleanString)(include_permissions),
+        skim: (0, import_utils25.parseBooleanString)(skim),
+        includePermissions: (0, import_utils25.parseBooleanString)(include_permissions),
         includeCount
       }
     );
@@ -5707,7 +6958,7 @@ function setModelCollectionRoutes(context) {
       context.getRequestSchema("requestSchemas.create")
     );
     const svc = context.getPublicService(req);
-    const result = await svc._create(data, {}, { includePermissions: (0, import_utils23.parseBooleanString)(include_permissions) });
+    const result = await svc._create(data, {}, { includePermissions: (0, import_utils25.parseBooleanString)(include_permissions) });
     handleResultError(result);
     return formatModelCreatedResponse(result);
   });
@@ -5743,7 +6994,7 @@ function setModelCollectionRoutes(context) {
       finalData,
       { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
-        includePermissions: includePermissions ?? (0, import_utils23.parseBooleanString)(include_permissions),
+        includePermissions: includePermissions ?? (0, import_utils25.parseBooleanString)(include_permissions),
         populateAccess
       }
     );
@@ -5835,8 +7086,8 @@ function setModelDocumentRoutes(context) {
       id,
       {},
       {
-        includePermissions: (0, import_utils23.parseBooleanString)(include_permissions),
-        tryList: (0, import_utils23.parseBooleanString)(try_list)
+        includePermissions: (0, import_utils25.parseBooleanString)(include_permissions),
+        tryList: (0, import_utils25.parseBooleanString)(try_list)
       }
     );
     handleResultError(result);
@@ -5921,8 +7172,8 @@ function setModelDocumentRoutes(context) {
       data,
       {},
       {
-        returningAll: (0, import_utils23.parseBooleanString)(returning_all),
-        includePermissions: (0, import_utils23.parseBooleanString)(include_permissions)
+        returningAll: (0, import_utils25.parseBooleanString)(returning_all),
+        includePermissions: (0, import_utils25.parseBooleanString)(include_permissions)
       }
     );
     handleResultError(result);
@@ -5968,8 +7219,8 @@ function setModelDocumentRoutes(context) {
       finalData,
       { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
-        returningAll: returningAll ?? (0, import_utils23.parseBooleanString)(returning_all),
-        includePermissions: includePermissions ?? (0, import_utils23.parseBooleanString)(include_permissions),
+        returningAll: returningAll ?? (0, import_utils25.parseBooleanString)(returning_all),
+        includePermissions: includePermissions ?? (0, import_utils25.parseBooleanString)(include_permissions),
         populateAccess
       }
     );
@@ -5997,8 +7248,8 @@ function setModelDocumentRoutes(context) {
       body,
       {},
       {
-        returningAll: (0, import_utils23.parseBooleanString)(returning_all),
-        includePermissions: (0, import_utils23.parseBooleanString)(include_permissions)
+        returningAll: (0, import_utils25.parseBooleanString)(returning_all),
+        includePermissions: (0, import_utils25.parseBooleanString)(include_permissions)
       }
     );
     handleResultError(result);
@@ -6042,8 +7293,8 @@ function setModelDocumentRoutes(context) {
       finalData,
       { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
-        returningAll: returningAll ?? (0, import_utils23.parseBooleanString)(returning_all),
-        includePermissions: includePermissions ?? (0, import_utils23.parseBooleanString)(include_permissions),
+        returningAll: returningAll ?? (0, import_utils25.parseBooleanString)(returning_all),
+        includePermissions: includePermissions ?? (0, import_utils25.parseBooleanString)(include_permissions),
         populateAccess
       }
     );
@@ -6281,11 +7532,11 @@ function setModelSubDocumentRoutes(context) {
 }
 
 // src/openapi/route-registration.ts
-var import_utils24 = require("@web-ts-toolkit/utils");
+var import_utils26 = require("@web-ts-toolkit/utils");
 function registerOpenApiRoute(runtime, basePath, defaultTag, route) {
   runtime.registerOpenApiRoute({
     ...route,
-    path: (0, import_utils24.normalizeUrlPath)(basePath + route.path),
+    path: (0, import_utils26.normalizeUrlPath)(basePath + route.path),
     tags: route.tags ?? [defaultTag]
   });
 }
@@ -6293,8 +7544,8 @@ function registerOpenApiRoute(runtime, basePath, defaultTag, route) {
 // src/routers/model-router.ts
 var clientErrors2 = import_express_json_router5.default.clientErrors;
 function setOption(parentKey, optionKey, option) {
-  const key = (0, import_utils25.isUndefined)(option) ? parentKey : `${parentKey}.${optionKey}`;
-  const value = (0, import_utils25.isUndefined)(option) ? optionKey : option;
+  const key = (0, import_utils27.isUndefined)(option) ? parentKey : `${parentKey}.${optionKey}`;
+  const value = (0, import_utils27.isUndefined)(option) ? optionKey : option;
   assertMutableRouterOption("model", key);
   this.runtime.setModelOption(this.modelName, key, value);
   return this;
@@ -6456,7 +7707,7 @@ var ModelRouter = class _ModelRouter {
     this.runtime = runtime;
     this.runtime.setModelOptions(modelName, initialOptions);
     this.options = this.runtime.getModelOptions(modelName);
-    this.fullBasePath = (0, import_utils25.normalizeUrlPath)(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = (0, import_utils27.normalizeUrlPath)(this.options.parentPath + this.options.basePath);
     this.modelName = modelName;
     this.router = new import_express_json_router5.default(this.options.basePath, createSetCore(this.runtime), accessRouterResponseHandler);
     this.model = new model_default(modelName, this.runtime);
@@ -6536,13 +7787,13 @@ var ModelRouter = class _ModelRouter {
   }
   logEndpoints() {
     runWithRuntime(this.runtime, () => {
-      (0, import_utils25.forEach)(this.router.getEndpoints(), ({ method, path }) => {
-        logInfoMessage(`${(0, import_utils25.padEnd)(method, 6)} ${(0, import_utils25.normalizeUrlPath)(this.options.parentPath + path)}`);
+      (0, import_utils27.forEach)(this.router.getEndpoints(), ({ method, path }) => {
+        logInfoMessage(`${(0, import_utils27.padEnd)(method, 6)} ${(0, import_utils27.normalizeUrlPath)(this.options.parentPath + path)}`);
       });
     });
   }
   set(keyOrOptions, value) {
-    if (arguments.length === 2 && (0, import_utils25.isString)(keyOrOptions)) {
+    if (arguments.length === 2 && (0, import_utils27.isString)(keyOrOptions)) {
       assertMutableRouterOption("model", keyOrOptions);
       this.runtime.setModelOption(
         this.modelName,
@@ -6550,7 +7801,7 @@ var ModelRouter = class _ModelRouter {
         value
       );
     }
-    if (arguments.length === 1 && (0, import_utils25.isPlainObject)(keyOrOptions)) {
+    if (arguments.length === 1 && (0, import_utils27.isPlainObject)(keyOrOptions)) {
       assertMutableRouterOptions("model", keyOrOptions);
       this.runtime.setModelOptions(this.modelName, keyOrOptions);
     }
@@ -6573,7 +7824,7 @@ var ModelRouter = class _ModelRouter {
 
 // src/routers/root-router.ts
 var import_express_json_router6 = __toESM(require("@web-ts-toolkit/express-json-router"));
-var import_utils26 = require("@web-ts-toolkit/utils");
+var import_utils28 = require("@web-ts-toolkit/utils");
 
 // src/core-data.ts
 var DataCore = class {
@@ -6839,7 +8090,7 @@ var RootRouter = class {
     this.setRoutes();
   }
   registerOpenApiRoute(route) {
-    registerOpenApiRoute(this.runtime, (0, import_utils26.normalizeUrlPath)(this.basename), "root", route);
+    registerOpenApiRoute(this.runtime, (0, import_utils28.normalizeUrlPath)(this.basename), "root", route);
   }
   wrapResult(index, item, result) {
     return {
@@ -6900,7 +8151,7 @@ var RootRouter = class {
   groupItemsByOrder(items) {
     const groups = /* @__PURE__ */ new Map();
     items.forEach((item, index) => {
-      const order = (0, import_utils26.isNumber)(item.order) ? item.order : 0;
+      const order = (0, import_utils28.isNumber)(item.order) ? item.order : 0;
       const group = groups.get(order);
       if (group) {
         group.push({ index, item });
@@ -6971,7 +8222,7 @@ var RootRouter = class {
         const arrResult = await this.runGroup(req, groupedItems[x]);
         results.push(...arrResult);
       }
-      return (0, import_utils26.orderBy)(results, ["index"], ["asc"]);
+      return (0, import_utils28.orderBy)(results, ["index"], ["asc"]);
     });
     this.registerOpenApiRoute({
       method: "post",
@@ -6989,11 +8240,11 @@ var RootRouter = class {
 
 // src/routers/data-router.ts
 var import_express_json_router7 = __toESM(require("@web-ts-toolkit/express-json-router"));
-var import_utils27 = require("@web-ts-toolkit/utils");
+var import_utils29 = require("@web-ts-toolkit/utils");
 var clientErrors4 = import_express_json_router7.default.clientErrors;
 function setOption2(parentKey, optionKey, option) {
-  const key = (0, import_utils27.isUndefined)(option) ? parentKey : `${parentKey}.${optionKey}`;
-  const value = (0, import_utils27.isUndefined)(option) ? optionKey : option;
+  const key = (0, import_utils29.isUndefined)(option) ? parentKey : `${parentKey}.${optionKey}`;
+  const value = (0, import_utils29.isUndefined)(option) ? optionKey : option;
   assertMutableRouterOption("data", key);
   this.runtime.setDataOption(this.dataName, key, value);
   return this;
@@ -7034,7 +8285,7 @@ var DataRouter = class {
     this.runtime = runtime;
     this.runtime.setDataOptions(dataName, initialOptions);
     this.options = this.runtime.getDataOptions(dataName);
-    this.fullBasePath = (0, import_utils27.normalizeUrlPath)(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = (0, import_utils29.normalizeUrlPath)(this.options.parentPath + this.options.basePath);
     this.dataName = dataName;
     this.router = new import_express_json_router7.default(this.options.basePath, createSetDataCore(this.runtime), accessRouterResponseHandler);
     this.setCollectionRoutes();
@@ -7067,8 +8318,8 @@ var DataRouter = class {
         req.query
       );
       const svc = this.getService(req);
-      const includeCount = (0, import_utils23.parseBooleanString)(include_count);
-      const includeExtraHeaders = (0, import_utils23.parseBooleanString)(include_extra_headers);
+      const includeCount = (0, import_utils25.parseBooleanString)(include_count);
+      const includeExtraHeaders = (0, import_utils25.parseBooleanString)(include_extra_headers);
       const result = await svc.find(
         {},
         { skip, limit, page, pageSize: page_size },
@@ -7186,11 +8437,11 @@ var DataRouter = class {
     });
   }
   set(keyOrOptions, value) {
-    if (arguments.length === 2 && (0, import_utils27.isString)(keyOrOptions)) {
+    if (arguments.length === 2 && (0, import_utils29.isString)(keyOrOptions)) {
       assertMutableRouterOption("data", keyOrOptions);
       this.runtime.setDataOption(this.dataName, keyOrOptions, value);
     }
-    if (arguments.length === 1 && (0, import_utils27.isPlainObject)(keyOrOptions)) {
+    if (arguments.length === 1 && (0, import_utils29.isPlainObject)(keyOrOptions)) {
       assertMutableRouterOptions("data", keyOrOptions);
       this.runtime.setDataOptions(this.dataName, keyOrOptions);
     }
@@ -7313,7 +8564,7 @@ function createRuntimeApi(runtime) {
   const wtt2 = runtimeMiddleware;
   wtt2.runtime = runtime;
   wtt2.createRouter = function(modelName, options) {
-    if ((0, import_utils28.isUndefined)(options)) {
+    if ((0, import_utils30.isUndefined)(options)) {
       return new RootRouter(modelName, runtime);
     }
     if (typeof modelName === "string") {
@@ -7334,10 +8585,10 @@ function createRuntimeApi(runtime) {
   };
   wtt2.combineRoutes = combineRoutes;
   wtt2.set = function(keyOrOptions, value) {
-    if (arguments.length === 2 && (0, import_utils28.isString)(keyOrOptions)) {
+    if (arguments.length === 2 && (0, import_utils30.isString)(keyOrOptions)) {
       return runtime.setGlobalOption(keyOrOptions, value);
     }
-    if (arguments.length === 1 && (0, import_utils28.isPlainObject)(keyOrOptions)) {
+    if (arguments.length === 1 && (0, import_utils30.isPlainObject)(keyOrOptions)) {
       return runtime.setGlobalOptions(keyOrOptions);
     }
   };