@web-ts-toolkit/access-router 0.53.0 → 0.55.0

package/advanced.js

@@ -123,10 +123,10 @@ var FilterOperator = /* @__PURE__ */ ((FilterOperator2) => {
 })(FilterOperator || {});
 
 // src/validation/parsers.ts
-var import_express_json_router2 = __toESM(require("@web-ts-toolkit/express-json-router"));
+var import_express_json_router3 = __toESM(require("@web-ts-toolkit/express-json-router"));
 
 // src/runtime.ts
-var import_mongoose2 = __toESM(require("mongoose"));
+var import_mongoose3 = __toESM(require("mongoose"));
 
 // src/validation/public-admission.ts
 var import_express_json_router = __toESM(require("@web-ts-toolkit/express-json-router"));
@@ -169,10 +169,10 @@ function assertPublicAdmission(input, kind = "envelope") {
     const add = (child, childKind, key) => {
       pending.push({ value: child, kind: childKind, path: `${path}.${key}` });
     };
-    const record = value;
+    const record2 = value;
     if (slot !== "data") {
       for (const key of privateControls) {
-        if (key in record) {
+        if (key in record2) {
           throw new PublicAdmissionError(
             `Unsupported public control ${path}.${key}; use explicit per-call internal service options for backend authorization`
           );
@@ -188,16 +188,16 @@ function assertPublicAdmission(input, kind = "envelope") {
       for (const [key, child] of Object.entries(value)) add(child, key === "$$sq" ? "envelope" : "data", key);
       continue;
     }
-    for (const key of ["args", "options", "sqOptions"]) add(record[key], "envelope", key);
-    add(record.include, "include", "include");
-    add(record.populate, "populate", "populate");
-    for (const key of ["filter", "match", "data"]) add(record[key], "data", key);
+    for (const key of ["args", "options", "sqOptions"]) add(record2[key], "envelope", key);
+    add(record2.include, "include", "include");
+    add(record2.populate, "populate", "populate");
+    for (const key of ["filter", "match", "data"]) add(record2[key], "data", key);
   }
 }
 function assertHydrationDefaults(defaults) {
   if (defaults && typeof defaults === "object") {
-    const record = defaults;
-    if ("hydration" in record)
+    const record2 = defaults;
+    if ("hydration" in record2)
       throw new TypeError("defaults.hydration is unsupported; use model hydration configuration");
     for (const bucket of [
       "publicListOptions",
@@ -213,7 +213,7 @@ function assertHydrationDefaults(defaults) {
       "publicCreateOptions",
       "publicUpdateOptions"
     ]) {
-      const options = record[bucket];
+      const options = record2[bucket];
       if (!options || typeof options !== "object" && typeof options !== "function") continue;
       for (const key of ["lean", "hydration"]) {
         if (!(key in options)) continue;
@@ -260,11 +260,28 @@ function normalizeHydrationUpdate(current, key, value) {
 
 // src/runtime.ts
 var import_mongoose_schema_jsonschema = __toESM(require("mongoose-schema-jsonschema"));
-var import_utils10 = require("@web-ts-toolkit/utils");
+var import_utils12 = require("@web-ts-toolkit/utils");
 
 // src/helpers/query.ts
 var import_utils2 = require("@web-ts-toolkit/utils");
 var DEFAULT_LIST_HARD_LIMIT = 1e3;
+function normalizeSelect(select) {
+  if (Array.isArray(select)) return (0, import_utils2.flattenDeep)(select.map(normalizeSelect));
+  if ((0, import_utils2.isPlainObject)(select)) {
+    return (0, import_utils2.reduce)(
+      select,
+      (ret, val, key) => {
+        if (val === 1) ret.push(key);
+        else if (val === -1) ret.push(`-${key}`);
+        return ret;
+      },
+      []
+    );
+  }
+  if ((0, import_utils2.isString)(select))
+    return String(select).split(/[\s,]+/).map((v) => v.trim()).filter(Boolean);
+  return [];
+}
 
 // src/helpers/sort-policy.ts
 var fieldPathPattern = /^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)*$/;
@@ -1180,14 +1197,490 @@ function validateRequestComplexity(value, options, scope = "request") {
   return errors;
 }
 
+// src/acl/virtual-descriptor.ts
+var import_utils10 = require("@web-ts-toolkit/utils");
+var isVirtualContainerValue = (value) => (0, import_utils10.isPlainObject)(value) && "sub" in value;
+function getScopeVirtualsObject(root, scopePath = []) {
+  let current = root;
+  for (let i = 0; i < scopePath.length; i += 2) {
+    if (!current || scopePath[i + 1] !== "sub") return null;
+    const container = current[scopePath[i]];
+    if (!isVirtualContainerValue(container)) return null;
+    current = container.sub;
+  }
+  return (0, import_utils10.isPlainObject)(current) ? current : null;
+}
+function toDescriptor(leaf, shared = {}) {
+  const record2 = (0, import_utils10.isFunction)(leaf) ? { get: leaf } : (0, import_utils10.isPlainObject)(leaf) ? leaf : null;
+  if (!record2 || !(0, import_utils10.isFunction)(record2.get)) return void 0;
+  const dependsOn = record2.dependsOn ?? shared.dependsOn ?? [];
+  const populated = record2.dependsOnPopulate === void 0 ? shared.dependsOnPopulate : record2.dependsOnPopulate;
+  return {
+    get: record2.get,
+    dependsOn: [...dependsOn],
+    ...populated === void 0 ? {} : {
+      dependsOnPopulate: populated.map(({ path, select }) => ({
+        path,
+        ...select === void 0 ? {} : { select: Array.isArray(select) ? [...select] : typeof select === "object" ? { ...select } : select }
+      }))
+    }
+  };
+}
+function resolveSnapshotDescriptor(scopeVirtuals, virtualName, access) {
+  const entry = scopeVirtuals?.[virtualName];
+  if (entry === void 0 || isVirtualContainerValue(entry)) return void 0;
+  if ((0, import_utils10.isFunction)(entry)) return toDescriptor(entry);
+  if (!(0, import_utils10.isPlainObject)(entry)) return void 0;
+  const record2 = entry;
+  if ("get" in record2) return toDescriptor(record2);
+  return toDescriptor(record2[access], record2) ?? toDescriptor(record2.default, record2);
+}
+
+// src/acl/virtual-populate-dependencies.ts
+var import_utils11 = require("@web-ts-toolkit/utils");
+
+// src/acl/authorization-snapshot.ts
+var import_node_util3 = require("util");
+var import_mongoose2 = require("mongoose");
+var import_express_json_router2 = __toESM(require("@web-ts-toolkit/express-json-router"));
+var ServiceAuthorizationError = class extends import_express_json_router2.default.clientErrors.BadRequestError {
+  constructor(detail) {
+    const errors = [{ detail: `Service authorization: ${detail}` }];
+    super("Bad Request", { errors });
+    this.result = { success: false, kind: "error", code: "bad_request" /* BadRequest */, errors };
+  }
+};
+function authorizationError(detail) {
+  throw new ServiceAuthorizationError(detail);
+}
+var unsafeKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function authorizationRecord(value, label) {
+  if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    authorizationError(`${label} must be a plain object`);
+  }
+  return value;
+}
+function copyAuthorizationValue(value, configuration = false) {
+  const active = /* @__PURE__ */ new WeakSet();
+  let nodes = 0;
+  function copy(input, depth) {
+    if (++nodes > 2e4 || depth > 100) authorizationError("snapshot exceeds structural limits");
+    if (typeof input === "function") {
+      if (configuration === true) return input;
+      authorizationError("functions are not policy values");
+    }
+    if (typeof input === "symbol") authorizationError("symbols are not policy values");
+    if (input === null || typeof input !== "object") return input;
+    if (active.has(input)) authorizationError("cyclic input");
+    active.add(input);
+    try {
+      if (input instanceof Date) return new Date(input.getTime());
+      if (Buffer.isBuffer(input)) return Buffer.from(input);
+      if (input instanceof RegExp) {
+        const result2 = new RegExp(input.source, input.flags);
+        result2.lastIndex = input.lastIndex;
+        return result2;
+      }
+      if (input instanceof import_mongoose2.mongo.BSON.BSONValue) {
+        try {
+          return import_mongoose2.mongo.BSON.deserialize(import_mongoose2.mongo.BSON.serialize({ value: input }), {
+            promoteValues: false,
+            bsonRegExp: true
+          }).value;
+        } catch {
+          authorizationError("unsupported BSON snapshot");
+        }
+      }
+      if (configuration && input instanceof Map) {
+        return new Map([...input].map(([key, entry]) => [copy(key, depth + 1), copy(entry, depth + 1)]));
+      }
+      if (configuration && input instanceof Set) return new Set([...input].map((entry) => copy(entry, depth + 1)));
+      const array = Array.isArray(input);
+      if (array && input.length > 2e4) authorizationError("snapshot array exceeds structural limits");
+      if (!array) authorizationRecord(input, "snapshot");
+      const result = array ? [] : {};
+      for (const key of Reflect.ownKeys(input)) {
+        if (array && key === "length") continue;
+        if (typeof key !== "string" || unsafeKeys.has(key)) authorizationError("unsafe snapshot key");
+        if (array && !/^(0|[1-9]\d*)$/.test(key)) authorizationError("invalid array property");
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (!("value" in descriptor) || !descriptor.enumerable && configuration !== "document")
+          authorizationError("accessor/non-enumerable input");
+        Object.defineProperty(result, key, {
+          value: copy(descriptor.value, depth + 1),
+          enumerable: true,
+          writable: true,
+          configurable: true
+        });
+      }
+      if (array) result.length = input.length;
+      return Object.freeze(result);
+    } finally {
+      active.delete(input);
+    }
+  }
+  return copy(value, 0);
+}
+
+// src/acl/field-catalog.ts
+var safeSegment = (part) => !!part && part !== "sub" && !["__proto__", "constructor", "prototype", "_doc", "__v"].includes(part) && !/^[+$-]|[\s*]/.test(part) && !part.includes("[") && !part.includes("]") && !/^\d+$/.test(part) && ![...part].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+var isSafeOutputPath = (path) => path.split(".").every(safeSegment);
+var inputControlSegments = /* @__PURE__ */ new Set([
+  "_permissions",
+  "_view",
+  "_edit",
+  "documentAuthorization",
+  "documentAuthorizationStage",
+  "resolvedAuthorization",
+  "execution",
+  "executionContext",
+  "serviceExecutionContext",
+  "preparedQuery",
+  "preparedFilter",
+  "preparedModelQuery",
+  "resolvedIdentifier",
+  "skipParsing",
+  "skipAuthorization",
+  "alreadyAuthorized"
+]);
+function isSafeInputPath(path, requestIdentity = false) {
+  return isSafeOutputPath(path) && path.split(".").every((part) => !inputControlSegments.has(part) && (requestIdentity || part !== "_id"));
+}
+function matchesCatalogPattern(pattern, path, descendants = false) {
+  const expected = pattern.split(".");
+  const actual = path.split(".");
+  return (descendants ? actual.length >= expected.length : actual.length === expected.length) && expected.every((part, index) => part === "$*" || part === actual[index]);
+}
+function captureAuthorizationFieldCatalog(schema, virtuals, documentPermissionField = "_permissions") {
+  const paths = /* @__PURE__ */ new Set();
+  const containers = /* @__PURE__ */ new Set();
+  const opaque = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const virtualPaths = /* @__PURE__ */ new Set();
+  const virtualScopes = /* @__PURE__ */ new Set();
+  const schemaVirtualPaths = /* @__PURE__ */ new Set();
+  const arrays = /* @__PURE__ */ new Set();
+  const protectedPaths = /* @__PURE__ */ new Set([documentPermissionField, "_doc", "$__", "__v"]);
+  const add = (path) => {
+    if (path.split(".").every((part) => part === "$*" || safeSegment(part))) paths.add(path);
+  };
+  const ancestors = (path) => {
+    const parts = path.split(".");
+    for (let n = 1; n < parts.length; n++) {
+      const parent = parts.slice(0, n).join(".");
+      add(parent);
+      containers.add(parent);
+    }
+  };
+  const visitType = (type, path, active) => {
+    add(path);
+    ancestors(path);
+    const element = type.$embeddedSchemaType ?? type.embeddedSchemaType ?? type.caster;
+    if (type.instance === "Array" || type.$isMongooseDocumentArray) arrays.add(path);
+    if (type.options?.ref || type.options?.refPath || element?.options?.ref || element?.options?.refPath) {
+      references.add(path);
+      return;
+    }
+    if (type.$isSchemaMap || type.instance === "Map") {
+      const value = type.$__schemaType;
+      if (value) visitType(value, `${path}.$*`, active);
+      else opaque.add(path);
+      containers.delete(path);
+      return;
+    }
+    const child = type.schema ?? element?.schema;
+    if (child) {
+      containers.add(path);
+      if (!active.has(child)) visitSchema(child, path, /* @__PURE__ */ new Set([...active, child]));
+      return;
+    }
+    if (type.instance === "Mixed" || element?.instance === "Mixed") opaque.add(path);
+  };
+  const visitSchema = (current, prefix, active) => {
+    const version = current.options.versionKey;
+    if (typeof version === "string") protectedPaths.add(prefix ? `${prefix}.${version}` : version);
+    for (const name of Object.keys(current.virtuals)) {
+      schemaVirtualPaths.add(prefix ? `${prefix}.${name}` : name);
+    }
+    for (const [name, raw] of Object.entries(current.paths)) {
+      if (name.includes("$*")) continue;
+      visitType(raw, prefix ? `${prefix}.${name}` : name, active);
+    }
+  };
+  visitSchema(schema, "", /* @__PURE__ */ new Set([schema]));
+  const persistedPaths = [...paths];
+  const visitVirtuals = (record2, prefix) => {
+    for (const [name, value] of Object.entries(record2 ?? {})) {
+      if (value === void 0) continue;
+      const path = prefix ? `${prefix}.${name}` : name;
+      if (!isSafeOutputPath(path)) continue;
+      if (value && typeof value === "object" && "sub" in value) {
+        if (references.has(path)) continue;
+        virtualScopes.add(path);
+        add(path);
+        containers.add(path);
+        visitVirtuals(value.sub, path);
+      } else {
+        add(path);
+        ancestors(path);
+        virtualPaths.add(path);
+      }
+    }
+  };
+  visitVirtuals(virtuals, "");
+  const eligible = [...paths].filter((p) => ![...protectedPaths].some((v) => matchesCatalogPattern(v, p, true)));
+  return Object.freeze({
+    paths: Object.freeze(eligible.filter((p) => !p.includes("$*"))),
+    persistedPaths: Object.freeze(persistedPaths),
+    arrayPaths: Object.freeze([...arrays]),
+    schemaVirtualPaths: Object.freeze([...schemaVirtualPaths]),
+    metadataPaths: Object.freeze([documentPermissionField]),
+    dynamicPaths: Object.freeze(eligible.filter((p) => p.includes("$*"))),
+    containerPaths: Object.freeze([...containers]),
+    opaquePaths: Object.freeze([...opaque]),
+    referencePaths: Object.freeze([...references]),
+    virtualPaths: Object.freeze([...virtualPaths]),
+    virtualScopePaths: Object.freeze([...virtualScopes]),
+    protectedPaths: Object.freeze([...protectedPaths])
+  });
+}
+
+// src/acl/virtual-populate-dependencies.ts
+var elementType = (type) => type.$embeddedSchemaType ?? type.embeddedSchemaType ?? type.caster;
+var join = (prefix, path) => prefix ? `${prefix}.${path}` : path;
+var within = (path, parent) => path === parent || path.startsWith(`${parent}.`);
+var accesses = ["default", "list", "create", "read", "update"];
+var fail = (label, message) => {
+  throw new Error(`Virtual ${label}: dependsOnPopulate ${message}`);
+};
+var varyingSchema = (schema) => Object.keys(schema.discriminators ?? {}).length > 0 || schema.discriminatorMapping?.isRoot === false;
+var varyingModel = (model) => !!model.baseModelName || Object.keys(model.discriminators ?? {}).length > 0 || varyingSchema(model.schema);
+function record(value, label) {
+  if (!(0, import_utils11.isPlainObject)(value)) return fail(label, "entries must be plain { path, select? } objects");
+  for (const key of Reflect.ownKeys(value)) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !property.enumerable || !("value" in property))
+      fail(label, "requires enumerable data properties");
+  }
+  return value;
+}
+function targetSelectionCatalog(schema, options) {
+  const leaves = /* @__PURE__ */ new Set();
+  const containers = /* @__PURE__ */ new Set();
+  const forbidden = /* @__PURE__ */ new Set([options.documentPermissionField ?? "_permissions"]);
+  const visit = (current, prefix, active) => {
+    const version = current.options.versionKey;
+    if (typeof version === "string") forbidden.add(join(prefix, version));
+    for (const name of Object.keys(current.virtuals)) forbidden.add(join(prefix, name));
+    for (const name of Object.keys(current.aliases ?? {})) forbidden.add(join(prefix, name));
+    for (const [name, raw] of Object.entries(current.paths)) {
+      const path = join(prefix, name);
+      if (!isSafeInputPath(path, true)) continue;
+      const parts = path.split(".");
+      for (let n = 1; n < parts.length; n++) containers.add(parts.slice(0, n).join("."));
+      let type = raw;
+      while (type.instance === "Array" && elementType(type)) type = elementType(type);
+      if (type.instance === "Mixed" || type.instance === "Map") {
+        forbidden.add(path);
+        continue;
+      }
+      const child = type.schema ?? raw.schema;
+      if (raw.options?.ref !== void 0 || raw.options?.refPath !== void 0 || type.options?.ref !== void 0 || type.options?.refPath !== void 0) {
+        if (child) forbidden.add(path);
+        else leaves.add(path);
+        continue;
+      }
+      if (child) {
+        if (active.has(child) || varyingSchema(child)) forbidden.add(path);
+        else {
+          containers.add(path);
+          visit(child, path, /* @__PURE__ */ new Set([...active, child]));
+        }
+      } else leaves.add(path);
+    }
+  };
+  visit(schema, "", /* @__PURE__ */ new Set([schema]));
+  const visitVirtuals = (virtuals, prefix) => {
+    for (const [name, entry] of Object.entries(virtuals)) {
+      if (entry === void 0) continue;
+      const path = join(prefix, name);
+      if (isVirtualContainerValue(entry)) visitVirtuals(entry.sub, path);
+      else forbidden.add(path);
+    }
+  };
+  visitVirtuals(options.virtuals ?? {}, "");
+  const allowed = (path) => ![...forbidden].some((blocked) => within(path, blocked));
+  return {
+    leaves: [...leaves].filter(allowed).sort(),
+    paths: new Set([...leaves, ...containers].filter(allowed))
+  };
+}
+function normalizeSelection(select, catalog, label) {
+  if (select !== void 0 && typeof select !== "string") {
+    if (Array.isArray(select)) {
+      if (Array.from(select).some((token) => typeof token !== "string")) fail(label, "select arrays require strings");
+    } else {
+      const projection = record(select, label);
+      for (const [path, value] of Object.entries(projection)) {
+        if (!isSafeInputPath(path, true) || value !== 1 && value !== -1)
+          fail(label, "select objects require safe persisted paths with 1/-1 values");
+      }
+    }
+  }
+  const tokens = normalizeSelect(select);
+  for (const token of tokens) {
+    const path = token.startsWith("-") ? token.slice(1) : token;
+    if (!isSafeInputPath(path, true) || !catalog.paths.has(path))
+      fail(label, `select path "${path}" is not an eligible static persisted target path`);
+  }
+  const positive = tokens.filter((token) => !token.startsWith("-"));
+  const negative = tokens.filter((token) => token.startsWith("-")).map((token) => token.slice(1));
+  const selection = catalog.leaves.filter(
+    (path) => (path === "_id" || positive.length === 0 || positive.some((included) => within(path, included))) && !negative.some((excluded) => within(path, excluded))
+  );
+  return {
+    selection: Object.freeze(selection),
+    fetchSelection: Object.freeze([.../* @__PURE__ */ new Set(["_id", ...selection])].sort()),
+    includeId: selection.includes("_id")
+  };
+}
+function captureVirtualPopulateDependencies(runtime, modelName, options) {
+  const model = runtime.getModelInstance(modelName);
+  const targets = /* @__PURE__ */ new Map();
+  const scopes = [];
+  const visit = (virtuals, schema, schemaPrefix, scopePath, unsupportedScope) => {
+    const sourcePrefix = scopePath.filter((_, index) => index % 2 === 0).join(".");
+    const captureList = (value, label) => {
+      if (value === void 0) return Object.freeze([]);
+      if (!Array.isArray(value)) return fail(label, "must be an array");
+      const seen = /* @__PURE__ */ new Set();
+      return Object.freeze(
+        Array.from(value, (entry) => {
+          const dependency = record(entry, label);
+          if (Object.keys(dependency).some((key) => key !== "path" && key !== "select"))
+            fail(label, "accepts only path/select");
+          const path = dependency.path;
+          if (typeof path !== "string" || path.includes(".") || !isSafeInputPath(path, true))
+            return fail(label, "path must be a safe scope-local persisted reference key");
+          if (seen.has(path)) fail(label, `duplicate path "${path}"`);
+          seen.add(path);
+          if (within(join(sourcePrefix, path), options.documentPermissionField ?? "_permissions") || path === schema?.options.versionKey)
+            fail(label, "source permission metadata/version paths are not reference inputs");
+          if (!model || !schema || unsupportedScope)
+            return fail(label, "requires a static embedded, non-discriminator source scope");
+          const type = schema.path(join(schemaPrefix, path));
+          const isArray6 = type?.instance === "Array";
+          const scalar = type && (isArray6 ? elementType(type) : type);
+          const ref = type?.options?.ref ?? scalar?.options?.ref;
+          if (!scalar || scalar.instance !== "ObjectId" || typeof ref !== "string" || !ref || type?.options?.refPath !== void 0 || scalar.options?.refPath !== void 0)
+            return fail(label, `path "${path}" requires a static string ref on an ObjectId scalar or 1D array`);
+          let captured = targets.get(ref);
+          if (!captured) {
+            if (ref !== modelName && !runtime.hasModel(ref))
+              return fail(label, `target "${ref}" must be configured first in this runtime`);
+            const targetModel = runtime.getModelInstance(ref);
+            if (!targetModel || targetModel.db !== model.db || model.db.models[ref] !== targetModel || varyingModel(targetModel) || targetModel.schema.path("_id")?.instance !== "ObjectId")
+              return fail(
+                label,
+                `target "${ref}" requires a registered same-connection non-discriminator ObjectId model bound to the source ref`
+              );
+            const targetOptions = ref === modelName ? options : runtime.getModelOptions(ref);
+            const defaults = runtime.getDefaultModelOptions();
+            const readOption = (key) => resolveNestedOption((path2, fallback) => (0, import_utils11.get)(targetOptions, path2, fallback), key, (0, import_utils11.get)(defaults, key));
+            const documentPermissionField = targetOptions.documentPermissionField ?? defaults.documentPermissionField;
+            const catalog = captureAuthorizationFieldCatalog(targetModel.schema, void 0, documentPermissionField);
+            const configuration = copyAuthorizationValue(
+              {
+                catalog,
+                documentPermissionField,
+                operationAccess: { read: readOption("operationAccess.read") },
+                baseFilter: { read: readOption("baseFilter.read") },
+                overrideFilter: { read: readOption("overrideFilter.read") },
+                hydration: targetOptions.hydration
+              },
+              true
+            );
+            captured = {
+              target: Object.freeze({
+                identity: Object.freeze({}),
+                runtime,
+                modelName: ref,
+                model: targetModel,
+                schema: targetModel.schema,
+                configuration
+              }),
+              catalog: targetSelectionCatalog(targetModel.schema, { ...targetOptions, documentPermissionField })
+            };
+            targets.set(ref, captured);
+          }
+          return Object.freeze({
+            path,
+            sourcePath: join(sourcePrefix, path),
+            cardinality: isArray6 ? "array" : "scalar",
+            target: captured.target,
+            ...normalizeSelection(dependency.select, captured.catalog, label)
+          });
+        })
+      );
+    };
+    for (const [name, raw] of Object.entries(virtuals)) {
+      if (isVirtualContainerValue(raw)) {
+        const path = join(schemaPrefix, name);
+        const type = schema?.path(path);
+        const element = type && elementType(type);
+        const child = type?.schema ?? element?.schema;
+        const nonEmbedded = [type, element].some(
+          (entry2) => entry2 && (entry2.options?.ref !== void 0 || entry2.options?.refPath !== void 0 || entry2.instance === "Map" || entry2.instance === "Mixed")
+        );
+        visit(
+          raw.sub,
+          child ?? schema,
+          child ? "" : path,
+          [...scopePath, name, "sub"],
+          unsupportedScope || nonEmbedded || !!(child && varyingSchema(child))
+        );
+        continue;
+      }
+      if (!(0, import_utils11.isPlainObject)(raw)) continue;
+      const entry = raw;
+      const label = join(sourcePrefix, name);
+      captureList(entry.dependsOnPopulate, label);
+      if (!("get" in entry))
+        for (const access of accesses) {
+          if ((0, import_utils11.isPlainObject)(entry[access]))
+            captureList(entry[access].dependsOnPopulate, `${label}.${access}`);
+        }
+      const byAccess = {};
+      let declared = false;
+      for (const access of accesses) {
+        const descriptor = resolveSnapshotDescriptor(virtuals, name, access);
+        if (descriptor) {
+          byAccess[access] = captureList(descriptor.dependsOnPopulate, `${label}.${access}`);
+          declared ||= descriptor.dependsOnPopulate !== void 0;
+        }
+      }
+      if (declared)
+        scopes.push(
+          Object.freeze({
+            scopePath: Object.freeze([...scopePath]),
+            virtualName: name,
+            byAccess: Object.freeze(byAccess)
+          })
+        );
+    }
+  };
+  visit(options.virtuals ?? {}, model?.schema, "", [], !!model && varyingModel(model));
+  return Object.freeze({ scopes: Object.freeze(scopes) });
+}
+
 // src/runtime.ts
 var mongooseJsonSchemaInitialized = false;
 var ensureMongooseJsonSchemaInitialized = () => {
   if (mongooseJsonSchemaInitialized) return;
-  (0, import_mongoose_schema_jsonschema.default)(import_mongoose2.default);
+  (0, import_mongoose_schema_jsonschema.default)(import_mongoose3.default);
   mongooseJsonSchemaInitialized = true;
 };
-var pluralize = import_mongoose2.default.pluralize();
+var pluralize = import_mongoose3.default.pluralize();
 var FIELD_ACCESS_KEYS = ["list", "create", "read", "update"];
 var defaultModelOptions = {
   basePath: null,
@@ -1200,44 +1693,44 @@ var defaultDataOptions = {
   listHardLimit: DEFAULT_LIST_HARD_LIMIT
 };
 var normalizeBasePath = (name, value) => {
-  if ((0, import_utils10.isNil)(value)) {
+  if ((0, import_utils12.isNil)(value)) {
     return `/${pluralize(name)}`;
   }
-  return (0, import_utils10.isString)(value) ? (0, import_utils10.addLeadingSlash)(value) : "";
+  return (0, import_utils12.isString)(value) ? (0, import_utils12.addLeadingSlash)(value) : "";
 };
 var hasModelPermission = (value, modelPermissionPrefix) => {
   if (!modelPermissionPrefix) {
     return true;
   }
-  if ((0, import_utils10.isString)(value)) {
+  if ((0, import_utils12.isString)(value)) {
     return value.trim().split(" ").some((item) => item.startsWith(modelPermissionPrefix));
   }
-  if ((0, import_utils10.isArray)(value)) {
+  if ((0, import_utils12.isArray)(value)) {
     return value.some((item) => {
-      if ((0, import_utils10.isString)(item) || (0, import_utils10.isArray)(item)) {
+      if ((0, import_utils12.isString)(item) || (0, import_utils12.isArray)(item)) {
         return hasModelPermission(item, modelPermissionPrefix);
       }
       return true;
     });
   }
-  return (0, import_utils10.isFunction)(value);
+  return (0, import_utils12.isFunction)(value);
 };
 var classifyPermissionSchema = (permissionSchema, modelPermissionPrefix) => {
   const schemaKeys = Object.keys(permissionSchema);
   const globalPermissionKeys = {};
   const modelPermissionKeys = {};
-  (0, import_utils10.forEach)(schemaKeys, (schemaKey) => {
+  (0, import_utils12.forEach)(schemaKeys, (schemaKey) => {
     const schemaRule = permissionSchema[schemaKey];
-    const ruleEntries = (0, import_utils10.isPlainObject)(schemaRule) ? Object.entries(schemaRule) : FIELD_ACCESS_KEYS.map((accessKey) => [accessKey, schemaRule]);
+    const ruleEntries = (0, import_utils12.isPlainObject)(schemaRule) ? Object.entries(schemaRule) : FIELD_ACCESS_KEYS.map((accessKey) => [accessKey, schemaRule]);
     for (let x = 0; x < ruleEntries.length; x++) {
       const [accessKey, value] = ruleEntries[x];
-      if (!(0, import_utils10.isArray)(globalPermissionKeys[accessKey])) {
+      if (!(0, import_utils12.isArray)(globalPermissionKeys[accessKey])) {
         globalPermissionKeys[accessKey] = [];
       }
-      if (!(0, import_utils10.isArray)(modelPermissionKeys[accessKey])) {
+      if (!(0, import_utils12.isArray)(modelPermissionKeys[accessKey])) {
         modelPermissionKeys[accessKey] = [];
       }
-      if ((0, import_utils10.isBoolean)(value)) {
+      if ((0, import_utils12.isBoolean)(value)) {
         globalPermissionKeys[accessKey].push(schemaKey);
         continue;
       }
@@ -1269,13 +1762,13 @@ var VIRTUAL_UNSUPPORTED_ACCESSES = ["delete", "distinct", "count"];
 var VIRTUAL_RESERVED_NAMES = /* @__PURE__ */ new Set(["_id", "__v", "id"]);
 var VIRTUAL_DANGEROUS_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 var VIRTUAL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
-var isVirtualContainerValue = (value) => (0, import_utils10.isPlainObject)(value) && "sub" in value;
+var isVirtualContainerValue2 = (value) => (0, import_utils12.isPlainObject)(value) && "sub" in value;
 var virtualFullPath = (prefix, name) => prefix ? `${prefix}.${name}` : name;
 var virtualPathsOverlap = (virtualPath, permissionField) => {
   if (!virtualPath || !permissionField) return false;
   try {
-    if ((0, import_utils10.get)((0, import_utils10.set)({}, virtualPath, true), permissionField) !== void 0) return true;
-    if ((0, import_utils10.get)((0, import_utils10.set)({}, permissionField, true), virtualPath) !== void 0) return true;
+    if ((0, import_utils12.get)((0, import_utils12.set)({}, virtualPath, true), permissionField) !== void 0) return true;
+    if ((0, import_utils12.get)((0, import_utils12.set)({}, permissionField, true), virtualPath) !== void 0) return true;
   } catch {
     return false;
   }
@@ -1336,12 +1829,12 @@ var cloneVirtualsForValidation = (value) => {
 };
 var validateVirtualDependsOn = (dependsOn, entryLabel, storedFields, siblingVirtualNames) => {
   if (dependsOn === void 0) return [];
-  if (!(0, import_utils10.isArray)(dependsOn)) {
+  if (!(0, import_utils12.isArray)(dependsOn)) {
     throw new Error(`Virtual ${entryLabel}: dependsOn must be an array of top-level persisted field names`);
   }
   const list = dependsOn;
   for (const dep of list) {
-    if (!(0, import_utils10.isString)(dep) || dep.length === 0) {
+    if (!(0, import_utils12.isString)(dep) || dep.length === 0) {
       throw new Error(`Virtual ${entryLabel}: dependsOn entries must be non-empty strings`);
     }
     if (dep.includes(".")) {
@@ -1363,18 +1856,20 @@ var validateVirtualDependsOn = (dependsOn, entryLabel, storedFields, siblingVirt
   return list;
 };
 var validateVirtualLeafValue = (value, entryLabel, storedFields, siblingVirtualNames, sharedDependsOn) => {
-  if ((0, import_utils10.isFunction)(value)) return;
-  if (!(0, import_utils10.isPlainObject)(value)) {
+  if ((0, import_utils12.isFunction)(value)) return;
+  if (!(0, import_utils12.isPlainObject)(value)) {
     throw new Error(`Virtual ${entryLabel}: descriptor must be a getter function or { get, dependsOn }`);
   }
-  const record = value;
-  if (!(0, import_utils10.isFunction)(record.get)) {
+  const record2 = value;
+  if (!(0, import_utils12.isFunction)(record2.get)) {
     throw new Error(`Virtual ${entryLabel}: descriptor.get must be a callable getter function`);
   }
-  validateVirtualDependsOn(record.dependsOn ?? sharedDependsOn, entryLabel, storedFields, siblingVirtualNames);
-  for (const k of Object.keys(record)) {
-    if (k !== "get" && k !== "dependsOn") {
-      throw new Error(`Virtual ${entryLabel}: unsupported descriptor key "${k}" (expected only get/dependsOn)`);
+  validateVirtualDependsOn(record2.dependsOn ?? sharedDependsOn, entryLabel, storedFields, siblingVirtualNames);
+  for (const k of Object.keys(record2)) {
+    if (k !== "get" && k !== "dependsOn" && k !== "dependsOnPopulate") {
+      throw new Error(
+        `Virtual ${entryLabel}: unsupported descriptor key "${k}" (expected get/dependsOn/dependsOnPopulate)`
+      );
     }
   }
 };
@@ -1383,7 +1878,7 @@ var validateVirtualsScope = (scope, documentPermissionField) => {
   const leafNames = /* @__PURE__ */ new Set();
   for (const [name, raw] of Object.entries(scopeVirtuals)) {
     if (raw === void 0) continue;
-    if (isVirtualContainerValue(raw)) continue;
+    if (isVirtualContainerValue2(raw)) continue;
     leafNames.add(name);
   }
   for (const [name, raw] of Object.entries(scopeVirtuals)) {
@@ -1400,15 +1895,15 @@ var validateVirtualsScope = (scope, documentPermissionField) => {
         `Virtual ${scopeLabel}${name}: overlaps document permission field "${documentPermissionField}" (equal/ancestor/descendant rejected)`
       );
     }
-    if (isVirtualContainerValue(raw)) {
-      const record2 = raw;
-      const extra = Object.keys(record2).filter((k) => k !== "sub");
+    if (isVirtualContainerValue2(raw)) {
+      const record3 = raw;
+      const extra = Object.keys(record3).filter((k) => k !== "sub");
       if (extra.length > 0) {
         throw new Error(
           `Virtual ${scopeLabel}${name}: scope-container must only hold "sub" (embedded container "${name}" is not a virtual-leaf collision)`
         );
       }
-      if (!(0, import_utils10.isPlainObject)(record2.sub)) {
+      if (!(0, import_utils12.isPlainObject)(record3.sub)) {
         throw new Error(`Virtual ${scopeLabel}${name}: scope-container "sub" must be a plain object`);
       }
       continue;
@@ -1418,19 +1913,19 @@ var validateVirtualsScope = (scope, documentPermissionField) => {
         `Virtual ${scopeLabel}${name}: collides with a stored path (inspected actual Mongoose schema/child scope; getModelAtt alone is insufficient)`
       );
     }
-    if ((0, import_utils10.isFunction)(raw)) continue;
-    if (!(0, import_utils10.isPlainObject)(raw)) {
+    if ((0, import_utils12.isFunction)(raw)) continue;
+    if (!(0, import_utils12.isPlainObject)(raw)) {
       throw new Error(
         `Virtual ${scopeLabel}${name}: malformed descriptor (expected getter, { get, dependsOn }, or per-access record)`
       );
     }
-    const record = raw;
-    const hasGet = "get" in record;
-    const accessKeys = Object.keys(record).filter((k) => VIRTUAL_SUPPORTED_ACCESSES.includes(k));
-    const unsupported2 = Object.keys(record).filter(
-      (k) => k !== "get" && k !== "dependsOn" && k !== "sub" && !VIRTUAL_SUPPORTED_ACCESSES.includes(k)
+    const record2 = raw;
+    const hasGet = "get" in record2;
+    const accessKeys = Object.keys(record2).filter((k) => VIRTUAL_SUPPORTED_ACCESSES.includes(k));
+    const unsupported2 = Object.keys(record2).filter(
+      (k) => k !== "get" && k !== "dependsOn" && k !== "dependsOnPopulate" && k !== "sub" && !VIRTUAL_SUPPORTED_ACCESSES.includes(k)
     );
-    for (const key of Object.keys(record)) {
+    for (const key of Object.keys(record2)) {
       if (VIRTUAL_UNSUPPORTED_ACCESSES.includes(key)) {
         throw new Error(
           `Virtual ${scopeLabel}${name}: unsupported access "${key}" (supported: default + list/create/read/update; NOT delete/distinct/count)`
@@ -1448,21 +1943,21 @@ var validateVirtualsScope = (scope, documentPermissionField) => {
           `Virtual ${scopeLabel}${name}: cannot mix "get" with per-access keys (use either bare { get, dependsOn } or a per-access record)`
         );
       }
-      if ("sub" in record) {
+      if ("sub" in record2) {
         throw new Error(`Virtual ${scopeLabel}${name}: cannot mix "get" with "sub" (leaf vs embedded container)`);
       }
       validateVirtualLeafValue(raw, `${scopeLabel}${name}`, storedFields, leafNames, void 0);
       continue;
     }
     if (accessKeys.length > 0) {
-      if ("sub" in record) {
+      if ("sub" in record2) {
         throw new Error(`Virtual ${scopeLabel}${name}: cannot mix per-access keys with "sub"`);
       }
-      validateVirtualDependsOn(record.dependsOn, `${scopeLabel}${name}`, storedFields, leafNames);
+      validateVirtualDependsOn(record2.dependsOn, `${scopeLabel}${name}`, storedFields, leafNames);
       for (const access of accessKeys) {
-        const leaf = record[access];
+        const leaf = record2[access];
         if (leaf === void 0) continue;
-        validateVirtualLeafValue(leaf, `${scopeLabel}${name}.${access}`, storedFields, leafNames, record.dependsOn);
+        validateVirtualLeafValue(leaf, `${scopeLabel}${name}.${access}`, storedFields, leafNames, record2.dependsOn);
       }
       continue;
     }
@@ -1473,7 +1968,7 @@ var validateVirtualsScope = (scope, documentPermissionField) => {
 };
 var validateVirtualsTree = (model, virtuals, documentPermissionField, modelName) => {
   if (virtuals === void 0 || virtuals === null) return;
-  if (!(0, import_utils10.isPlainObject)(virtuals)) {
+  if (!(0, import_utils12.isPlainObject)(virtuals)) {
     throw new Error(`Virtuals for model "${modelName}": virtuals must be a plain object mapping names to descriptors`);
   }
   const rootSchema = model?.schema ?? null;
@@ -1483,13 +1978,14 @@ var validateVirtualsTree = (model, virtuals, documentPermissionField, modelName)
     { scopeVirtuals: rootVirtuals, storedFields: rootStored, scopePrefix: "", scopeLabel: "" },
     documentPermissionField
   );
-  const visitContainers = (currentVirtuals, currentSchema, currentPrefix) => {
+  const visitContainers = (currentVirtuals, currentSchema, currentPrefix, schemaPrefix = "") => {
     for (const [containerName, raw] of Object.entries(currentVirtuals)) {
-      if (raw === void 0 || !isVirtualContainerValue(raw)) continue;
-      const record = raw;
-      const childSchema = getChildSchemaForField(currentSchema, containerName);
-      const nestedFields = getNestedChildFields(currentSchema, containerName);
-      const currentStored = collectStoredTopLevel(currentSchema);
+      if (raw === void 0 || !isVirtualContainerValue2(raw)) continue;
+      const record2 = raw;
+      const schemaPath = virtualFullPath(schemaPrefix, containerName);
+      const childSchema = getChildSchemaForField(currentSchema, schemaPath);
+      const nestedFields = getNestedChildFields(currentSchema, schemaPath);
+      const currentStored = schemaPrefix ? getNestedChildFields(currentSchema, schemaPrefix) : collectStoredTopLevel(currentSchema);
       if (!currentStored.has(containerName)) {
         throw new Error(
           `Virtual ${containerName}: scope-container "${containerName}" is not a persisted field in its scope`
@@ -1503,7 +1999,7 @@ var validateVirtualsTree = (model, virtuals, documentPermissionField, modelName)
       }
       const subStored = childSchema ? collectStoredTopLevel(childSchema) : nestedFields;
       const subPrefix = currentPrefix ? `${currentPrefix}.${containerName}` : containerName;
-      const subVirtuals = record.sub ?? {};
+      const subVirtuals = record2.sub ?? {};
       validateVirtualsScope(
         {
           scopeVirtuals: subVirtuals,
@@ -1513,37 +2009,11 @@ var validateVirtualsTree = (model, virtuals, documentPermissionField, modelName)
         },
         documentPermissionField
       );
-      const nextSchema = childSchema;
-      visitContainers(subVirtuals, nextSchema, subPrefix);
+      visitContainers(subVirtuals, childSchema ?? currentSchema, subPrefix, childSchema ? "" : schemaPath);
     }
   };
   visitContainers(rootVirtuals, rootSchema, "");
 };
-var getScopeVirtualsObject = (rootVirtuals, scopePath) => {
-  if (!rootVirtuals || !(0, import_utils10.isPlainObject)(rootVirtuals)) return null;
-  if (!scopePath || scopePath.length === 0) return rootVirtuals;
-  let current = rootVirtuals;
-  for (let i = 0; i < scopePath.length; i += 2) {
-    const field = scopePath[i];
-    const subMarker = scopePath[i + 1];
-    if (!field || subMarker !== "sub") return null;
-    if (!(0, import_utils10.isPlainObject)(current)) return null;
-    const container = current[field];
-    if (!isVirtualContainerValue(container)) return null;
-    current = container.sub;
-    if (!(0, import_utils10.isPlainObject)(current)) return null;
-  }
-  return current;
-};
-var toVirtualDescriptor = (leaf, sharedDependsOn) => {
-  if ((0, import_utils10.isFunction)(leaf))
-    return { get: leaf, dependsOn: sharedDependsOn ?? [] };
-  if (!(0, import_utils10.isPlainObject)(leaf)) return null;
-  const record = leaf;
-  if (!(0, import_utils10.isFunction)(record.get)) return null;
-  const dependsOn = record.dependsOn ?? sharedDependsOn ?? [];
-  return { get: record.get, dependsOn };
-};
 var AccessRuntime = class {
   constructor(options = {}) {
     this.globalOptions = new OptionsManager(
@@ -1592,20 +2062,20 @@ var AccessRuntime = class {
     this.modelInstances[modelName] = model;
   }
   hasModelInstance(modelName) {
-    return modelName in this.modelInstances || this.allowGlobalModelLookup && modelName in import_mongoose2.default.models;
+    return modelName in this.modelInstances || this.allowGlobalModelLookup && modelName in import_mongoose3.default.models;
   }
   getModelInstance(modelName) {
     const registered = this.modelInstances[modelName];
     if (registered) return registered;
     if (!this.allowGlobalModelLookup) return null;
-    const global = import_mongoose2.default.models[modelName];
+    const global = import_mongoose3.default.models[modelName];
     if (!global) return null;
     this.registerModelInstance(modelName, global);
     return global;
   }
   registerOpenApiRoute(route) {
     this.openApiRegistry.register(
-      this.openApiPathPrefix ? { ...route, path: (0, import_utils10.normalizeUrlPath)(`${this.openApiPathPrefix}/${route.path}`) } : route
+      this.openApiPathPrefix ? { ...route, path: (0, import_utils12.normalizeUrlPath)(`${this.openApiPathPrefix}/${route.path}`) } : route
     );
   }
   /**
@@ -1616,7 +2086,7 @@ var AccessRuntime = class {
    */
   withOpenApiPathPrefix(prefix, build) {
     const previous = this.openApiPathPrefix;
-    this.openApiPathPrefix = (0, import_utils10.normalizeUrlPath)(`${previous}/${prefix}`);
+    this.openApiPathPrefix = (0, import_utils12.normalizeUrlPath)(`${previous}/${prefix}`);
     try {
       return build();
     } finally {
@@ -1752,7 +2222,7 @@ var AccessRuntime = class {
     if (keyStr === "defaults") assertPublicDefaults(value);
     else if (keyStr.startsWith("defaults.")) {
       const proposed = {};
-      (0, import_utils10.set)(proposed, keyStr.slice("defaults.".length), value);
+      (0, import_utils12.set)(proposed, keyStr.slice("defaults.".length), value);
       assertPublicDefaults(proposed);
     }
     this.defaultModelOptions.set(key, value);
@@ -1781,7 +2251,7 @@ var AccessRuntime = class {
     }).onchange("basePath", function(newval, key, target) {
       target[key] = normalizeBasePath(
         modelName,
-        (0, import_utils10.isString)(newval) || (0, import_utils10.isNil)(newval) ? newval : void 0
+        (0, import_utils12.isString)(newval) || (0, import_utils12.isNil)(newval) ? newval : void 0
       );
     }).build();
     this.modelJsonSchemas[modelName] = model.jsonSchema();
@@ -1805,13 +2275,14 @@ var AccessRuntime = class {
   setModelOptions(modelName, options) {
     assertPublicDefaults(options.defaults);
     if ("hydration" in options) options = { ...options, hydration: normalizeHydration(options.hydration) };
-    const manager = this.getOrCreateModelOptions(modelName);
     const defaultOptions = this.getDefaultModelOptions();
-    const currentModelOptions = manager.fetch();
+    const currentModelOptions = this.modelOptions[modelName]?.fetch() ?? { ...defaultModelOptions, modelName };
     const merged = { ...defaultOptions, ...currentModelOptions, ...options };
     const model = this.getModelInstance(modelName);
     const permissionField = merged.documentPermissionField ?? currentModelOptions.documentPermissionField ?? this.getDefaultModelOption("documentPermissionField") ?? "_permissions";
     validateVirtualsTree(model, merged.virtuals, permissionField, modelName);
+    captureVirtualPopulateDependencies(this, modelName, merged);
+    const manager = this.getOrCreateModelOptions(modelName);
     manager.assign({ ...defaultOptions, ...currentModelOptions, ...options });
   }
   setModelOption(modelName, key, value) {
@@ -1824,14 +2295,14 @@ var AccessRuntime = class {
     if (keyStr === "defaults") assertPublicDefaults(value);
     else if (keyStr.startsWith("defaults.")) {
       const proposed = {};
-      (0, import_utils10.set)(proposed, keyStr.slice("defaults.".length), value);
+      (0, import_utils12.set)(proposed, keyStr.slice("defaults.".length), value);
       assertPublicDefaults(proposed);
     }
-    const manager = this.getOrCreateModelOptions(modelName);
+    const manager = this.modelOptions[modelName];
     if (keyStr === "virtuals" || keyStr.startsWith("virtuals.") || keyStr === "documentPermissionField") {
       const model = this.getModelInstance(modelName);
-      const currentVirtuals = manager.get("virtuals");
-      const currentPermissionField = manager.get("documentPermissionField") ?? this.getDefaultModelOption("documentPermissionField") ?? "_permissions";
+      const currentVirtuals = manager?.get("virtuals");
+      const currentPermissionField = manager?.get("documentPermissionField") ?? this.getDefaultModelOption("documentPermissionField") ?? "_permissions";
       let proposedVirtuals = currentVirtuals;
       let proposedPermissionField = currentPermissionField;
       if (keyStr === "documentPermissionField") {
@@ -1845,21 +2316,27 @@ var AccessRuntime = class {
           const segments = nestedPath.split(".");
           let cursor = cloned;
           for (let i = 0; i < segments.length - 1; i++) {
-            if (!(0, import_utils10.isPlainObject)(cursor)) break;
+            if (!(0, import_utils12.isPlainObject)(cursor)) break;
             cursor = cursor[segments[i]];
           }
-          if ((0, import_utils10.isPlainObject)(cursor)) {
+          if ((0, import_utils12.isPlainObject)(cursor)) {
             delete cursor[segments[segments.length - 1]];
           }
           proposedVirtuals = cloned;
         } else {
-          (0, import_utils10.set)(cloned, nestedPath, value);
+          (0, import_utils12.set)(cloned, nestedPath, value);
           proposedVirtuals = cloned;
         }
       }
       validateVirtualsTree(model, proposedVirtuals, proposedPermissionField, modelName);
+      captureVirtualPopulateDependencies(this, modelName, {
+        ...this.getDefaultModelOptions(),
+        ...manager?.fetch(),
+        virtuals: proposedVirtuals,
+        documentPermissionField: proposedPermissionField
+      });
     }
-    manager.set(key, value);
+    this.getOrCreateModelOptions(modelName).set(key, value);
   }
   /** Frozen stored snapshot, not fully resolved per-path defaults. Read again for current configuration. */
   getModelOptions(modelName) {
@@ -1898,7 +2375,7 @@ var AccessRuntime = class {
     const rootVirtuals = manager.get("virtuals");
     const scopeVirtuals = getScopeVirtualsObject(rootVirtuals, scopePath);
     if (!scopeVirtuals) return [];
-    return Object.entries(scopeVirtuals).filter(([, v]) => v !== void 0 && !isVirtualContainerValue(v)).map(([k]) => k);
+    return Object.entries(scopeVirtuals).filter(([, v]) => v !== void 0 && !isVirtualContainerValue2(v)).map(([k]) => k);
   }
   /**
    * Whether a field is a registered virtual leaf in a scope (VIRT-01).
@@ -1912,7 +2389,7 @@ var AccessRuntime = class {
     const scopeVirtuals = getScopeVirtualsObject(rootVirtuals, scopePath);
     if (!scopeVirtuals || !(fieldName in scopeVirtuals)) return false;
     const entry = scopeVirtuals[fieldName];
-    if (entry === void 0 || isVirtualContainerValue(entry)) return false;
+    if (entry === void 0 || isVirtualContainerValue2(entry)) return false;
     return true;
   }
   /**
@@ -1922,34 +2399,14 @@ var AccessRuntime = class {
    * interpreted as a getter descriptor when the access is absent: an
    * inapplicable registered name stays virtual (excluded from persisted
    * projections, write admission, and DB sort/filter/distinct).
-   * Shared record-level `dependsOn` is inherited when a leaf lacks its own.
+   * Shared `dependsOn` and `dependsOnPopulate` lists inherit independently;
+   * each defined leaf list replaces its shared list wholesale.
    */
   resolveVirtualDescriptor(modelName, virtualName, access, scopePath) {
     const manager = this.getOrCreateModelOptions(modelName);
     const rootVirtuals = manager.get("virtuals");
     const scopeVirtuals = getScopeVirtualsObject(rootVirtuals, scopePath);
-    if (!scopeVirtuals || !(virtualName in scopeVirtuals)) return void 0;
-    const entry = scopeVirtuals[virtualName];
-    if (entry === void 0 || isVirtualContainerValue(entry)) return void 0;
-    if ((0, import_utils10.isFunction)(entry)) return { get: entry, dependsOn: [] };
-    if (!(0, import_utils10.isPlainObject)(entry)) return void 0;
-    const record = entry;
-    if ("get" in record) {
-      const descriptor = toVirtualDescriptor(entry, void 0);
-      return descriptor ?? void 0;
-    }
-    const sharedDependsOn = record.dependsOn;
-    const exact = record[access];
-    if (exact !== void 0) {
-      const descriptor = toVirtualDescriptor(exact, sharedDependsOn);
-      if (descriptor) return descriptor;
-    }
-    const fallback = record.default;
-    if (fallback !== void 0) {
-      const descriptor = toVirtualDescriptor(fallback, sharedDependsOn);
-      if (descriptor) return descriptor;
-    }
-    return void 0;
+    return resolveSnapshotDescriptor(scopeVirtuals, virtualName, access);
   }
   getModelNames() {
     return Object.keys(this.modelOptions);
@@ -1968,7 +2425,7 @@ var AccessRuntime = class {
     manager.onchange("basePath", function(newval, key, target) {
       target[key] = normalizeBasePath(
         dataName,
-        (0, import_utils10.isString)(newval) || (0, import_utils10.isNil)(newval) ? newval : void 0
+        (0, import_utils12.isString)(newval) || (0, import_utils12.isNil)(newval) ? newval : void 0
       );
     }).build();
     return manager;
@@ -2028,20 +2485,20 @@ var AccessRuntime = class {
     const schema = model.schema;
     this.modelRefs[modelName] = buildRefs(schema.tree);
     this.modelSubs[modelName] = buildSubPaths(schema.tree);
-    this.modelAtts[modelName] = (0, import_utils10.keys)(schema.obj);
+    this.modelAtts[modelName] = (0, import_utils12.keys)(schema.obj);
   }
   getModelRef(modelName, refPath) {
     this.ensureModelMeta(modelName);
-    const value = (0, import_utils10.get)(this.modelRefs, `${modelName}.${refPath}`, null);
-    return (0, import_utils10.isString)(value) ? value : null;
+    const value = (0, import_utils12.get)(this.modelRefs, `${modelName}.${refPath}`, null);
+    return (0, import_utils12.isString)(value) ? value : null;
   }
   getModelSub(modelName) {
     this.ensureModelMeta(modelName);
-    return (0, import_utils10.get)(this.modelSubs, modelName, []);
+    return (0, import_utils12.get)(this.modelSubs, modelName, []);
   }
   getModelAtt(modelName) {
     this.ensureModelMeta(modelName);
-    return (0, import_utils10.get)(this.modelAtts, modelName, []);
+    return (0, import_utils12.get)(this.modelAtts, modelName, []);
   }
 };
 var defaultRuntime = new AccessRuntime({ allowGlobalModelLookup: true });
@@ -2061,7 +2518,7 @@ var getGlobalOption = (key, defaultValue) => {
 
 // src/validation/common.ts
 var import_zod2 = require("zod");
-var import_utils12 = require("@web-ts-toolkit/utils");
+var import_utils14 = require("@web-ts-toolkit/utils");
 
 // src/validation/public-admission-schema.ts
 var admissions = /* @__PURE__ */ new WeakMap();
@@ -2083,7 +2540,7 @@ function assertTransformedPublicAdmission(schema, value) {
 }
 
 // src/correlated-includes.ts
-var import_utils11 = require("@web-ts-toolkit/utils");
+var import_utils13 = require("@web-ts-toolkit/utils");
 var PARENT_MARKER_KEY = "$parent";
 var ESCAPE_WRAPPER_KEY = "$escape";
 var SUBQUERY_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["$$sq", "$$date"]);
@@ -2094,10 +2551,10 @@ var FIELD_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
 var ARRAY_INDEX_SEGMENT_PATTERN = /^(0|[1-9]\d*)$/;
 var ownKeys = (value) => Object.keys(value);
 function isParentRefMarker(value) {
-  return (0, import_utils11.isPlainObject)(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
+  return (0, import_utils13.isPlainObject)(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
 }
 function isEscapedParentRef(value) {
-  return (0, import_utils11.isPlainObject)(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === ESCAPE_WRAPPER_KEY;
+  return (0, import_utils13.isPlainObject)(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === ESCAPE_WRAPPER_KEY;
 }
 function hasMarkerKey(value) {
   return ownKeys(value).includes(PARENT_MARKER_KEY) || ownKeys(value).includes(ESCAPE_WRAPPER_KEY);
@@ -2116,12 +2573,12 @@ function containsParentMarkerShape(value) {
   const seen = /* @__PURE__ */ new Set();
   const visit = (current) => {
     if (isParentRefMarker(current) || isEscapedParentRef(current)) return true;
-    if ((0, import_utils11.isArray)(current)) {
+    if ((0, import_utils13.isArray)(current)) {
       if (seen.has(current)) return false;
       seen.add(current);
       return current.some(visit);
     }
-    if ((0, import_utils11.isPlainObject)(current)) {
+    if ((0, import_utils13.isPlainObject)(current)) {
       if (seen.has(current)) return false;
       seen.add(current);
       if (hasMarkerKey(current)) return true;
@@ -2151,7 +2608,7 @@ function scanTemplateValueNode(value, path, issues) {
     }
     return;
   }
-  if ((0, import_utils11.isPlainObject)(value)) {
+  if ((0, import_utils13.isPlainObject)(value)) {
     if (hasMarkerKey(value)) {
       issues.push({
         message: 'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }',
@@ -2162,7 +2619,7 @@ function scanTemplateValueNode(value, path, issues) {
     scanTemplateObjectEntries(value, path, issues);
     return;
   }
-  if ((0, import_utils11.isArray)(value)) {
+  if ((0, import_utils13.isArray)(value)) {
     value.forEach((item, index) => scanTemplateValueNode(item, [...path, index], issues));
   }
 }
@@ -2203,7 +2660,7 @@ function scanTemplateObjectEntries(obj, basePath, issues) {
       continue;
     }
     if (LOGICAL_CLAUSE_KEYS.has(key)) {
-      if (!(0, import_utils11.isArray)(child)) {
+      if (!(0, import_utils13.isArray)(child)) {
         scanTemplateValueNode(child, childPath, issues);
         continue;
       }
@@ -2216,7 +2673,7 @@ function scanTemplateObjectEntries(obj, basePath, issues) {
           });
           return;
         }
-        if ((0, import_utils11.isPlainObject)(clause)) {
+        if ((0, import_utils13.isPlainObject)(clause)) {
           scanTemplateObjectEntries(clause, clausePath, issues);
         }
       });
@@ -2227,7 +2684,7 @@ function scanTemplateObjectEntries(obj, basePath, issues) {
 }
 function validateCorrelatedFilterTemplate(filter) {
   const issues = [];
-  if (!(0, import_utils11.isPlainObject)(filter)) {
+  if (!(0, import_utils13.isPlainObject)(filter)) {
     issues.push({ message: "Correlated include filter must be an object", path: [] });
     return issues;
   }
@@ -2355,7 +2812,7 @@ var correlatedFilterSchema = import_zod2.z.record(import_zod2.z.string(), import
   }
 });
 var correlatedEmptyOptionsSchema = import_zod2.z.unknown().refine(
-  (value) => value === void 0 || (0, import_utils12.isPlainObject)(value) && Object.keys(value).length === 0,
+  (value) => value === void 0 || (0, import_utils14.isPlainObject)(value) && Object.keys(value).length === 0,
   "Correlated include options must be absent or empty"
 ).optional();
 var correlatedPathSchema = import_zod2.z.string().min(1).superRefine((path, ctx) => {
@@ -2392,7 +2849,7 @@ var correlatedListArgsSchema = import_zod2.z.object({
   include: import_zod2.z.lazy(() => correlatedNestedIncludeSchema).optional()
 }).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
 var correlatedCountArgsSchema = import_zod2.z.unknown().refine(
-  (value) => value === void 0 || (0, import_utils12.isPlainObject)(value) && Object.keys(value).length === 0,
+  (value) => value === void 0 || (0, import_utils14.isPlainObject)(value) && Object.keys(value).length === 0,
   "Count includes accept no args"
 ).optional();
 var correlatedReadByIdSchema = import_zod2.z.object({
@@ -2445,7 +2902,7 @@ var correlatedNestedIncludeSchema = import_zod2.z.union([includeItemSchema, impo
 var rejectDuplicateCorrelatedPaths = (items, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   items.forEach((item, index) => {
-    if ((0, import_utils12.isPlainObject)(item) && item.mode === "correlated" && typeof item.path === "string") {
+    if ((0, import_utils14.isPlainObject)(item) && item.mode === "correlated" && typeof item.path === "string") {
       if (seen.has(item.path)) {
         ctx.addIssue({
           code: import_zod2.z.ZodIssueCode.custom,
@@ -2483,7 +2940,7 @@ function rejectKeys(body, ctx, keys2) {
 }
 
 // src/validation/parsers.ts
-var clientErrors = import_express_json_router2.default.clientErrors;
+var clientErrors = import_express_json_router3.default.clientErrors;
 function parsePathParam(value, parameter) {
   const result = stringOrStringArray.safeParse(value);
   if (!result.success) {
@@ -2915,8 +3372,8 @@ function isArkTypeErrors(value) {
   if (typeof value !== "object" || value === null) {
     return false;
   }
-  const record = value;
-  return record.arkKind === "errors" || record[" arkKind"] === "errors";
+  const record2 = value;
+  return record2.arkKind === "errors" || record2[" arkKind"] === "errors";
 }
 function isThenable(value) {
   return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";