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

package/{parsers-ZSrF7SNu.d.mts → parsers-BXKoUKMa.d.mts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import mongoose from 'mongoose';
+import mongoose, { Model, Schema } from 'mongoose';
 import express from 'express';
 
 interface BooleanObject {
@@ -24,6 +24,13 @@ declare class Permission {
 type Permissions = Permission;
 type AccessRouterPermissions = Permission;
 
+/** Package-only, per-call output intent. Resolve defaults before any async admission. */
+
+interface ModelServiceIntent {
+    readonly args: FindArgs;
+    readonly options: Omit<FindOptions & FindOneOptions, 'authorization'>;
+}
+
 type OpenApiMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 type OpenApiSchema = Record<string, unknown>;
 type OpenApiSchemaSource = unknown;
@@ -104,224 +111,6 @@ type OpenApiRouterOptions = Partial<OpenApiDocumentOptions> & {
     swaggerUiBundleUrl?: string;
 };
 
-type ModelReferenceMap = {
-    [key: string]: string | ModelReferenceMap;
-};
-/**
- * Owner of global/model/data options, registered Mongoose models and OpenAPI routes.
- * Prefer createAccessRuntime() for a callable API with factories and bound setters;
- * its `.runtime` exposes this owner. A bare instance has no createRouter method.
- * Registries/configuration are isolated; the Mongoose jsonSchema extension is initialized
- * idempotently. The defaultRuntime additionally adopts process-global named models.
- */
-declare class AccessRuntime {
-    private readonly allowGlobalModelLookup;
-    constructor(options?: {
-        allowGlobalModelLookup?: boolean;
-    });
-    private readonly globalOptions;
-    private readonly defaultModelOptions;
-    private readonly modelOptions;
-    private readonly modelJsonSchemas;
-    private readonly dataOptions;
-    private readonly modelRefs;
-    private readonly modelSubs;
-    private readonly modelAtts;
-    private readonly modelInstances;
-    private readonly openApiRegistry;
-    private openApiPathPrefix;
-    registerModelInstance<TModel>(modelName: string, model: mongoose.Model<TModel>): void;
-    hasModelInstance(modelName: string): boolean;
-    getModelInstance<TModel = unknown>(modelName: string): mongoose.Model<TModel> | null;
-    registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
-    /**
-     * Compose OpenAPI paths while synchronously constructing mounted routers.
-     * Prefixes apply before collision checks; prior descriptors and Express paths
-     * are unchanged. Nested calls compose and the prior scope is restored even on
-     * failure. The callback must finish registration synchronously (no async work).
-     */
-    withOpenApiPathPrefix<T>(prefix: string, build: () => T): T;
-    /**
-     * Enable strict OpenAPI collision detection for the remainder of this
-     * runtime's lifetime. After this call, conflicting method/path
-     * registrations and duplicate operationIds throw {@link OpenApiCollisionError}
-     * instead of silently replacing. Existing already-registered routes are
-     * not retroactively re-validated.
-     */
-    enableOpenApiCollisionDetection(): void;
-    getOpenApiRoutes(): OpenApiRouteDescriptor[];
-    clearOpenApiRoutes(): void;
-    getOpenApiSpec(info: OpenApiDocumentOptions): {
-        openapi: string;
-        info: Omit<OpenApiDocumentOptions, "servers">;
-        servers?: OpenApiDocumentOptions["servers"];
-        paths: Record<string, Record<string, {
-            [key: `x-${string}`]: unknown;
-            operationId?: string;
-            summary?: string;
-            description?: string;
-            tags?: string[];
-            deprecated?: boolean;
-            parameters?: OpenApiParameter[];
-            requestBody?: {
-                required?: boolean;
-                content: Record<string, {
-                    schema: OpenApiSchema;
-                }>;
-            };
-            responses: OpenApiResponses;
-        }>>;
-    };
-    createBootstrapSnapshot(): {
-        globalOptions: GlobalOptions;
-        defaultModelOptions: DefaultModelRouterOptions;
-        modelOptions: Record<string, ModelRouterOptions>;
-        dataOptions: Record<string, DataRouterOptions>;
-        modelInstances: Record<string, mongoose.Model<unknown>>;
-        modelJsonSchemas: Record<string, Record<string, unknown>>;
-        modelRefs: Record<string, ModelReferenceMap>;
-        modelSubs: Record<string, string[]>;
-        modelAtts: Record<string, string[]>;
-        openApi: {
-            routes: OpenApiRouteDescriptor[];
-            options: Required<OpenApiRegistryOptions>;
-        };
-    };
-    restoreBootstrapSnapshot(snapshot: ReturnType<AccessRuntime['createBootstrapSnapshot']>): void;
-    /** Shallowly replace supplied global values; nested objects such as requestComplexity are not deep-merged. */
-    setGlobalOptions(options: GlobalOptions): void;
-    setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
-    getGlobalOptions(): GlobalOptions;
-    getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
-    /** Update model starting defaults shallowly; already-stored model values are not broadcast-replaced. */
-    setDefaultModelOptions(options: DefaultModelRouterOptions): void;
-    setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
-    getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
-    getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
-    private createModelOptions;
-    private getOrCreateModelOptions;
-    /**
-     * Assign `{ ...modelDefaults, ...storedOptions, ...options }` shallowly. A supplied
-     * operationAccess/defaults object replaces that whole value. Defaults accept only
-     * query/presentation settings; virtual configuration is validated before assignment.
-     * Existing router.options remains its construction-time snapshot. Fresh model-service
-     * calls capture the owner's current options/defaults; in-flight calls retain their snapshot.
-     */
-    setModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): void;
-    setModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): void;
-    /** Frozen stored snapshot, not fully resolved per-path defaults. Read again for current configuration. */
-    getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
-    /**
-     * Generic stored exact → parent.default → parent lookup; only undefined falls through.
-     * The exact runtime-model-default path is the final fallback if the stored parent is
-     * absent. This is not the route-specific variant-to-base resolver; use
-     * getExactModelOption to inspect a variant including its exact model-default fallback.
-     */
-    getModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K | string, defaultValue?: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): ExtendedModelRouterOptions<TModel, TVirtuals>[K];
-    /** Exact stored path, then the same runtime-model-default path; no parent/default or variant-to-base lookup. */
-    getExactModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K | string): ExtendedModelRouterOptions<TModel, TVirtuals>[K];
-    /**
-     * List registered virtual leaf names for a scope (VIRT-01).
-     * Scope containers (`{ sub }`) are not leaves. Inapplicable names are
-     * still listed here; applicability is decided per-access by
-     * {@link resolveVirtualDescriptor}. Request-controlled include collisions
-     * are validated by VIRT-05, not guessed here.
-     */
-    getVirtualNames(modelName: string, scopePath?: string[]): string[];
-    /**
-     * Whether a field is a registered virtual leaf in a scope (VIRT-01).
-     * Inapplicable registered names stay virtual (never persisted), even when
-     * no getter applies for the current access. Containers and persisted
-     * fields return false.
-     */
-    isVirtualField(modelName: string, fieldName: string, scopePath?: string[]): boolean;
-    /**
-     * Resolve an applicable virtual descriptor with exact → `.default` → bare
-     * semantics (VIRT-01, VIRT-00A D1/D5). Returns `undefined` when no getter
-     * applies for `access`. Crucially, an access-record object is NEVER
-     * 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.
-     */
-    resolveVirtualDescriptor(modelName: string, virtualName: string, access: string, scopePath?: string[]): {
-        get: (...args: never[]) => unknown;
-        dependsOn: string[];
-    } | undefined;
-    getModelNames(): string[];
-    hasModel(modelName: string): boolean;
-    getModelJsonSchema(modelName: string): Record<string, unknown>;
-    private createDataOptions;
-    private getOrCreateDataOptions;
-    setDataOptions<TData = unknown>(dataName: string, options: DataRouterOptions<TData>): void;
-    setDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K, value: ExtendedDataRouterOptions<TData>[K]): void;
-    getDataOptions<TData = unknown>(dataName: string): DataRouterOptions<TData>;
-    /**
-     * Reusable configured data view: plain containers are frozen; native properties
-     * return detached mutable copies on access. Native identity is not stable.
-     * Replacement leaves previously captured views on their original data version.
-     */
-    getDataSnapshot<TData = unknown>(dataName: string): readonly TData[];
-    getDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string, defaultValue?: ExtendedDataRouterOptions<TData>[K]): ExtendedDataRouterOptions<TData>[K];
-    getExactDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string): ExtendedDataRouterOptions<TData>[K];
-    getDataNames(): string[];
-    ensureModelMeta(modelName: string): void;
-    getModelRef(modelName: string, refPath: string): string | null;
-    getModelSub(modelName: string): string[];
-    getModelAtt(modelName: string): string[];
-}
-declare const defaultRuntime: AccessRuntime;
-
-declare class DataCore {
-    private req;
-    private readonly requestRuntime;
-    private caches;
-    private cachedPermissions;
-    constructor(req: AccessRouterBaseRequest);
-    genIDFilter<TData = unknown>(dataName: string, id: string): Promise<Filter<TData>>;
-    genFilter<TData = unknown>(dataName: string, access?: BaseFilterAccess, _filter?: Filter<TData>): Promise<Filter<TData>>;
-    /** Request-schema allowlist, independent of doc values. No model hooks or backend elevation. */
-    genAllowedFields(dataName: string, _doc: unknown, access: SelectAccess, options?: DataFieldOptions): Promise<string[]>;
-    /** Request-only existing-value pick. No automatic identity/metadata retention; options default to {}. */
-    pickAllowedFields<TDoc>(dataName: string, doc: TDoc, access: SelectAccess, options?: DataFieldOptions): Promise<TDoc>;
-    /**
-     * Request-only requested-token intersection. Omitted/null/empty/exclusion-only select
-     * yields []; DataService then applies no extra projection after request trimming.
-     * Named options default to {}; legacy elevation and positional arguments are removed.
-     */
-    genSelect(dataName: string, access: SelectAccess, targetFields?: Projection, options?: DataFieldOptions): Promise<string[]>;
-    private fieldPermissionSchema;
-    decorate<TDoc>(dataName: string, doc: TDoc, access: DecorateAccess, context?: DataHookContext): Promise<TDoc>;
-    decorateAll<TDoc>(dataName: string, docs: TDoc[], access: DecorateAllAccess, context?: DataHookContext): Promise<TDoc[]>;
-    getPermissions(): Permission;
-    setPermissions(): Promise<void>;
-    canActivate(routeGuard: Validation): Promise<boolean>;
-    isAllowed(dataName: string, access: RouteGuardAccess | string): Promise<boolean>;
-    /** Authorize route entry using explicit server-owned basic/advanced metadata. */
-    isAllowedRoute(dataName: string, baseAccess: RouteGuardAccess | string, variant: RouteVariant): Promise<boolean>;
-    getService<TData = unknown>(dataName: string): DataService<TData>;
-    service<TData = unknown>(dataName: string): DataService<TData>;
-    svc<TData = unknown>(dataName: string): DataService<TData>;
-    private getGlobalPermissions;
-}
-
-declare const MIDDLEWARE: unique symbol;
-declare const DATA_MIDDLEWARE: unique symbol;
-declare const PERMISSIONS: unique symbol;
-declare const PERMISSION_KEYS: unique symbol;
-
-interface AccessRouterRequestExtensions {
-    macl?: Core;
-    dacl?: DataCore;
-    [PERMISSIONS]?: AccessRouterPermissions;
-    [PERMISSION_KEYS]?: string[];
-    [MIDDLEWARE]?: unknown[] | unknown;
-    [DATA_MIDDLEWARE]?: unknown[] | unknown;
-    [key: string]: unknown;
-    [key: symbol]: unknown;
-}
-type AccessRouterRequest = express.Request & AccessRouterRequestExtensions;
-
 /** Request-only list arguments: advanced body fields, or root-entry args; no per-call authorization. */
 interface PublicListArgs {
     select?: Projection;
@@ -530,21 +319,525 @@ interface CorrelatedCountInclude extends CorrelatedIncludeBase {
     filter: CorrelatedFilter;
     id?: never;
 }
-type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
-/** Related output cannot overwrite authorization metadata at any supported nested level. */
-type Include = LegacyInclude | CorrelatedInclude;
-type FindAccess = 'list' | 'read';
-type PopulateAccess = 'list' | 'read';
-interface Populate {
-    path: string;
-    select?: Projection;
-    match?: unknown;
-    access?: PopulateAccess;
+type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
+/** Related output cannot overwrite authorization metadata at any supported nested level. */
+type Include = LegacyInclude | CorrelatedInclude;
+type FindAccess = 'list' | 'read';
+type PopulateAccess = 'list' | 'read';
+interface Populate {
+    path: string;
+    select?: Projection;
+    match?: unknown;
+    access?: PopulateAccess;
+}
+interface SubPopulate {
+    path: string;
+    select?: Projection;
+}
+
+type MaybePromise<T> = T | Promise<T>;
+type AccessRouterFieldKey<T> = [Extract<keyof T, string>] extends [never] ? string : Extract<keyof T, string>;
+type IdentifierHook<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, id: string) => MaybePromise<Filter<TValue>>;
+type GlobalPermissionValue = Record<string, boolean> | string[] | string | null | undefined;
+type BaseFilterHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, permissions: AccessRouterPermissions) => MaybePromise<Filter | true | null | undefined>;
+type OverrideFilterHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, filter: Filter, permissions: AccessRouterPermissions) => MaybePromise<Filter>;
+type Hook<TValue, TContext, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: TValue, permissions: AccessRouterPermissions, context: TContext) => MaybePromise<TValue>;
+type HookChain<TValue, TContext, TRequest extends AccessRouterRequest = AccessRouterRequest> = Hook<TValue, TContext, TRequest> | Array<Hook<TValue, TContext, TRequest>>;
+type ValidateRule = boolean | unknown[];
+type ValidateHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, allowedData: unknown, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<ValidateRule>;
+type DocPermissionsHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, doc: unknown, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<Record<string, unknown>>;
+type ChangeHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, previousValue: unknown, nextValue: unknown, changes: Change[], context: ModelHookContext) => MaybePromise<void>;
+type DeleteHook<TValue = unknown, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: TValue, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<void>;
+type DocumentHook<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: ModelDocument<TValue>, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<ModelDocument<TValue>>;
+type DocumentHookChain<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = DocumentHook<TValue, TRequest> | Array<DocumentHook<TValue, TRequest>>;
+type ModelBaseFilterHook = BaseFilterHook<ModelRequest>;
+type DataBaseFilterHook = BaseFilterHook<DataRequest>;
+type ModelOverrideFilterHook = OverrideFilterHook<ModelRequest>;
+type DataOverrideFilterHook = OverrideFilterHook<DataRequest>;
+type ModelIdentifierHook<TValue = unknown> = IdentifierHook<TValue, ModelRequest>;
+type DataIdentifierHook<TValue = unknown> = IdentifierHook<TValue, DataRequest>;
+type ModelValidateHook = ValidateHook<ModelRequest>;
+/**
+ * Request-user grants from untrimmed projected input. Declare private persisted inputs
+ * with alwaysSelectFields. Integrated output resolves once per document/access stage,
+ * independently of skim or metadata serialization; use the result's document handle
+ * for later picks after input/metadata trim. Backend grants do not forge user metadata.
+ */
+type ModelDocPermissionsHook = DocPermissionsHook<ModelRequest>;
+type ModelChangeHook = ChangeHook<ModelRequest>;
+type ModelDocumentHook<TValue = unknown> = DocumentHookChain<TValue, ModelRequest>;
+type ModelDeleteHook<TValue = unknown> = DeleteHook<ModelDocument<TValue>, ModelRequest>;
+type ModelHook<TValue = unknown> = HookChain<TValue, ModelHookContext, ModelRequest>;
+type ModelListHook<TValue = unknown> = HookChain<TValue[], ModelHookContext, ModelRequest>;
+type DataHook<TValue = unknown> = HookChain<TValue, DataHookContext, DataRequest>;
+type DataListHook<TValue = unknown> = HookChain<TValue[], DataHookContext, DataRequest>;
+/**
+ * Supported per-access virtual getter keys (VIRT-00A D1/D5).
+ * `default` is a fallback access; `delete`/`distinct`/`count` are NOT
+ * virtual accesses and must be rejected at configuration time.
+ */
+type ModelVirtualAccess = 'list' | 'create' | 'read' | 'update';
+type ModelVirtualRecordAccess = 'default' | ModelVirtualAccess;
+/**
+ * Scope-aware virtual getter context (VIRT-00A D2, frozen).
+ * Extends {@link ModelHookContext} with the receiving model, definition/
+ * permission `scopePath` (e.g. `[]` at root, `['contacts','sub']` for
+ * `contacts.sub.displayName`), and the three effective accesses. The
+ * initiating operation stays in `context.operation` and is never
+ * overwritten with fallback/effective visibility.
+ *
+ * Embedded outputs reuse the owning parent's internally computed grants with
+ * the scope's `permissionSchema.<field>.sub` rules; dedicated subdocument
+ * routes resolve grants from the raw parent lookup. Related (populate/
+ * include) targets finalize with the target model's own definitions,
+ * permissions, selection, and effective access before parent getters run.
+ * Declaration-scoped private inputs use the getter's fourth argument, never
+ * this context or its document-authorization metadata.
+ */
+interface ModelVirtualContext extends ModelHookContext {
+    receivingModelName: string;
+    scopePath: string[];
+    virtualAccess: ModelVirtualAccess;
+    outputAccess: ModelVirtualAccess;
+    docPermissionsAccess: ModelVirtualAccess;
+}
+type IsUnknownVirtual<T> = unknown extends T ? ([keyof T] extends [never] ? true : false) : false;
+/**
+ * Typed isolated persisted view for a virtual getter scope (VIRT-00A D3/D4).
+ * Known models use a partial read-only persisted view (never
+ * `Record<string, unknown>`); unknown/untyped models keep an explicit
+ * loose fallback. This first argument retains the ordinary persisted/local
+ * dependency and finalized-public-related view. `dependsOnPopulate` does not
+ * retype persisted ref IDs or add its automatically retained refs here.
+ */
+type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ? Readonly<Partial<Record<string, unknown>>> : [Extract<keyof TModel, string>] extends [never] ? Readonly<Partial<Record<string, unknown>>> : Readonly<Partial<TModel>>;
+/**
+ * Server-owned, one-hop persisted input declaration. `path` is a scope-local
+ * ObjectId ref (scalar or 1D array) to a model already configured in this runtime.
+ * Embedded virtuals use their `.sub` scope's field, never a dotted source path.
+ * `select` uses Populate's string/array/1-or-minus-1 grammar; omitted/empty means
+ * all eligible static persisted fields. Target virtuals, metadata, dynamic paths
+ * 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 bypasses source/target input-field permissions, not the virtual's own output
+ * authorization. GlobalOptions.requireReadOperationAccessForPopulateDependencies 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.
+ */
+interface ModelVirtualPopulateDependency<TModel = unknown> {
+    /** Top-level ref relative to this virtual's scope; no dotted source paths. Retained automatically. */
+    path: AccessRouterFieldKey<TModel>;
+    /** Persisted target mask: string, string[], or 1/-1 object (not 0). Empty/omitted selects all eligible fields. */
+    select?: Projection;
+}
+type VirtualPopulateMap<TModel, TPopulated> = {
+    [K in keyof TPopulated]: K extends AccessRouterFieldKey<TModel> ? unknown : never;
+};
+type VirtualPopulatePartial<T> = T extends Date | RegExp | ArrayBuffer | ArrayBufferView | {
+    readonly _bsontype: string;
+} ? T : T extends readonly (infer U)[] ? readonly VirtualPopulatePartial<U>[] : T extends object ? {
+    readonly [K in keyof T]?: VirtualPopulatePartial<T[K]>;
+} : T;
+type VirtualPopulateKnownValue<TSource, TTarget> = TSource extends readonly unknown[] ? readonly (VirtualPopulatePartial<TTarget> | null)[] : VirtualPopulatePartial<TTarget>;
+type VirtualPopulateValue<TSource, TTarget> = unknown extends TSource ? VirtualPopulatePartial<TTarget> | readonly (VirtualPopulatePartial<TTarget> | null)[] | null : VirtualPopulateKnownValue<NonNullable<TSource>, TTarget> | null;
+/**
+ * Declaration-scoped fourth getter input. Explicitly map source keys to target
+ * persisted shapes; IDs cannot infer a target model. Each key and target field
+ * may be missing, scalar misses are null, and arrays preserve null slots. Source
+ * cardinality determines the view (unknown sources permit scalar or array).
+ * Containers are deeply readonly/partial; native scalar types are preserved.
+ * Each getter/row/array slot receives isolated copies, including native mutable
+ * leaves. Native methods are not made immutable by this type. Hydrated and lean
+ * materialization can differ; this is not a JSON-value conversion promise.
+ * This annotation does not select fields or confer authority. No implicit transport
+ * to DTOs, hooks, handles or metadata; an authorized getter's deliberate return is output.
+ */
+type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> = {
+    readonly [K in keyof TPopulated]?: VirtualPopulateValue<K extends keyof TModel ? TModel[K] : unknown, TPopulated[K]>;
+};
+/**
+ * Virtual getter signature (VIRT-00A D3/D4, frozen).
+ * Its first argument is an isolated plain-object snapshot of ordinary persisted/
+ * local-dependency inputs + finalized public related/embedded outputs for its scope.
+ * Sibling virtual values are not visible. Input mutations have no implicit effect
+ * on response data or lifecycle snapshots. Only the returned field value is committed;
+ * `undefined` omits the field; throws omit fail-closed. `this` is the
+ * model request. The optional fourth argument contains only this getter's
+ * declared private populated inputs; default it to `{}` or guard undefined.
+ * 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 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.
+ */
+type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> = (this: ModelRequest, doc: ModelVirtualDoc<TModel>, permissions: AccessRouterPermissions, context: ModelVirtualContext, populated?: ModelVirtualPopulateInputs<TModel, TPopulated>) => MaybePromise<TValue | undefined>;
+/**
+ * Leaf virtual descriptor: `{ get, dependsOn?, dependsOnPopulate? }`.
+ * `dependsOn` lists top-level persisted field names relative to the
+ * definition's scope (e.g. `['displayName']` inside `contacts.sub`, never
+ * `['contacts.sub.displayName']`). Dotted paths and virtual-to-virtual
+ * dependencies are rejected at configuration time.
+ *
+ * The getter runs after `toObject()`/lean normalization and after internal
+ * document-permissions computation, with global permissions available and
+ * before `decorate`/`decorateAll`/tasks. Only the returned field value is
+ * committed via document-aware helpers: `undefined` (or a throw) omits the
+ * field fail-closed and computed values never persist. Getters see an
+ * isolated plain-object view for both lean and hydrated results; mutating the
+ * input has no implicit effect on response data or lifecycle snapshots.
+ *
+ * Annotate a descriptor separately with `TPopulated` to type its private fourth
+ * getter argument, then assign it to ordinary `ModelVirtuals`. The optional
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import type { ModelVirtualDescriptor } from '@web-ts-toolkit/access-router';
+ * import type { Types } from 'mongoose';
+ * interface Order { total: number; account: Types.ObjectId | null; }
+ * interface Account { balance: number; creditLimit: number; }
+ * const descriptor: ModelVirtualDescriptor<Order, boolean, { account: Account }> = {
+ *   dependsOn: ['total'],
+ *   dependsOnPopulate: [{ path: 'account', select: ['balance', 'creditLimit'] }],
+ *   get(doc, _permissions, _context, populated = {}) {
+ *     const account = populated.account;
+ *     if (doc.total === undefined || account?.balance === undefined || account.creditLimit === undefined)
+ *       return undefined;
+ *     return doc.total <= account.balance + account.creditLimit;
+ *   },
+ * };
+ * ```
+ */
+interface ModelVirtualDescriptor<TModel = unknown, TValue = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> {
+    /** Only this return becomes virtual output; private inputs are not implicitly transported. */
+    get: ModelVirtualGetter<TModel, TValue, TPopulated>;
+    /** Local top-level persisted input names relative to the definition's scope. */
+    dependsOn?: Array<AccessRouterFieldKey<TModel>>;
+    /** Server-only private fourth-argument inputs; source refs retained automatically. `[]` clears a shared list. */
+    dependsOnPopulate?: ModelVirtualPopulateDependency<TModel>[];
+}
+/**
+ * Per-access virtual record (VIRT-01): `default` + `list`/`create`/`read`/
+ * `update` (NOT `delete`/`distinct`/`count`). Each present access holds a
+ * leaf descriptor or bare getter shorthand. An optional shared `dependsOn`
+ * supports the documented `{ dependsOn, read: getter }` shape; a leaf's own
+ * `dependsOn` wins over the shared list during resolution. `dependsOnPopulate`
+ * inherits independently by the same rule: undefined inherits, a defined leaf
+ * list replaces the shared list wholesale (including `[]`).
+ */
+type ModelVirtualAccessRecord<TModel = unknown, TValue = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> = {
+    default?: ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualGetter<TModel, TValue, TPopulated>;
+    list?: ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualGetter<TModel, TValue, TPopulated>;
+    create?: ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualGetter<TModel, TValue, TPopulated>;
+    read?: ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualGetter<TModel, TValue, TPopulated>;
+    update?: ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualGetter<TModel, TValue, TPopulated>;
+    dependsOn?: Array<AccessRouterFieldKey<TModel>>;
+    /** Shared private input list; each resolved getter gets only its own mask. A leaf's defined list replaces it. */
+    dependsOnPopulate?: ModelVirtualPopulateDependency<TModel>[];
+};
+/** Single virtual entry: bare getter, leaf descriptor, or per-access record. */
+type ModelVirtualLeaf<TModel = unknown, TValue = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> = ModelVirtualGetter<TModel, TValue, TPopulated> | ModelVirtualDescriptor<TModel, TValue, TPopulated> | ModelVirtualAccessRecord<TModel, TValue, TPopulated>;
+type UnwrapVirtualArray<T> = T extends readonly (infer U)[] ? U : T;
+/**
+ * Persisted sub-scope model for an embedded container field (VIRT-01).
+ * Unwraps arrays/nullable wrappers to the element/object type; unknown
+ * fields fall back to a loose record.
+ */
+type VirtualSubModel<TModel, TField extends string> = TField extends keyof TModel ? UnwrapVirtualArray<NonNullable<TModel[TField]>> : Record<string, unknown>;
+type LooseVirtualLeaf = ModelVirtualGetter<Record<string, unknown>, unknown> | ModelVirtualDescriptor<Record<string, unknown>, unknown> | ModelVirtualAccessRecord<Record<string, unknown>, unknown>;
+type LooseVirtualSubEntry = LooseVirtualLeaf | {
+    sub?: Record<string, LooseVirtualLeaf | {
+        sub?: Record<string, LooseVirtualLeaf>;
+    }>;
+};
+/**
+ * Virtual definitions for a model scope (VIRT-01).
+ * Root leaves come from `TVirtuals` (strict: unknown persisted getter
+ * fields are type errors). Embedded containers mirror
+ * `permissionSchema.<field>.sub`: any persisted field may host a `sub`
+ * record whose leaves use the container's persisted sub-model view.
+ * Untyped models keep an explicit loose record fallback.
+ *
+ * Selected virtual outputs are optional (`Partial`): authorization, absent
+ * dependencies, `undefined`, and fail-closed errors can omit them. Virtual
+ * names are never added to persisted `Filter`, sort/distinct inputs, or
+ * client write types.
+ *
+ * @example End-to-end typed virtual (persisted `User` has no `fullAddress`):
+ * ```ts
+ * import acl from '@web-ts-toolkit/access-router';
+ * import type { SelectedPublicOutput } from '@web-ts-toolkit/access-router/advanced';
+ * interface User { name: string; address: string; }
+ * interface UserVirtuals { fullAddress: string; }
+ * const router = acl.createRouter<User, UserVirtuals>('User', {
+ *   permissionSchema: {
+ *     name: { read: true },
+ *     address: { read: 'canViewAddress' },
+ *     fullAddress: { read: 'canViewAddress' },
+ *   },
+ *   virtuals: {
+ *     fullAddress: {
+ *       dependsOn: ['address'],
+ *       read: async function (doc) {
+ *         if (doc.address === undefined) return undefined;
+ *         return `addr:${doc.address}`;
+ *       },
+ *     },
+ *   },
+ * });
+ * type Out = SelectedPublicOutput<User, ['name', 'fullAddress'], UserVirtuals>;
+ * const out: Out = { name: 'Ada', fullAddress: 'addr:x' };
+ * const omitted: Out = { name: 'Ada' }; // virtual is optional when denied/missing
+ * void [router, out, omitted];
+ * ```
+ */
+type ModelVirtuals<TModel = unknown, TVirtuals extends object = Record<never, never>> = IsUnknownVirtual<TModel> extends true ? Record<string, LooseVirtualSubEntry> : {
+    [K in Extract<keyof TVirtuals, string>]?: ModelVirtualLeaf<TModel, TVirtuals[K]>;
+} & {
+    [K in Extract<keyof TModel, string>]?: {
+        sub?: Record<string, ModelVirtualLeaf<VirtualSubModel<TModel, K>, unknown> | {
+            sub?: Record<string, LooseVirtualLeaf>;
+        }>;
+    };
+};
+
+interface ResolvedVirtualDescriptor {
+    get: (...args: never[]) => unknown;
+    dependsOn: string[];
+    dependsOnPopulate?: ModelVirtualPopulateDependency[];
+}
+
+type ModelReferenceMap = {
+    [key: string]: string | ModelReferenceMap;
+};
+/**
+ * Owner of global/model/data options, registered Mongoose models and OpenAPI routes.
+ * Prefer createAccessRuntime() for a callable API with factories and bound setters;
+ * its `.runtime` exposes this owner. A bare instance has no createRouter method.
+ * Registries/configuration are isolated; the Mongoose jsonSchema extension is initialized
+ * idempotently. The defaultRuntime additionally adopts process-global named models.
+ */
+declare class AccessRuntime {
+    private readonly allowGlobalModelLookup;
+    constructor(options?: {
+        allowGlobalModelLookup?: boolean;
+    });
+    private readonly globalOptions;
+    private readonly defaultModelOptions;
+    private readonly modelOptions;
+    private readonly modelJsonSchemas;
+    private readonly dataOptions;
+    private readonly modelRefs;
+    private readonly modelSubs;
+    private readonly modelAtts;
+    private readonly modelInstances;
+    private readonly openApiRegistry;
+    private openApiPathPrefix;
+    registerModelInstance<TModel>(modelName: string, model: mongoose.Model<TModel>): void;
+    hasModelInstance(modelName: string): boolean;
+    getModelInstance<TModel = unknown>(modelName: string): mongoose.Model<TModel> | null;
+    registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
+    /**
+     * Compose OpenAPI paths while synchronously constructing mounted routers.
+     * Prefixes apply before collision checks; prior descriptors and Express paths
+     * are unchanged. Nested calls compose and the prior scope is restored even on
+     * failure. The callback must finish registration synchronously (no async work).
+     */
+    withOpenApiPathPrefix<T>(prefix: string, build: () => T): T;
+    /**
+     * Enable strict OpenAPI collision detection for the remainder of this
+     * runtime's lifetime. After this call, conflicting method/path
+     * registrations and duplicate operationIds throw {@link OpenApiCollisionError}
+     * instead of silently replacing. Existing already-registered routes are
+     * not retroactively re-validated.
+     */
+    enableOpenApiCollisionDetection(): void;
+    getOpenApiRoutes(): OpenApiRouteDescriptor[];
+    clearOpenApiRoutes(): void;
+    getOpenApiSpec(info: OpenApiDocumentOptions): {
+        openapi: string;
+        info: Omit<OpenApiDocumentOptions, "servers">;
+        servers?: OpenApiDocumentOptions["servers"];
+        paths: Record<string, Record<string, {
+            [key: `x-${string}`]: unknown;
+            operationId?: string;
+            summary?: string;
+            description?: string;
+            tags?: string[];
+            deprecated?: boolean;
+            parameters?: OpenApiParameter[];
+            requestBody?: {
+                required?: boolean;
+                content: Record<string, {
+                    schema: OpenApiSchema;
+                }>;
+            };
+            responses: OpenApiResponses;
+        }>>;
+    };
+    createBootstrapSnapshot(): {
+        globalOptions: GlobalOptions;
+        defaultModelOptions: DefaultModelRouterOptions;
+        modelOptions: Record<string, ModelRouterOptions>;
+        dataOptions: Record<string, DataRouterOptions>;
+        modelInstances: Record<string, mongoose.Model<unknown>>;
+        modelJsonSchemas: Record<string, Record<string, unknown>>;
+        modelRefs: Record<string, ModelReferenceMap>;
+        modelSubs: Record<string, string[]>;
+        modelAtts: Record<string, string[]>;
+        openApi: {
+            routes: OpenApiRouteDescriptor[];
+            options: Required<OpenApiRegistryOptions>;
+        };
+    };
+    restoreBootstrapSnapshot(snapshot: ReturnType<AccessRuntime['createBootstrapSnapshot']>): void;
+    /** Shallowly replace supplied global values; nested objects such as requestComplexity are not deep-merged. */
+    setGlobalOptions(options: GlobalOptions): void;
+    setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
+    getGlobalOptions(): GlobalOptions;
+    getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
+    /** Update model starting defaults shallowly; already-stored model values are not broadcast-replaced. */
+    setDefaultModelOptions(options: DefaultModelRouterOptions): void;
+    setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
+    getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
+    getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
+    private createModelOptions;
+    private getOrCreateModelOptions;
+    /**
+     * Assign `{ ...modelDefaults, ...storedOptions, ...options }` shallowly. A supplied
+     * operationAccess/defaults object replaces that whole value. Defaults accept only
+     * query/presentation settings; virtual configuration is validated before assignment.
+     * Existing router.options remains its construction-time snapshot. Fresh model-service
+     * calls capture the owner's current options/defaults; in-flight calls retain their snapshot.
+     */
+    setModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): void;
+    setModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): void;
+    /** Frozen stored snapshot, not fully resolved per-path defaults. Read again for current configuration. */
+    getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
+    /**
+     * Generic stored exact → parent.default → parent lookup; only undefined falls through.
+     * The exact runtime-model-default path is the final fallback if the stored parent is
+     * absent. This is not the route-specific variant-to-base resolver; use
+     * getExactModelOption to inspect a variant including its exact model-default fallback.
+     */
+    getModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K | string, defaultValue?: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): ExtendedModelRouterOptions<TModel, TVirtuals>[K];
+    /** Exact stored path, then the same runtime-model-default path; no parent/default or variant-to-base lookup. */
+    getExactModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K | string): ExtendedModelRouterOptions<TModel, TVirtuals>[K];
+    /**
+     * List registered virtual leaf names for a scope (VIRT-01).
+     * Scope containers (`{ sub }`) are not leaves. Inapplicable names are
+     * still listed here; applicability is decided per-access by
+     * {@link resolveVirtualDescriptor}. Request-controlled include collisions
+     * are validated by VIRT-05, not guessed here.
+     */
+    getVirtualNames(modelName: string, scopePath?: string[]): string[];
+    /**
+     * Whether a field is a registered virtual leaf in a scope (VIRT-01).
+     * Inapplicable registered names stay virtual (never persisted), even when
+     * no getter applies for the current access. Containers and persisted
+     * fields return false.
+     */
+    isVirtualField(modelName: string, fieldName: string, scopePath?: string[]): boolean;
+    /**
+     * Resolve an applicable virtual descriptor with exact → `.default` → bare
+     * semantics (VIRT-01, VIRT-00A D1/D5). Returns `undefined` when no getter
+     * applies for `access`. Crucially, an access-record object is NEVER
+     * 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 `dependsOn` and `dependsOnPopulate` lists inherit independently;
+     * each defined leaf list replaces its shared list wholesale.
+     */
+    resolveVirtualDescriptor(modelName: string, virtualName: string, access: string, scopePath?: string[]): ResolvedVirtualDescriptor | undefined;
+    getModelNames(): string[];
+    hasModel(modelName: string): boolean;
+    getModelJsonSchema(modelName: string): Record<string, unknown>;
+    private createDataOptions;
+    private getOrCreateDataOptions;
+    setDataOptions<TData = unknown>(dataName: string, options: DataRouterOptions<TData>): void;
+    setDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K, value: ExtendedDataRouterOptions<TData>[K]): void;
+    getDataOptions<TData = unknown>(dataName: string): DataRouterOptions<TData>;
+    /**
+     * Reusable configured data view: plain containers are frozen; native properties
+     * return detached mutable copies on access. Native identity is not stable.
+     * Replacement leaves previously captured views on their original data version.
+     */
+    getDataSnapshot<TData = unknown>(dataName: string): readonly TData[];
+    getDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string, defaultValue?: ExtendedDataRouterOptions<TData>[K]): ExtendedDataRouterOptions<TData>[K];
+    getExactDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string): ExtendedDataRouterOptions<TData>[K];
+    getDataNames(): string[];
+    ensureModelMeta(modelName: string): void;
+    getModelRef(modelName: string, refPath: string): string | null;
+    getModelSub(modelName: string): string[];
+    getModelAtt(modelName: string): string[];
+}
+declare const defaultRuntime: AccessRuntime;
+
+declare class DataCore {
+    private req;
+    private readonly requestRuntime;
+    private caches;
+    private cachedPermissions;
+    constructor(req: AccessRouterBaseRequest);
+    genIDFilter<TData = unknown>(dataName: string, id: string): Promise<Filter<TData>>;
+    genFilter<TData = unknown>(dataName: string, access?: BaseFilterAccess, _filter?: Filter<TData>): Promise<Filter<TData>>;
+    /** Request-schema allowlist, independent of doc values. No model hooks or backend elevation. */
+    genAllowedFields(dataName: string, _doc: unknown, access: SelectAccess, options?: DataFieldOptions): Promise<string[]>;
+    /** Request-only existing-value pick. No automatic identity/metadata retention; options default to {}. */
+    pickAllowedFields<TDoc>(dataName: string, doc: TDoc, access: SelectAccess, options?: DataFieldOptions): Promise<TDoc>;
+    /**
+     * Request-only requested-token intersection. Omitted/null/empty/exclusion-only select
+     * yields []; DataService then applies no extra projection after request trimming.
+     * Named options default to {}; legacy elevation and positional arguments are removed.
+     */
+    genSelect(dataName: string, access: SelectAccess, targetFields?: Projection, options?: DataFieldOptions): Promise<string[]>;
+    private fieldPermissionSchema;
+    decorate<TDoc>(dataName: string, doc: TDoc, access: DecorateAccess, context?: DataHookContext): Promise<TDoc>;
+    decorateAll<TDoc>(dataName: string, docs: TDoc[], access: DecorateAllAccess, context?: DataHookContext): Promise<TDoc[]>;
+    getPermissions(): Permission;
+    setPermissions(): Promise<void>;
+    canActivate(routeGuard: Validation): Promise<boolean>;
+    isAllowed(dataName: string, access: RouteGuardAccess | string): Promise<boolean>;
+    /** Authorize route entry using explicit server-owned basic/advanced metadata. */
+    isAllowedRoute(dataName: string, baseAccess: RouteGuardAccess | string, variant: RouteVariant): Promise<boolean>;
+    getService<TData = unknown>(dataName: string): DataService<TData>;
+    service<TData = unknown>(dataName: string): DataService<TData>;
+    svc<TData = unknown>(dataName: string): DataService<TData>;
+    private getGlobalPermissions;
 }
