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

package/llms.txt

@@ -35,8 +35,9 @@
 - [Includes/count cardinality](README.md#include-cardinality) · [Bounded numeric Map counts and Set-to-number migration](README.md#numeric-grouped-count-service-api-breaking-migration) · [Source/attachment provenance](README.md#safe-include-output-paths)
 - [Correlated includes and literal escapes](README.md#correlated-includes) · [Nested writes and trusted hooks](README.md#nested-updates-and-trusted-hooks)
 - [Virtuals, literal-filter preservation and output compatibility](README.md#virtuals-computed-fields) · [Request/runtime reentrant hook chains](README.md#hook-admission-and-reentrant-service-calls) · [Separate persistence limits](README.md#persistence-concurrency-and-resource-limits)
-- [Private populated dependencies](README.md#private-populated-dependencies) · [Runnable three-shape example](README.md#runnable-private-dependency-example): server virtual `dependsOnPopulate: [{ path, select? }]`, automatically retained scope-local static ObjectId ref/1D array, eagerly registered same-runtime/same-connection target. Explicit `ModelVirtualDescriptor<Source, Value, { ref: Target }>` types only optional getter argument four (`populated = {}`); argument one/local dependsOn and persisted/write/public types stay unchanged. New root/advanced types: ModelVirtualPopulateDependency, ModelVirtualPopulateInputs. No client/query authority or new entrypoint.
-- [Private target/read/selection rules](README.md#target-authority-selection-and-reconstruction): original actor's captured base read and request tenant rows, independent from public match/access/authorization.related; compatible fetch union never changes original public output. Ordinary populate returns its authorized original mask, otherwise restore exact selected/permitted IDs/arrays or omit hidden refs. Each getter gets only its declared mask; no implicit DTO/handle/metadata/hook/task transport, only its authorized deliberate return. No recursive private target virtuals; unavailable private inputs omit virtuals without retrying successful writes. See README for 1/-1/empty selection, errors, inheritance, fixed hydration differences and measured compatible-group batching (not constant across independent correlated queries).
+- [Private populated dependencies](README.md#private-populated-dependencies) · [Runnable example](README.md#runnable-private-dependency-example): server virtual `dependsOnPopulate: [{ path, select? }]`, automatically retained scope-local static ObjectId ref/1D array, eagerly registered same-runtime/same-connection target. Explicit `ModelVirtualDescriptor<Source, Value, { ref: Target }>` types only optional getter argument four (`populated = {}`); argument one/local dependsOn and persisted/write/public types stay unchanged. Root/advanced types: ModelVirtualPopulateDependency, ModelVirtualPopulateInputs. No client/query authority or new entrypoint.
+- [Runtime populate operation policies](README.md#runtime-populate-operation-policies): exactly `requireOperationAccessForPopulateQueries` and `requireOperationAccessForPopulateDependencies`, both default true; only literal false bypasses its operation gate (malformed JS/undefined is true). Q=false skips ordinary effective target read/list/custom admission only; source entry/field authorization, target field/document grants, rows/transforms, original select/_id, match and mandatory IDs remain. D=false skips private target base operationAccess.read only; server declarations grant input fields, virtual output authorization and request baseFilter.read/overrideFilter.read/original IDs remain. Four independent modes: true/true strict both; false/true public only; true/false private only; false/false both, subject to those policies. Direct/root target access stays denied. Every target needs an actual runtime-registered model and effective object permissionSchema (defaults allowed, {} closes business fields); a configuration-only Document needs no HTTP routes. Missing policy is controlled bad_request before target I/O/write. Typed GlobalOptions/setters/aliases/getGlobalOptions frozen snapshots; server/runtime-only, captured before awaits through nested output, later calls see updates, runtimes isolated.
+- [Reference reconstruction](README.md#target-authority-selection-and-reconstruction) · [Breaking migration](README.md#breaking-release-populate-policy-migration): no additional target-base-read reference-visibility gate. Adding a virtual does not change ordinary refs. Source unselected/field-denied -> omit; no admitted public population -> exact original IDs/arrays/nulls/missing IDs/order/duplicates/presence, even on strict private denial or private row/query/getter failure. Admitted population -> original authorized mask, scalar null/filtered-array misses (not IDs). Compatible positive fetch unions retain separate immutable public/private masks and request read-row scope, independent of public match/access/related grants. Each getter sees only its declared fourth-argument mask; no implicit DTO/handle/metadata/hook/snapshot/task transport, only its authorized deliberate return. No recursive private target virtuals or successful-write retries. Removed old flags have no aliases/raw mapping; see the migration note. README covers error guards/static validation/native isolation/hydration caveats and measured batching.
 
 ## Additional examples
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/access-router",
   "description": "ACL-aware Express routers and in-memory data services for Mongoose-backed APIs",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "sideEffects": [
     "./**/index.js",
     "./**/index.mjs",
@@ -57,8 +57,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.55.0",
-    "@web-ts-toolkit/utils": "0.55.0",
+    "@web-ts-toolkit/express-json-router": "0.57.0",
+    "@web-ts-toolkit/utils": "0.57.0",
     "just-diff": "^6.0.2",
     "mongoose-schema-jsonschema": "^4.0.1",
     "sift": "^17.1.3",

package/{parsers-BrVRL2fg.d.mts → parsers-CngKnVjW.d.mts}

@@ -420,10 +420,22 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * and traversal through target refs are rejected. `_id` is included unless excluded.
  * Static string refs must bind the actual same-connection ObjectId model; register
  * its model instance AND options first. Validation is eager/atomic, including setters.
- * This grants getter input fields only, not public population or output fields.
- * Target operationAccess.read, overrideFilter.read and baseFilter.read still use
- * the original actor's request authority/tenant scope, independently of ordinary
+ * This bypasses source/target input-field permissions, not the virtual's own output
+ * authorization. GlobalOptions.requireOperationAccessForPopulateDependencies defaults
+ * to true, requiring the captured caller's target base operationAccess.read for private
+ * loading. Only literal false bypasses that gate; private-only loading then adds no
+ * operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
+ * retained source IDs always use request authority/tenant scope, independently of ordinary
  * populate match/access and authorization.related. Private target virtuals never run.
+ * Private work does not change ordinary reference shape. Selected/permitted source refs
+ * keep exact original IDs, including array order/duplicates/missing IDs/nulls, unless an
+ * admitted ordinary population owns the slot (then its original public mask/miss applies).
+ * Strict private denial, row/query/getter failure and deferred virtual denial cannot hide
+ * permitted IDs. Only source unselection/field denial omits them; there is no extra target
+ * base-read visibility gate. GlobalOptions.requireOperationAccessForPopulateQueries
+ * independently controls ordinary target operation admission. Both flags and source/target
+ * policy are captured before awaits; registration and an effective object permissionSchema
+ * remain mandatory. Private inputs never implicitly enter hooks, handles or metadata.
  */
 interface ModelVirtualPopulateDependency<TModel = unknown> {
     /** Top-level ref relative to this virtual's scope; no dotted source paths. Retained automatically. */
@@ -468,7 +480,7 @@ type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopu
  * It is separate from `doc`, whose persisted/public-related typing is unchanged.
  * The runtime supplies it (empty without a declaration); the empty default generic
  * guesses no target shape. Optionality preserves legacy three-argument direct calls
- * and callbacks. Absent source refs or unavailable target reads skip invocation;
+ * and callbacks. Absent source refs or unavailable private inputs skip invocation;
  * present null/empty refs and missing target rows yield null/[]/null array slots.
  * Private values are not implicitly transported to output or authorization metadata;
  * an authorized getter can deliberately return a computed value using them.
@@ -494,7 +506,9 @@ type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends V
  * generic never changes the persisted model, write types or public output.
  * Use `populated = {}` or guard undefined to retain three-argument direct calls.
  * See the shipped README's "Private populated dependencies" for registration,
- * all three public reference shapes, target read/row gates and absence/error rules.
+ * source-field omission/population/ID shapes, independent captured operation policies,
+ * mandatory row gates and absence/error rules. Private computation does not grant output
+ * or remove otherwise permitted parent IDs.
  *
  * @example
  * ```ts
@@ -1143,6 +1157,10 @@ interface AuthorizationConfiguration {
     readonly catalog: AuthorizationFieldCatalog;
     /** Opaque terminal private-input capture. Never related authority or public document metadata. */
     readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
+    /** Runtime-owned private input admission mode, not public output/related authority. */
+    readonly requireOperationAccessForPopulateDependencies?: boolean;
+    /** Independent ordinary-populate operation admission from the same global snapshot. */
+    readonly requireOperationAccessForPopulateQueries?: boolean;
     readonly documentPermissionField?: string;
     /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
     readonly [key: string]: unknown;
@@ -1156,8 +1174,7 @@ interface AuthorizationRelatedTarget {
     readonly queryIntent?: ModelServiceIntent;
     /** Existing include operation gate, resolved synchronously with its target. */
     readonly operationGuard?: unknown;
-    /** Passthrough is the existing global unregistered-populate opt-out, not a caller policy. */
-    readonly kind?: 'output' | 'count' | 'passthrough';
+    readonly kind?: 'output' | 'count';
     readonly relatedTargets?: readonly AuthorizationRelatedTarget[];
     /** Captured supported raw-ref transport shape; exotic ordinary populates keep their adapter path. */
     readonly staticObjectIdReference?: boolean;
@@ -2096,7 +2113,7 @@ declare class Core {
     /** Persisted request-only populate admission; fetch planning is not field authority. */
     private requestPopulateSelect;
     /** Request-only population. Use named response scopePath; positional subPaths are removed. */
-    genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<(string | Populate)[]>;
+    genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
     validate(modelName: string, allowedData: unknown, access: ValidateAccess, context: ModelHookContext): Promise<boolean | unknown[]>;
     prepare<T>(modelName: string, allowedData: T, access: PrepareAccess, context: ModelHookContext): Promise<T>;
     transform<T>(modelName: string, doc: T, access: TransformAccess, context: ModelHookContext): Promise<T>;
@@ -3116,7 +3133,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization and resource settings, configured with
+ * Runtime-wide request initialization, populate operation policies and resource settings, configured with
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
  * options. Object assignment is shallow; nested requestComplexity replaces as a unit.
  */
@@ -3132,8 +3149,57 @@ interface GlobalOptions {
      * context. Generated routers do not authenticate client claims for this hook.
      */
     globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
-    /** Require populate target models to be registered in the active runtime. Defaults to `true`. */
-    requireRegisteredPopulateModels?: boolean;
+    /**
+     * Require the caller's effective target operation (`read`, supported `list` or trusted
+     * custom access) for ordinary query population (default `true`). Only literal `false`
+     * skips that admission gate; source entry/field authorization, target field/document
+     * grants, row/base/transform policies, original selection, match and mandatory reference
+     * IDs still constrain output. Denied population retains selected/permitted original
+     * source IDs; admitted population misses return null/filtered arrays, not restored IDs.
+     * Targets always require an actual Mongoose model and ACL configuration with an
+     * effective object permissionSchema in this runtime; `{}` closes business fields.
+     * Runtime-owned and captured before awaits, independently of private dependency
+     * admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
+     * read/list operations stay denied. No per-model/query/client override.
+     */
+    requireOperationAccessForPopulateQueries?: boolean;
+    /**
+     * Require the original caller's target base `operationAccess.read` before loading
+     * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
+     * `false` bypasses that operation gate; undefined/malformed JS values normalize to
+     * `true`. Source/target input-field permissions are already bypassed by the server
+     * declaration; the virtual's own output authorization still applies. Target request-mode
+     * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
+     * Captured with source/target policy and query intent before the first await, including
+     * nested output scopes. In-flight calls retain their mode; later calls see updates.
+     * Runtime-isolated server configuration only: no caller/query or per-model override.
+     *
+     * Neither mode changes ordinary reference shape: selected/permitted parent fields keep
+     * exact original IDs (including array order, duplicates, missing IDs and nulls) when no
+     * admitted ordinary population owns them. Private denial, row/query/getter failure or
+     * deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
+     * denial; admitted public DTO/null/filtered-array results retain their original masks.
+     * There is no additional target-base-read reference-visibility gate. False-mode loading
+     * adds no operation check solely for its private fetch. Private fourth-argument inputs
+     * never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
+     * An actual registered model, effective object permissionSchema and static declarations
+     * remain mandatory, independently of requireOperationAccessForPopulateQueries.
+     *
+     * @example
+     * ```ts
+     * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
+     * const api = createAccessRuntime();
+     * const policy = {
+     *   requireOperationAccessForPopulateQueries: true,
+     *   requireOperationAccessForPopulateDependencies: false,
+     * } satisfies GlobalOptions;
+     * api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
+     * const snapshot: GlobalOptions = api.getGlobalOptions();
+     * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
+     * void snapshot; // stored snapshot; read again to observe the setter
+     * ```
+     */
+    requireOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3289,6 +3355,12 @@ interface ModelHydrationOptions {
 }
 /** Model starting defaults; data/root routers do not inherit these. Nested values assign shallowly. */
 interface DefaultModelRouterOptions<TModel = unknown> {
+    /**
+     * Default business-field policy when a model's permissionSchema is undefined.
+     * Populate targets require an effective object schema; `{}` explicitly closes
+     * business fields. A model's defined schema replaces this entire default.
+     */
+    permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
     /** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
     hydration?: ModelHydrationOptions;
     /** Maximum returned list rows (default 1000), independent of exact match/count totals. */
@@ -3414,6 +3486,8 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * siblings; a whole-object/array grant permits replacement (no generic deep merge).
      * Send nested JSON; literal dotted client keys are not update operators.
      * Basic/advanced keys are route guards in operationAccess, not field grants here.
+     * Requested populate targets require an effective object schema in their owning
+     * runtime (model defaults may supply it); `{}` explicitly closes business fields.
      */
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel> | Extract<keyof TVirtuals, string>>;
     /**
@@ -3441,8 +3515,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
      * { ref: Target }> separately, then assign here; persisted/write/public types
      * stay unchanged. Register target models/options first in this runtime. Source
-     * refs are retained automatically; target base read/tenant gates still apply.
-     * The original public selection/population is preserved, including ID restoration.
+     * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
+     * defaults to true; false bypasses only private target-operation admission, never
+     * request read-row filters/retained IDs. Neither mode changes ordinary reference
+     * shape: admitted population keeps its original authorized mask/miss; otherwise
+     * selected/permitted parent fields keep exact original IDs, even on private failure.
+     * Only unselected/field-denied source refs are omitted. Query operation admission is
+     * independently controlled by GlobalOptions.requireOperationAccessForPopulateQueries.
      *
      * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
      * ```ts
@@ -3567,7 +3646,7 @@ interface DataRouterOptions<TData = unknown> {
     decorateAll?: DataListHook<TData> | Record<string, DataListHook<TData>>;
     requestSchemas?: DataRequestSchemas;
 }
-interface ExtendedModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends ModelRouterOptions<TModel, TVirtuals>, ExtendedDefaultModelRouterOptions<TModel> {
+interface ExtendedModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends ModelRouterOptions<TModel, TVirtuals>, Omit<ExtendedDefaultModelRouterOptions<TModel>, 'permissionSchema'> {
     'alwaysSelectFields.default'?: string[];
     'alwaysSelectFields.list'?: string[];
     'alwaysSelectFields.create'?: string[];

package/{parsers-BrVRL2fg.d.ts → parsers-CngKnVjW.d.ts}

@@ -420,10 +420,22 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * and traversal through target refs are rejected. `_id` is included unless excluded.
  * Static string refs must bind the actual same-connection ObjectId model; register
  * its model instance AND options first. Validation is eager/atomic, including setters.
- * This grants getter input fields only, not public population or output fields.
- * Target operationAccess.read, overrideFilter.read and baseFilter.read still use
- * the original actor's request authority/tenant scope, independently of ordinary
+ * This bypasses source/target input-field permissions, not the virtual's own output
+ * authorization. GlobalOptions.requireOperationAccessForPopulateDependencies defaults
+ * to true, requiring the captured caller's target base operationAccess.read for private
+ * loading. Only literal false bypasses that gate; private-only loading then adds no
+ * operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
+ * retained source IDs always use request authority/tenant scope, independently of ordinary
  * populate match/access and authorization.related. Private target virtuals never run.
+ * Private work does not change ordinary reference shape. Selected/permitted source refs
+ * keep exact original IDs, including array order/duplicates/missing IDs/nulls, unless an
+ * admitted ordinary population owns the slot (then its original public mask/miss applies).
+ * Strict private denial, row/query/getter failure and deferred virtual denial cannot hide
+ * permitted IDs. Only source unselection/field denial omits them; there is no extra target
+ * base-read visibility gate. GlobalOptions.requireOperationAccessForPopulateQueries
+ * independently controls ordinary target operation admission. Both flags and source/target
+ * policy are captured before awaits; registration and an effective object permissionSchema
+ * remain mandatory. Private inputs never implicitly enter hooks, handles or metadata.
  */
 interface ModelVirtualPopulateDependency<TModel = unknown> {
     /** Top-level ref relative to this virtual's scope; no dotted source paths. Retained automatically. */
@@ -468,7 +480,7 @@ type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopu
  * It is separate from `doc`, whose persisted/public-related typing is unchanged.
  * The runtime supplies it (empty without a declaration); the empty default generic
  * guesses no target shape. Optionality preserves legacy three-argument direct calls
- * and callbacks. Absent source refs or unavailable target reads skip invocation;
+ * and callbacks. Absent source refs or unavailable private inputs skip invocation;
  * present null/empty refs and missing target rows yield null/[]/null array slots.
  * Private values are not implicitly transported to output or authorization metadata;
  * an authorized getter can deliberately return a computed value using them.
@@ -494,7 +506,9 @@ type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends V
  * generic never changes the persisted model, write types or public output.
  * Use `populated = {}` or guard undefined to retain three-argument direct calls.
  * See the shipped README's "Private populated dependencies" for registration,
- * all three public reference shapes, target read/row gates and absence/error rules.
+ * source-field omission/population/ID shapes, independent captured operation policies,
+ * mandatory row gates and absence/error rules. Private computation does not grant output
+ * or remove otherwise permitted parent IDs.
  *
  * @example
  * ```ts
@@ -1143,6 +1157,10 @@ interface AuthorizationConfiguration {
     readonly catalog: AuthorizationFieldCatalog;
     /** Opaque terminal private-input capture. Never related authority or public document metadata. */
     readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
+    /** Runtime-owned private input admission mode, not public output/related authority. */
+    readonly requireOperationAccessForPopulateDependencies?: boolean;
+    /** Independent ordinary-populate operation admission from the same global snapshot. */
+    readonly requireOperationAccessForPopulateQueries?: boolean;
     readonly documentPermissionField?: string;
     /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
     readonly [key: string]: unknown;
@@ -1156,8 +1174,7 @@ interface AuthorizationRelatedTarget {
     readonly queryIntent?: ModelServiceIntent;
     /** Existing include operation gate, resolved synchronously with its target. */
     readonly operationGuard?: unknown;
-    /** Passthrough is the existing global unregistered-populate opt-out, not a caller policy. */
-    readonly kind?: 'output' | 'count' | 'passthrough';
+    readonly kind?: 'output' | 'count';
     readonly relatedTargets?: readonly AuthorizationRelatedTarget[];
     /** Captured supported raw-ref transport shape; exotic ordinary populates keep their adapter path. */
     readonly staticObjectIdReference?: boolean;
@@ -2096,7 +2113,7 @@ declare class Core {
     /** Persisted request-only populate admission; fetch planning is not field authority. */
     private requestPopulateSelect;
     /** Request-only population. Use named response scopePath; positional subPaths are removed. */
-    genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<(string | Populate)[]>;
+    genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
     validate(modelName: string, allowedData: unknown, access: ValidateAccess, context: ModelHookContext): Promise<boolean | unknown[]>;
     prepare<T>(modelName: string, allowedData: T, access: PrepareAccess, context: ModelHookContext): Promise<T>;
     transform<T>(modelName: string, doc: T, access: TransformAccess, context: ModelHookContext): Promise<T>;
@@ -3116,7 +3133,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization and resource settings, configured with
+ * Runtime-wide request initialization, populate operation policies and resource settings, configured with
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
  * options. Object assignment is shallow; nested requestComplexity replaces as a unit.
  */
@@ -3132,8 +3149,57 @@ interface GlobalOptions {
      * context. Generated routers do not authenticate client claims for this hook.
      */
     globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
-    /** Require populate target models to be registered in the active runtime. Defaults to `true`. */
-    requireRegisteredPopulateModels?: boolean;
+    /**
+     * Require the caller's effective target operation (`read`, supported `list` or trusted
+     * custom access) for ordinary query population (default `true`). Only literal `false`
+     * skips that admission gate; source entry/field authorization, target field/document
+     * grants, row/base/transform policies, original selection, match and mandatory reference
+     * IDs still constrain output. Denied population retains selected/permitted original
+     * source IDs; admitted population misses return null/filtered arrays, not restored IDs.
+     * Targets always require an actual Mongoose model and ACL configuration with an
+     * effective object permissionSchema in this runtime; `{}` closes business fields.
+     * Runtime-owned and captured before awaits, independently of private dependency
+     * admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
+     * read/list operations stay denied. No per-model/query/client override.
+     */
+    requireOperationAccessForPopulateQueries?: boolean;
+    /**
+     * Require the original caller's target base `operationAccess.read` before loading
+     * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
+     * `false` bypasses that operation gate; undefined/malformed JS values normalize to
+     * `true`. Source/target input-field permissions are already bypassed by the server
+     * declaration; the virtual's own output authorization still applies. Target request-mode
+     * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
+     * Captured with source/target policy and query intent before the first await, including
+     * nested output scopes. In-flight calls retain their mode; later calls see updates.
+     * Runtime-isolated server configuration only: no caller/query or per-model override.
+     *
+     * Neither mode changes ordinary reference shape: selected/permitted parent fields keep
+     * exact original IDs (including array order, duplicates, missing IDs and nulls) when no
+     * admitted ordinary population owns them. Private denial, row/query/getter failure or
+     * deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
+     * denial; admitted public DTO/null/filtered-array results retain their original masks.
+     * There is no additional target-base-read reference-visibility gate. False-mode loading
+     * adds no operation check solely for its private fetch. Private fourth-argument inputs
+     * never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
+     * An actual registered model, effective object permissionSchema and static declarations
+     * remain mandatory, independently of requireOperationAccessForPopulateQueries.
+     *
+     * @example
+     * ```ts
+     * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
+     * const api = createAccessRuntime();
+     * const policy = {
+     *   requireOperationAccessForPopulateQueries: true,
+     *   requireOperationAccessForPopulateDependencies: false,
+     * } satisfies GlobalOptions;
+     * api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
+     * const snapshot: GlobalOptions = api.getGlobalOptions();
+     * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
+     * void snapshot; // stored snapshot; read again to observe the setter
+     * ```
+     */
+    requireOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3289,6 +3355,12 @@ interface ModelHydrationOptions {
 }
 /** Model starting defaults; data/root routers do not inherit these. Nested values assign shallowly. */
 interface DefaultModelRouterOptions<TModel = unknown> {
+    /**
+     * Default business-field policy when a model's permissionSchema is undefined.
+     * Populate targets require an effective object schema; `{}` explicitly closes
+     * business fields. A model's defined schema replaces this entire default.
+     */
+    permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
     /** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
     hydration?: ModelHydrationOptions;
     /** Maximum returned list rows (default 1000), independent of exact match/count totals. */
@@ -3414,6 +3486,8 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * siblings; a whole-object/array grant permits replacement (no generic deep merge).
      * Send nested JSON; literal dotted client keys are not update operators.
      * Basic/advanced keys are route guards in operationAccess, not field grants here.
+     * Requested populate targets require an effective object schema in their owning
+     * runtime (model defaults may supply it); `{}` explicitly closes business fields.
      */
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel> | Extract<keyof TVirtuals, string>>;
     /**
@@ -3441,8 +3515,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
      * { ref: Target }> separately, then assign here; persisted/write/public types
      * stay unchanged. Register target models/options first in this runtime. Source
-     * refs are retained automatically; target base read/tenant gates still apply.
-     * The original public selection/population is preserved, including ID restoration.
+     * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
+     * defaults to true; false bypasses only private target-operation admission, never
+     * request read-row filters/retained IDs. Neither mode changes ordinary reference
+     * shape: admitted population keeps its original authorized mask/miss; otherwise
+     * selected/permitted parent fields keep exact original IDs, even on private failure.
+     * Only unselected/field-denied source refs are omitted. Query operation admission is
+     * independently controlled by GlobalOptions.requireOperationAccessForPopulateQueries.
      *
      * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
      * ```ts
@@ -3567,7 +3646,7 @@ interface DataRouterOptions<TData = unknown> {
     decorateAll?: DataListHook<TData> | Record<string, DataListHook<TData>>;
     requestSchemas?: DataRequestSchemas;
 }
-interface ExtendedModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends ModelRouterOptions<TModel, TVirtuals>, ExtendedDefaultModelRouterOptions<TModel> {
+interface ExtendedModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends ModelRouterOptions<TModel, TVirtuals>, Omit<ExtendedDefaultModelRouterOptions<TModel>, 'permissionSchema'> {
     'alwaysSelectFields.default'?: string[];
     'alwaysSelectFields.list'?: string[];
     'alwaysSelectFields.create'?: string[];