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

package/llms.txt

@@ -36,8 +36,8 @@
 - [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 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 private-read mode](README.md#runtime-private-read-mode): `api.setGlobalOptions({ requireReadOperationAccessForPopulateDependencies: false })` opts out of private target operationAccess.read only; default true, only literal false bypasses, malformed JS/undefined stays conservative true. Typed GlobalOptions/exact setters/getters; server/runtime-only, isolated and captured with source/target/query intent before awaits, including nested output. Not requireRegisteredPopulateModels: eager private registration/static declarations remain. Source/target input-field permissions are already bypassed; virtual output authorization and request baseFilter.read/overrideFilter.read/retained IDs still govern. False + virtual-only selection adds no operation check solely to fetch.
-- [Private target/read/selection rules](README.md#target-authority-selection-and-reconstruction) · [Release compatibility](README.md#release-compatibility-dependency-reference-omission): BOTH modes apply an independent captured caller target BASE-read visibility gate to active selected/applicable dependency refs. Source unselected/denied -> omit; target read denied/failed -> omit entire ref INCLUDING ID, outranking list/custom populate access and public related-operation grants. Read allowed + ordinary population -> original authorized mask; read allowed + no population -> exact original refs/arrays/nulls/misses/order/duplicates/presence. This intentionally supersedes prior D1 denied-ID fallback even in default mode; no active plan/no feature keeps ordinary behavior. Private availability/getter outcomes never grant reference output. Compatible positive fetch unions retain separate masks/private request row scope, independent of public match/access/related grants. Each getter gets only its declared fourth-argument mask; no implicit DTO/handle/metadata/hook/task transport, only its authorized deliberate return. No recursive private target virtuals or successful-write retries. See README for selection/errors/inheritance/native isolation/hydration caveats and measured compatible-group batching.
+- [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.56.0",
+  "version": "0.57.0",
   "sideEffects": [
     "./**/index.js",
     "./**/index.mjs",
@@ -57,8 +57,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.56.0",
-    "@web-ts-toolkit/utils": "0.56.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-BXKoUKMa.d.mts → parsers-CngKnVjW.d.mts}

@@ -421,18 +421,21 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * 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 bypasses source/target input-field permissions, not the virtual's own output
- * authorization. GlobalOptions.requireReadOperationAccessForPopulateDependencies defaults
+ * 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.
- * In both modes, active selected/applicable dependency refs denied caller-context base
- * read visibility are omitted entirely, including IDs; public list/custom access or a
- * related-operation grant cannot override this. Allowed selected/permitted refs keep the
- * original authorized populate mask or exact original refs. No active plan keeps ordinary
- * behavior. The mode and source/target policy are captured before awaits; registration
- * remains mandatory independently of requireRegisteredPopulateModels.
+ * 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. */
@@ -503,8 +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,
- * reference omission/population/ID shapes, captured private-read mode, mandatory row
- * gates and absence/error rules. Private computation does not imply reference visibility.
+ * 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
@@ -1154,9 +1158,9 @@ interface AuthorizationConfiguration {
     /** 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 requireReadOperationAccessForPopulateDependencies?: boolean;
-    /** Independent ordinary-populate registration posture from the same global snapshot. */
-    readonly requireRegisteredPopulateModels?: boolean;
+    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;
@@ -1170,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;
@@ -2110,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>;
@@ -3130,7 +3133,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization, private-input policy 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.
  */
@@ -3146,8 +3149,20 @@ 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
@@ -3159,28 +3174,32 @@ interface GlobalOptions {
      * 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.
      *
-     * In BOTH modes, references in an active selected/applicable dependency plan require
-     * source selection/field permission AND the captured caller-context target base read
-     * grant. Denied/failed read visibility omits the entire reference, including its ID,
-     * even with ordinary list/custom populate access or a public related-operation grant.
-     * Allowed read keeps the original authorized public populate mask, or exact original
-     * refs without population. No active dependency plan leaves ordinary behavior intact.
-     * False-mode private-only loading adds no operation check solely for that fetch.
-     * This never grants public fields, row/write authority or query controls. Registration
-     * and static input declarations remain required, independently of requireRegisteredPopulateModels.
+     * 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 = { requireReadOperationAccessForPopulateDependencies: false } satisfies GlobalOptions;
-     * api.setGlobalOptions(policy); // privileged computation inputs; no public target-read grant
+     * 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('requireReadOperationAccessForPopulateDependencies', true);
+     * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
      * void snapshot; // stored snapshot; read again to observe the setter
      * ```
      */
-    requireReadOperationAccessForPopulateDependencies?: boolean;
+    requireOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3336,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. */
@@ -3461,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>>;
     /**
@@ -3488,12 +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. GlobalOptions.requireReadOperationAccessForPopulateDependencies
+     * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
      * defaults to true; false bypasses only private target-operation admission, never
-     * request read-row filters/retained IDs. In both modes an active dependency ref's
-     * denied caller-context target base read omits the entire ref, including its ID.
-     * Allowed refs keep the original authorized populate mask or exact original IDs;
-     * unselected/denied source fields remain hidden. No active plan keeps ordinary behavior.
+     * 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
@@ -3618,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-BXKoUKMa.d.ts → parsers-CngKnVjW.d.ts}

@@ -421,18 +421,21 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * 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 bypasses source/target input-field permissions, not the virtual's own output
- * authorization. GlobalOptions.requireReadOperationAccessForPopulateDependencies defaults
+ * 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.
- * In both modes, active selected/applicable dependency refs denied caller-context base
- * read visibility are omitted entirely, including IDs; public list/custom access or a
- * related-operation grant cannot override this. Allowed selected/permitted refs keep the
- * original authorized populate mask or exact original refs. No active plan keeps ordinary
- * behavior. The mode and source/target policy are captured before awaits; registration
- * remains mandatory independently of requireRegisteredPopulateModels.
+ * 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. */
@@ -503,8 +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,
- * reference omission/population/ID shapes, captured private-read mode, mandatory row
- * gates and absence/error rules. Private computation does not imply reference visibility.
+ * 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
@@ -1154,9 +1158,9 @@ interface AuthorizationConfiguration {
     /** 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 requireReadOperationAccessForPopulateDependencies?: boolean;
-    /** Independent ordinary-populate registration posture from the same global snapshot. */
-    readonly requireRegisteredPopulateModels?: boolean;
+    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;
@@ -1170,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;
@@ -2110,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>;
@@ -3130,7 +3133,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization, private-input policy 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.
  */
@@ -3146,8 +3149,20 @@ 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
@@ -3159,28 +3174,32 @@ interface GlobalOptions {
      * 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.
      *
-     * In BOTH modes, references in an active selected/applicable dependency plan require
-     * source selection/field permission AND the captured caller-context target base read
-     * grant. Denied/failed read visibility omits the entire reference, including its ID,
-     * even with ordinary list/custom populate access or a public related-operation grant.
-     * Allowed read keeps the original authorized public populate mask, or exact original
-     * refs without population. No active dependency plan leaves ordinary behavior intact.
-     * False-mode private-only loading adds no operation check solely for that fetch.
-     * This never grants public fields, row/write authority or query controls. Registration
-     * and static input declarations remain required, independently of requireRegisteredPopulateModels.
+     * 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 = { requireReadOperationAccessForPopulateDependencies: false } satisfies GlobalOptions;
-     * api.setGlobalOptions(policy); // privileged computation inputs; no public target-read grant
+     * 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('requireReadOperationAccessForPopulateDependencies', true);
+     * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
      * void snapshot; // stored snapshot; read again to observe the setter
      * ```
      */
-    requireReadOperationAccessForPopulateDependencies?: boolean;
+    requireOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3336,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. */
@@ -3461,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>>;
     /**
@@ -3488,12 +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. GlobalOptions.requireReadOperationAccessForPopulateDependencies
+     * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
      * defaults to true; false bypasses only private target-operation admission, never
-     * request read-row filters/retained IDs. In both modes an active dependency ref's
-     * denied caller-context target base read omits the entire ref, including its ID.
-     * Allowed refs keep the original authorized populate mask or exact original IDs;
-     * unselected/denied source fields remain hidden. No active plan keeps ordinary behavior.
+     * 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
@@ -3618,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[];