-interface SubPopulate {
-    path: string;
-    select?: Projection;
+
+declare const MIDDLEWARE: unique symbol;
+declare const DATA_MIDDLEWARE: unique symbol;
+declare const PERMISSIONS: unique symbol;
+declare const PERMISSION_KEYS: unique symbol;
+
+interface AccessRouterRequestExtensions {
+    macl?: Core;
+    dacl?: DataCore;
+    [PERMISSIONS]?: AccessRouterPermissions;
+    [PERMISSION_KEYS]?: string[];
+    [MIDDLEWARE]?: unknown[] | unknown;
+    [DATA_MIDDLEWARE]?: unknown[] | unknown;
+    [key: string]: unknown;
+    [key: symbol]: unknown;
 }
+type AccessRouterRequest = express.Request & AccessRouterRequestExtensions;
 
 /**
  * Bounded persisted/registered-virtual response paths, including embedded array children.
@@ -798,6 +1091,37 @@ type AllowedOutputFieldOptions<TModel = unknown, TVirtuals extends object = Reco
     readonly purpose: 'output';
 };
 
+/** Package-private D2 validation/capture. Terminal persisted inputs, never output grants or target I/O. */
+
+interface VirtualPopulateTarget {
+    /** Stable per-capture identity for grouping even when native policy values are copied on read. */
+    readonly identity: object;
+    readonly runtime: AccessRuntime;
+    readonly modelName: string;
+    readonly model: Model<unknown>;
+    /** Binding identity only. Execution uses the owned catalog/selections, not live schema inspection. */
+    readonly schema: Schema;
+    /** Terminal read policy: no target virtual registry or private dependency graph. */
+    readonly configuration: AuthorizationConfiguration;
+}
+interface CapturedVirtualPopulateDependency {
+    /** Scope-local path and absolute persisted source path (no `.sub` markers). */
+    readonly path: string;
+    readonly sourcePath: string;
+    readonly cardinality: 'scalar' | 'array';
+    readonly target: VirtualPopulateTarget;
+    /** Eligible leaf mask for this getter only; never a public output selection. */
+    readonly selection: readonly string[];
+    /** Positive persisted paths, including association identity even for `-_id`. */
+    readonly fetchSelection: readonly string[];
+    readonly includeId: boolean;
+}
+/**
+ * An opaque function identity survives configuration copying without copying a
+ * Mongoose schema/runtime graph. Bindings live only here, not on DTOs or handles.
+ */
+type VirtualPopulateSnapshotToken = () => void;
+
 interface AuthorizationBinding {
     readonly request: AccessRouterRequest;
     readonly runtime: object;
@@ -827,6 +1151,12 @@ interface AuthorizationFieldCatalog {
 }
 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 requireReadOperationAccessForPopulateDependencies?: boolean;
+    /** Independent ordinary-populate registration posture from the same global snapshot. */
+    readonly requireRegisteredPopulateModels?: boolean;
     readonly documentPermissionField?: string;
     /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
     readonly [key: string]: unknown;
@@ -836,9 +1166,15 @@ interface AuthorizationRelatedTarget {
     readonly path: string;
     readonly modelName: string;
     readonly configuration: AuthorizationConfiguration;
+    /** Effective include args/options, resolved with that target's captured defaults. */
+    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 relatedTargets?: readonly AuthorizationRelatedTarget[];
+    /** Captured supported raw-ref transport shape; exotic ordinary populates keep their adapter path. */
+    readonly staticObjectIdReference?: boolean;
 }
 declare const resolvedAuthorizationBrand: unique symbol;
 interface ResolvedServiceAuthorization {
@@ -883,6 +1219,7 @@ type FieldAuthorizationState = 'granted' | 'deferred' | 'denied';
 type VirtualProjectionAccess = 'list' | 'create' | 'read' | 'update' | (string & {});
 type VirtualCandidateAuthState = 'granted' | 'deferred';
 interface VirtualProjectionSnapshot {
+    virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
     catalog?: AuthorizationFieldCatalog;
     permissionSchema?: Record<string, unknown> | null;
     virtuals?: Record<string, unknown> | null;
@@ -894,12 +1231,11 @@ interface VirtualProjectionSnapshot {
 }
 interface PlanVirtualCandidate {
     name: string;
-    descriptor: {
-        get: (...args: never[]) => unknown;
-        dependsOn: string[];
-    };
+    descriptor: ResolvedVirtualDescriptor;
     authState: VirtualCandidateAuthState;
     dependsOn: string[];
+    /** Terminal private reads for this active getter; not first-argument dependencies. */
+    populateDependencies: readonly CapturedVirtualPopulateDependency[];
     virtualAccess: VirtualProjectionAccess;
     outputAccess: VirtualProjectionAccess;
 }
@@ -925,6 +1261,10 @@ interface VirtualProjectionPlan {
     outputVirtualNames: string[];
     /** Safe Mongoose projection: no virtuals, no `.sub` paths, no `-_id`. */
     persistedFetchSelection: string[];
+    /** Pre-expansion persisted/hook input mask. Fetching new refs confers no hook-input authority. */
+    publicPersistedFetchSelection: string[];
+    /** Empty embedded hook views retain container shape, never a private fetch's contents. */
+    publicStructurePaths?: string[];
     candidates: PlanVirtualCandidate[];
     virtualOnlyDeps: string[];
     internalOnlyFields: string[];
@@ -1013,6 +1353,13 @@ declare class Service<TModel = unknown, TVirtuals extends object = Record<never,
     /** Presence, not truthiness: never read a legacy slot or treat it as payload data. */
     private admitServiceCall;
     private executionOutputPlan;
+    private preparedOutputIntent;
+    /** Raw result -> exact ref capture -> detached ordinary source/hook rows.
+     * Private inputs travel separately through finalization, never through snapshots.
+     */
+    private loadOutputPopulateDependencies;
+    /** Dependency-bearing post-lifecycle/template work uses detached output copies. */
+    private prepareDetachedOutputRows;
     private requestSortFields;
     /** One output stage per row, independent of metadata and of pre-write admission. */
     private finalizeDirectOutput;
@@ -1062,7 +1409,8 @@ declare class Service<TModel = unknown, TVirtuals extends object = Record<never,
      * Finalizes already-filtered (visible-only) sub rows through the shared
      * boundary with scope ` [sub,'sub']`, owning-parent `read` grants, and
      * scoped rules. Children (deeper nested + related via `related`) finalize
-     * before sub getters; only finalized children appear in getter views.
+     * before sub getters; argument one has finalized public children. Declared
+     * private populated inputs travel separately in argument four.
      * Uses a bounded row map + request/runtime hook-chain admission (stable
      * order, limit-one reentry, no persistence permits held). Waiting ancestor
      * callback frames do not consume extra permits. Callers must filter rows BEFORE
@@ -1247,18 +1595,6 @@ declare class Service<TModel = unknown, TVirtuals extends object = Record<never,
     countByFieldValues(foreignField: string, values: readonly unknown[], filter?: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<Map<string, number>> | ErrorResult>;
     private countPreparedByFieldValueGroups;
     getDocPermissions(doc: unknown): Record<string, unknown>;
-    private resolveFindOneArgs;
-    private resolveFindOneOptions;
-    private resolveFindByIdArgs;
-    private resolveFindByIdOptions;
-    private resolveFindArgs;
-    private resolveFindOptions;
-    private resolveCreateArgs;
-    private resolveCreateOptions;
-    private resolveUpdateOneArgs;
-    private resolveUpdateOneOptions;
-    private resolveUpdateByIdArgs;
-    private resolveUpdateByIdOptions;
     private resolveUpsertArgs;
     private resolveUpsertOptions;
     private resolveExistsOptions;
@@ -1356,6 +1692,8 @@ declare class PublicService<TModel = unknown, TVirtuals extends object = Record<
     _delete(id: string): Promise<SingleResult<unknown> | ErrorResult>;
     _distinct(field: string, options?: DistinctArgs<TModel>): Promise<ListResult<unknown> | ErrorResult>;
     _count(filter: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<number> | ErrorResult>;
+    /** Own the conditional gate with the read; execute only after a nonterminal miss. */
+    private captureListFallbackAdmission;
     private admitPublicCall;
     private resolvePublicListArgs;
     private resolvePublicListOptions;
@@ -1635,7 +1973,7 @@ declare class Base<TModel = unknown, TVirtuals extends object = Record<never, ne
     protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation, path?: string, parentAuthorization?: ResolvedServiceAuthorization): Promise<PublicService<unknown, Record<never, never>>>;
     private relatedBinding;
     private relatedExecution;
-    protected processInclude(include: Include | Include[]): {
+    protected processInclude(include: Include | Include[], authorization?: ResolvedServiceAuthorization): {
         includes: LegacyInclude[];
         correlatedIncludes: CorrelatedInclude[];
         includeLocalFields: string[];
@@ -2688,198 +3026,6 @@ interface ExistsOptions {
     includeId?: boolean;
 }
 
-type MaybePromise<T> = T | Promise<T>;
-type AccessRouterFieldKey<T> = [Extract<keyof T, string>] extends [never] ? string : Extract<keyof T, string>;
-type IdentifierHook<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, id: string) => MaybePromise<Filter<TValue>>;
-type GlobalPermissionValue = Record<string, boolean> | string[] | string | null | undefined;
-type BaseFilterHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, permissions: AccessRouterPermissions) => MaybePromise<Filter | true | null | undefined>;
-type OverrideFilterHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, filter: Filter, permissions: AccessRouterPermissions) => MaybePromise<Filter>;
-type Hook<TValue, TContext, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: TValue, permissions: AccessRouterPermissions, context: TContext) => MaybePromise<TValue>;
-type HookChain<TValue, TContext, TRequest extends AccessRouterRequest = AccessRouterRequest> = Hook<TValue, TContext, TRequest> | Array<Hook<TValue, TContext, TRequest>>;
-type ValidateRule = boolean | unknown[];
-type ValidateHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, allowedData: unknown, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<ValidateRule>;
-type DocPermissionsHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, doc: unknown, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<Record<string, unknown>>;
-type ChangeHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, previousValue: unknown, nextValue: unknown, changes: Change[], context: ModelHookContext) => MaybePromise<void>;
-type DeleteHook<TValue = unknown, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: TValue, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<void>;
-type DocumentHook<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, value: ModelDocument<TValue>, permissions: AccessRouterPermissions, context: ModelHookContext) => MaybePromise<ModelDocument<TValue>>;
-type DocumentHookChain<TValue, TRequest extends AccessRouterRequest = AccessRouterRequest> = DocumentHook<TValue, TRequest> | Array<DocumentHook<TValue, TRequest>>;
-type ModelBaseFilterHook = BaseFilterHook<ModelRequest>;
-type DataBaseFilterHook = BaseFilterHook<DataRequest>;
-type ModelOverrideFilterHook = OverrideFilterHook<ModelRequest>;
-type DataOverrideFilterHook = OverrideFilterHook<DataRequest>;
-type ModelIdentifierHook<TValue = unknown> = IdentifierHook<TValue, ModelRequest>;
-type DataIdentifierHook<TValue = unknown> = IdentifierHook<TValue, DataRequest>;
-type ModelValidateHook = ValidateHook<ModelRequest>;
-/**
- * Request-user grants from untrimmed projected input. Declare private persisted inputs
- * with alwaysSelectFields. Integrated output resolves once per document/access stage,
- * independently of skim or metadata serialization; use the result's document handle
- * for later picks after input/metadata trim. Backend grants do not forge user metadata.
- */
-type ModelDocPermissionsHook = DocPermissionsHook<ModelRequest>;
-type ModelChangeHook = ChangeHook<ModelRequest>;
-type ModelDocumentHook<TValue = unknown> = DocumentHookChain<TValue, ModelRequest>;
-type ModelDeleteHook<TValue = unknown> = DeleteHook<ModelDocument<TValue>, ModelRequest>;
-type ModelHook<TValue = unknown> = HookChain<TValue, ModelHookContext, ModelRequest>;
-type ModelListHook<TValue = unknown> = HookChain<TValue[], ModelHookContext, ModelRequest>;
-type DataHook<TValue = unknown> = HookChain<TValue, DataHookContext, DataRequest>;
-type DataListHook<TValue = unknown> = HookChain<TValue[], DataHookContext, DataRequest>;
-/**
- * Supported per-access virtual getter keys (VIRT-00A D1/D5).
- * `default` is a fallback access; `delete`/`distinct`/`count` are NOT
- * virtual accesses and must be rejected at configuration time.
- */
-type ModelVirtualAccess = 'list' | 'create' | 'read' | 'update';
-type ModelVirtualRecordAccess = 'default' | ModelVirtualAccess;
-/**
- * Scope-aware virtual getter context (VIRT-00A D2, frozen).
- * Extends {@link ModelHookContext} with the receiving model, definition/
- * permission `scopePath` (e.g. `[]` at root, `['contacts','sub']` for
- * `contacts.sub.displayName`), and the three effective accesses. The
- * initiating operation stays in `context.operation` and is never
- * overwritten with fallback/effective visibility.
- *
- * Embedded outputs reuse the owning parent's internally computed grants with
- * the scope's `permissionSchema.<field>.sub` rules; dedicated subdocument
- * routes resolve grants from the raw parent lookup. Related (populate/
- * include) targets finalize with the target model's own definitions,
- * permissions, selection, and effective access before parent getters run.
- */
-interface ModelVirtualContext extends ModelHookContext {
-    receivingModelName: string;
-    scopePath: string[];
-    virtualAccess: ModelVirtualAccess;
-    outputAccess: ModelVirtualAccess;
-    docPermissionsAccess: ModelVirtualAccess;
-}
-type IsUnknownVirtual<T> = unknown extends T ? ([keyof T] extends [never] ? true : false) : false;
-/**
- * Typed isolated persisted view for a virtual getter scope (VIRT-00A D3/D4).
- * Known models use a partial read-only persisted view (never
- * `Record<string, unknown>`); unknown/untyped models keep an explicit
- * loose fallback.
- */
-type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ? Readonly<Partial<Record<string, unknown>>> : [Extract<keyof TModel, string>] extends [never] ? Readonly<Partial<Record<string, unknown>>> : Readonly<Partial<TModel>>;
-/**
- * Virtual getter signature (VIRT-00A D3/D4, frozen).
- * Receives an isolated plain-object snapshot of persisted dependencies +
- * already-finalized related/embedded outputs for its scope. Sibling virtual
- * values are not visible. Mutating the input cannot change response data or
- * lifecycle snapshots. Only the returned field value is committed;
- * `undefined` omits the field; throws omit fail-closed. `this` is the
- * model request.
- */
-type ModelVirtualGetter<TModel = unknown, TValue = unknown> = (this: ModelRequest, doc: ModelVirtualDoc<TModel>, permissions: AccessRouterPermissions, context: ModelVirtualContext) => MaybePromise<TValue | undefined>;
-/**
- * Leaf virtual descriptor (VIRT-01): `{ get, dependsOn }`.
- * `dependsOn` lists top-level persisted field names relative to the
- * definition's scope (e.g. `['displayName']` inside `contacts.sub`, never
- * `['contacts.sub.displayName']`). Dotted paths and virtual-to-virtual
- * dependencies are rejected at configuration time.
- *
- * The getter runs after `toObject()`/lean normalization and after internal
- * document-permissions computation, with global permissions available and
- * before `decorate`/`decorateAll`/tasks. Only the returned field value is
- * committed via document-aware helpers: `undefined` (or a throw) omits the
- * field fail-closed and computed values never persist. Getters see an
- * isolated plain-object view for both lean and hydrated results; mutating the
- * input cannot change response data or lifecycle snapshots.
- *
- * @example
- * ```ts
- * import type { ModelVirtualDescriptor } from '@web-ts-toolkit/access-router';
- * interface User { name: string; address: string; }
- * const descriptor: ModelVirtualDescriptor<User, string> = {
- *   dependsOn: ['address'],
- *   get: async (doc) => (doc.address === undefined ? undefined : `addr:${doc.address}`),
- * };
- * ```
- */
-interface ModelVirtualDescriptor<TModel = unknown, TValue = unknown> {
-    get: ModelVirtualGetter<TModel, TValue>;
-    dependsOn?: Array<AccessRouterFieldKey<TModel>>;
-}
-/**
- * Per-access virtual record (VIRT-01): `default` + `list`/`create`/`read`/
- * `update` (NOT `delete`/`distinct`/`count`). Each present access holds a
- * leaf descriptor or bare getter shorthand. An optional shared `dependsOn`
- * supports the documented `{ dependsOn, read: getter }` shape; a leaf's own
- * `dependsOn` wins over the shared list during resolution.
- */
-type ModelVirtualAccessRecord<TModel = unknown, TValue = unknown> = {
-    default?: ModelVirtualDescriptor<TModel, TValue> | ModelVirtualGetter<TModel, TValue>;
-    list?: ModelVirtualDescriptor<TModel, TValue> | ModelVirtualGetter<TModel, TValue>;
-    create?: ModelVirtualDescriptor<TModel, TValue> | ModelVirtualGetter<TModel, TValue>;
-    read?: ModelVirtualDescriptor<TModel, TValue> | ModelVirtualGetter<TModel, TValue>;
-    update?: ModelVirtualDescriptor<TModel, TValue> | ModelVirtualGetter<TModel, TValue>;
-    dependsOn?: Array<AccessRouterFieldKey<TModel>>;
-};
-/** Single virtual entry: bare getter, leaf descriptor, or per-access record. */
-type ModelVirtualLeaf<TModel = unknown, TValue = unknown> = ModelVirtualGetter<TModel, TValue> | ModelVirtualDescriptor<TModel, TValue> | ModelVirtualAccessRecord<TModel, TValue>;
-type UnwrapVirtualArray<T> = T extends readonly (infer U)[] ? U : T;
-/**
- * Persisted sub-scope model for an embedded container field (VIRT-01).
- * Unwraps arrays/nullable wrappers to the element/object type; unknown
- * fields fall back to a loose record.
- */
-type VirtualSubModel<TModel, TField extends string> = TField extends keyof TModel ? UnwrapVirtualArray<NonNullable<TModel[TField]>> : Record<string, unknown>;
-type LooseVirtualLeaf = ModelVirtualGetter<Record<string, unknown>, unknown> | ModelVirtualDescriptor<Record<string, unknown>, unknown> | ModelVirtualAccessRecord<Record<string, unknown>, unknown>;
-type LooseVirtualSubEntry = LooseVirtualLeaf | {
-    sub?: Record<string, LooseVirtualLeaf | {
-        sub?: Record<string, LooseVirtualLeaf>;
-    }>;
-};
-/**
- * Virtual definitions for a model scope (VIRT-01).
- * Root leaves come from `TVirtuals` (strict: unknown persisted getter
- * fields are type errors). Embedded containers mirror
- * `permissionSchema.<field>.sub`: any persisted field may host a `sub`
- * record whose leaves use the container's persisted sub-model view.
- * Untyped models keep an explicit loose record fallback.
- *
- * Selected virtual outputs are optional (`Partial`): authorization, absent
- * dependencies, `undefined`, and fail-closed errors can omit them. Virtual
- * names are never added to persisted `Filter`, sort/distinct inputs, or
- * client write types.
- *
- * @example End-to-end typed virtual (persisted `User` has no `fullAddress`):
- * ```ts
- * import acl from '@web-ts-toolkit/access-router';
- * import type { SelectedPublicOutput } from '@web-ts-toolkit/access-router/advanced';
- * interface User { name: string; address: string; }
- * interface UserVirtuals { fullAddress: string; }
- * const router = acl.createRouter<User, UserVirtuals>('User', {
- *   permissionSchema: {
- *     name: { read: true },
- *     address: { read: 'canViewAddress' },
- *     fullAddress: { read: 'canViewAddress' },
- *   },
- *   virtuals: {
- *     fullAddress: {
- *       dependsOn: ['address'],
- *       read: async function (doc) {
- *         if (doc.address === undefined) return undefined;
- *         return `addr:${doc.address}`;
- *       },
- *     },
- *   },
- * });
- * type Out = SelectedPublicOutput<User, ['name', 'fullAddress'], UserVirtuals>;
- * const out: Out = { name: 'Ada', fullAddress: 'addr:x' };
- * const omitted: Out = { name: 'Ada' }; // virtual is optional when denied/missing
- * void [router, out, omitted];
- * ```
- */
-type ModelVirtuals<TModel = unknown, TVirtuals extends object = Record<never, never>> = IsUnknownVirtual<TModel> extends true ? Record<string, LooseVirtualSubEntry> : {
-    [K in Extract<keyof TVirtuals, string>]?: ModelVirtualLeaf<TModel, TVirtuals[K]>;
-} & {
-    [K in Extract<keyof TModel, string>]?: {
-        sub?: Record<string, ModelVirtualLeaf<VirtualSubModel<TModel, K>, unknown> | {
-            sub?: Record<string, LooseVirtualLeaf>;
-        }>;
-    };
-};
-
 type RequestSchema = RequestSchemaLike;
 type NestedRequestSchema = {
     default?: RequestSchema;
@@ -2984,7 +3130,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization and resource settings, configured with
+ * Runtime-wide request initialization, private-input policy 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.
  */
@@ -3002,6 +3148,39 @@ interface GlobalOptions {
     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 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.
+     *
+     * 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.
+     *
+     * @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 snapshot: GlobalOptions = api.getGlobalOptions();
+     * api.setGlobalOption('requireReadOperationAccessForPopulateDependencies', true);
+     * void snapshot; // stored snapshot; read again to observe the setter
+     * ```
+     */
+    requireReadOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3305,6 +3484,16 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * authorized. Virtuals are output-only: registered names (including
      * embedded `sub` leaves) are excluded from persisted projections, client
      * write admission, and database sort/filter/distinct handling.
+     * `dependsOnPopulate` declares one-hop private persisted target inputs only in
+     * 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
+     * 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.
      *
      * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
      * ```ts
@@ -3611,4 +3800,4 @@ declare function fromIoTs<TValue = unknown>(decoder: IoTsDecoderLike<TValue>): R
 declare function fromSuperstruct<TStruct, TOutput = unknown>(struct: TStruct, validate: SuperstructValidateLike): RequestSchemaValidator<TOutput>;
 declare function fromVine<TValue = unknown>(validator: VineValidatorLike<TValue>): RequestSchemaValidator<TValue>;
 
-export { type DecorateAccess as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CorrelatedReadByFilterInclude as D, type CorrelatedReadByIdInclude as E, type CountBody as F, type CreateArgs as G, type CreateAuthorization as H, type CreateOptions as I, type CreateQueryInput as J, CustomHeaders as K, DATA_MIDDLEWARE as L, type DataBaseFilterHook as M, type DataFieldOptions as N, type DataFilter as O, type DataFindArgs as P, type DataFindOneArgs as Q, type DataFindOneOptions as R, type DataFindOptions as S, type DataHook as T, type DataHookContext as U, type DataIdentifierHook as V, type DataListHook as W, type DataOverrideFilterHook as X, type DataRequest as Y, type DataRequestSchemas as Z, type DataRouterOptions as _, type AccessRouterFieldKey as a, type ModelVirtualGetter as a$, type DecorateAllAccess as a0, type DeepFieldPath as a1, type DefaultModelRouterOptions as a2, type Defaults as a3, type DistinctArgs as a4, type DistinctBody as a5, type DocPermissionsAccess as a6, type DocumentAuthorization as a7, type ErrorResult as a8, type ExistsOptions as a9, type JoiValidationErrorDetailLike as aA, type KeyValueProjection as aB, type LegacyInclude as aC, type ListQueryInput as aD, type ListResult as aE, MIDDLEWARE as aF, type MaybePromise as aG, type ModelBaseFilterHook as aH, type ModelChangeHook as aI, type ModelDeleteHook as aJ, type ModelDocPermissionsHook as aK, type ModelDocument as aL, type ModelDocumentHook as aM, type ModelHook as aN, type ModelHookContext as aO, type ModelHydrationOptions as aP, type ModelIdentifierHook as aQ, type ModelListHook as aR, type ModelOverrideFilterHook as aS, type ModelRequest as aT, type ModelRouterOptions as aU, type ModelValidateHook as aV, type ModelVirtualAccess as aW, type ModelVirtualAccessRecord as aX, type ModelVirtualContext as aY, type ModelVirtualDescriptor as aZ, type ModelVirtualDoc as a_, type ExtendedDataRouterOptions as aa, type ExtendedDefaultModelRouterOptions as ab, type ExtendedModelRouterOptions as ac, type FieldAuthorization as ad, type FieldOperationAccess as ae, type Filter as af, FilterOperator as ag, type FindAccess as ah, type FindArgs as ai, type FindByIdArgs as aj, type FindByIdOptions as ak, type FindOneArgs as al, type FindOneOptions as am, type FindOptions as an, type GlobalOptions as ao, type GlobalPermissionValue as ap, type GuardHook as aq, type HydrationMode as ar, type IdentifierHook as as, type Include as at, type InputFieldAuthorization as au, type InputFieldPath as av, type IoTsContextEntryLike as aw, type IoTsDecodeErrorLike as ax, type IoTsDecoderLike as ay, type JoiSchemaLike as az, type AccessRouterLogger as b, type RootModelNewQueryEntry as b$, type ModelVirtualLeaf as b0, type ModelVirtualRecordAccess as b1, type ModelVirtuals as b2, type MutationAuthorization as b3, type NewArgs as b4, type NewOptions as b5, type OperationAccess as b6, type OperationAuthorization as b7, type OutputAuthorization as b8, type OutputFieldOptions as b9, type PublicSubdocumentMutationOptions as bA, type PublicSubdocumentReadOptions as bB, type PublicUpdateArgs as bC, type PublicUpdateOptions as bD, type PublicUpsertArgs as bE, type PublicUpsertOptions as bF, type ReadQueryInput as bG, type RelatedAuthorization as bH, type Request as bI, type RequestSchemaAdapter as bJ, type RequestSchemaFailure as bK, type RequestSchemaIssue as bL, type RequestSchemaLike as bM, type RequestSchemaOptions as bN, type RequestSchemaResult as bO, type RequestSchemaSuccess as bP, type RequestSchemaValidator as bQ, type RequestSchemas as bR, type RootDataListQueryEntry as bS, type RootDataOperation as bT, type RootDataReadByFilterQueryEntry as bU, type RootDataReadByIdQueryEntry as bV, type RootModelCountQueryEntry as bW, type RootModelCreateQueryEntry as bX, type RootModelDeleteQueryEntry as bY, type RootModelDistinctQueryEntry as bZ, type RootModelListQueryEntry as b_, type OutputFieldPath as ba, type OutputPlanningOptions as bb, PERMISSIONS as bc, PERMISSION_KEYS as bd, type PairedRouteAccess as be, type ParentRef as bf, type PathValue as bg, type PermissionSchema as bh, type Populate as bi, type PopulateAccess as bj, type PopulatePlanningOptions as bk, type PrepareAccess as bl, type Projection as bm, type PublicCreateArgs as bn, type PublicCreateOptions as bo, type PublicErrorResult as bp, type PublicListArgs as bq, type PublicListOptions as br, type PublicListResult as bs, type PublicOutput as bt, type PublicReadArgs as bu, type PublicReadOptions as bv, type PublicServiceResult as bw, type PublicSingleResult as bx, type PublicSubdocumentCreateOptions as by, type PublicSubdocumentListOptions as bz, type AccessRouterRequest as c, type SubdocumentReadAuthorization as c$, type RootModelOperation as c0, type RootModelReadByFilterQueryEntry as c1, type RootModelReadByIdQueryEntry as c2, type RootModelSubBulkUpdateQueryEntry as c3, type RootModelSubCreateQueryEntry as c4, type RootModelSubDeleteQueryEntry as c5, type RootModelSubListQueryEntry as c6, type RootModelSubReadQueryEntry as c7, type RootModelSubUpdateQueryEntry as c8, type RootModelUpdateQueryEntry as c9, type StandardSchemaSuccess as cA, type StandardSchemaV1 as cB, StatusCodes as cC, type SubListBody as cD, type SubOperationAccess as cE, type SubPopulate as cF, type SubQueryEntry as cG, type SubReadBody as cH, type SubRouteGuardOptions as cI, type SubdocumentBulkRecord as cJ, type SubdocumentBulkUpdateInput as cK, type SubdocumentCreateAuthorization as cL, type SubdocumentCreateInput as cM, type SubdocumentCreateOptions as cN, type SubdocumentCreateVisibilityAuthorization as cO, type SubdocumentDeleteAuthorization as cP, type SubdocumentDeleteOptions as cQ, type SubdocumentGateAuthorization as cR, type SubdocumentId as cS, type SubdocumentInputAuthorization as cT, type SubdocumentListOptions as cU, type SubdocumentModel as cV, type SubdocumentMutationAuthorization as cW, type SubdocumentName as cX, type SubdocumentOutputAuthorization as cY, type SubdocumentParentArgs as cZ, type SubdocumentParentOptions as c_, type RootModelUpsertQueryEntry as ca, type RootOperationResult as cb, type RootQueryEntry as cc, type RootRouterOptions as cd, type RootSubOperation as ce, type RootTarget as cf, type RouteBaseAccess as cg, type RouteGuardAccess as ch, type RouteVariant as ci, type RouteVariantAccess as cj, type RowAuthorization as ck, type SelectAccess as cl, type SelectedPopulatedPublicOutput as cm, type SelectedPublicOutput as cn, type ServiceAuthorization as co, type ServiceOutputContext as cp, type ServiceOutputDecorator as cq, type ServiceResult as cr, type SingleResult as cs, type Sort as ct, type SortOrder as cu, type StandardSchemaFailure as cv, type StandardSchemaInferOutput as cw, type StandardSchemaIssue as cx, type StandardSchemaPathSegment as cy, type StandardSchemaResult as cz, type AccessRouterRequestExtensions as d, type AccessRouterPermissions as d$, type SubdocumentReadOptions as d0, type SubdocumentRecord as d1, type SubdocumentUpdateOptions as d2, type SubdocumentVirtuals as d3, type SubdocumentVisibilityAuthorization as d4, type SuperstructFailureLike as d5, type SuperstructValidateLike as d6, type Task as d7, type TaskType as d8, type TransformAccess as d9, fromAjv as dA, fromArkType as dB, fromIoTs as dC, fromJoi as dD, fromStandardSchema as dE, fromSuperstruct as dF, fromValibot as dG, fromVine as dH, fromYup as dI, fromZod as dJ, parseBody as dK, parseBodyWithSchema as dL, parseNestedBodyWithSchema as dM, parsePathParam as dN, parseQuery as dO, AccessRuntime as dP, DataService as dQ, Service as dR, PublicService as dS, type OpenApiRouterOptions as dT, type OpenApiRegistryOptions as dU, type OpenApiRouteDescriptor as dV, type OpenApiDocumentOptions as dW, type OpenApiParameter as dX, type OpenApiSchema as dY, type OpenApiResponses as dZ, type AccessRouterPermissionMap as d_, type TypedFilter as da, type UpdateByIdArgs as db, type UpdateByIdOptions as dc, type UpdateOneArgs as dd, type UpdateOneOptions as de, type UpdateQueryInput as df, type UpsertArgs as dg, type UpsertOptions as dh, type UpsertQueryInput as di, type ValibotIssueLike as dj, type ValibotPathItemLike as dk, type ValibotSafeParseLike as dl, type ValibotSafeParseResult as dm, type ValidateAccess as dn, type ValidateRule as dp, type Validation as dq, type ValidationError as dr, type VineValidationErrorLike as ds, type VineValidationMessageLike as dt, type VineValidatorLike as du, type VirtualSubModel as dv, type WithVirtuals as dw, type YupSchemaLike as dx, type YupValidationErrorLike as dy, defineRequestSchema as dz, type AdvancedCreateBody as e, type OpenApiMethod as e0, type Permissions as e1, defaultRuntime as e2, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type AllowedOutputFieldOptions as o, type ArkTypeErrorsLike as p, type ArkTypeLike as q, type ArkTypeProblemLike as r, type AuthorizedListResult as s, type AuthorizedSingleResult as t, Codes as u, type CorrelatedCountInclude as v, type CorrelatedFilter as w, type CorrelatedInclude as x, type CorrelatedIncludeArgs as y, type CorrelatedListInclude as z };
+export { type DecorateAccess as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CorrelatedReadByFilterInclude as D, type CorrelatedReadByIdInclude as E, type CountBody as F, type CreateArgs as G, type CreateAuthorization as H, type CreateOptions as I, type CreateQueryInput as J, CustomHeaders as K, DATA_MIDDLEWARE as L, type DataBaseFilterHook as M, type DataFieldOptions as N, type DataFilter as O, type DataFindArgs as P, type DataFindOneArgs as Q, type DataFindOneOptions as R, type DataFindOptions as S, type DataHook as T, type DataHookContext as U, type DataIdentifierHook as V, type DataListHook as W, type DataOverrideFilterHook as X, type DataRequest as Y, type DataRequestSchemas as Z, type DataRouterOptions as _, type AccessRouterFieldKey as a, type ModelVirtualGetter as a$, type DecorateAllAccess as a0, type DeepFieldPath as a1, type DefaultModelRouterOptions as a2, type Defaults as a3, type DistinctArgs as a4, type DistinctBody as a5, type DocPermissionsAccess as a6, type DocumentAuthorization as a7, type ErrorResult as a8, type ExistsOptions as a9, type JoiValidationErrorDetailLike as aA, type KeyValueProjection as aB, type LegacyInclude as aC, type ListQueryInput as aD, type ListResult as aE, MIDDLEWARE as aF, type MaybePromise as aG, type ModelBaseFilterHook as aH, type ModelChangeHook as aI, type ModelDeleteHook as aJ, type ModelDocPermissionsHook as aK, type ModelDocument as aL, type ModelDocumentHook as aM, type ModelHook as aN, type ModelHookContext as aO, type ModelHydrationOptions as aP, type ModelIdentifierHook as aQ, type ModelListHook as aR, type ModelOverrideFilterHook as aS, type ModelRequest as aT, type ModelRouterOptions as aU, type ModelValidateHook as aV, type ModelVirtualAccess as aW, type ModelVirtualAccessRecord as aX, type ModelVirtualContext as aY, type ModelVirtualDescriptor as aZ, type ModelVirtualDoc as a_, type ExtendedDataRouterOptions as aa, type ExtendedDefaultModelRouterOptions as ab, type ExtendedModelRouterOptions as ac, type FieldAuthorization as ad, type FieldOperationAccess as ae, type Filter as af, FilterOperator as ag, type FindAccess as ah, type FindArgs as ai, type FindByIdArgs as aj, type FindByIdOptions as ak, type FindOneArgs as al, type FindOneOptions as am, type FindOptions as an, type GlobalOptions as ao, type GlobalPermissionValue as ap, type GuardHook as aq, type HydrationMode as ar, type IdentifierHook as as, type Include as at, type InputFieldAuthorization as au, type InputFieldPath as av, type IoTsContextEntryLike as aw, type IoTsDecodeErrorLike as ax, type IoTsDecoderLike as ay, type JoiSchemaLike as az, type AccessRouterLogger as b, type RootModelDistinctQueryEntry as b$, type ModelVirtualLeaf as b0, type ModelVirtualPopulateDependency as b1, type ModelVirtualPopulateInputs as b2, type ModelVirtualRecordAccess as b3, type ModelVirtuals as b4, type MutationAuthorization as b5, type NewArgs as b6, type NewOptions as b7, type OperationAccess as b8, type OperationAuthorization as b9, type PublicSubdocumentCreateOptions as bA, type PublicSubdocumentListOptions as bB, type PublicSubdocumentMutationOptions as bC, type PublicSubdocumentReadOptions as bD, type PublicUpdateArgs as bE, type PublicUpdateOptions as bF, type PublicUpsertArgs as bG, type PublicUpsertOptions as bH, type ReadQueryInput as bI, type RelatedAuthorization as bJ, type Request as bK, type RequestSchemaAdapter as bL, type RequestSchemaFailure as bM, type RequestSchemaIssue as bN, type RequestSchemaLike as bO, type RequestSchemaOptions as bP, type RequestSchemaResult as bQ, type RequestSchemaSuccess as bR, type RequestSchemaValidator as bS, type RequestSchemas as bT, type RootDataListQueryEntry as bU, type RootDataOperation as bV, type RootDataReadByFilterQueryEntry as bW, type RootDataReadByIdQueryEntry as bX, type RootModelCountQueryEntry as bY, type RootModelCreateQueryEntry as bZ, type RootModelDeleteQueryEntry as b_, type OutputAuthorization as ba, type OutputFieldOptions as bb, type OutputFieldPath as bc, type OutputPlanningOptions as bd, PERMISSIONS as be, PERMISSION_KEYS as bf, type PairedRouteAccess as bg, type ParentRef as bh, type PathValue as bi, type PermissionSchema as bj, type Populate as bk, type PopulateAccess as bl, type PopulatePlanningOptions as bm, type PrepareAccess as bn, type Projection as bo, type PublicCreateArgs as bp, type PublicCreateOptions as bq, type PublicErrorResult as br, type PublicListArgs as bs, type PublicListOptions as bt, type PublicListResult as bu, type PublicOutput as bv, type PublicReadArgs as bw, type PublicReadOptions as bx, type PublicServiceResult as by, type PublicSingleResult as bz, type AccessRouterRequest as c, type SubdocumentParentArgs as c$, type RootModelListQueryEntry as c0, type RootModelNewQueryEntry as c1, type RootModelOperation as c2, type RootModelReadByFilterQueryEntry as c3, type RootModelReadByIdQueryEntry as c4, type RootModelSubBulkUpdateQueryEntry as c5, type RootModelSubCreateQueryEntry as c6, type RootModelSubDeleteQueryEntry as c7, type RootModelSubListQueryEntry as c8, type RootModelSubReadQueryEntry as c9, type StandardSchemaPathSegment as cA, type StandardSchemaResult as cB, type StandardSchemaSuccess as cC, type StandardSchemaV1 as cD, StatusCodes as cE, type SubListBody as cF, type SubOperationAccess as cG, type SubPopulate as cH, type SubQueryEntry as cI, type SubReadBody as cJ, type SubRouteGuardOptions as cK, type SubdocumentBulkRecord as cL, type SubdocumentBulkUpdateInput as cM, type SubdocumentCreateAuthorization as cN, type SubdocumentCreateInput as cO, type SubdocumentCreateOptions as cP, type SubdocumentCreateVisibilityAuthorization as cQ, type SubdocumentDeleteAuthorization as cR, type SubdocumentDeleteOptions as cS, type SubdocumentGateAuthorization as cT, type SubdocumentId as cU, type SubdocumentInputAuthorization as cV, type SubdocumentListOptions as cW, type SubdocumentModel as cX, type SubdocumentMutationAuthorization as cY, type SubdocumentName as cZ, type SubdocumentOutputAuthorization as c_, type RootModelSubUpdateQueryEntry as ca, type RootModelUpdateQueryEntry as cb, type RootModelUpsertQueryEntry as cc, type RootOperationResult as cd, type RootQueryEntry as ce, type RootRouterOptions as cf, type RootSubOperation as cg, type RootTarget as ch, type RouteBaseAccess as ci, type RouteGuardAccess as cj, type RouteVariant as ck, type RouteVariantAccess as cl, type RowAuthorization as cm, type SelectAccess as cn, type SelectedPopulatedPublicOutput as co, type SelectedPublicOutput as cp, type ServiceAuthorization as cq, type ServiceOutputContext as cr, type ServiceOutputDecorator as cs, type ServiceResult as ct, type SingleResult as cu, type Sort as cv, type SortOrder as cw, type StandardSchemaFailure as cx, type StandardSchemaInferOutput as cy, type StandardSchemaIssue as cz, type AccessRouterRequestExtensions as d, type OpenApiResponses as d$, type SubdocumentParentOptions as d0, type SubdocumentReadAuthorization as d1, type SubdocumentReadOptions as d2, type SubdocumentRecord as d3, type SubdocumentUpdateOptions as d4, type SubdocumentVirtuals as d5, type SubdocumentVisibilityAuthorization as d6, type SuperstructFailureLike as d7, type SuperstructValidateLike as d8, type Task as d9, type YupValidationErrorLike as dA, defineRequestSchema as dB, fromAjv as dC, fromArkType as dD, fromIoTs as dE, fromJoi as dF, fromStandardSchema as dG, fromSuperstruct as dH, fromValibot as dI, fromVine as dJ, fromYup as dK, fromZod as dL, parseBody as dM, parseBodyWithSchema as dN, parseNestedBodyWithSchema as dO, parsePathParam as dP, parseQuery as dQ, AccessRuntime as dR, DataService as dS, Service as dT, PublicService as dU, type OpenApiRouterOptions as dV, type OpenApiRegistryOptions as dW, type OpenApiRouteDescriptor as dX, type OpenApiDocumentOptions as dY, type OpenApiParameter as dZ, type OpenApiSchema as d_, type TaskType as da, type TransformAccess as db, type TypedFilter as dc, type UpdateByIdArgs as dd, type UpdateByIdOptions as de, type UpdateOneArgs as df, type UpdateOneOptions as dg, type UpdateQueryInput as dh, type UpsertArgs as di, type UpsertOptions as dj, type UpsertQueryInput as dk, type ValibotIssueLike as dl, type ValibotPathItemLike as dm, type ValibotSafeParseLike as dn, type ValibotSafeParseResult as dp, type ValidateAccess as dq, type ValidateRule as dr, type Validation as ds, type ValidationError as dt, type VineValidationErrorLike as du, type VineValidationMessageLike as dv, type VineValidatorLike as dw, type VirtualSubModel as dx, type WithVirtuals as dy, type YupSchemaLike as dz, type AdvancedCreateBody as e, type AccessRouterPermissionMap as e0, type AccessRouterPermissions as e1, type OpenApiMethod as e2, type Permissions as e3, defaultRuntime as e4, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type AllowedOutputFieldOptions as o, type ArkTypeErrorsLike as p, type ArkTypeLike as q, type ArkTypeProblemLike as r, type AuthorizedListResult as s, type AuthorizedSingleResult as t, Codes as u, type CorrelatedCountInclude as v, type CorrelatedFilter as w, type CorrelatedInclude as x, type CorrelatedIncludeArgs as y, type CorrelatedListInclude as z };