@web-ts-toolkit/access-router 0.47.1 → 0.49.0

package/{parsers-BidvJUu7.d.mts → parsers-DhUuvj9B.d.mts}

@@ -24,9 +24,128 @@ declare class Permission {
 type Permissions = Permission;
 type AccessRouterPermissions = Permission;
 
-declare class Service<TModel = unknown> extends Base<TModel> {
+declare class RequestConcurrencyScheduler {
+    readonly limit: number;
+    private activeWork;
+    private readonly waiters;
+    constructor(limit: number);
+    map<TInput, TOutput>(items: TInput[], iteratee: (item: TInput, index: number, scheduled: true) => Promise<TOutput>): Promise<TOutput[]>;
+    run<TOutput>(iteratee: (scheduled: true) => Promise<TOutput>): Promise<TOutput>;
+    work<TOutput>(operation: () => TOutput | PromiseLike<TOutput>): Promise<TOutput>;
+}
+/**
+ * Shared hook-orchestration gate for VIRT-03 finalization (VIRT-00A D7).
+ *
+ * Distinct from {@link RequestConcurrencyScheduler.work} (leaf persistence
+ * permits): this gate admits virtual getter bodies only, never persistence
+ * ops. A single gate instance is shared across all rows of a top-level list
+ * so peak active getter work stays at or below the configured limit instead
+ * of multiplying by row count. Callers hold the gate only for the getter body
+ * itself — never while awaiting descendant finalization — so limit-1
+ * configurations complete without deadlock. FIFO admission keeps completion
+ * order independent of input order; the surrounding row map preserves stable
+ * index-keyed output association regardless of completion order.
+ */
+declare class SharedHookGate {
+    readonly limit: number;
+    private active;
+    private readonly waiters;
+    constructor(limit: number);
+    run<TOutput>(operation: () => TOutput | PromiseLike<TOutput>): Promise<TOutput>;
+}
+
+/** Internal effective data policy, including trusted custom accesses; virtual configuration keys stay narrow. */
+type VirtualProjectionAccess = 'list' | 'create' | 'read' | 'update' | (string & {});
+type VirtualCandidateAuthState = 'granted' | 'deferred';
+interface VirtualProjectionSnapshot {
+    permissionSchema?: Record<string, unknown> | null;
+    virtuals?: Record<string, unknown> | null;
+    /** Raw `alwaysSelectFields` option: array or per-access record. */
+    alwaysSelectFields?: string[] | Record<string, string[]> | null;
+    modelPermissionPrefix?: string;
+    requireExplicitSelect?: boolean;
+    documentPermissionField?: string;
+}
+interface PlanVirtualCandidate {
+    name: string;
+    descriptor: {
+        get: (...args: never[]) => unknown;
+        dependsOn: string[];
+    };
+    authState: VirtualCandidateAuthState;
+    dependsOn: string[];
+    virtualAccess: VirtualProjectionAccess;
+    outputAccess: VirtualProjectionAccess;
+}
+interface VirtualProjectionPlan {
+    receivingModelName: string;
+    scopePath: string[];
+    virtualAccess: VirtualProjectionAccess;
+    outputAccess: VirtualProjectionAccess;
+    docPermissionsAccess: VirtualProjectionAccess;
+    selectionMode: 'all' | 'include' | 'exclude';
+    /** Normalized effective select (empty = omitted/effectively empty). */
+    effectiveSelectNorm: string[];
+    /** Persisted output eligibility + virtual names eligible for output. */
+    outputSelection: string[];
+    outputPersistedFields: string[];
+    outputVirtualNames: string[];
+    /** Safe Mongoose projection: no virtuals, no `.sub` paths, no `-_id`. */
+    persistedFetchSelection: string[];
+    candidates: PlanVirtualCandidate[];
+    virtualOnlyDeps: string[];
+    internalOnlyFields: string[];
+    depProvenance: Record<string, string[]>;
+    outputIdExcluded: boolean;
+    fetchIdRetained: boolean;
+    internalIdentityFields: string[];
+    internalJoinFields: string[];
+    childPlans: Record<string, VirtualProjectionPlan>;
+    relatedPlans: VirtualProjectionPlan[];
+}
+
+type VirtualFinalizeAccess = VirtualProjectionAccess;
+interface FinalizeSnapshot extends VirtualProjectionSnapshot {
+    documentPermissionField?: string;
+    exposedDocPermissionKeys?: string[] | undefined;
+    stripPermissionsField?: boolean;
+    disableFieldPermissions?: boolean;
+}
+interface FinalizeRelatedTarget {
+    /** Output path in the parent scope (top-level name for v1; dotted supported). */
+    path: string;
+    plan: VirtualProjectionPlan;
+    snapshot: FinalizeSnapshot;
+    virtualAccess: VirtualFinalizeAccess;
+    outputAccess: VirtualFinalizeAccess;
+    docPermissionsAccess: VirtualFinalizeAccess;
+}
+
+/**
+ * VIRT-04 direct-operation virtual wiring (VIRT-00A D1/D6/D7/D8).
+ *
+ * - Access matrix: list `list/list/list`; read/readFilter `read/read/read`
+ *   (read using list fallback becomes `list/list/list` with
+ *   `operation: 'read'` preserved); create/create-branch `create/read/create`;
+ *   update/update-branch `update/read/update`; new template
+ *   `create/create/create` (see `new()` note on ignored `args.select`).
+ * - Effective mutation output selection is carried on the internal plan
+ *   into the shared finalizer before evaluation (explicit select,
+ *   `returningAll: false` implicits, decorator/task selection preserved
+ *   via existing public picks after decorate/tasks). Internal create/update
+ *   args omit `select`; `overrides.effectiveSelect` is the deliberate
+ *   transport (see `interfaces/service-create.ts`, `service-update.ts`).
+ * - Output-only admission runs before validation/persistence; computed
+ *   values are assigned only to output copies (finalizer), never to
+ *   persisted docs/snapshots.
+ * - `maxHookConcurrency` bounds active getter + row-finalization work via
+ *   ONE bounded row map + shared `SharedHookGate` (stable order, limit-1
+ *   completes, no persistence permits held).
+ */
+type VirtualOperationAccess = 'list' | 'create' | 'read' | 'update';
+declare class Service<TModel = unknown, TVirtuals extends object = Record<never, never>> extends Base<TModel, TVirtuals> {
     protected model: any;
-    protected options: ModelRouterOptions<TModel>;
+    protected options: ModelRouterOptions<TModel, TVirtuals>;
     defaults: Defaults<TModel>;
     protected baseFields: string[];
     protected baseFieldsExt: string[];
@@ -38,9 +157,187 @@ declare class Service<TModel = unknown> extends Base<TModel> {
         lean: boolean;
     }): any;
     protected createModelAdapter(modelName: string): any;
-    protected getModelRouterOptions(modelName: string): ModelRouterOptions<TModel>;
+    protected getModelRouterOptions(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
+    /**
+     * Router-level permission output postures (see `ModelRouterOptions`).
+     * Absolute: they win over client input and per-operation `defaults`.
+     */
+    getPermissionsPosture(): {
+        stripPermissionsField: boolean;
+        disableFieldPermissions: boolean;
+    };
+    /**
+     * Router posture `stripPermissionsField`: drop the whole document
+     * permissions field (including the empty placeholder) from output instead
+     * of emitting permission metadata. Returns true when applied.
+     */
+    private stripPermissionsOutput;
     private asServiceHookContext;
     private getEffectiveAllowedSortFields;
+    /**
+     * With `requireExplicitSelect`, an omitted client select behaves as an
+     * `_id`-only projection, yielding field-less rows. Explicit selects pass
+     * through untouched.
+     */
+    protected resolveEffectiveSelect(select: Projection | undefined): Projection | undefined;
+    /**
+     * Capture a coherent virtual snapshot for an operation (VIRT-00A D1/D2,
+     * VIRT-01 copy-on-write). Planner and finalizer use this same object for
+     * the operation so in-flight descriptor replacement cannot mix versions.
+     * Public for VIRT-06 subdocument routes (same coherence per sub op).
+     */
+    captureVirtualSnapshot(): FinalizeSnapshot;
+    getVirtualGlobalPermissions(): {
+        has: (key: string) => boolean;
+        hasKey: (key: string) => boolean;
+    };
+    getVirtualHookConcurrencyLimit(): number;
+    buildVirtualPlan(args: {
+        snapshot: FinalizeSnapshot;
+        virtualAccess: VirtualOperationAccess;
+        outputAccess: VirtualOperationAccess;
+        docPermissionsAccess: VirtualOperationAccess;
+        requestedSelect?: Projection;
+        effectiveSelect?: Projection;
+        internalFetch?: {
+            baseFields?: string[];
+            joinFields?: string[];
+            identityFields?: string[];
+            extraPersistedFields?: string[];
+            trustedOverrideSelect?: Projection;
+        };
+    }): VirtualProjectionPlan;
+    /**
+     * VIRT-06 sub-scope planner.
+     *
+     * Builds a `planVirtualProjection` with `scopePath=[sub,'sub']` for
+     * dedicated subdocument routes (`virtuals.<field>.sub.<name>.<access>`).
+     * `dependsOn` resolves relative to that scope (VIRT-00A D5); literal
+     * `.sub` segments never become DB/response names (planner strips them).
+     * Uses the same coherent `snapshot` captured once per sub op.
+     */
+    buildSubVirtualPlan(sub: string, snapshot: FinalizeSnapshot, virtualAccess: VirtualOperationAccess, outputAccess: VirtualOperationAccess, docPermissionsAccess: VirtualOperationAccess, requestedSelect?: Projection, effectiveSelect?: Projection): VirtualProjectionPlan;
+    /**
+     * VIRT-06 internal accessors for dedicated subdocument routes.
+     * `model-subdocument-service` uses these instead of reaching into
+     * protected `req`/`modelName`/`model`, preserving raw docs for
+     * persistence (never substituting trimmed DTOs) and keeping request
+     * ownership inside `Service`.
+     */
+    getServiceRequest(): ModelRequest;
+    getServiceModelName(): string;
+    getServiceMongooseModel(): unknown;
+    /**
+     * VIRT-06 owning-parent internal grants (VIRT-00A D2).
+     *
+     * Dedicated subdocument routes reuse the owning parent's internally
+     * computed `read` grants with scoped `permissionSchema.<field>.sub` rules;
+     * v1 adds NO independent embedded `docPermissions` hook family. `operation`
+     * stays the initiating sub op (`subList`/`subRead`/`subCreate`/`subUpdate`/
+     * `subBulkUpdate`) for logs, while `docPermissionsAccess` is `read`.
+     * Never throws: hook failure yields `{}` (fail-closed downstream).
+     */
+    getSubParentGrants(parentDoc: unknown, operation: string): Promise<Record<string, unknown>>;
+    /**
+     * VIRT-06 bounded sub-row finalization (VIRT-00A D7, VIRT-03 strategy).
+     *
+     * 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.
+     * Uses ONE bounded row map + shared `SharedHookGate` (stable order,
+     * peak ≤ `maxHookConcurrency`, limit-1 completes, no persistence permits
+     * held). Callers must filter rows (existing row/operation filters) BEFORE
+     * calling; hidden rows never reach getters. Never mutates inputs.
+     */
+    finalizeSubRowsWithVirtuals(args: {
+        sub: string;
+        rows: unknown[];
+        plan: VirtualProjectionPlan;
+        snapshot: FinalizeSnapshot;
+        parentGrants: Record<string, unknown>;
+        virtualAccess: VirtualOperationAccess;
+        outputAccess: VirtualOperationAccess;
+        docPermissionsAccess: VirtualOperationAccess;
+        operation: string;
+        related?: FinalizeRelatedTarget[];
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * VIRT-06 single sub-row finalization (same boundary/bounds as list).
+     * Returns `null` when input is nullish (caller maps to `null` for
+     * denied-post-persist single visibility, never a retryable error).
+     */
+    finalizeSingleSubRowWithVirtuals(args: {
+        sub: string;
+        row: unknown;
+        plan: VirtualProjectionPlan;
+        snapshot: FinalizeSnapshot;
+        parentGrants: Record<string, unknown>;
+        virtualAccess: VirtualOperationAccess;
+        outputAccess: VirtualOperationAccess;
+        docPermissionsAccess: VirtualOperationAccess;
+        operation: string;
+        related?: FinalizeRelatedTarget[];
+    }): Promise<Record<string, unknown> | null>;
+    /**
+     * VIRT-06 populate finalization for sub parents (VIRT-05 path).
+     *
+     * After Mongoose `populate` resolves on the raw parent (e.g.
+     * `contacts.friend` via `genSubPopulate`), finalize each actual target
+     * with its own plan/context before sub getters. Handles null/scalar/array
+     * + dotted through embedded arrays; trims even without virtuals. Bounded
+     * via shared gate; limit-1 completes. No-op when no entries.
+     */
+    finalizePopulateForSubParent(parentDoc: unknown, populateEntries: Populate[], parentOperation: string, hookLimit?: number, sharedGate?: SharedHookGate): Promise<void>;
+    /**
+     * Output-only write admission (VIRT-04 requirement 4). Excludes registered
+     * virtual names for any access (including bare `true` rules and inactive
+     * descriptors) and sanitizes registered embedded virtual keys inside
+     * whole-object/array grants. Trusted prepare/transform authority is
+     * preserved (this runs on client data before validation only); computed
+     * values are assigned only to output copies by the finalizer.
+     */
+    private admitWriteDataForVirtuals;
+    private filterAllowedFieldsForVirtuals;
+    private stripVirtualsFromFilterForSnapshot;
+    /**
+     * Preserve the `permissions` Mongoose virtual (from `permissionsPlugin`) for
+     * hydrated outputs. `isolateDocForOutput` uses `toObject({ virtuals: false })`
+     * so Mongoose getter virtuals never leak into package-virtual planning;
+     * `lean: true` therefore drops them (explicit parity rule). For `lean: false`
+     * (hydrated Mongoose documents) the historical contract exposes
+     * `doc.permissions` as an alias of the document-permission field. The shared
+     * finalizer keeps only the document-permission field, so restore the alias
+     * here for backward compatibility when the input was hydrated and the
+     * virtual existed. Lean outputs stay without the virtual. Models without
+     * the plugin never had the virtual and stay unchanged.
+     */
+    private preservePermissionsVirtual;
+    /**
+     * VIRT-05 populate + association helpers.
+     *
+     * - Populate targets finalize with their own plan/context before parent
+     *   getters (target trimming even without virtuals). Handles null, scalar
+     *   IDs when population is skipped, arrays, and dotted paths through
+     *   embedded arrays (e.g. `contacts.friend`). One evaluation per logical
+     *   target output, no in-place mutation of shared/cached instances (targets
+     *   are replaced, never mutated; parents are fresh per-query docs, consistent
+     *   with `includeDocs` in-place attachment), isolated copies per parent,
+     *   bounded via the shared `SharedHookGate` + `mapWithConcurrencyLimit`
+     *   (no unbounded fan-out, limit-1 completes, no persistence permits held).
+     * - Association transport stays service-only (symbols, outside serializers
+     *   and finalized output input): `find` fetches `foreignField` fetch-only,
+     *   captures immutable values before trim, and returns them aligned to rows.
+     */
+    private getAssociationFieldFromOptions;
+    private buildDbSelectForAssociation;
+    private captureAssociationValues;
+    private captureTargetSnapshotForPopulate;
+    private resolvePopulateMeta;
+    private isScalarPopulateValue;
+    private finalizeSinglePopulateTarget;
+    private finalizePopulatePath;
+    private finalizePopulateForSingleDoc;
     private beginOp;
     private completeOp;
     constructor(req: ModelRequest, modelName: string);
@@ -54,6 +351,7 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     }): Promise<SingleResult<TModel>>;
     /**
      * Update at authorized policy paths: admitted leaves preserve omitted siblings;
@@ -143,43 +441,52 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     getParentDoc(id: SubdocumentId, sub: SubdocumentName, args?: SubdocumentParentArgs, options?: SubdocumentParentOptions): Promise<any>;
 }
 
-declare class PublicService<TModel = unknown> extends Service<TModel> {
+declare class PublicService<TModel = unknown, TVirtuals extends object = Record<never, never>> extends Service<TModel, TVirtuals> {
     _list<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(filter: Filter<TModel>, args?: Omit<PublicListArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
-    }, options?: PublicListOptions): Promise<ListResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicListOptions): Promise<ListResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     _create<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(data: unknown, args?: Omit<PublicCreateArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
-    }, options?: PublicCreateOptions): Promise<ListResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicCreateOptions): Promise<ListResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     _new(args?: {
         select?: string[];
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
-    }): Promise<SingleResult<PublicOutput<TModel>>>;
+        includeFieldPermissions?: boolean;
+    }): Promise<SingleResult<PublicOutput<TModel, TVirtuals>>>;
     _read<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(id: string, args?: Omit<PublicReadArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
-    }, options?: PublicReadOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicReadOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     _readFilter<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(filter: Filter<TModel>, args?: Omit<PublicReadArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
         sort?: Sort;
-    }, options?: PublicReadOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicReadOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     _update<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(id: string, data: Record<string, unknown>, args?: Omit<PublicUpdateArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
-    }, options?: PublicUpdateOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicUpdateOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     /**
      * With an _id, check update-policy existence then update: terminal denial returns
      * Forbidden, an allowed miss remains Unauthorized, and neither creates a row.
      * Without an _id, use the create path.
+     *
+     * VIRT-04 D1/D6: both branches keep `operation: 'upsert'` while accesses
+     * follow the taken branch (update/read/update vs create/read/create).
+     * Effective selection is carried via internal `overrides.effectiveSelect`
+     * before evaluation; presentation picks after decorate/tasks are preserved.
+     * Internal `updateById`/`create` are called directly (not via `_update`/
+     * `_create`) so the initiating operation is not overwritten with the
+     * branch name.
      */
     _upsert<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(data: Record<string, unknown>, args?: Omit<PublicUpsertArgs, 'select' | 'populate'> & {
         select?: TSelect;
         populate?: TPopulate;
-    }, options?: PublicUpsertOptions): Promise<ServiceResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | ErrorResult>;
+    }, options?: PublicUpsertOptions): Promise<ServiceResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate, TVirtuals>> | ErrorResult>;
     _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>;
@@ -398,22 +705,28 @@ type ListQueryInput = {
     page_size?: string;
     skim?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     include_count?: 'true' | 'false';
     include_extra_headers?: 'true' | 'false';
 };
 type CreateQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type ReadQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     try_list?: 'true' | 'false';
 };
 type UpdateQueryInput = {
     returning_all?: 'true' | 'false';
+    include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type UpsertQueryInput = {
     returning_all?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type AdvancedListBody = {
     filter?: Filter | unknown[];
@@ -429,9 +742,10 @@ type AdvancedListBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         includeCount?: boolean;
         includeExtraHeaders?: boolean;
-        populateAccess?: unknown;
+        populateAccess?: PopulateAccess;
     };
 };
 type CountBody = {
@@ -447,8 +761,9 @@ type AdvancedReadFilterBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
-        populateAccess?: unknown;
+        populateAccess?: PopulateAccess;
     };
 };
 type AdvancedReadBody = {
@@ -459,8 +774,9 @@ type AdvancedReadBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
-        populateAccess?: unknown;
+        populateAccess?: PopulateAccess;
     };
 };
 type AdvancedCreateBody = {
@@ -470,7 +786,8 @@ type AdvancedCreateBody = {
     tasks?: Task | Task[];
     options?: {
         includePermissions?: boolean;
-        populateAccess?: unknown;
+        includeFieldPermissions?: boolean;
+        populateAccess?: PopulateAccess;
     };
 };
 type AdvancedUpdateBody = {
@@ -481,7 +798,8 @@ type AdvancedUpdateBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
-        populateAccess?: unknown;
+        includeFieldPermissions?: boolean;
+        populateAccess?: PopulateAccess;
     };
 };
 type AdvancedUpsertBody = {
@@ -492,7 +810,8 @@ type AdvancedUpsertBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
-        populateAccess?: unknown;
+        includeFieldPermissions?: boolean;
+        populateAccess?: PopulateAccess;
     };
 };
 type DistinctBody = {
@@ -524,6 +843,23 @@ interface RequestComplexityOptions {
      * Not a process-wide connection limit or protection against competing edits.
      */
     maxBulkConcurrency?: number;
+    /**
+     * Defaults to 10. Per-request/per-runtime ceiling on concurrently awaited
+     * virtual-getter + row-finalization orchestration work (VIRT-00A D7), NOT a
+     * per-row multiplier and NOT leaf persistence admission. Top-level lists
+     * finalize rows through ONE bounded map with a shared hook gate held only
+     * for getter bodies (stable index-keyed order regardless of completion
+     * order), so peak active getter work stays at or below this limit — never
+     * `rows × getters`. Nested include/populate/embedded work uses bounded
+     * child maps with a finite bound derived from the same limit; recursion
+     * depth is additionally bounded by `maxCorrelatedDepth` and the correlated
+     * budgets. Recursive orchestration never holds leaf persistence permits
+     * (`RequestConcurrencyScheduler.work`, which admits only leaf
+     * adapter/document persistence ops) while awaiting descendants or hooks,
+     * so limit-1 configurations complete. Trusted direct DB/network I/O issued
+     * by virtual getters themselves runs outside the leaf persistence ceiling
+     * (no dataloader/batching in v1). Not a process-wide connection limit.
+     */
     maxHookConcurrency?: number;
     /** Cumulative correlated target executions per request/runtime (default 100); permit release does not refund this budget. */
     maxCorrelatedQueries?: number;
@@ -698,21 +1034,49 @@ declare class AccessRuntime {
     getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
     private createModelOptions;
     private getOrCreateModelOptions;
-    setModelOptions<TModel = unknown>(modelName: string, options: ModelRouterOptions<TModel>): void;
-    setModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel>[K]): void;
-    getModelOptions<TModel = unknown>(modelName: string): ModelRouterOptions<TModel>;
-    getModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K | string, defaultValue?: ExtendedModelRouterOptions<TModel>[K]): ExtendedModelRouterOptions<TModel>[K];
-    getExactModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K | string): ExtendedModelRouterOptions<TModel>[K];
+    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;
+    getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
+    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];
+    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 DataRouterOptions<TData>, TData = unknown>(dataName: string, key: K, value: DataRouterOptions<TData>[K]): 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>;
     getDataSnapshot<TData = unknown>(dataName: string): readonly TData[];
