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

package/index.mjs

@@ -1,16 +1,16 @@
 // src/index.ts
-import { isPlainObject as isPlainObject18, isString as isString10, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject20, isString as isString10, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
 
 // src/middleware.ts
 import JsonRouter2 from "@web-ts-toolkit/express-json-router";
-import { isArray as isArray11, isFunction as isFunction6, isPlainObject as isPlainObject15, isString as isString7 } from "@web-ts-toolkit/utils";
+import { isArray as isArray12, isFunction as isFunction6, isPlainObject as isPlainObject16, isString as isString7 } from "@web-ts-toolkit/utils";
 
 // src/core.ts
 import {
   castArray as castArray4,
   compact as compact3,
   forEach as forEach7,
-  isArray as isArray10,
+  isArray as isArray11,
   isBoolean as isBoolean5,
   isFunction as isFunction5,
   isString as isString6,
@@ -784,6 +784,29 @@ var cloneConfigValue = (value) => {
     ])
   );
 };
+var cloneForRead = (value) => {
+  if (Array.isArray(value)) {
+    if (Object.isFrozen(value)) {
+      return value;
+    }
+    return value.map((item) => cloneForRead(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    return value;
+  }
+  if (Object.isFrozen(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([entryKey, entryValue]) => [
+      entryKey,
+      cloneForRead(entryValue)
+    ])
+  );
+};
 var freezeConfigValue = (value) => {
   if (!value || typeof value !== "object") {
     return value;
@@ -799,6 +822,7 @@ var freezeConfigValue = (value) => {
   }
   return value;
 };
+var cloneAndFreezeForStore = (value) => freezeConfigValue(cloneForRead(value));
 var getNestedOption = (manager, key, defaultValue) => {
   const keys2 = String(key).split(".");
   if (keys2.length === 1) {
@@ -828,6 +852,14 @@ var OptionsManager = class {
         target[keystr] = value;
         _this.listeners[keystr] && _this.listeners[keystr].call(_this, value, keystr, target, oldvalue);
         return true;
+      },
+      defineProperty(target, key, descriptor) {
+        const keystr = String(key);
+        const oldvalue = target[keystr];
+        const result = Reflect.defineProperty(target, key, descriptor);
+        const newValue = target[keystr];
+        _this.listeners[keystr] && _this.listeners[keystr].call(_this, newValue, keystr, target, oldvalue);
+        return result;
       }
     });
   }
@@ -841,18 +873,18 @@ var OptionsManager = class {
   set(key, value) {
     const path = toPath(key);
     if (path.length <= 1) {
-      set2(this.currentOptions, path, this.preserveKeys.has(String(path[0])) ? value : cloneConfigValue(value));
+      set2(this.currentOptions, path, this.preserveKeys.has(String(path[0])) ? value : cloneAndFreezeForStore(value));
       return;
     }
     const [rootKey, ...nestedPath] = path;
     const currentRoot = get2(this.currentOptions, [rootKey], void 0);
     const baseRoot = isPlainObject8(currentRoot) ? currentRoot : {};
     const nextRoot = cloneConfigValue(baseRoot);
-    set2(nextRoot, nestedPath, cloneConfigValue(value));
-    set2(this.currentOptions, [rootKey], nextRoot);
+    set2(nextRoot, nestedPath, cloneForRead(value));
+    set2(this.currentOptions, [rootKey], freezeConfigValue(nextRoot));
   }
   fetch() {
-    const cloned = cloneConfigValue(this.currentOptions);
+    const cloned = cloneForRead(this.currentOptions);
     for (const key of this.preserveKeys) {
       if (key in this.currentOptions) {
         cloned[key] = this.currentOptions[key];
@@ -861,20 +893,20 @@ var OptionsManager = class {
     return freezeConfigValue(cloned);
   }
   assign(options) {
-    const cloned = cloneConfigValue(options);
+    const cloned = cloneForRead(options);
     for (const key of this.preserveKeys) {
       if (key in options) {
         cloned[key] = options[key];
       }
     }
-    assign(this.currentOptions, cloned);
+    assign(this.currentOptions, freezeConfigValue(cloned));
   }
   onchange(key, func) {
     set2(this.listeners, key, func);
     return this;
   }
   snapshot() {
-    const cloned = cloneConfigValue(this.currentOptions);
+    const cloned = cloneForRead(this.currentOptions);
     for (const key of this.preserveKeys) {
       if (key in this.currentOptions) {
         cloned[key] = this.currentOptions[key];
@@ -890,13 +922,13 @@ var OptionsManager = class {
         delete current[key];
       }
     }
-    const cloned = cloneConfigValue(snap);
+    const cloned = cloneForRead(snap);
     for (const key of this.preserveKeys) {
       if (key in snap) {
         cloned[key] = snap[key];
       }
     }
-    assign(current, cloned);
+    assign(current, freezeConfigValue(cloned));
   }
 };
 
@@ -911,7 +943,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;
@@ -931,6 +965,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") {
@@ -1366,8 +1408,7 @@ var AccessRuntime = class {
   }
   setDataOptions(dataName, options) {
     const manager = this.getOrCreateDataOptions(dataName);
-    const currentDataOptions = manager.fetch();
-    manager.assign({ ...currentDataOptions, ...options });
+    manager.assign(options);
   }
   setDataOption(dataName, key, value) {
     const manager = this.getOrCreateDataOptions(dataName);
@@ -1377,6 +1418,11 @@ var AccessRuntime = class {
     const manager = this.getOrCreateDataOptions(dataName);
     return manager.fetch();
   }
+  getDataSnapshot(dataName) {
+    const manager = this.getOrCreateDataOptions(dataName);
+    const snapshot = manager.get("data");
+    return snapshot ?? [];
+  }
   getDataOption(dataName, key, defaultValue) {
     const manager = this.getOrCreateDataOptions(dataName);
     return getNestedOption(manager, key, defaultValue);
@@ -1498,6 +1544,9 @@ var getRuntime4 = () => getActiveRuntime() ?? defaultRuntime;
 var getDataOptions = (dataName) => {
   return getRuntime4().getDataOptions(dataName);
 };
+var getDataSnapshot = (dataName) => {
+  return getRuntime4().getDataSnapshot(dataName);
+};
 var getDataOption = (dataName, key, defaultValue) => {
   return getRuntime4().getDataOption(dataName, key, defaultValue);
 };
@@ -1507,21 +1556,475 @@ var getRuntime5 = () => getActiveRuntime() ?? defaultRuntime;
 var getModelRef = (modelName, refPath) => {
   return getRuntime5().getModelRef(modelName, refPath);
 };
-var getModelSub = (modelName) => {
-  return getRuntime5().getModelSub(modelName);
-};
 
 // src/services/base.ts
 import {
   castArray,
+  cloneDeep as cloneDeep2,
   compact,
   flatten,
   forEach as forEach3,
   get as get4,
-  isArray as isArray6,
-  isPlainObject as isPlainObject11,
+  isArray as isArray7,
+  isPlainObject as isPlainObject12,
   uniq
 } from "@web-ts-toolkit/utils";
+
+// src/correlated-includes.ts
+import { cloneDeep, isArray as isArray6, isPlainObject as isPlainObject11 } from "@web-ts-toolkit/utils";
+var PARENT_MARKER_KEY = "$parent";
+var ESCAPE_WRAPPER_KEY = "$escape";
+var SUBQUERY_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["$$sq", "$$date"]);
+var MARKER_FORBIDDEN_OPERATOR_KEYS = /* @__PURE__ */ new Set(["$text", "$where", "$comment"]);
+var LOGICAL_CLAUSE_KEYS = /* @__PURE__ */ new Set(["$and", "$or", "$nor"]);
+var DANGEROUS_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var FIELD_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var ARRAY_INDEX_SEGMENT_PATTERN = /^(0|[1-9]\d*)$/;
+var ownKeys = (value) => Object.keys(value);
+function isParentRefMarker(value) {
+  return isPlainObject11(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
+}
+function isEscapedParentRef(value) {
+  return isPlainObject11(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === ESCAPE_WRAPPER_KEY;
+}
+function hasMarkerKey(value) {
+  return ownKeys(value).includes(PARENT_MARKER_KEY) || ownKeys(value).includes(ESCAPE_WRAPPER_KEY);
+}
+function isValidParentRefPath(path) {
+  if (typeof path !== "string" || path.length === 0) return false;
+  const segments = path.split(".");
+  return segments.every(
+    (segment) => (FIELD_SEGMENT_PATTERN.test(segment) || ARRAY_INDEX_SEGMENT_PATTERN.test(segment)) && !DANGEROUS_PATH_SEGMENTS.has(segment)
+  );
+}
+function isValidCorrelatedOutputPath(path) {
+  return typeof path === "string" && path.length > 0 && isValidFieldPath(path) && path !== "_id" && !path.startsWith("$");
+}
+function containsParentMarkerShape(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (current) => {
+    if (isParentRefMarker(current) || isEscapedParentRef(current)) return true;
+    if (isArray6(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      return current.some(visit);
+    }
+    if (isPlainObject11(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      if (hasMarkerKey(current)) return true;
+      return Object.values(current).some(visit);
+    }
+    return false;
+  };
+  return visit(value);
+}
+function scanTemplateValueNode(value, path, issues) {
+  if (isEscapedParentRef(value)) {
+    const inner = value.$escape;
+    if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
+      issues.push({
+        message: 'Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }',
+        path
+      });
+    }
+    return;
+  }
+  if (isParentRefMarker(value)) {
+    if (!isValidParentRefPath(value.$parent)) {
+      issues.push({
+        message: `Invalid $parent reference path at ${path.length === 0 ? "#" : path.join(".")}`,
+        path
+      });
+    }
+    return;
+  }
+  if (isPlainObject11(value)) {
+    if (hasMarkerKey(value)) {
+      issues.push({
+        message: 'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }',
+        path
+      });
+      return;
+    }
+    scanTemplateObjectEntries(value, path, issues);
+    return;
+  }
+  if (isArray6(value)) {
+    value.forEach((item, index) => scanTemplateValueNode(item, [...path, index], issues));
+  }
+}
+function scanTemplateObjectEntries(obj, basePath, issues) {
+  for (const [key, child] of Object.entries(obj)) {
+    const childPath = [...basePath, key];
+    if (key === PARENT_MARKER_KEY) {
+      issues.push({ message: "$parent is never a field name in correlated templates", path: childPath });
+      continue;
+    }
+    if (SUBQUERY_PAYLOAD_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in subquery payloads`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in ${key} values`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (key === "$elemMatch") {
+      if (isParentRefMarker(child) || isEscapedParentRef(child)) {
+        issues.push({
+          message: "Unsupported $parent reference as a direct $elemMatch value",
+          path: childPath
+        });
+        continue;
+      }
+      scanTemplateValueNode(child, childPath, issues);
+      continue;
+    }
+    if (LOGICAL_CLAUSE_KEYS.has(key)) {
+      if (!isArray6(child)) {
+        scanTemplateValueNode(child, childPath, issues);
+        continue;
+      }
+      child.forEach((clause, index) => {
+        const clausePath = [...childPath, index];
+        if (isParentRefMarker(clause) || isEscapedParentRef(clause)) {
+          issues.push({
+            message: `Unsupported $parent reference as a direct ${key} clause: clauses must be filter objects`,
+            path: clausePath
+          });
+          return;
+        }
+        if (isPlainObject11(clause)) {
+          scanTemplateObjectEntries(clause, clausePath, issues);
+        }
+      });
+      continue;
+    }
+    scanTemplateValueNode(child, childPath, issues);
+  }
+}
+function validateCorrelatedFilterTemplate(filter2) {
+  const issues = [];
+  if (!isPlainObject11(filter2)) {
+    issues.push({ message: "Correlated include filter must be an object", path: [] });
+    return issues;
+  }
+  if (isParentRefMarker(filter2) || isEscapedParentRef(filter2)) {
+    issues.push({ message: "Correlated include filter must not itself be a $parent reference", path: [] });
+    return issues;
+  }
+  scanTemplateObjectEntries(filter2, [], issues);
+  return issues;
+}
+function validateCorrelatedIdTemplate(id) {
+  if (typeof id === "string") {
+    return id.length > 0 ? [] : [{ message: "Correlated include id must be a non-empty string or $parent reference", path: [] }];
+  }
+  if (isEscapedParentRef(id)) {
+    return [{ message: "Unsupported $escape as a correlated include id", path: [] }];
+  }
+  if (isParentRefMarker(id)) {
+    return isValidParentRefPath(id.$parent) ? [] : [{ message: "Invalid $parent reference path in correlated include id", path: [] }];
+  }
+  return [{ message: "Correlated include id must be a string or $parent reference", path: [] }];
+}
+function findArgsMarkerIssue(value, where) {
+  if (value !== void 0 && containsParentMarkerShape(value)) {
+    return {
+      message: `Unsupported $parent reference in ${where}: references are only supported in filter and id positions`,
+      path: []
+    };
+  }
+  return null;
+}
+function collectFilterReferencePaths(filter2) {
+  const paths = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visitValue = (value) => {
+    if (isParentRefMarker(value)) {
+      if (typeof value.$parent === "string") {
+        paths.push(value.$parent);
+      }
+      return;
+    }
+    if (isEscapedParentRef(value)) return;
+    if (isArray6(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
+      value.forEach(visitValue);
+      return;
+    }
+    if (isPlainObject11(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
+      for (const [key, child] of Object.entries(value)) {
+        if (SUBQUERY_PAYLOAD_KEYS.has(key) || MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) continue;
+        visitValue(child);
+      }
+    }
+  };
+  visitValue(filter2);
+  return paths;
+}
+function collectCorrelatedReferencePaths(include) {
+  const paths = [];
+  if (isParentRefMarker(include.id) && typeof include.id !== "string") {
+    const ref = include.id;
+    if (typeof ref.$parent === "string") paths.push(ref.$parent);
+  } else if (typeof include.id === "string") {
+  }
+  const filter2 = include.filter;
+  if (filter2 !== void 0) {
+    paths.push(...collectFilterReferencePaths(filter2));
+  }
+  return [...new Set(paths)];
+}
+var CorrelatedReferenceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CorrelatedReferenceError";
+  }
+};
+var UNRESOLVABLE = /* @__PURE__ */ Symbol("correlated-include-unresolvable");
+function getOwnPathValue(parent, path) {
+  const segments = path.split(".");
+  let current = parent;
+  for (const segment of segments) {
+    if (DANGEROUS_PATH_SEGMENTS.has(segment)) {
+      throw new CorrelatedReferenceError(`Invalid $parent reference path: ${path}`);
+    }
+    if (typeof current !== "object" || current === null) return void 0;
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function cloneSubstitutedValue(value) {
+  if (isPlainObject11(value) || isArray6(value)) return cloneDeep(value);
+  return value;
+}
+function literalParentRefObject(path) {
+  const literal = {};
+  Object.defineProperty(literal, PARENT_MARKER_KEY, {
+    value: path,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+  return literal;
+}
+function resolveObjectEntries(obj, parent) {
+  const out = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === PARENT_MARKER_KEY) {
+      throw new CorrelatedReferenceError("$parent is never a field name in correlated templates");
+    }
+    if (SUBQUERY_PAYLOAD_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        throw new CorrelatedReferenceError(`Unsupported $parent reference inside ${key}`);
+      }
+      out[key] = cloneSubstitutedValue(child);
+      continue;
+    }
+    if (MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        throw new CorrelatedReferenceError(`Unsupported $parent reference inside ${key}`);
+      }
+      out[key] = cloneSubstitutedValue(child);
+      continue;
+    }
+    if (key === "$elemMatch") {
+      if (isParentRefMarker(child) || isEscapedParentRef(child)) {
+        throw new CorrelatedReferenceError("Unsupported $parent reference as a direct $elemMatch value");
+      }
+      out[key] = resolveValueNode(child, parent, false);
+      continue;
+    }
+    if (LOGICAL_CLAUSE_KEYS.has(key)) {
+      if (!isArray6(child)) {
+        out[key] = resolveValueNode(child, parent, false);
+        continue;
+      }
+      out[key] = child.map((clause) => {
+        if (isParentRefMarker(clause) || isEscapedParentRef(clause)) {
+          throw new CorrelatedReferenceError(`Unsupported $parent reference as a direct ${key} clause`);
+        }
+        if (!isPlainObject11(clause)) return cloneSubstitutedValue(clause);
+        return resolveObjectEntries(clause, parent);
+      });
+      continue;
+    }
+    if (key.startsWith("$")) {
+      out[key] = resolveValueNode(child, parent, false);
+      continue;
+    }
+    out[key] = resolveValueNode(child, parent, true);
+  }
+  return out;
+}
+function resolveValueNode(template, parent, bare) {
+  if (isEscapedParentRef(template)) {
+    const inner = template.$escape;
+    if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
+      throw new CorrelatedReferenceError('Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }');
+    }
+    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 && isPlainObject11(value)) return { $eq: cloneDeep(value) };
+    return cloneSubstitutedValue(value);
+  }
+  if (isPlainObject11(template)) {
+    if (hasMarkerKey(template)) {
+      throw new CorrelatedReferenceError(
+        'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }'
+      );
+    }
+    return resolveObjectEntries(template, parent);
+  }
+  if (isArray6(template)) {
+    return template.map((item) => resolveValueNode(item, parent, false));
+  }
+  return template;
+}
+function isUnresolvableSignal(error2) {
+  return error2 === UNRESOLVABLE;
+}
+function resolveCorrelatedIdTemplate(id, parent) {
+  try {
+    if (typeof id === "string") {
+      if (id.length === 0) throw new CorrelatedReferenceError("Correlated include id must be a non-empty string");
+      return { status: "resolved", id };
+    }
+    if (isParentRefMarker(id)) {
+      const path = id.$parent;
+      if (!isValidParentRefPath(path)) {
+        throw new CorrelatedReferenceError(`Invalid $parent reference path: ${String(path)}`);
+      }
+      const value = getOwnPathValue(parent, path);
+      if (typeof value === "string") return { status: "resolved", id: value };
+      if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return { status: "resolved", id: String(value) };
+      }
+      throw UNRESOLVABLE;
+    }
+    throw new CorrelatedReferenceError("Correlated include id must be a string or $parent reference");
+  } catch (error2) {
+    if (isUnresolvableSignal(error2)) return { status: "unresolvable" };
+    throw error2;
+  }
+}
+function resolveCorrelatedFilterTemplate(filter2, parent) {
+  try {
+    if (!isPlainObject11(filter2) || isParentRefMarker(filter2) || isEscapedParentRef(filter2)) {
+      throw new CorrelatedReferenceError("Correlated include filter must be an object");
+    }
+    return { status: "resolved", filter: resolveObjectEntries(filter2, parent) };
+  } catch (error2) {
+    if (isUnresolvableSignal(error2)) return { status: "unresolvable" };
+    throw error2;
+  }
+}
+function validateExpandedCorrelatedOperands(expanded, limits) {
+  return validateRequestComplexity(expanded, limits ?? null, "filter");
+}
+var MAX_NESTED_INCLUDE_DEPTH = 10;
+function validateCorrelatedArgsShape(args, op, depth) {
+  if (args === void 0) return [];
+  if (!isPlainObject11(args)) return ["Correlated include args must be an object"];
+  const record = args;
+  const allowed = op === "list" ? /* @__PURE__ */ new Set(["select", "sort", "skip", "limit", "page", "pageSize", "include"]) : /* @__PURE__ */ new Set(["select", "sort", "include"]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) return [`Unsupported correlated include arg: ${key}`];
+  }
+  if (op === "count" && Object.keys(record).length > 0) return ["Count includes accept no args"];
+  const selectIssue = findArgsMarkerIssue(record.select, "args.select");
+  if (selectIssue) return [selectIssue.message];
+  const sortIssue = findArgsMarkerIssue(record.sort, "args.sort");
+  if (sortIssue) return [sortIssue.message];
+  if (record.include !== void 0) {
+    if (depth >= MAX_NESTED_INCLUDE_DEPTH) return ["Correlated include nesting exceeds the supported depth"];
+    const nested = Array.isArray(record.include) ? record.include : [record.include];
+    for (const entry of nested) {
+      const errors = validateCorrelatedIncludeShape(entry, depth + 1);
+      if (errors.length > 0) return errors;
+    }
+  }
+  return [];
+}
+function validateCorrelatedIncludeShape(entry, depth = 0) {
+  if (!isPlainObject11(entry)) return ["Correlated include must be an object"];
+  const record = entry;
+  if (record.mode !== "correlated") return ['Correlated include mode must be "correlated"'];
+  if (typeof record.model !== "string" || record.model.length === 0)
+    return ["Correlated include model must be a non-empty string"];
+  if (record.op !== "list" && record.op !== "read" && record.op !== "count") {
+    return ['Correlated include op must be one of "list", "read", or "count"'];
+  }
+  if (!isValidCorrelatedOutputPath(record.path))
+    return [`Invalid correlated include output path: ${String(record.path)}`];
+  if ("localField" in record || "foreignField" in record) {
+    return ["Correlated includes must not carry localField or foreignField"];
+  }
+  if (record.options !== void 0 && !(isPlainObject11(record.options) && Object.keys(record.options).length === 0)) {
+    return ["Correlated include options must be absent or empty"];
+  }
+  const hasId = record.id !== void 0;
+  const hasFilter = record.filter !== void 0;
+  if (record.op === "read") {
+    if (hasId === hasFilter) return ['Correlated read includes require exactly one of "id" or "filter"'];
+    if (hasId) {
+      const issues = validateCorrelatedIdTemplate(record.id);
+      if (issues.length > 0) return [issues[0].message];
+    } else {
+      const issues = validateCorrelatedFilterTemplate(record.filter);
+      if (issues.length > 0) return [issues[0].message];
+    }
+  } else {
+    if (!hasFilter || hasId) return [`Correlated ${record.op} includes require a filter and no id`];
+    const issues = validateCorrelatedFilterTemplate(record.filter);
+    if (issues.length > 0) return [issues[0].message];
+  }
+  return validateCorrelatedArgsShape(record.args, record.op, depth);
+}
+function isCorrelatedInclude(value) {
+  return isPlainObject11(value) && value.mode === "correlated";
+}
+
+// src/services/base.ts
+var correlatedExecStates = /* @__PURE__ */ new WeakMap();
+function getCorrelatedTemplateDepth(includes) {
+  let max = 0;
+  const visit = (entries, depth) => {
+    const list = castArray(entries).filter(Boolean);
+    for (const entry of list) {
+      if (!isPlainObject12(entry)) continue;
+      max = Math.max(max, depth);
+      const nested = entry.args?.include;
+      if (nested !== void 0) {
+        visit(nested, depth + 1);
+      }
+    }
+  };
+  if (includes.length > 0) visit(includes, 1);
+  return max;
+}
 var ClientRequestError = class extends Error {
   constructor(result) {
     super(String(result.code));
@@ -1536,11 +2039,11 @@ function validateClientFilter(filter2) {
   }
   const blockedOperators = /* @__PURE__ */ new Set(["$where", "$expr", "$function", "$accumulator"]);
   const visit = (value, path) => {
-    if (isArray6(value)) {
+    if (isArray7(value)) {
       value.forEach((item, index) => visit(item, `${path}[${index}]`));
       return;
     }
-    if (!isPlainObject11(value)) return;
+    if (!isPlainObject12(value)) return;
     Object.entries(value).forEach(([key, child]) => {
       const nextPath = path ? `${path}.${key}` : key;
       if (blockedOperators.has(key)) {
@@ -1660,21 +2163,52 @@ var Base = class {
     return this.req.macl.getPublicService(modelName);
   }
   processInclude(include) {
-    const includes = compact(castArray(include)).filter(({ model, op, path, localField, foreignField }) => {
-      return model && op && path && localField && foreignField;
-    });
+    const items = compact(castArray(include));
+    const legacy = [];
+    const correlated = [];
+    const correlatedReferenceFields = [];
+    for (const entry of items) {
+      if (isCorrelatedInclude(entry)) {
+        const shapeErrors = validateCorrelatedIncludeShape(entry);
+        if (shapeErrors.length > 0) {
+          this.throwClientRequestError("bad_request" /* BadRequest */, shapeErrors[0]);
+        }
+        correlated.push(entry);
+        correlatedReferenceFields.push(...collectCorrelatedReferencePaths(entry));
+        continue;
+      }
+      if (containsParentMarkerShape(entry)) {
+        this.throwClientRequestError(
+          "bad_request" /* BadRequest */,
+          'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")'
+        );
+      }
+      const candidate = entry;
+      if (candidate.model && candidate.op && candidate.path && candidate.localField && candidate.foreignField) {
+        legacy.push(entry);
+      }
+    }
+    const seenCorrelatedPaths = /* @__PURE__ */ new Set();
+    for (const entry of correlated) {
+      if (seenCorrelatedPaths.has(entry.path)) {
+        this.throwClientRequestError("bad_request" /* BadRequest */, `Duplicate correlated include output path: ${entry.path}`);
+      }
+      seenCorrelatedPaths.add(entry.path);
+    }
     let includeLocalFields = [];
     let includePaths = [];
-    forEach3(includes, (inc) => {
+    forEach3(legacy, (inc) => {
       includeLocalFields.push(inc.localField);
       includePaths.push(inc.path);
     });
     includeLocalFields = uniq(compact(includeLocalFields));
     includePaths = uniq(compact(includePaths));
     return {
-      includes,
+      includes: legacy,
+      correlatedIncludes: correlated,
       includeLocalFields,
-      includePaths
+      includePaths,
+      correlatedReferenceFields: uniq(compact(correlatedReferenceFields))
     };
   }
   getForeignKeyValues(value) {
@@ -1717,7 +2251,7 @@ var Base = class {
     return ids.size;
   }
   sanitizeIncludeArgs(args) {
-    if (!isPlainObject11(args)) return {};
+    if (!isPlainObject12(args)) return {};
     const { overrides: _clientOverrides, ...trustedArgs } = args;
     return trustedArgs;
   }
@@ -1730,10 +2264,16 @@ var Base = class {
     if (!include) return docs;
     const includes = compact(castArray(include));
     if (includes.length === 0) return docs;
-    const isSingle = !isArray6(docs);
+    const isSingle = !isArray7(docs);
     let docList = isSingle ? [docs] : docs;
     for (let x = 0; x < includes.length; x++) {
       const include2 = includes[x];
+      if (isCorrelatedInclude(include2)) {
+        this.throwClientRequestError(
+          "bad_request" /* BadRequest */,
+          "Correlated includes are not supported by the legacy include executor"
+        );
+      }
       this.assertIncludeForeignField(include2);
       switch (include2.op) {
         case "count":
@@ -1812,6 +2352,356 @@ var Base = class {
     }
     return docs;
   }
+  getCorrelatedExecState() {
+    const key = this.req;
+    let state = correlatedExecStates.get(key);
+    if (!state) {
+      state = {
+        totalQueries: 0,
+        scheduler: new RequestConcurrencyScheduler(this.getRequestComplexity().maxBulkConcurrency)
+      };
+      correlatedExecStates.set(key, state);
+    }
+    return state;
+  }
+  claimCorrelatedQuerySlot() {
+    const limits = this.getRequestComplexity();
+    const state = this.getCorrelatedExecState();
+    if (state.totalQueries >= limits.maxCorrelatedQueries) {
+      this.throwClientRequestError(
+        "bad_request" /* BadRequest */,
+        `Correlated include query budget exceeded (max ${limits.maxCorrelatedQueries})`
+      );
+    }
+    state.totalQueries += 1;
+  }
+  sanitizeCorrelatedArgs(include) {
+    const args = include.args ?? {};
+    if (include.op === "list") {
+      const { select: select2, sort: sort2, skip, limit, page, pageSize, include: nestedInclude2 } = args;
+      return { select: select2, sort: sort2, skip, limit, page, pageSize, nestedInclude: nestedInclude2 };
+    }
+    const { select, sort, include: nestedInclude } = args;
+    return { select, sort, nestedInclude };
+  }
+  async includeCorrelatedDocs(docs, correlatedIncludes, snapshots, depth = 0) {
+    if (correlatedIncludes.length === 0) return docs;
+    const limits = this.getRequestComplexity();
+    const templateDepth = getCorrelatedTemplateDepth(correlatedIncludes);
+    if (depth + templateDepth > limits.maxCorrelatedDepth) {
+      this.throwClientRequestError(
+        "bad_request" /* BadRequest */,
+        `Correlated include depth exceeded (max ${limits.maxCorrelatedDepth})`
+      );
+    }
+    const state = this.getCorrelatedExecState();
+    const resolvedSnapshots = snapshots ?? docs.map((doc) => cloneDeep2(toObject(doc)));
+    for (const include of correlatedIncludes) {
+      switch (include.op) {
+        case "read":
+          await this.includeCorrelatedRead(docs, include, resolvedSnapshots, state, depth);
+          break;
+        case "list":
+          await this.includeCorrelatedList(docs, include, resolvedSnapshots, state, depth);
+          break;
+        case "count":
+          await this.includeCorrelatedCount(docs, include, resolvedSnapshots, state, depth);
+          break;
+        default:
+          this.throwClientRequestError(
+            "bad_request" /* BadRequest */,
+            `Unsupported correlated include op: ${include.op}`
+          );
+      }
+    }
+    return docs;
+  }
+  async includeCorrelatedRead(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "read");
+    const { select, sort, nestedInclude } = this.sanitizeCorrelatedArgs(include);
+    const hasId = include.id !== void 0;
+    if (hasId) {
+      const idTemplate = include.id;
+      const tasks2 = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+      await state.scheduler.map(tasks2, async ({ index, snapshot }) => {
+        let resolution;
+        try {
+          resolution = resolveCorrelatedIdTemplate(idTemplate, snapshot);
+        } catch (error2) {
+          if (error2 instanceof CorrelatedReferenceError) {
+            throw new ClientRequestError({
+              success: false,
+              kind: "error",
+              code: "bad_request" /* BadRequest */,
+              errors: [{ detail: error2.message }]
+            });
+          }
+          throw error2;
+        }
+        if (resolution.status === "unresolvable") {
+          setDocValue(docs[index], include.path, null);
+          return;
+        }
+        const resolvedId = resolution.id;
+        let idFilter;
+        try {
+          idFilter = await svc.genIDFilter(resolvedId);
+        } catch (error2) {
+          const clientResult = this.getClientRequestErrorResult(error2);
+          if (clientResult) throw new ClientRequestError(clientResult);
+          throw error2;
+        }
+        const authorized = await svc.genFilter("read", idFilter);
+        if (authorized === false) {
+          throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+        }
+        this.claimCorrelatedQuerySlot();
+        let result;
+        try {
+          result = await svc.findOne(
+            {},
+            {
+              select,
+              sort,
+              include: nestedInclude,
+              overrides: { filter: authorized }
+            },
+            { access: "read", lean: true, includePermissions: false }
+          );
+        } catch (error2) {
+          const clientResult = this.getClientRequestErrorResult(error2);
+          if (clientResult) throw new ClientRequestError(clientResult);
+          throw error2;
+        }
+        if (result.success) {
+          setDocValue(docs[index], include.path, result.data);
+        } else if (result.code === "not_found" /* NotFound */) {
+          setDocValue(docs[index], include.path, null);
+        } else {
+          throw new ClientRequestError(result);
+        }
+      });
+      return;
+    }
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    let parsedTemplate;
+    try {
+      parsedTemplate = await this.parseClientData(
+        filterTemplate,
+        state.scheduler
+      );
+    } catch (error2) {
+      const clientResult = this.getClientRequestErrorResult(error2);
+      if (clientResult) throw new ClientRequestError(clientResult);
+      throw error2;
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(parsedTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, null);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("read", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.findOne(
+          {},
+          {
+            select,
+            sort,
+            include: nestedInclude,
+            overrides: { filter: authorized }
+          },
+          { access: "read", lean: true, includePermissions: false }
+        );
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else if (result.code === "not_found" /* NotFound */) {
+        setDocValue(docs[index], include.path, null);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
+  }
+  async includeCorrelatedList(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "list");
+    const { select, sort, skip, limit, page, pageSize, nestedInclude } = this.sanitizeCorrelatedArgs(include);
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    let parsedTemplate;
+    try {
+      parsedTemplate = await this.parseClientData(
+        filterTemplate,
+        state.scheduler
+      );
+    } catch (error2) {
+      const clientResult = this.getClientRequestErrorResult(error2);
+      if (clientResult) throw new ClientRequestError(clientResult);
+      throw error2;
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(parsedTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, []);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("list", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.find(
+          {},
+          {
+            select,
+            sort,
+            skip,
+            limit,
+            page,
+            pageSize,
+            include: nestedInclude,
+            overrides: { filter: authorized }
+          },
+          { includeCount: false, lean: true, includePermissions: false }
+        );
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
+  }
+  async includeCorrelatedCount(docs, include, snapshots, state, depth) {
+    const svc = await this.getAuthorizedTargetService(include.model, "count");
+    const filterTemplate = include.filter;
+    const templateErrors = this.validateClientFilter(filterTemplate);
+    if (templateErrors.length > 0) {
+      this.throwClientRequestError("bad_request" /* BadRequest */, templateErrors[0]);
+    }
+    const tasks = docs.map((_, index) => ({ index, snapshot: snapshots[index] }));
+    await state.scheduler.map(tasks, async ({ index, snapshot }) => {
+      let resolution;
+      try {
+        resolution = resolveCorrelatedFilterTemplate(filterTemplate, snapshot);
+      } catch (error2) {
+        if (error2 instanceof CorrelatedReferenceError) {
+          throw new ClientRequestError({
+            success: false,
+            kind: "error",
+            code: "bad_request" /* BadRequest */,
+            errors: [{ detail: error2.message }]
+          });
+        }
+        throw error2;
+      }
+      if (resolution.status === "unresolvable") {
+        setDocValue(docs[index], include.path, 0);
+        return;
+      }
+      const expanded = resolution.filter;
+      const operandErrors = validateExpandedCorrelatedOperands(expanded, this.getRequestComplexity());
+      if (operandErrors.length > 0) {
+        throw new ClientRequestError({
+          success: false,
+          kind: "error",
+          code: "bad_request" /* BadRequest */,
+          errors: [{ detail: operandErrors[0].detail }]
+        });
+      }
+      const authorized = await svc.genFilter("count", expanded);
+      if (authorized === false) {
+        throw new ClientRequestError({ success: false, kind: "error", code: "forbidden" /* Forbidden */ });
+      }
+      this.claimCorrelatedQuerySlot();
+      let result;
+      try {
+        result = await svc.countTrusted(authorized);
+      } catch (error2) {
+        const clientResult = this.getClientRequestErrorResult(error2);
+        if (clientResult) throw new ClientRequestError(clientResult);
+        throw error2;
+      }
+      if (result.success) {
+        setDocValue(docs[index], include.path, result.data);
+      } else {
+        throw new ClientRequestError(result);
+      }
+    });
+    void depth;
+  }
   async parseClientData(filter2, scheduler = new RequestConcurrencyScheduler(this.getRequestComplexity().maxBulkConcurrency), scheduled = false) {
     const result = await iterateQuery(
       filter2,
@@ -1854,7 +2744,7 @@ var Base = class {
     }
     let ret = result.data;
     if (sqOptions.path) {
-      ret = isArray6(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
+      ret = isArray7(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
     }
     if (sqOptions.compact) {
       ret = compact(castArray(ret));
@@ -1871,8 +2761,9 @@ var Base = class {
 // src/services/service.ts
 import {
   castArray as castArray2,
+  cloneDeep as cloneDeep3,
   compact as compact2,
-  isArray as isArray7,
+  isArray as isArray8,
   isBoolean as isBoolean3,
   isFunction as isFunction3,
   omit,
@@ -2375,6 +3266,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({
@@ -2441,8 +3355,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,
@@ -2475,8 +3390,14 @@ var Service = class extends Base {
       originalDocumentSnapshot: toObject(doc),
       resolvedQuery: query
     };
+    const correlatedSnapshots = [cloneDeep3(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) {
@@ -2494,8 +3415,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 };
@@ -2541,11 +3474,12 @@ var Service = class extends Base {
       this.genAllowedFields({}, "list", this.baseFieldsExt)
     ]);
     const finalSelect = normalizeSelect(_select);
-    const filteredPopulate = isArray7(finalSelect) && isArray7(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
-    const { includes, includeLocalFields, includePaths } = this.processInclude(include);
+    const filteredPopulate = isArray8(finalSelect) && isArray8(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
+    const { includes, correlatedIncludes, includeLocalFields, includePaths, correlatedReferenceFields } = 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
@@ -2554,7 +3488,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) {
@@ -2579,8 +3513,12 @@ var Service = class extends Base {
       resolvedQuery: query
     }));
     const _decorate = isFunction3(decorate) ? decorate : (v) => v;
+    const correlatedSnapshots = docs.map((doc) => cloneDeep3(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) {
@@ -2602,8 +3540,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;
@@ -2688,7 +3638,7 @@ var Service = class extends Base {
           validationErrors.push({ index, errors: [] });
           return void 0;
         }
-      } else if (isArray7(validated)) {
+      } else if (isArray8(validated)) {
         if (validated.length > 0) {
           validationErrors.push({
             index,
@@ -2845,7 +3795,7 @@ var Service = class extends Base {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */ };
       }
-    } else if (isArray7(validated)) {
+    } else if (isArray8(validated)) {
       if (validated.length > 0) {
         this.completeOp("updateOne", startedAt, "bad_request" /* BadRequest */, _filter);
         return { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors: validated };
@@ -3032,6 +3982,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 {
@@ -3436,7 +4403,7 @@ var DataService = class {
     this.req = req;
     this.dataName = dataName;
     this.options = getDataOptions(dataName);
-    this.data = this.options.data ?? [];
+    this.data = getDataSnapshot(dataName);
   }
   async findOne(filter2, args, options) {
     const filterErrors = validateClientFilter(filter2);
@@ -3547,29 +4514,64 @@ var DataService = class {
 };
 
 // src/processors.ts
-import { cloneDeep, forEach as forEach6, get as get7, isArray as isArray8, isPlainObject as isPlainObject13, map, set as set5 } from "@web-ts-toolkit/utils";
+import { cloneDeep as cloneDeep4, forEach as forEach6, get as get7, hasOwn, isArray as isArray9, isPlainObject as isPlainObject14, map, set as set5 } from "@web-ts-toolkit/utils";
 var UNSAFE_PATH_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-function failUnsafeSegment(path) {
+var DEFAULT_MAX_SLICE = 1e3;
+var DEFAULT_MASK_REPLACEMENT = "***";
+function failUnsafeSegment(path, fn = "copyAndDepopulate") {
   throw new Error(
-    `copyAndDepopulate: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
+    `${fn}: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
   );
 }
 function failMissingId(path) {
   throw new Error(`copyAndDepopulate: path '${path}' resolved to a record missing the configured id field.`);
 }
-function assertSafePath(path) {
+function failInvalidSlice(value, field, fn) {
+  throw new Error(`${fn}: '${field}' must be a non-negative safe integer, received ${String(value)}.`);
+}
+function assertSafePath(path, fn = "copyAndDepopulate") {
   const segs = path.split(".");
   for (const seg of segs) {
     if (seg.length === 0) continue;
     if (UNSAFE_PATH_KEYS.has(seg)) {
-      failUnsafeSegment(path);
+      failUnsafeSegment(path, fn);
     }
   }
 }
+function assertNonNegativeSafeInteger(value, field, fn) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    failInvalidSlice(value, field, fn);
+  }
+}
+function resolveLeafParents(obj, src) {
+  const segs = src.split(".");
+  let targets = [obj];
+  for (let ind = 0; ind < segs.length - 1; ind += 1) {
+    const seg = segs[ind];
+    targets = targets.reduce((ret, target) => {
+      if (!isPlainObject14(target)) return ret;
+      const targetObject = target;
+      const next = targetObject[seg];
+      if (isArray9(next)) {
+        for (const item of next) {
+          ret.push(item);
+        }
+      } else if (next !== null && next !== void 0) ret.push(next);
+      return ret;
+    }, []);
+  }
+  const leaf = segs[segs.length - 1];
+  const pairs = [];
+  forEach6(targets, (target) => {
+    if (!isPlainObject14(target)) return;
+    pairs.push({ parent: target, leaf });
+  });
+  return pairs;
+}
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
   const mutable = options.mutable !== false;
   const idField = options.idField ?? "_id";
-  const obj = mutable ? docObject : cloneDeep(docObject);
+  const obj = mutable ? docObject : cloneDeep4(docObject);
   forEach6(Array.isArray(operations) ? operations : [], (op) => {
     if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
     const src = op.src;
@@ -3582,15 +4584,15 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
     forEach6(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
         forEach6(targets, (target) => {
-          if (!isPlainObject13(target)) return;
+          if (!isPlainObject14(target)) return;
           const targetObject = target;
           const leaf = targetObject[seg];
           const sourceForDest = leaf;
           let depopulated;
-          if (isArray8(leaf)) {
+          if (isArray9(leaf)) {
             if (leaf.length === 0) {
               depopulated = [];
-            } else if (leaf.every((item) => isPlainObject13(item))) {
+            } else if (leaf.every((item) => isPlainObject14(item))) {
               depopulated = map(leaf, idField).map((id, i) => {
                 if (id === void 0) {
                   failMissingId(`${src}[${i}]`);
@@ -3600,7 +4602,7 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
             } else {
               return;
             }
-          } else if (isPlainObject13(leaf)) {
+          } else if (isPlainObject14(leaf)) {
             const id = get7(leaf, idField);
             if (id === void 0) {
               failMissingId(src);
@@ -3614,11 +4616,14 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
         });
       } else {
         targets = targets.reduce((ret, target) => {
-          if (!isPlainObject13(target)) return ret;
+          if (!isPlainObject14(target)) return ret;
           const targetObject = target;
           const next = targetObject[seg];
-          if (isArray8(next)) ret.push(...next);
-          else if (next !== null && next !== void 0) ret.push(next);
+          if (isArray9(next)) {
+            for (const item of next) {
+              ret.push(item);
+            }
+          } else if (next !== null && next !== void 0) ret.push(next);
           return ret;
         }, []);
       }
@@ -3626,6 +4631,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 : cloneDeep4(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "copyPaths");
+    assertSafePath(dest, "copyPaths");
+    if (src === dest) return;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      set5(parent, dest, cloneDeep4(parent[leaf]));
+    });
+  });
+  return obj;
+};
+var movePaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : cloneDeep4(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "movePaths");
+    assertSafePath(dest, "movePaths");
+    if (src === dest) return;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      const value = cloneDeep4(parent[leaf]);
+      set5(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 : cloneDeep4(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "sliceArrays");
+    const rawDest = typeof op.dest === "undefined" ? void 0 : op.dest;
+    if (typeof rawDest !== "undefined") {
+      if (typeof rawDest !== "string" || rawDest.length === 0) return;
+      assertSafePath(rawDest, "sliceArrays");
+    }
+    const skip = op.skip ?? 0;
+    assertNonNegativeSafeInteger(skip, "skip", "sliceArrays");
+    let limit;
+    if (typeof op.limit !== "undefined") {
+      assertNonNegativeSafeInteger(op.limit, "limit", "sliceArrays");
+      limit = Math.min(op.limit, maxSlice);
+    }
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      const leafValue = parent[leaf];
+      if (!isArray9(leafValue)) return;
+      const end = typeof limit === "undefined" ? void 0 : skip + limit;
+      const window = leafValue.slice(skip, end);
+      if (typeof rawDest === "undefined") {
+        set5(parent, leaf, window);
+      } else {
+        set5(parent, rawDest, window);
+      }
+    });
+  });
+  return obj;
+};
+var countPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : cloneDeep4(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "countPaths");
+    assertSafePath(dest, "countPaths");
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      const leafValue = parent[leaf];
+      let count;
+      if (isArray9(leafValue)) {
+        count = leafValue.length;
+      } else if (isPlainObject14(leafValue)) {
+        count = Object.keys(leafValue).length;
+      } else if (leafValue === null || typeof leafValue === "undefined") {
+        count = 0;
+      } else {
+        count = 1;
+      }
+      set5(parent, dest, count);
+    });
+  });
+  return obj;
+};
+var maskPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : cloneDeep4(docObject);
+  forEach6(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "maskPaths");
+    const replacement = Object.prototype.hasOwnProperty.call(op, "replacement") ? op.replacement : DEFAULT_MASK_REPLACEMENT;
+    forEach6(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!hasOwn(parent, leaf)) return;
+      set5(parent, leaf, replacement);
+    });
+  });
+  return obj;
+};
 
 // src/symbols.ts
 var MIDDLEWARE = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/access-router/middleware");
@@ -3668,18 +4792,18 @@ var Cache = class {
 import {
   castArray as castArray3,
   arrayToRecord,
-  hasOwn as hasOwn2,
-  isArray as isArray9,
+  hasOwn as hasOwn3,
+  isArray as isArray10,
   isBoolean as isBoolean4,
   isEmpty as isEmpty2,
   isEqual,
   isFunction as isFunction4,
-  isPlainObject as isPlainObject14,
+  isPlainObject as isPlainObject15,
   isString as isString5
 } from "@web-ts-toolkit/utils";
 
 // src/permission.ts
-import { hasOwn } from "@web-ts-toolkit/utils";
+import { hasOwn as hasOwn2 } from "@web-ts-toolkit/utils";
 var Permission = class {
   constructor(permissions) {
     this.permissions = { ...permissions };
@@ -3695,7 +4819,7 @@ var Permission = class {
     return [permissionOrPermissions].concat(permissions);
   }
   hasKey(permission) {
-    return hasOwn(this.permissions, permission);
+    return hasOwn2(this.permissions, permission);
   }
   has(permission) {
     return this.permissions[permission] === true;
@@ -3715,10 +4839,10 @@ var permission_default = Permission;
 
 // src/core-shared.ts
 function isAndFilter(filter2) {
-  return !!filter2 && isPlainObject14(filter2) && Object.keys(filter2).length === 1 && isArray9(filter2.$and);
+  return !!filter2 && isPlainObject15(filter2) && Object.keys(filter2).length === 1 && isArray10(filter2.$and);
 }
 function isMergeableClause(filter2) {
-  return !!filter2 && isPlainObject14(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
+  return !!filter2 && isPlainObject15(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
 }
 function optimizeAndFilter(clausesInput) {
   const clauses = [];
@@ -3733,10 +4857,10 @@ function optimizeAndFilter(clausesInput) {
     }
   }
   const dedupeKey = (value) => {
-    if (isArray9(value)) {
+    if (isArray10(value)) {
       return `[${value.map(dedupeKey).join(",")}]`;
     }
-    if (isPlainObject14(value)) {
+    if (isPlainObject15(value)) {
       return `{${Object.keys(value).sort().map((key) => `${key}:${dedupeKey(value[key])}`).join(",")}}`;
     }
     return JSON.stringify(value);
@@ -3760,7 +4884,7 @@ function optimizeAndFilter(clausesInput) {
     }
     let canMerge = true;
     for (const [key, value] of Object.entries(clause)) {
-      if (hasOwn2(mergedClause, key) && !isEqual(mergedClause[key], value)) {
+      if (hasOwn3(mergedClause, key) && !isEqual(mergedClause[key], value)) {
         canMerge = false;
         break;
       }
@@ -3778,7 +4902,7 @@ function optimizeAndFilter(clausesInput) {
 }
 function normalizeFilter(filter2) {
   if (filter2 === false) return false;
-  if (!filter2 || !isPlainObject14(filter2) || isEmpty2(filter2)) return null;
+  if (!filter2 || !isPlainObject15(filter2) || isEmpty2(filter2)) return null;
   if (!isAndFilter(filter2)) {
     return filter2;
   }
@@ -3804,11 +4928,12 @@ async function resolveAccessFilter({
 }) {
   let nextFilter = normalizeFilter(filter2);
   const overrideFilterFn = getOption(`overrideFilter.${access}`, null);
-  if (isFunction4(overrideFilterFn)) {
+  if (nextFilter !== false && isFunction4(overrideFilterFn)) {
     nextFilter = normalizeFilter(await overrideFilterFn.call(req, nextFilter, permissions));
   }
+  if (nextFilter === false) return false;
   const baseFilterFn = getOption(`baseFilter.${access}`, null);
-  if (!isFunction4(baseFilterFn)) return nextFilter || {};
+  if (!isFunction4(baseFilterFn)) return nextFilter ?? {};
   const baseFilter = normalizeFilter(
     cache.has(cacheKey) ? cache.get(cacheKey) : await baseFilterFn.call(req, permissions)
   );
@@ -3816,7 +4941,7 @@ async function resolveAccessFilter({
     cache.set(cacheKey, baseFilter);
   }
   if (baseFilter === false) return false;
-  if (!baseFilter) return nextFilter || {};
+  if (!baseFilter) return nextFilter ?? {};
   if (!nextFilter) return baseFilter;
   return optimizeAndFilter([baseFilter, nextFilter]);
 }
@@ -3824,15 +4949,30 @@ function getRequestPermissions(req) {
   const requestPermissionField = getGlobalOption("requestPermissionField");
   return new permission_default(req[requestPermissionField] || {});
 }
+var permissionFieldOwners = /* @__PURE__ */ new WeakMap();
+function getPermissionFieldOwnerMap(req) {
+  let owners = permissionFieldOwners.get(req);
+  if (!owners) {
+    owners = /* @__PURE__ */ new Map();
+    permissionFieldOwners.set(req, owners);
+  }
+  return owners;
+}
 async function setRequestPermissions(req) {
   const requestPermissionField = getGlobalOption("requestPermissionField");
-  if (req[requestPermissionField]) return;
+  const activeRuntime = getActiveRuntime();
+  const owners = getPermissionFieldOwnerMap(req);
+  const owner = owners.get(requestPermissionField);
+  const hasFieldValue = Boolean(req[requestPermissionField]);
+  if (owner === activeRuntime) return;
+  if (hasFieldValue && owner === void 0) return;
   const globalPermissions = getGlobalOption("globalPermissions");
   if (!isFunction4(globalPermissions)) return;
   const permissions = await globalPermissions.call(req, req);
-  if (isPlainObject14(permissions)) req[requestPermissionField] = permissions;
-  else if (isArray9(permissions)) req[requestPermissionField] = arrayToRecord(permissions);
+  if (isPlainObject15(permissions)) req[requestPermissionField] = permissions;
+  else if (isArray10(permissions)) req[requestPermissionField] = arrayToRecord(permissions);
   else if (isString5(permissions)) req[requestPermissionField] = { [permissions]: true };
+  owners.set(requestPermissionField, activeRuntime);
 }
 async function evaluateRouteGuard(req, permissions, routeGuard) {
   const phas = (key) => permissions.has(key);
@@ -3843,7 +4983,7 @@ async function evaluateRouteGuard(req, permissions, routeGuard) {
   if (isString5(routeGuard)) {
     return stringHandler(routeGuard);
   }
-  if (isArray9(routeGuard)) {
+  if (isArray10(routeGuard)) {
     return arrayHandler(routeGuard);
   }
   if (isFunction4(routeGuard)) {
@@ -3881,7 +5021,7 @@ async function collectSchemaFields({
       if (value) fields.push(key);
     } else if (isString5(value)) {
       if (stringHandler(value)) fields.push(key);
-    } else if (isArray9(value)) {
+    } else if (isArray10(value)) {
       if (arrayHandler(value)) fields.push(key);
     } else if (isFunction4(value)) {
       if (await value.call(req, ...functionArgs)) fields.push(key);
@@ -3900,17 +5040,14 @@ function getResolvedRequestPermissions(req) {
 async function setResolvedRequestPermissions(req) {
   await setRequestPermissions(req);
 }
-async function canActivateRequest(req, routeGuard) {
-  const permissions = getGlobalPermissions(req);
-  return evaluateRouteGuard(req, permissions, routeGuard);
-}
 async function initializeAclRequest({
   req,
   flag,
+  runtime,
   createCore,
   assignCore
 }) {
-  if (req[flag]) {
+  if (req[flag] === runtime) {
     return null;
   }
   const core = createCore(req);
@@ -3918,7 +5055,7 @@ async function initializeAclRequest({
   assignCore(core);
   req[PERMISSIONS] = core.getPermissions();
   req[PERMISSION_KEYS] = [...req[PERMISSIONS].keys];
-  req[flag] = true;
+  req[flag] = runtime;
   return core;
 }
 
@@ -4054,6 +5191,7 @@ async function resolveSelectForRequest({
 // src/core.ts
 var Core = class {
   constructor(req) {
+    this.cachedPermissions = null;
     this.req = req;
     this.caches = {
       baseFilter: new Cache()
@@ -4188,7 +5326,7 @@ var Core = class {
     if (isFunction5(validate)) {
       const permissions = this.getGlobalPermissions();
       return validate.call(this.req, allowedData, permissions, context);
-    } else if (isBoolean5(validate) || isArray10(validate)) {
+    } else if (isBoolean5(validate) || isArray11(validate)) {
       return validate;
     } else {
       return true;
@@ -4332,18 +5470,55 @@ 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;
   }
   getPermissions() {
+    if (this.cachedPermissions) return this.cachedPermissions;
     return getResolvedRequestPermissions(this.req);
   }
   async setPermissions() {
     await setResolvedRequestPermissions(this.req);
+    this.cachedPermissions = getResolvedRequestPermissions(this.req);
   }
   async canActivate(routeGuard) {
-    return canActivateRequest(this.req, routeGuard);
+    return evaluateRouteGuard(this.req, this.getGlobalPermissions(), routeGuard);
   }
   async isAllowed(modelName, access) {
     if (access.startsWith("subs")) {
@@ -4379,6 +5554,7 @@ var Core = class {
     return this.getPublicService(modelName);
   }
   getGlobalPermissions() {
+    if (this.cachedPermissions) return this.cachedPermissions;
     return getGlobalPermissions(this.req);
   }
 };
@@ -4388,6 +5564,7 @@ var createSetCore = (runtime = defaultRuntime) => {
       await initializeAclRequest({
         req,
         flag: MIDDLEWARE,
+        runtime,
         createCore: (request) => new Core(request),
         assignCore: (core) => {
           req.macl = core;
@@ -4405,19 +5582,19 @@ function guard(condition) {
     const permissions = req[PERMISSIONS];
     let cond = condition;
     let phas = (key) => permissions.has(key);
-    if (isPlainObject15(condition)) {
+    if (isPlainObject16(condition)) {
       const { modelName, id, condition: _cond } = condition;
       const svc = req.macl.getPublicService(modelName);
       const select = getModelOption(modelName, `alwaysSelectFields.read`, void 0);
       let _id = isString7(id) ? id : null;
-      if (isPlainObject15(id)) {
+      if (isPlainObject16(id)) {
         const { type = "param", key } = id;
         if (type === "param") {
           const paramValue = req.params[key];
-          _id = isArray11(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
+          _id = isArray12(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
         } else if (type === "query") {
           const _qval = req.query[key];
-          if (isArray11(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
+          if (isArray12(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
           else _id = _qval;
         } else {
           _id = null;
@@ -4437,7 +5614,7 @@ function guard(condition) {
     const { stringHandler, arrayHandler } = createValidator(phas);
     if (isString7(cond)) {
       if (stringHandler(cond)) return next();
-    } else if (isArray11(cond)) {
+    } else if (isArray12(cond)) {
       if (arrayHandler(cond)) return next();
     } else if (isFunction6(cond)) {
       const result = await cond.call(req, permissions);
@@ -4452,7 +5629,7 @@ import express2 from "express";
 
 // src/routers/model-router.ts
 import JsonRouter5 from "@web-ts-toolkit/express-json-router";
-import { forEach as forEach8, isPlainObject as isPlainObject16, isString as isString8, isUndefined as isUndefined2, normalizeUrlPath as normalizeUrlPath2, padEnd } from "@web-ts-toolkit/utils";
+import { forEach as forEach8, isPlainObject as isPlainObject18, isString as isString8, isUndefined as isUndefined2, normalizeUrlPath as normalizeUrlPath2, padEnd } from "@web-ts-toolkit/utils";
 
 // src/routers/router-mutation.ts
 var MODEL_BUILD_TIME_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -4581,6 +5758,7 @@ import JsonRouter4 from "@web-ts-toolkit/express-json-router";
 
 // src/validation/common.ts
 import { z as z2 } from "zod";
+import { isPlainObject as isPlainObject17 } from "@web-ts-toolkit/utils";
 var stringOrStringArray = z2.union([z2.string(), z2.array(z2.string())]);
 var safeIntegerString = (min, message) => z2.string().regex(/^\d+$/, message).refine((value) => Number.isSafeInteger(Number(value)), "Expected a safe integer").refine((value) => Number(value) >= min, message);
 var queryBooleanString = z2.enum(["true", "false"]);
@@ -4641,7 +5819,8 @@ var subPopulateSchema = z2.union([
     select: projectionSchema.optional()
   }).passthrough()
 ]);
-var includeItemSchema = z2.object({
+var legacyIncludeItemSchema = z2.object({
+  mode: z2.enum(["legacy"]).optional(),
   model: z2.string().min(1),
   op: z2.enum(["list", "read", "count"]),
   path: z2.string().min(1),
@@ -4650,8 +5829,139 @@ var includeItemSchema = z2.object({
   foreignField: z2.string().min(1),
   args: z2.unknown().optional().describe("Forwarded to list/read includes. Count includes ignore pagination fields so counts remain exact."),
   options: z2.unknown().optional()
-}).passthrough();
-var includeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+}).passthrough().superRefine((entry, ctx) => {
+  if (entry.filter !== void 0 && containsParentMarkerShape(entry.filter)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: 'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")',
+      path: ["filter"]
+    });
+  }
+});
+var parentRefSchema = z2.object({ $parent: z2.string().min(1) }).strict().superRefine((value, ctx) => {
+  if (!isValidParentRefPath(value.$parent)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid $parent reference path: ${value.$parent}`,
+      path: ["$parent"]
+    });
+  }
+});
+var correlatedIdSchema = z2.union([z2.string().min(1), parentRefSchema]);
+var correlatedFilterSchema = z2.record(z2.string(), z2.unknown()).superRefine((filter2, ctx) => {
+  for (const issue of validateCorrelatedFilterTemplate(filter2)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: issue.message,
+      path: issue.path.map(String)
+    });
+  }
+});
+var correlatedEmptyOptionsSchema = z2.unknown().refine(
+  (value) => value === void 0 || isPlainObject17(value) && Object.keys(value).length === 0,
+  "Correlated include options must be absent or empty"
+).optional();
+var correlatedPathSchema = z2.string().min(1).superRefine((path, ctx) => {
+  if (!isValidCorrelatedOutputPath(path)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid correlated include output path: ${path}`,
+      path: []
+    });
+  }
+});
+var checkArgsMarkers = (select, sort, ctx) => {
+  const selectIssue = findArgsMarkerIssue(select, "args.select");
+  if (selectIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: selectIssue.message, path: ["select"] });
+  }
+  const sortIssue = findArgsMarkerIssue(sort, "args.sort");
+  if (sortIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: sortIssue.message, path: ["sort"] });
+  }
+};
+var correlatedReadArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedListArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  skip: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  limit: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  page: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  pageSize: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedCountArgsSchema = z2.unknown().refine(
+  (value) => value === void 0 || isPlainObject17(value) && Object.keys(value).length === 0,
+  "Count includes accept no args"
+).optional();
+var correlatedReadByIdSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  id: correlatedIdSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedReadByFilterSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedListSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("list"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedListArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedCountSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("count"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedCountArgsSchema,
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var includeItemSchema = z2.union([
+  legacyIncludeItemSchema,
+  correlatedReadByIdSchema,
+  correlatedReadByFilterSchema,
+  correlatedListSchema,
+  correlatedCountSchema
+]);
+var correlatedNestedIncludeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+var rejectDuplicateCorrelatedPaths = (items, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if (isPlainObject17(item) && item.mode === "correlated" && typeof item.path === "string") {
+      if (seen.has(item.path)) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `Duplicate correlated include output path: ${item.path}`,
+          path: [index, "path"]
+        });
+      } else {
+        seen.add(item.path);
+      }
+    }
+  });
+};
+var includeSchema = z2.union([
+  includeItemSchema,
+  z2.array(includeItemSchema).superRefine(rejectDuplicateCorrelatedPaths)
+]);
 var fieldsSchema = z2.array(z2.string().min(1));
 var taskSchema = z2.object({
   type: z2.string().min(1),
@@ -4768,8 +6078,9 @@ function defineRequestSchema(validator, options = {}) {
   };
 }
 function fromZod(schema) {
-  return (value) => {
-    const result = schema.safeParse(value);
+  return async (value) => {
+    const candidate = schema;
+    const result = typeof candidate.safeParseAsync === "function" ? await candidate.safeParseAsync.call(schema, value) : schema.safeParse(value);
     if (result.success) {
       return {
         success: true,
@@ -4806,6 +6117,9 @@ function fromYup(schema) {
         data
       };
     } catch (error2) {
+      if (!isYupValidationError(error2)) {
+        throw error2;
+      }
       return {
         success: false,
         issues: normalizeYupIssues(error2)
@@ -4830,8 +6144,32 @@ function fromJoi(schema) {
 }
 function fromAjv(validator) {
   return async (value) => {
-    const valid = await validator(value);
-    if (valid) {
+    const outcome = validator(value);
+    if (isThenable(outcome)) {
+      try {
+        const data = await outcome;
+        if (data === false) {
+          return {
+            success: false,
+            issues: normalizeAjvIssues(validator.errors ?? [])
+          };
+        }
+        return {
+          success: true,
+          data: data === true ? value : data
+        };
+      } catch (error2) {
+        if (!isAjvValidationError(error2)) {
+          throw error2;
+        }
+        return {
+          success: false,
+          issues: normalizeAjvIssues(error2.errors ?? [])
+        };
+      }
+    }
+    const errorsSnapshot = validator.errors ? [...validator.errors] : [];
+    if (outcome) {
       return {
         success: true,
         data: value
@@ -4839,7 +6177,7 @@ function fromAjv(validator) {
     }
     return {
       success: false,
-      issues: normalizeAjvIssues(validator.errors ?? [])
+      issues: normalizeAjvIssues(errorsSnapshot)
     };
   };
 }
@@ -4860,6 +6198,25 @@ function fromValibot(schema, safeParse) {
 }
 function fromArkType(type) {
   return async (value) => {
+    if (isStandardSchema(type)) {
+      const result2 = await type["~standard"].validate(value);
+      if (isArkTypeErrors(result2)) {
+        return {
+          success: false,
+          issues: normalizeArkTypeIssues(result2)
+        };
+      }
+      if (isStandardSchemaFailure(result2)) {
+        return {
+          success: false,
+          issues: normalizeArkTypeStandardIssues(result2.issues)
+        };
+      }
+      return {
+        success: true,
+        data: result2.value
+      };
+    }
     const result = await type(value);
     if (!isArkTypeErrors(result)) {
       return {
@@ -4912,6 +6269,9 @@ function fromVine(validator) {
         data: output
       };
     } catch (error2) {
+      if (!isVineValidationError(error2)) {
+        throw error2;
+      }
       return {
         success: false,
         issues: normalizeVineError(error2)
@@ -4972,6 +6332,13 @@ function normalizeArkTypeIssues(issues) {
   }));
   return normalized.length ? normalized : [{ message: issues.summary ?? "Validation failed" }];
 }
+function normalizeArkTypeStandardIssues(issues) {
+  const normalized = issues.map((issue) => ({
+    message: issue.message ?? issue.problem ?? "Validation failed",
+    path: issue.path?.flatMap((segment) => normalizePathSegment(segment))
+  }));
+  return normalized.length ? normalized : [{ message: "Validation failed" }];
+}
 function normalizeIoTsIssues(issues) {
   return issues.map((issue) => ({
     message: issue.message ?? "Validation failed",
@@ -5006,25 +6373,64 @@ function normalizeVineField(message) {
   }
   return path.length ? path : void 0;
 }
+function decodeAjvSegment(segment) {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function encodePointerSegment(segment) {
+  return encodeURIComponent(segment.replace(/~/g, "~0").replace(/\//g, "~1"));
+}
 function parseAjvPath(issue) {
-  const path = issue.instancePath?.split("/").filter(Boolean).map((segment) => /^\d+$/.test(segment) ? Number(segment) : segment);
-  if (issue.params?.missingProperty) {
-    return (path ?? []).concat(issue.params.missingProperty);
+  const raw = issue.instancePath;
+  const base = raw == null || raw === "" ? [] : (raw.startsWith("/") ? raw.slice(1) : raw).split("/").map(decodeAjvSegment);
+  const missing = issue.params?.missingProperty;
+  if (typeof missing === "string") {
+    return [...base, missing];
   }
-  return path;
+  return base;
 }
 function parsePathString(path) {
   if (!path) return void 0;
   return path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean).map((segment) => /^\d+$/.test(segment) ? Number(segment) : segment);
 }
 function isYupValidationError(error2) {
-  return typeof error2 === "object" && error2 !== null && "message" in error2;
+  if (typeof error2 !== "object" || error2 === null || !("message" in error2)) {
+    return false;
+  }
+  const candidate = error2;
+  return candidate.name === "ValidationError" && typeof candidate.message === "string" && Array.isArray(candidate.errors) && Array.isArray(candidate.inner);
 }
 function isArkTypeErrors(value) {
-  return Array.isArray(value);
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return record.arkKind === "errors" || record[" arkKind"] === "errors";
+}
+function isThenable(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isAjvValidationError(error2) {
+  if (typeof error2 !== "object" || error2 === null || !("errors" in error2)) {
+    return false;
+  }
+  const errors = error2.errors;
+  return errors == null || Array.isArray(errors);
 }
 function isVineValidationError(error2) {
-  return typeof error2 === "object" && error2 !== null && "messages" in error2 && Array.isArray(error2.messages);
+  if (typeof error2 !== "object" || error2 === null || !("messages" in error2)) {
+    return false;
+  }
+  const candidate = error2;
+  if (!Array.isArray(candidate.messages) || candidate.messages.length === 0) {
+    return false;
+  }
+  const hasDiscriminator = candidate.code === "E_VALIDATION_ERROR" || candidate.name === "ValidationError";
+  if (!hasDiscriminator) {
+    return false;
+  }
+  return candidate.messages.every(
+    (message) => typeof message === "object" && message !== null && typeof message.message === "string" && typeof message.field === "string"
+  );
 }
 function formatIssue(issue, key, location = "pointer") {
   const path = (issue.path ?? []).map(String);
@@ -5041,7 +6447,7 @@ function formatIssue(issue, key, location = "pointer") {
   };
 }
 function buildPointer(path) {
-  return path.length === 0 ? "#" : `#/${path.join("/")}`;
+  return path.length === 0 ? "#" : `#/${path.map(encodePointerSegment).join("/")}`;
 }
 
 // src/validation/model-router.ts
@@ -5092,7 +6498,7 @@ var listBodySchema = z3.object({
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
 var countBodySchema = z3.object({
   filter: objectOrArraySchema.optional()
-}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options"]));
+}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options", "include"]));
 var readFilterBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
@@ -5542,24 +6948,26 @@ function setModelCollectionRoutes(context) {
   router.post(`/${options.mutationRouteSegment}`, async (req) => {
     await context.assertAllowed(req, "create");
     const { include_permissions } = parseQuery(requestSchemas.createQuery, req.query);
-    const body = await parseNestedBodyWithSchema(
+    const intermediateBody = await parseNestedBodyWithSchema(
       advancedCreateBodySchema,
       req.body,
       "data",
       context.getRequestSchema("requestSchemas.advancedCreate.data")
     );
-    const { data, select, populate, tasks } = body;
-    const advancedOptions = body.options ?? {};
-    await parseBodyWithSchema(
+    const { data: nestedData, select: nestedSelect, populate: nestedPopulate, tasks: nestedTasks } = intermediateBody;
+    const nestedOptions = intermediateBody.options ?? {};
+    const finalBody = await parseBodyWithSchema(
       advancedCreateBodySchema,
-      { data, select, populate, tasks, options: advancedOptions },
+      { data: nestedData, select: nestedSelect, populate: nestedPopulate, tasks: nestedTasks, options: nestedOptions },
       context.getRequestSchema("requestSchemas.advancedCreate.default") ?? context.getRequestSchema("requestSchemas.advancedCreate")
     );
-    const { includePermissions, populateAccess } = advancedOptions;
+    const { data: finalData, select: finalSelect, populate: finalPopulate, tasks: finalTasks } = finalBody;
+    const finalOptions = finalBody.options ?? {};
+    const { includePermissions, populateAccess } = finalOptions;
     const svc = context.getPublicService(req);
     const result = await svc._create(
-      data,
-      { select, populate, tasks },
+      finalData,
+      { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
         includePermissions: includePermissions ?? parseBooleanString(include_permissions),
         populateAccess
@@ -5758,25 +7166,33 @@ function setModelDocumentRoutes(context) {
     await context.assertAllowed(req, "update");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
     const { returning_all, include_permissions } = parseQuery(requestSchemas.updateQuery, req.query);
-    const body = await parseNestedBodyWithSchema(
+    const intermediateBody = await parseNestedBodyWithSchema(
       advancedUpdateBodySchema,
       req.body,
       "data",
       context.getRequestSchema("requestSchemas.advancedUpdate.data")
     );
-    const { data, select, populate, tasks } = body;
-    const advancedOptions = body.options ?? {};
-    await parseBodyWithSchema(
+    const { data: nestedData, select: nestedSelect, populate: nestedPopulate, tasks: nestedTasks } = intermediateBody;
+    const nestedOptions = intermediateBody.options ?? {};
+    const finalBody = await parseBodyWithSchema(
       advancedUpdateBodySchema,
-      { data, select, populate, tasks, options: advancedOptions },
+      {
+        data: nestedData,
+        select: nestedSelect,
+        populate: nestedPopulate,
+        tasks: nestedTasks,
+        options: nestedOptions
+      },
       context.getRequestSchema("requestSchemas.advancedUpdate.default") ?? context.getRequestSchema("requestSchemas.advancedUpdate")
     );
-    const { returningAll, includePermissions, populateAccess } = advancedOptions;
+    const { data: finalData, select: finalSelect, populate: finalPopulate, tasks: finalTasks } = finalBody;
+    const finalOptions = finalBody.options ?? {};
+    const { returningAll, includePermissions, populateAccess } = finalOptions;
     const svc = context.getPublicService(req);
     const result = await svc._update(
       id,
-      data,
-      { select, populate, tasks },
+      finalData,
+      { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
         returningAll: returningAll ?? parseBooleanString(returning_all),
         includePermissions: includePermissions ?? parseBooleanString(include_permissions),
@@ -5826,23 +7242,31 @@ function setModelDocumentRoutes(context) {
     await context.assertAllowed(req, "upsert");
     const svc = context.getPublicService(req);
     const { returning_all, include_permissions } = parseQuery(requestSchemas.upsertQuery, req.query);
-    const body = await parseNestedBodyWithSchema(
+    const intermediateBody = await parseNestedBodyWithSchema(
       advancedUpsertBodySchema,
       req.body,
       "data",
       context.getRequestSchema("requestSchemas.advancedUpsert.data")
     );
-    const { data, select, populate, tasks } = body;
-    const advancedOptions = body.options ?? {};
-    await parseBodyWithSchema(
+    const { data: nestedData, select: nestedSelect, populate: nestedPopulate, tasks: nestedTasks } = intermediateBody;
+    const nestedOptions = intermediateBody.options ?? {};
+    const finalBody = await parseBodyWithSchema(
       advancedUpsertBodySchema,
-      { data, select, populate, tasks, options: advancedOptions },
+      {
+        data: nestedData,
+        select: nestedSelect,
+        populate: nestedPopulate,
+        tasks: nestedTasks,
+        options: nestedOptions
+      },
       context.getRequestSchema("requestSchemas.advancedUpsert.default") ?? context.getRequestSchema("requestSchemas.advancedUpsert")
     );
-    const { returningAll, includePermissions, populateAccess } = advancedOptions;
+    const { data: finalData, select: finalSelect, populate: finalPopulate, tasks: finalTasks } = finalBody;
+    const finalOptions = finalBody.options ?? {};
+    const { returningAll, includePermissions, populateAccess } = finalOptions;
     const result = await svc._upsert(
-      data,
-      { select, populate, tasks },
+      finalData,
+      { select: finalSelect, populate: finalPopulate, tasks: finalTasks },
       {
         returningAll: returningAll ?? parseBooleanString(returning_all),
         includePermissions: includePermissions ?? parseBooleanString(include_permissions),
@@ -5912,7 +7336,7 @@ function setModelDocumentRoutes(context) {
 
 // src/routers/model-router-subdocument-routes.ts
 function setModelSubDocumentRoutes(context) {
-  const subs = getModelSub(context.modelName);
+  const subs = context.runtime.getModelSub(context.modelName);
   for (let x = 0; x < subs.length; x++) {
     const sub = subs[x];
     context.router.get(`/:${context.options.idParam}/${sub}`, async (req) => {
@@ -6137,7 +7561,9 @@ var ModelRouter = class _ModelRouter {
       "baseFilter"
     );
     /**
-     * The override filter definitions applied in every query transaction.
+     * Trusted filter replacements applied before base-filter composition.
+     * They may replace ordinary filters, but cannot replace an existing `false` denial.
+     * Returning `false` denies the transaction.
      * @operation `list`, `read`, `update`, `delete`
      */
     this.overrideFilter = setOption.bind(this, "overrideFilter");
@@ -6297,6 +7723,7 @@ var ModelRouter = class _ModelRouter {
       modelName: this.modelName,
       router: this.router,
       options: this.options,
+      runtime: this.runtime,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
       assertAllowed: this.assertAllowed.bind(this),
@@ -6311,6 +7738,7 @@ var ModelRouter = class _ModelRouter {
       modelName: this.modelName,
       router: this.router,
       options: this.options,
+      runtime: this.runtime,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
       assertAllowed: this.assertAllowed.bind(this),
@@ -6325,6 +7753,7 @@ var ModelRouter = class _ModelRouter {
       modelName: this.modelName,
       router: this.router,
       options: this.options,
+      runtime: this.runtime,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
       assertAllowed: this.assertAllowed.bind(this),
@@ -6347,7 +7776,7 @@ var ModelRouter = class _ModelRouter {
         value
       );
     }
-    if (arguments.length === 1 && isPlainObject16(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject18(keyOrOptions)) {
       assertMutableRouterOptions("model", keyOrOptions);
       this.runtime.setModelOptions(this.modelName, keyOrOptions);
     }
@@ -6375,6 +7804,7 @@ import { isNumber as _isNumber, normalizeUrlPath as normalizeUrlPath3, orderBy a
 // src/core-data.ts
 var DataCore = class {
   constructor(req) {
+    this.cachedPermissions = null;
     this.req = req;
     this.caches = {
       baseFilter: new Cache()
@@ -6468,13 +7898,15 @@ var DataCore = class {
     });
   }
   getPermissions() {
+    if (this.cachedPermissions) return this.cachedPermissions;
     return getResolvedRequestPermissions(this.req);
   }
   async setPermissions() {
     await setResolvedRequestPermissions(this.req);
+    this.cachedPermissions = getResolvedRequestPermissions(this.req);
   }
   async canActivate(routeGuard) {
-    return canActivateRequest(this.req, routeGuard);
+    return evaluateRouteGuard(this.req, this.getGlobalPermissions(), routeGuard);
   }
   async isAllowed(dataName, access) {
     const operationAccess = getDataOption(dataName, `operationAccess.${access}`);
@@ -6490,6 +7922,7 @@ var DataCore = class {
     return this.getService(dataName);
   }
   getGlobalPermissions() {
+    if (this.cachedPermissions) return this.cachedPermissions;
     return getGlobalPermissions(this.req);
   }
 };
@@ -6499,6 +7932,7 @@ var createSetDataCore = (runtime = defaultRuntime) => {
       await initializeAclRequest({
         req,
         flag: DATA_MIDDLEWARE,
+        runtime,
         createCore: (request) => new DataCore(request),
         assignCore: (core) => {
           req.dacl = core;
@@ -6781,7 +8215,7 @@ var RootRouter = class {
 
 // src/routers/data-router.ts
 import JsonRouter7 from "@web-ts-toolkit/express-json-router";
-import { isPlainObject as isPlainObject17, isString as isString9, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath4 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject19, isString as isString9, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath4 } from "@web-ts-toolkit/utils";
 var clientErrors4 = JsonRouter7.clientErrors;
 function setOption2(parentKey, optionKey, option) {
   const key = isUndefined3(option) ? parentKey : `${parentKey}.${optionKey}`;
@@ -6803,6 +8237,11 @@ var DataRouter = class {
       this,
       "baseFilter"
     );
+    /**
+     * Trusted filter replacements applied before base-filter composition.
+     * They may replace ordinary filters, but cannot replace an existing `false` denial.
+     * Returning `false` denies the transaction.
+     */
     this.overrideFilter = setOption2.bind(this, "overrideFilter");
     this.decorate = setOption2.bind(
       this,
@@ -6977,7 +8416,7 @@ var DataRouter = class {
       assertMutableRouterOption("data", keyOrOptions);
       this.runtime.setDataOption(this.dataName, keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject17(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject19(keyOrOptions)) {
       assertMutableRouterOptions("data", keyOrOptions);
       this.runtime.setDataOptions(this.dataName, keyOrOptions);
     }
@@ -7124,7 +8563,7 @@ function createRuntimeApi(runtime) {
     if (arguments.length === 2 && isString10(keyOrOptions)) {
       return runtime.setGlobalOption(keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject18(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject20(keyOrOptions)) {
       return runtime.setGlobalOptions(keyOrOptions);
     }
   };