-    getDataOption<K extends keyof DataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string, defaultValue?: DataRouterOptions<TData>[K]): DataRouterOptions<TData>[K];
+    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;
@@ -722,22 +1086,12 @@ declare class AccessRuntime {
 }
 declare const defaultRuntime: AccessRuntime;
 
-declare class RequestConcurrencyScheduler {
-    readonly limit: number;
-    private activeWork;
-    private readonly waiters;
-    constructor(limit: number);
-    map<TInput, TOutput>(items: TInput[], iteratee: (item: TInput, index: number, scheduled: true) => Promise<TOutput>): Promise<TOutput[]>;
-    run<TOutput>(iteratee: (scheduled: true) => Promise<TOutput>): Promise<TOutput>;
-    work<TOutput>(operation: () => TOutput | PromiseLike<TOutput>): Promise<TOutput>;
-}
-
 type CrossResourceModelOperation = 'list' | 'read' | 'count';
 interface CorrelatedExecState {
     totalQueries: number;
     scheduler: RequestConcurrencyScheduler;
 }
-declare class Base<TModel = unknown> {
+declare class Base<TModel = unknown, TVirtuals extends object = Record<never, never>> {
     protected req: ModelRequest;
     protected modelName: string;
     protected readonly requestRuntime: AccessRuntime;
@@ -772,7 +1126,7 @@ declare class Base<TModel = unknown> {
     getRequestComplexity(): Required<RequestComplexityOptions>;
     protected getClientRequestErrorResult(error: unknown): ErrorResult | null;
     protected throwClientRequestError(code: ErrorResult['code'], detail: string): never;
-    protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation): Promise<PublicService<unknown>>;
+    protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation): Promise<PublicService<unknown, Record<never, never>>>;
     protected processInclude(include: Include | Include[]): {
         includes: LegacyInclude[];
         correlatedIncludes: CorrelatedInclude[];
@@ -781,6 +1135,17 @@ declare class Base<TModel = unknown> {
         correlatedReferenceFields: string[];
     };
     private validateIncludeOutputPath;
+    /**
+     * VIRT-05 preflight: request include output paths vs registered virtual
+     * paths with ancestor/descendant checks per receiving scope, before any
+     * target dispatch. Registered virtual names remain virtual even when no
+     * getter applies; an include that would overwrite a virtual (equal,
+     * ancestor, or descendant, including bracket equivalents) fails closed
+     * with `BadRequest`. Ordinary non-virtual collisions stay permitted and
+     * existing permission-metadata protections above are preserved.
+     */
+    private collectVirtualDbPathsForPreflight;
+    private validateIncludeVirtualCollision;
     private assertIncludeOutputPaths;
     private getForeignKeyValues;
     private getForeignKey;
@@ -853,6 +1218,20 @@ declare class Core {
     beforeDelete<T>(modelName: string, doc: T, context: ModelHookContext): Promise<void>;
     afterDelete<T>(modelName: string, doc: T, context: ModelHookContext): Promise<void>;
     genDocPermissions(modelName: string, doc: unknown, access: DocPermissionsAccess, context: ModelHookContext): Promise<{}>;
+    /**
+     * VIRT-03 internal grant resolution (VIRT-00A D1/D2).
+     *
+     * Returns full internal document grants for virtual authorization without
+     * consulting response-metadata switches (`includePermissions`,
+     * `includeFieldPermissions`, `skim`, `stripPermissionsField`,
+     * `exposedDocPermissionKeys`, `disableFieldPermissions`): those switches
+     * affect serialization at the caller boundary only, never authorization
+     * inputs. When `supplied` is a plain object it is reused as-is (no second
+     * hook invocation for the same output-stage access); otherwise the correct
+     * `docPermissionsAccess` hook runs once. The result populates scope-aware
+     * `context.docPermissions` (full grants, distinct from serialized metadata).
+     */
+    resolveFinalizerDocPermissions(modelName: string, doc: unknown, access: DocPermissionsAccess, context: ModelHookContext, supplied?: unknown): Promise<Record<string, unknown>>;
     addEmptyPermissions<T>(modelName: string, doc: T): T;
     addDocPermissions<T>(modelName: string, doc: T, access: DocPermissionsAccess, context: ModelHookContext): Promise<T>;
     addFieldPermissions<T extends {
@@ -865,10 +1244,12 @@ declare class Core {
     setPermissions(): Promise<void>;
     canActivate(routeGuard: Validation): Promise<boolean>;
     isAllowed(modelName: string, access: RouteGuardAccess | string): Promise<boolean>;
-    getService<TModel = unknown>(modelName: string): Service<TModel>;
-    getPublicService<TModel = unknown>(modelName: string): PublicService<TModel>;
-    service<TModel = unknown>(modelName: string): PublicService<TModel>;
-    svc<TModel = unknown>(modelName: string): PublicService<TModel>;
+    /** Authorize route entry using explicit server-owned basic/advanced metadata. */
+    isAllowedRoute(modelName: string, baseAccess: RouteGuardAccess | string, variant: RouteVariant): Promise<boolean>;
+    getService<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): Service<TModel, TVirtuals>;
+    getPublicService<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): PublicService<TModel, TVirtuals>;
+    service<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): PublicService<TModel, TVirtuals>;
+    svc<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): PublicService<TModel, TVirtuals>;
     private getGlobalPermissions;
 }
 
@@ -888,6 +1269,8 @@ declare class DataCore {
     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>;
@@ -948,10 +1331,37 @@ interface PublicCreateArgs {
     tasks?: Task | Task[];
 }
 interface CreateArgs extends Omit<PublicCreateArgs, 'select' | 'tasks'> {
+    overrides?: {
+        populate?: Populate[] | string;
+        /**
+         * VIRT-04 internal plan transport (VIRT-00A D6).
+         * Effective mutation output selection carried into internal finalization
+         * before virtual evaluation. Internal create args omit `select` publicly;
+         * this trusted transport supplies the effective selection (explicit
+         * `select` or `undefined` for all) without changing public presentation
+         * (public `_create` still picks after decorate/tasks).
+         */
+        effectiveSelect?: Projection;
+        /**
+         * VIRT-04 initiating operation (VIRT-00A D1). Upsert branches keep
+         * `operation: 'upsert'` while virtual/output/doc accesses follow the
+         * taken branch. Defaults to `'create'` when absent.
+         */
+        operation?: string;
+    };
 }
 interface PublicCreateOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface CreateOptions extends PublicCreateOptions {
@@ -971,6 +1381,15 @@ interface PublicListArgs {
 interface PublicListOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -987,6 +1406,15 @@ interface PublicReadOptions {
     populateAccess?: PopulateAccess;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     /** Retry an authorized read miss with list access (default true); requires list operation access. Forbidden/BadRequest never retry. */
     tryList?: boolean;
 }
@@ -1003,13 +1431,34 @@ interface UpdateOneArgs<T = unknown> extends Omit<PublicUpdateArgs, 'select' | '
         /** Trusted replacement: nullish generates row policy; false returns Forbidden without filter generation or persistence. */
         filter?: Filter<T>;
         populate?: Populate[] | string;
+        /**
+         * VIRT-04 internal plan transport (VIRT-00A D6).
+         * Effective mutation output selection carried into internal finalization
+         * before virtual evaluation (explicit `select`, `returningAll: false`
+         * implicit `Object.keys(data)+_id`, or `undefined` for all). Public
+         * `_update` still enforces presentation pick after decorate/tasks.
+         */
+        effectiveSelect?: Projection;
+        /**
+         * VIRT-04 initiating operation (VIRT-00A D1). Upsert branches keep
+         * `operation: 'upsert'` while accesses follow the taken branch.
+         * Defaults to `'update'` when absent.
+         */
+        operation?: string;
     };
 }
-interface UpdateByIdArgs<T = unknown> extends Omit<UpdateOneArgs<T>, 'overrides'> {
+interface UpdateByIdArgs<T = unknown> extends Omit<PublicUpdateArgs, 'select' | 'tasks'> {
     overrides?: {
         populate?: Populate[] | string;
         /** Nullish resolves the identifier; false denies without ID/filter generation or persistence. Objects still receive row policy. */
         idFilter?: Filter<T>;
+        /**
+         * VIRT-04 internal plan transport (VIRT-00A D6): effective output
+         * selection for virtual planning before decorate/tasks.
+         */
+        effectiveSelect?: Projection;
+        /** VIRT-04 initiating operation (VIRT-00A D1); defaults to `'update'`. */
+        operation?: string;
     };
 }
 interface UpsertArgs<T = unknown> extends UpdateOneArgs<T> {
@@ -1018,6 +1467,15 @@ interface PublicUpdateOptions {
     skim?: boolean;
     returningAll?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface PublicUpsertOptions extends PublicUpdateOptions {
@@ -1067,7 +1525,13 @@ type WithDefaultId<T> = T extends object ? T & {
 } : {
     _id?: unknown;
 };
-type PublicOutput<T> = T extends object ? T & Record<string, unknown> : Record<string, unknown>;
+/**
+ * Public output with optional computed virtual shape (VIRT-01, VIRT-00A D3).
+ * Virtual names are NEVER added to persisted `Filter`, sort/distinct inputs,
+ * or client write types — only selected output shape gains optional virtuals.
+ */
+type WithVirtuals<TModel, TVirtuals extends object = Record<never, never>> = TModel & Partial<TVirtuals>;
+type PublicOutput<T, TVirtuals extends object = Record<never, never>> = WithVirtuals<T, TVirtuals> extends object ? WithVirtuals<T, TVirtuals> & Record<string, unknown> : Record<string, unknown>;
 type ModelDocument<TModel = unknown> = mongoose.Document & TModel;
 type TrimLeft<S extends string> = S extends ` ${infer Rest}` ? TrimLeft<Rest> : S;
 type TrimRight<S extends string> = S extends `${infer Rest} ` ? TrimRight<Rest> : S;
@@ -1085,7 +1549,12 @@ type DeepPickSingle<T, TPath extends string> = TPath extends `${infer Head}.${in
     [K in Head]: WithDefaultId<T>[K] extends readonly (infer U)[] ? Array<Simplify<DeepPickSingle<U, Tail>>> : WithDefaultId<T>[K] extends object ? Simplify<DeepPickSingle<WithDefaultId<T>[K], Tail>> : WithDefaultId<T>[K];
 } : {} : {} : TPath extends keyof WithDefaultId<T> ? Pick<WithDefaultId<T>, TPath> : {};
 type DeepPick<T, TPaths extends string> = Simplify<UnionToIntersection<DeepPickSingle<T, TPaths>>>;
-type SelectedPublicOutput<T, TProjection> = string extends PositiveProjectionPaths<TProjection> ? PublicOutput<T> : [PositiveProjectionPaths<TProjection>] extends [never] ? PublicOutput<T> : DeepPick<T, Extract<PositiveProjectionPaths<TProjection>, string>>;
+/**
+ * Literal-select output with optional virtuals (VIRT-01, VIRT-00A D3).
+ * Virtual outputs stay optional (`Partial`) because authorization, absent
+ * dependencies, `undefined`, and fail-closed errors can omit them.
+ */
+type SelectedPublicOutput<T, TProjection, TVirtuals extends object = Record<never, never>> = string extends PositiveProjectionPaths<TProjection> ? PublicOutput<T, TVirtuals> : [PositiveProjectionPaths<TProjection>] extends [never] ? PublicOutput<T, TVirtuals> : DeepPick<WithVirtuals<T, TVirtuals>, Extract<PositiveProjectionPaths<TProjection>, string>>;
 type PopulateInput = Populate | string;
 type PopulateInputs<TPopulate> = TPopulate extends readonly (infer U)[] ? U : TPopulate;
 type PopulatePath<TPopulateEntry> = TPopulateEntry extends string ? TPopulateEntry : TPopulateEntry extends {
@@ -1102,7 +1571,7 @@ type PopulateEntryShape<T, TPath extends string, TValue> = TPath extends `${infe
 }, TPath> : {};
 type PopulateOutputShape<T, TPopulateEntry> = PopulatePath<TPopulateEntry> extends infer TPath extends string ? PopulateEntryShape<T, TPath, PopulateLeafValue<PathValue<WithDefaultId<T>, TPath>, TPopulateEntry>> : {};
 type PopulateOutput<T, TPopulate> = string extends PopulatePath<PopulateInputs<TPopulate>> ? {} : [PopulatePath<PopulateInputs<TPopulate>>] extends [never] ? {} : Simplify<UnionToIntersection<PopulateOutputShape<T, Extract<PopulateInputs<TPopulate>, PopulateInput>>>>;
-type SelectedPopulatedPublicOutput<T, TProjection, TPopulate> = Simplify<SelectedPublicOutput<T, TProjection> & PopulateOutput<T, TPopulate>>;
+type SelectedPopulatedPublicOutput<T, TProjection, TPopulate, TVirtuals extends object = Record<never, never>> = Simplify<SelectedPublicOutput<T, TProjection, TVirtuals> & PopulateOutput<T, TPopulate>>;
 type Unwrap<T> = NonNullable<Descend<T>>;
 type DeepFieldPath<T, Depth extends number = 4> = [Depth] extends [never] ? never : Unwrap<T> extends NonTraversable ? never : {
     [K in Extract<keyof Unwrap<T>, string>]: K | (NonNullable<Unwrap<T>[K]> extends NonTraversable ? never : NonNullable<Unwrap<T>[K]> extends readonly (infer U)[] ? Unwrap<U> extends NonTraversable ? never : `${K}.${DeepFieldPath<U, PrevDepth[Depth]>}` : NonNullable<Unwrap<T>[K]> extends object ? `${K}.${DeepFieldPath<NonNullable<Unwrap<T>[K]>, PrevDepth[Depth]>}` : never);
@@ -1233,7 +1702,16 @@ interface SubPopulate {
 type GuardHook<TRequest extends AccessRouterRequest = AccessRouterRequest> = (this: TRequest, permissions: AccessRouterPermissions) => boolean | Promise<boolean>;
 type Validation = boolean | string | string[] | GuardHook;
 type SelectAccess = 'list' | 'create' | 'read' | 'update' | string;
-type RouteGuardAccess = 'new' | 'list' | 'read' | 'update' | 'upsert' | 'delete' | 'create' | 'distinct' | 'count' | 'subs' | string;
+/** Base operations with both basic and advanced generated model routes. */
+type PairedRouteAccess = 'list' | 'read' | 'create' | 'update' | 'upsert' | 'count' | 'distinct';
+/** Existing base route guards, including unpaired operations and subdocument access. */
+type RouteBaseAccess = PairedRouteAccess | 'new' | 'delete' | 'subs';
+/** Server-owned transport variant for a paired generated route. */
+type RouteVariant = 'basic' | 'advanced';
+/** The fourteen route-only keys, or the two keys for a specified paired base operation. */
+type RouteVariantAccess<TAccess extends PairedRouteAccess = PairedRouteAccess> = `${RouteVariant}${Capitalize<TAccess>}`;
+/** Known route guards with the existing trusted custom access-string compatibility. */
+type RouteGuardAccess = RouteBaseAccess | RouteVariantAccess | (string & {});
 type DocPermissionsAccess = 'list' | 'create' | 'read' | 'update' | string;
 type BaseFilterAccess = 'list' | 'read' | 'update' | 'delete' | string;
 type DecorateAccess = 'list' | 'create' | 'read' | 'update' | string;
@@ -1302,6 +1780,7 @@ interface RootModelNewQueryEntry extends RootQueryEntryBase<'model', 'new'> {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     };
 }
 interface RootModelListQueryEntry extends RootQueryEntryBase<'model', 'list'> {
@@ -1431,7 +1910,7 @@ interface Task {
     options?: Record<string, unknown>;
 }
 interface AccessRouterBaseRequest extends AccessRouterRequest {
-    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
+    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_field_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
 }
 interface ModelRequest extends AccessRouterBaseRequest {
     macl: Core;
@@ -1522,6 +2001,15 @@ interface FindArgs<T = unknown> {
 interface FindOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -1544,6 +2032,15 @@ interface FindOneOptions {
     skim?: boolean;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
 }
 interface FindByIdArgs<T = unknown> {
     select?: Projection;
@@ -1597,6 +2094,161 @@ type ModelHook<TValue = unknown> = HookChain<TValue, ModelHookContext, ModelRequ
 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>;
+        }>;
+    };
+};
 
 interface DefaultFindOneArgs<TModel = unknown> extends Omit<FindOneArgs<TModel>, 'overrides'> {
 }
@@ -1609,7 +2261,33 @@ type NestedRequestSchema = {
     default?: RequestSchema;
     data?: RequestSchema;
 };
-type SubRouteGuardOptions = Record<string, Validation | Record<string, Validation>>;
+/**
+ * One field's subdocument route guards: exact variant → field base → field scalar
+ * or closed object. Only an absent field rule falls back to top-level variant/base
+ * guards. A defined object with no applicable key denies; nested `.default` is not
+ * a fallback. Dynamic legacy operation names remain supported.
+ */
+interface SubOperationAccess {
+    /** Base list guard for this field; fallback for both subdocument list variants. */
+    list?: Validation;
+    /** Base read guard for this field; fallback for both subdocument read variants. */
+    read?: Validation;
+    create?: Validation;
+    update?: Validation;
+    delete?: Validation;
+    /** GET /:id/<field>; undefined inherits this field's `list` rule. */
+    basicList?: Validation;
+    /** POST /:id/<field>/__query; undefined inherits this field's `list` rule. */
+    advancedList?: Validation;
+    /** GET /:id/<field>/:subId (and HEAD); undefined inherits this field's `read` rule. */
+    basicRead?: Validation;
+    /** POST /:id/<field>/:subId/__query; undefined inherits this field's `read` rule. */
+    advancedRead?: Validation;
+    [access: string]: Validation | undefined;
+}
+/** Per-field subdocument route objects or scalar guards; field names remain dynamic. */
+type SubRouteGuardOptions = Record<string, Validation | SubOperationAccess>;
+type SubFieldPermissionOptions = Record<string, Validation | Record<string, Validation>>;
 interface RequestSchemas {
     create?: RequestSchema;
     update?: RequestSchema;
@@ -1678,25 +2356,93 @@ interface GlobalOptions {
 }
 interface RootRouterOptions {
     basePath: string;
+    /** Guard for the batch endpoint. Entries use target base operations, never basic/advanced variant names. */
     operationAccess?: Validation;
     maxBatchEntries?: number;
     maxOrderGroups?: number;
     /** Whole root operations per order group; separate from requestComplexity.maxBulkConcurrency persistence admission. */
     maxConcurrentOperations?: number;
 }
-interface OperationAccess {
+/** Base-operation field grants used by PermissionSchema. Basic/advanced route keys do not grant fields. */
+interface FieldOperationAccess {
+    new?: Validation;
+    list?: Validation;
+    create?: Validation;
+    read?: Validation;
+    update?: Validation;
+    upsert?: Validation;
+    delete?: Validation;
+    distinct?: Validation;
+    count?: Validation;
+    subs?: Validation | SubFieldPermissionOptions;
+}
+/**
+ * Live generated-route guards, separate from PermissionSchema field grants.
+ * An exact basic/advanced rule replaces its base guard; only undefined inherits
+ * the base operation's exact → `.default` → scalar-shorthand resolution. Selected
+ * false/empty-array/false-returning guards are terminal, not ANDed with the base.
+ * Model exact lookup includes runtime-default variants; data has no model defaults.
+ * Denial is HTTP 401; routes remain registered in getEndpoints() and OpenAPI.
+ * Field/row/hook, root-entry, related-target and mutation-response policies keep
+ * their existing base operations. Paths below use the default route segments.
+ */
+interface OperationAccess extends Omit<FieldOperationAccess, 'subs'> {
+    /** GET /new guard; unpaired, with no basic/advanced override. */
     new?: Validation;
+    /** Base list guard and fallback for both list routes; also governs model read-to-list retries. */
     list?: Validation;
+    /** Base create guard and fallback for both model create routes. */
     create?: Validation;
+    /** Base read guard and fallback for both read variants; advancedRead covers both POST read routes. */
     read?: Validation;
+    /** Base update guard and fallback for both model update routes. */
     update?: Validation;
+    /** Base upsert guard and fallback for both upserts; create/update route variants do not gate its branches. */
     upsert?: Validation;
+    /** DELETE /:id guard; unpaired, with no basic/advanced override. */
     delete?: Validation;
+    /** Base distinct guard and fallback for GET and POST /distinct/:field. */
     distinct?: Validation;
+    /** Base count guard and fallback for GET and POST /count. */
     count?: Validation;
+    /** Fallback for a base operation without an exact rule; explicit base/variant guards take precedence. */
+    default?: Validation;
+    /** GET / (and HEAD) override for model/data list; undefined inherits `list`. */
+    basicList?: Validation;
+    /** POST /__query override for model/data list; undefined inherits `list`. */
+    advancedList?: Validation;
+    /** GET /:id (and HEAD) override for model/data read; undefined inherits `read`. */
+    basicRead?: Validation;
+    /** POST /__query/:id and /__query/__filter override for model/data read; undefined inherits `read`. */
+    advancedRead?: Validation;
+    /** POST / model create override; undefined inherits `create`. */
+    basicCreate?: Validation;
+    /** POST /__mutation model create override; undefined inherits `create`. */
+    advancedCreate?: Validation;
+    /** PATCH /:id model update override; undefined inherits `update`. */
+    basicUpdate?: Validation;
+    /** PATCH /__mutation/:id model update override; undefined inherits `update`. */
+    advancedUpdate?: Validation;
+    /** PUT / model upsert override; undefined inherits `upsert`. */
+    basicUpsert?: Validation;
+    /** PUT /__mutation model upsert override; undefined inherits `upsert`. */
+    advancedUpsert?: Validation;
+    /** GET /count model count override; undefined inherits `count`. */
+    basicCount?: Validation;
+    /** POST /count model filtered-count override; undefined inherits `count`. */
+    advancedCount?: Validation;
+    /** GET /distinct/:field model distinct override; undefined inherits `distinct`. */
+    basicDistinct?: Validation;
+    /** POST /distinct/:field model filtered-distinct override; undefined inherits `distinct`. */
+    advancedDistinct?: Validation;
+    /**
+     * Per-field scalar or closed-object guards, with list/read variants. Legacy scalar
+     * `subs` is accepted but is not an umbrella guard for absent fields; they use top-level rules.
+     */
     subs?: Validation | SubRouteGuardOptions;
 }
-type PermissionRule = Validation | OperationAccess;
+type PermissionRule = Validation | FieldOperationAccess;
+/** Field grants by base operation. Put basic/advanced route guards in operationAccess, not field-rule objects. */
 type PermissionSchema<TField extends string = string> = Partial<Record<TField, PermissionRule>>;
 interface DocPermissions {
     list?: ModelDocPermissionsHook;
@@ -1714,8 +2460,28 @@ interface DefaultModelRouterOptions<TModel = unknown> {
     parentPath?: string;
     queryRouteSegment?: string;
     mutationRouteSegment?: string;
+    /**
+     * Live model route guards: scalar Validation shorthand or base/variant rules.
+     * `{ list: true, read: true, basicRead: false }` denies only GET /:id (and HEAD)
+     * among top-level routes, retaining both advanced read POSTs subject to ordinary
+     * field/row policy. Subdocument reads follow their field-rule precedence.
+     * Exact runtime-default variants precede base fallback; option objects replace
+     * top-level keys shallowly, rather than recursively merging operationAccess.
+     */
     operationAccess?: Validation | OperationAccess;
     modelPermissionPrefix?: string;
+    /**
+     * When `true`, list/read/update requests without an explicit `select` return
+     * field-less rows (only `_id`, plus the permission field when requested)
+     * instead of all allowed fields. Applies to plain and advanced PATCH
+     * (returned updated record honors `select`, including `?select=` on plain
+     * PATCH and body `select` on advanced PATCH). Only an omitted (`undefined`)
+     * select triggers this; explicit selects — including backend `defaults` and
+     * an explicitly empty string/array (which keep their current meaning) — are
+     * unaffected. Counts, ordering, includes and permission enforcement are
+     * unchanged. Defaults to `false`.
+     */
+    requireExplicitSelect?: boolean;
     /**
      * Extra fields allowed in `sort` regardless of `list`/`read` field policy.
      * Merged as a union with permission-derived allowed fields (`id`/`_id` are
@@ -1729,6 +2495,25 @@ interface DefaultModelRouterOptions<TModel = unknown> {
      * Defaults to `false` (strict: disallowed sort returns `BadRequest`).
      */
     stripDisallowedSort?: boolean;
+    /**
+     * When `true`, the document permissions field (`documentPermissionField`,
+     * default `_permissions`) is removed from all outputs — including its empty
+     * placeholder — and client `includePermissions`/`includeFieldPermissions`
+     * input (query params, body/root-batch options and service-direct options)
+     * as well as per-operation `defaults` are ignored (both resolve to `false`).
+     * Output matches `includePermissions: false` with the permissions field
+     * removed entirely. Enforcement still runs; only output metadata is
+     * affected. Defaults to `false`.
+     */
+    stripPermissionsField?: boolean;
+    /**
+     * When `true`, client `includeFieldPermissions` input (query params,
+     * body/root-batch options and service-direct options) as well as
+     * per-operation `defaults` are ignored and field maps (`_view`/`_edit`)
+     * are never computed. `docPermissions`-hook keys still follow
+     * `includePermissions`. Defaults to `false`.
+     */
+    disableFieldPermissions?: boolean;
 }
 interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
     'operationAccess.default'?: Validation;
@@ -1741,19 +2526,92 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
     'operationAccess.create'?: Validation;
     'operationAccess.distinct'?: Validation;
     'operationAccess.count'?: Validation;
-    'operationAccess.subs'?: SubRouteGuardOptions;
-}
-interface ModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
+    'operationAccess.basicList'?: Validation;
+    'operationAccess.advancedList'?: Validation;
+    'operationAccess.basicRead'?: Validation;
+    'operationAccess.advancedRead'?: Validation;
+    'operationAccess.basicCreate'?: Validation;
+    'operationAccess.advancedCreate'?: Validation;
+    'operationAccess.basicUpdate'?: Validation;
+    'operationAccess.advancedUpdate'?: Validation;
+    'operationAccess.basicUpsert'?: Validation;
+    'operationAccess.advancedUpsert'?: Validation;
+    'operationAccess.basicCount'?: Validation;
+    'operationAccess.advancedCount'?: Validation;
+    'operationAccess.basicDistinct'?: Validation;
+    'operationAccess.advancedDistinct'?: Validation;
+    'operationAccess.subs'?: Validation | SubRouteGuardOptions;
+}
+interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends DefaultModelRouterOptions<TModel> {
     modelName?: string;
     basePath?: string;
     /**
      * Update grants define assignment boundaries: authorized leaves preserve omitted
      * siblings; a whole-object/array grant permits replacement (no generic deep merge).
      * Send nested JSON; literal dotted client keys are not update operators.
+     * Basic/advanced keys are route guards in operationAccess, not field grants here.
+     */
+    permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel> | Extract<keyof TVirtuals, string>>;
+    /**
+     * Package-level computed fields ("virtuals", VIRT-01).
+     * Typed getter/descriptor/output generics per VIRT-00A D3: typed getters
+     * use a partial read-only persisted view for their scope, never
+     * `Record<string, unknown>` for a known model; untyped consumers keep an
+     * explicit loose fallback. Per-access records use `default` +
+     * `list`/`create`/`read`/`update` (NOT `delete`/`distinct`/`count`) and
+     * recursive embedded `sub` scopes mirroring
+     * `permissionSchema.<field>.sub`. Inapplicable registered names stay
+     * virtual (never persisted). Mutable post-construction (not a build-time
+     * key); replacement swaps the frozen snapshot so in-flight planning keeps
+     * a coherent version.
+     *
+     * Getters run after `toObject()`/lean normalization (both lean and
+     * hydrated results compute), after internal document-permissions
+     * computation, and before `decorate`/`decorateAll`/tasks and final
+     * trimming. `dependsOn` fields are fetched internally even when the caller
+     * may not receive them, then stripped unless independently selected and
+     * 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.
+     *
+     * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
+     * ```ts
+     * import acl from '@web-ts-toolkit/access-router';
+     * 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}`;
+     *       },
+     *     },
+     *   },
+     * });
+     * // Selected output: { name: string; fullAddress?: string } — virtual is optional.
+     * void router;
+     * ```
      */
-    permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
+    virtuals?: ModelVirtuals<TModel, TVirtuals>;
     alwaysSelectFields?: string[];
     docPermissions?: DocPermissions | ModelDocPermissionsHook;
+    /**
+     * Allowlist of `docPermissions`-hook keys exposed in API responses.
+     * Enforcement always uses the full hook map; only serialization is reduced,
+     * after all grant computations and decorate hooks have run. `_view`/`_edit`
+     * are always kept. `undefined` (default) exposes everything (current
+     * behavior); any array (including `[]`) exposes `_view`/`_edit` plus the
+     * listed keys. Note `guard()` conditions on stripped doc-level keys fail
+     * closed — allowlist any key a custom route guard evaluates.
+     */
+    exposedDocPermissionKeys?: string[];
     baseFilter?: ModelBaseFilterHook | Record<string, ModelBaseFilterHook>;
     overrideFilter?: ModelOverrideFilterHook | Record<string, ModelOverrideFilterHook>;
     decorate?: ModelHook<TModel> | Record<string, ModelHook<TModel>>;
@@ -1793,9 +2651,16 @@ interface DataRouterOptions<TData = unknown> {
     resolveIdFilter?: DataIdentifierHook<TData>;
     parentPath?: string;
     queryRouteSegment?: string;
+    /**
+     * Live data-route guards: list/read plus basicList/advancedList/basicRead/advancedRead.
+     * Only undefined variants inherit their base; false denies with HTTP 401 while
+     * routes remain registered. Data never inherits model defaults. The broader
+     * legacy operation-rule object and scalar Validation shorthand remain accepted.
+     */
     operationAccess?: Validation | OperationAccess;
     dataName?: string;
     basePath?: string;
+    /** Base-operation field grants, independent of operationAccess's basic/advanced route guards. */
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TData>>;
     baseFilter?: DataBaseFilterHook | Record<string, DataBaseFilterHook>;
     overrideFilter?: DataOverrideFilterHook | Record<string, DataOverrideFilterHook>;
@@ -1803,7 +2668,7 @@ interface DataRouterOptions<TData = unknown> {
     decorateAll?: DataListHook<TData> | Record<string, DataListHook<TData>>;
     requestSchemas?: DataRequestSchemas;
 }
-interface ExtendedModelRouterOptions<TModel = unknown> extends ModelRouterOptions<TModel>, ExtendedDefaultModelRouterOptions<TModel> {
+interface ExtendedModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends ModelRouterOptions<TModel, TVirtuals>, ExtendedDefaultModelRouterOptions<TModel> {
     'alwaysSelectFields.default'?: string[];
     'alwaysSelectFields.list'?: string[];
     'alwaysSelectFields.create'?: string[];
@@ -1885,8 +2750,29 @@ interface ExtendedModelRouterOptions<TModel = unknown> extends ModelRouterOption
     'defaults.publicReadOptions'?: PublicReadOptions;
     'defaults.publicUpdateArgs'?: PublicUpdateArgs;
     'defaults.publicUpdateOptions'?: PublicUpdateOptions;
+    /**
+     * Virtual dotted keys (VIRT-01): `virtuals`, `virtuals.<name>`,
+     * `virtuals.<name>.<access>`, `virtuals.<field>.sub...` (recursive).
+     * The template fallback preserves typed getter doc views for known
+     * models so unknown persisted getter fields fail (including dotted
+     * setters); embedded `sub` records stay structurally loose here and are
+     * fully validated at runtime against the receiving Mongoose schema +
+     * child scopes.
+     */
+    [key: `virtuals.${string}`]: ModelVirtuals<TModel, TVirtuals>[Extract<keyof TVirtuals, string>] | ModelVirtualDescriptor<TModel, unknown> | ModelVirtualGetter<TModel, unknown> | {
+        sub?: Record<string, unknown>;
+    } | Record<string, ModelVirtualDescriptor<Record<string, unknown>, unknown> | ModelVirtualGetter<Record<string, unknown>, unknown> | {
+        sub?: unknown;
+    }>;
 }
 interface ExtendedDataRouterOptions<TData = unknown> extends DataRouterOptions<TData> {
+    'operationAccess.default'?: Validation;
+    'operationAccess.list'?: Validation;
+    'operationAccess.read'?: Validation;
+    'operationAccess.basicList'?: Validation;
+    'operationAccess.advancedList'?: Validation;
+    'operationAccess.basicRead'?: Validation;
+    'operationAccess.advancedRead'?: Validation;
     'requestSchemas.advancedList'?: RequestSchema;
     'requestSchemas.advancedReadFilter'?: RequestSchema;
     'requestSchemas.advancedRead'?: RequestSchema;
@@ -1993,4 +2879,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 DistinctArgs as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CreateArgs as D, type CreateOptions as E, type CreateQueryInput as F, CustomHeaders as G, DATA_MIDDLEWARE as H, type DataBaseFilterHook as I, type DataFilter as J, type DataFindArgs as K, type DataFindOneArgs as L, type DataFindOneOptions as M, type DataFindOptions as N, type DataHook as O, type DataHookContext as P, type DataIdentifierHook as Q, type DataListHook as R, type DataOverrideFilterHook as S, type DataRequest as T, type DataRequestSchemas as U, type DataRouterOptions as V, type DecorateAccess as W, type DecorateAllAccess as X, type DeepFieldPath as Y, type DefaultModelRouterOptions as Z, type Defaults as _, type AccessRouterFieldKey as a, type PublicReadOptions as a$, type DistinctBody as a0, type DocPermissionsAccess as a1, type ErrorResult as a2, type ExistsOptions as a3, type ExtendedDataRouterOptions as a4, type ExtendedDefaultModelRouterOptions as a5, type ExtendedModelRouterOptions as a6, type Filter as a7, FilterOperator as a8, type FindAccess as a9, type ModelDocument as aA, type ModelDocumentHook as aB, type ModelHook as aC, type ModelHookContext as aD, type ModelIdentifierHook as aE, type ModelListHook as aF, type ModelOverrideFilterHook as aG, type ModelRequest as aH, type ModelRouterOptions as aI, type ModelValidateHook as aJ, PERMISSIONS as aK, PERMISSION_KEYS as aL, type ParentRef as aM, type PathValue as aN, type PermissionSchema as aO, type Populate as aP, type PopulateAccess as aQ, type PrepareAccess as aR, type Projection as aS, type PublicCreateArgs as aT, type PublicCreateOptions as aU, type PublicErrorResult as aV, type PublicListArgs as aW, type PublicListOptions as aX, type PublicListResult as aY, type PublicOutput as aZ, type PublicReadArgs as a_, type FindArgs as aa, type FindByIdArgs as ab, type FindByIdOptions as ac, type FindOneArgs as ad, type FindOneOptions as ae, type FindOptions as af, type GlobalOptions as ag, type GlobalPermissionValue as ah, type GuardHook as ai, type IdentifierHook as aj, type Include as ak, type IoTsContextEntryLike as al, type IoTsDecodeErrorLike as am, type IoTsDecoderLike as an, type JoiSchemaLike as ao, type JoiValidationErrorDetailLike as ap, type KeyValueProjection as aq, type LegacyInclude as ar, type ListQueryInput as as, type ListResult as at, MIDDLEWARE as au, type MaybePromise as av, type ModelBaseFilterHook as aw, type ModelChangeHook as ax, type ModelDeleteHook as ay, type ModelDocPermissionsHook as az, type AccessRouterLogger as b, type SubdocumentBulkRecord as b$, type PublicServiceResult as b0, type PublicSingleResult as b1, type PublicUpdateArgs as b2, type PublicUpdateOptions as b3, type PublicUpsertArgs as b4, type PublicUpsertOptions as b5, type ReadQueryInput as b6, type Request as b7, type RequestSchemaAdapter as b8, type RequestSchemaFailure as b9, type RootModelUpdateQueryEntry as bA, type RootModelUpsertQueryEntry as bB, type RootOperationResult as bC, type RootQueryEntry as bD, type RootRouterOptions as bE, type RootSubOperation as bF, type RootTarget as bG, type RouteGuardAccess as bH, type SelectAccess as bI, type SelectedPopulatedPublicOutput as bJ, type SelectedPublicOutput as bK, type ServiceResult as bL, type SingleResult as bM, type Sort as bN, type SortOrder as bO, type StandardSchemaFailure as bP, type StandardSchemaInferOutput as bQ, type StandardSchemaIssue as bR, type StandardSchemaPathSegment as bS, type StandardSchemaResult as bT, type StandardSchemaSuccess as bU, type StandardSchemaV1 as bV, StatusCodes as bW, type SubListBody as bX, type SubPopulate as bY, type SubQueryEntry as bZ, type SubReadBody as b_, type RequestSchemaIssue as ba, type RequestSchemaLike as bb, type RequestSchemaOptions as bc, type RequestSchemaResult as bd, type RequestSchemaSuccess as be, type RequestSchemaValidator as bf, type RequestSchemas as bg, type RootDataListQueryEntry as bh, type RootDataOperation as bi, type RootDataReadByFilterQueryEntry as bj, type RootDataReadByIdQueryEntry as bk, type RootModelCountQueryEntry as bl, type RootModelCreateQueryEntry as bm, type RootModelDeleteQueryEntry as bn, type RootModelDistinctQueryEntry as bo, type RootModelListQueryEntry as bp, type RootModelNewQueryEntry as bq, type RootModelOperation as br, type RootModelReadByFilterQueryEntry as bs, type RootModelReadByIdQueryEntry as bt, type RootModelSubBulkUpdateQueryEntry as bu, type RootModelSubCreateQueryEntry as bv, type RootModelSubDeleteQueryEntry as bw, type RootModelSubListQueryEntry as bx, type RootModelSubReadQueryEntry as by, type RootModelSubUpdateQueryEntry as bz, type AccessRouterRequest as c, type OpenApiResponses as c$, type SubdocumentBulkUpdateInput as c0, type SubdocumentCreateInput as c1, type SubdocumentCreateOptions as c2, type SubdocumentId as c3, type SubdocumentListOptions as c4, type SubdocumentName as c5, type SubdocumentParentArgs as c6, type SubdocumentParentOptions as c7, type SubdocumentReadOptions as c8, type SubdocumentRecord as c9, type YupValidationErrorLike as cA, defineRequestSchema as cB, fromAjv as cC, fromArkType as cD, fromIoTs as cE, fromJoi as cF, fromStandardSchema as cG, fromSuperstruct as cH, fromValibot as cI, fromVine as cJ, fromYup as cK, fromZod as cL, parseBody as cM, parseBodyWithSchema as cN, parseNestedBodyWithSchema as cO, parsePathParam as cP, parseQuery as cQ, AccessRuntime as cR, DataService as cS, Service as cT, PublicService as cU, type OpenApiRouterOptions as cV, type OpenApiRegistryOptions as cW, type OpenApiRouteDescriptor as cX, type OpenApiDocumentOptions as cY, type OpenApiParameter as cZ, type OpenApiSchema as c_, type SuperstructFailureLike as ca, type SuperstructValidateLike as cb, type Task as cc, type TaskType as cd, type TransformAccess as ce, type TypedFilter as cf, type UpdateByIdArgs as cg, type UpdateByIdOptions as ch, type UpdateOneArgs as ci, type UpdateOneOptions as cj, type UpdateQueryInput as ck, type UpsertArgs as cl, type UpsertOptions as cm, type UpsertQueryInput as cn, type ValibotIssueLike as co, type ValibotPathItemLike as cp, type ValibotSafeParseLike as cq, type ValibotSafeParseResult as cr, type ValidateAccess as cs, type ValidateRule as ct, type Validation as cu, type ValidationError as cv, type VineValidationErrorLike as cw, type VineValidationMessageLike as cx, type VineValidatorLike as cy, type YupSchemaLike as cz, type AccessRouterRequestExtensions as d, type AccessRouterPermissionMap as d0, type AccessRouterPermissions as d1, type OpenApiMethod as d2, type Permissions as d3, defaultRuntime as d4, type AdvancedCreateBody as e, 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 ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CorrelatedCountInclude as s, type CorrelatedFilter as t, type CorrelatedInclude as u, type CorrelatedIncludeArgs as v, type CorrelatedListInclude as w, type CorrelatedReadByFilterInclude as x, type CorrelatedReadByIdInclude as y, type CountBody as z };
+export { type DistinctArgs as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CreateArgs as D, type CreateOptions as E, type CreateQueryInput as F, CustomHeaders as G, DATA_MIDDLEWARE as H, type DataBaseFilterHook as I, type DataFilter as J, type DataFindArgs as K, type DataFindOneArgs as L, type DataFindOneOptions as M, type DataFindOptions as N, type DataHook as O, type DataHookContext as P, type DataIdentifierHook as Q, type DataListHook as R, type DataOverrideFilterHook as S, type DataRequest as T, type DataRequestSchemas as U, type DataRouterOptions as V, type DecorateAccess as W, type DecorateAllAccess as X, type DeepFieldPath as Y, type DefaultModelRouterOptions as Z, type Defaults as _, type AccessRouterFieldKey as a, type Populate as a$, type DistinctBody as a0, type DocPermissionsAccess as a1, type ErrorResult as a2, type ExistsOptions as a3, type ExtendedDataRouterOptions as a4, type ExtendedDefaultModelRouterOptions as a5, type ExtendedModelRouterOptions as a6, type FieldOperationAccess as a7, type Filter as a8, FilterOperator as a9, type ModelDocPermissionsHook as aA, type ModelDocument as aB, type ModelDocumentHook as aC, type ModelHook as aD, type ModelHookContext as aE, type ModelIdentifierHook as aF, type ModelListHook as aG, type ModelOverrideFilterHook as aH, type ModelRequest as aI, type ModelRouterOptions as aJ, type ModelValidateHook as aK, type ModelVirtualAccess as aL, type ModelVirtualAccessRecord as aM, type ModelVirtualContext as aN, type ModelVirtualDescriptor as aO, type ModelVirtualDoc as aP, type ModelVirtualGetter as aQ, type ModelVirtualLeaf as aR, type ModelVirtualRecordAccess as aS, type ModelVirtuals as aT, type OperationAccess as aU, PERMISSIONS as aV, PERMISSION_KEYS as aW, type PairedRouteAccess as aX, type ParentRef as aY, type PathValue as aZ, type PermissionSchema as a_, type FindAccess as aa, type FindArgs as ab, type FindByIdArgs as ac, type FindByIdOptions as ad, type FindOneArgs as ae, type FindOneOptions as af, type FindOptions as ag, type GlobalOptions as ah, type GlobalPermissionValue as ai, type GuardHook as aj, type IdentifierHook as ak, type Include as al, type IoTsContextEntryLike as am, type IoTsDecodeErrorLike as an, type IoTsDecoderLike as ao, type JoiSchemaLike as ap, type JoiValidationErrorDetailLike as aq, type KeyValueProjection as ar, type LegacyInclude as as, type ListQueryInput as at, type ListResult as au, MIDDLEWARE as av, type MaybePromise as aw, type ModelBaseFilterHook as ax, type ModelChangeHook as ay, type ModelDeleteHook as az, type AccessRouterLogger as b, type SingleResult as b$, type PopulateAccess as b0, type PrepareAccess as b1, type Projection as b2, type PublicCreateArgs as b3, type PublicCreateOptions as b4, type PublicErrorResult as b5, type PublicListArgs as b6, type PublicListOptions as b7, type PublicListResult as b8, type PublicOutput as b9, type RootModelDistinctQueryEntry as bA, type RootModelListQueryEntry as bB, type RootModelNewQueryEntry as bC, type RootModelOperation as bD, type RootModelReadByFilterQueryEntry as bE, type RootModelReadByIdQueryEntry as bF, type RootModelSubBulkUpdateQueryEntry as bG, type RootModelSubCreateQueryEntry as bH, type RootModelSubDeleteQueryEntry as bI, type RootModelSubListQueryEntry as bJ, type RootModelSubReadQueryEntry as bK, type RootModelSubUpdateQueryEntry as bL, type RootModelUpdateQueryEntry as bM, type RootModelUpsertQueryEntry as bN, type RootOperationResult as bO, type RootQueryEntry as bP, type RootRouterOptions as bQ, type RootSubOperation as bR, type RootTarget as bS, type RouteBaseAccess as bT, type RouteGuardAccess as bU, type RouteVariant as bV, type RouteVariantAccess as bW, type SelectAccess as bX, type SelectedPopulatedPublicOutput as bY, type SelectedPublicOutput as bZ, type ServiceResult as b_, type PublicReadArgs as ba, type PublicReadOptions as bb, type PublicServiceResult as bc, type PublicSingleResult as bd, type PublicUpdateArgs as be, type PublicUpdateOptions as bf, type PublicUpsertArgs as bg, type PublicUpsertOptions as bh, type ReadQueryInput as bi, type Request as bj, type RequestSchemaAdapter as bk, type RequestSchemaFailure as bl, type RequestSchemaIssue as bm, type RequestSchemaLike as bn, type RequestSchemaOptions as bo, type RequestSchemaResult as bp, type RequestSchemaSuccess as bq, type RequestSchemaValidator as br, type RequestSchemas as bs, type RootDataListQueryEntry as bt, type RootDataOperation as bu, type RootDataReadByFilterQueryEntry as bv, type RootDataReadByIdQueryEntry as bw, type RootModelCountQueryEntry as bx, type RootModelCreateQueryEntry as by, type RootModelDeleteQueryEntry as bz, type AccessRouterRequest as c, fromValibot as c$, type Sort as c0, type SortOrder as c1, type StandardSchemaFailure as c2, type StandardSchemaInferOutput as c3, type StandardSchemaIssue as c4, type StandardSchemaPathSegment as c5, type StandardSchemaResult as c6, type StandardSchemaSuccess as c7, type StandardSchemaV1 as c8, StatusCodes as c9, type UpdateOneOptions as cA, type UpdateQueryInput as cB, type UpsertArgs as cC, type UpsertOptions as cD, type UpsertQueryInput as cE, type ValibotIssueLike as cF, type ValibotPathItemLike as cG, type ValibotSafeParseLike as cH, type ValibotSafeParseResult as cI, type ValidateAccess as cJ, type ValidateRule as cK, type Validation as cL, type ValidationError as cM, type VineValidationErrorLike as cN, type VineValidationMessageLike as cO, type VineValidatorLike as cP, type VirtualSubModel as cQ, type WithVirtuals as cR, type YupSchemaLike as cS, type YupValidationErrorLike as cT, defineRequestSchema as cU, fromAjv as cV, fromArkType as cW, fromIoTs as cX, fromJoi as cY, fromStandardSchema as cZ, fromSuperstruct as c_, type SubListBody as ca, type SubOperationAccess as cb, type SubPopulate as cc, type SubQueryEntry as cd, type SubReadBody as ce, type SubRouteGuardOptions as cf, type SubdocumentBulkRecord as cg, type SubdocumentBulkUpdateInput as ch, type SubdocumentCreateInput as ci, type SubdocumentCreateOptions as cj, type SubdocumentId as ck, type SubdocumentListOptions as cl, type SubdocumentName as cm, type SubdocumentParentArgs as cn, type SubdocumentParentOptions as co, type SubdocumentReadOptions as cp, type SubdocumentRecord as cq, type SuperstructFailureLike as cr, type SuperstructValidateLike as cs, type Task as ct, type TaskType as cu, type TransformAccess as cv, type TypedFilter as cw, type UpdateByIdArgs as cx, type UpdateByIdOptions as cy, type UpdateOneArgs as cz, type AccessRouterRequestExtensions as d, fromVine as d0, fromYup as d1, fromZod as d2, parseBody as d3, parseBodyWithSchema as d4, parseNestedBodyWithSchema as d5, parsePathParam as d6, parseQuery as d7, AccessRuntime as d8, DataService as d9, Service as da, PublicService as db, type OpenApiRouterOptions as dc, type OpenApiRegistryOptions as dd, type OpenApiRouteDescriptor as de, type OpenApiDocumentOptions as df, type OpenApiParameter as dg, type OpenApiSchema as dh, type OpenApiResponses as di, type AccessRouterPermissionMap as dj, type AccessRouterPermissions as dk, type OpenApiMethod as dl, type Permissions as dm, defaultRuntime as dn, type AdvancedCreateBody as e, 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 ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CorrelatedCountInclude as s, type CorrelatedFilter as t, type CorrelatedInclude as u, type CorrelatedIncludeArgs as v, type CorrelatedListInclude as w, type CorrelatedReadByFilterInclude as x, type CorrelatedReadByIdInclude as y, type CountBody as z };