@web-ts-toolkit/access-router 0.45.0 → 0.47.0

package/{parsers-DppKW-Fd.d.ts → parsers-BidvJUu7.d.ts}

@@ -30,6 +30,7 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     defaults: Defaults<TModel>;
     protected baseFields: string[];
     protected baseFieldsExt: string[];
+    private readonly persist;
     findRawParentDoc(args: {
         filter: Filter<TModel>;
         select: string;
@@ -39,6 +40,7 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     protected createModelAdapter(modelName: string): any;
     protected getModelRouterOptions(modelName: string): ModelRouterOptions<TModel>;
     private asServiceHookContext;
+    private getEffectiveAllowedSortFields;
     private beginOp;
     private completeOp;
     constructor(req: ModelRequest, modelName: string);
@@ -53,13 +55,27 @@ declare class Service<TModel = unknown> extends Base<TModel> {
         skim?: boolean;
         includePermissions?: boolean;
     }): Promise<SingleResult<TModel>>;
+    /**
+     * Update at authorized policy paths: admitted leaves preserve omitted siblings;
+     * whole-authorized objects/arrays replace. Shared by updateById and existing-row
+     * upsert. Validation precedes trusted prepare output (not re-filtered); partial
+     * prepare containers preserve omissions. Transform retains explicit document-setter
+     * replacement authority. Send nested client JSON, not literal dotted update keys.
+     */
     updateOne(filter: Filter<TModel>, data: Record<string, unknown>, args?: UpdateOneArgs<TModel>, options?: UpdateOneOptions, decorate?: (doc: unknown, context?: ModelHookContext) => unknown): Promise<SingleResult<TModel> | ErrorResult>;
     updateById(id: string, data: Record<string, unknown>, args?: UpdateByIdArgs<TModel>, options?: UpdateByIdOptions, decorate?: (doc: unknown, context?: ModelHookContext) => unknown): Promise<SingleResult<TModel> | ErrorResult>;
     upsert(filter: Filter<TModel>, data: Record<string, unknown>, args?: UpsertArgs<TModel>, options?: UpsertOptions, decorate?: (doc: unknown, context?: ModelHookContext) => unknown): Promise<ServiceResult<TModel>>;
     delete(id: string): Promise<SingleResult<unknown> | ErrorResult>;
+    /**
+     * Check existence under row policy (read by default). Terminal false returns a
+     * Forbidden ErrorResult before adapter dispatch, in both includeId modes.
+     * Allowed matches return true or an `{ _id }` record; misses return false or null.
+     * Custom HTTP routes must map ErrorResult to their intended response status.
+     */
     exists(filter: Filter<TModel>, options: ExistsOptions & {
         includeId: true;
     }): Promise<SingleResult<unknown> | ErrorResult>;
+    /** Boolean existence; terminal false policy returns Forbidden, not successful false. */
     exists(filter: Filter<TModel>, options?: ExistsOptions): Promise<SingleResult<boolean> | ErrorResult>;
     protected isValidDistinctFieldName(field: unknown): boolean;
     protected authorizeDistinctField(field: string): Promise<ErrorResult | null>;
@@ -72,6 +88,13 @@ declare class Service<TModel = unknown> extends Base<TModel> {
      * validation and subquery parsing so substituted parent data stays inert.
      */
     countTrusted(authorizedFilter: Filter<TModel>): Promise<SingleResult<number> | ErrorResult>;
+    /**
+     * Group target document IDs by original parent-key aliases using one aggregate.
+     * Resolves the requested row policy (legacy count includes pass `count`), casts
+     * authorized filters/foreign operands with the target schema, and deduplicates IDs
+     * independently of pagination. Cast failures return BadRequest; false policy returns
+     * Forbidden. Casting does not execute countDocuments middleware/plugins.
+     */
     countByFieldValues(foreignField: string, values: unknown[], filter?: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<Map<string, Set<string>>> | ErrorResult>;
     getDocPermissions(doc: unknown): Record<string, unknown>;
     private resolveFindOneArgs;
@@ -93,8 +116,28 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     private getAccessibleIdSet;
     listSub(id: SubdocumentId, sub: SubdocumentName, options?: SubdocumentListOptions<TModel>): Promise<ListResult | ErrorResult>;
     readSub(id: SubdocumentId, sub: SubdocumentName, subId: SubdocumentId, options?: SubdocumentReadOptions): Promise<SingleResult | ErrorResult>;
+    /**
+     * Apply authorized policy-path updates, preserving protected siblings, then save.
+     * Output requires post-save parent read and subdocument read operation/row access;
+     * hidden output is successful `data: null` (direct/root-entry 200), not a failed write.
+     * Visible output uses read fields plus `_id`. Do not retry solely for null output.
+     */
     updateSub(id: SubdocumentId, sub: SubdocumentName, subId: SubdocumentId, data: Record<string, unknown>): Promise<SingleResult | ErrorResult>;
+    /**
+     * Save authorized targeted updates, then return readable targets in stored order.
+     * Requires parent/subdocument read access for output, not subdocument list access;
+     * uses read fields plus `_id`. Hidden output succeeds with `data: [], count: 0`
+     * (direct/root-entry 200); count measures visible rows, not all updated rows.
+     */
     bulkUpdateSub(id: SubdocumentId, sub: SubdocumentName, data: SubdocumentBulkUpdateInput | Record<string, unknown>): Promise<ListResult | ErrorResult>;
+    /**
+     * Append/prepend admitted rows, then return the visible full array (including when
+     * input is empty). Output requires post-save parent read and subdocument list AND
+     * read guards/row filters; fields use read projection plus `_id`.
+     * Hidden output succeeds with code `created`, `data: [], count: 0`
+     * (direct/root-entry 201). Visible count/order follow filtered stored rows.
+     * Empty output does not mean the write failed; addFirst is a service option.
+     */
     createSub(id: SubdocumentId, sub: SubdocumentName, data: SubdocumentCreateInput, options?: SubdocumentCreateOptions): Promise<ListResult | ErrorResult>;
     deleteSub(id: SubdocumentId, sub: SubdocumentName, subId: SubdocumentId): Promise<SingleResult | ErrorResult>;
     getParentDoc(id: SubdocumentId, sub: SubdocumentName, args?: SubdocumentParentArgs, options?: SubdocumentParentOptions): Promise<any>;
@@ -128,6 +171,11 @@ declare class PublicService<TModel = unknown> extends Service<TModel> {
         select?: TSelect;
         populate?: TPopulate;
     }, options?: PublicUpdateOptions): Promise<SingleResult<SelectedPopulatedPublicOutput<TModel, TSelect, TPopulate>> | 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.
+     */
     _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;
@@ -244,12 +292,32 @@ type AjvErrorObjectLike = {
     };
 };
 type AjvValidationErrorLike = {
-    errors?: ReadonlyArray<AjvErrorObjectLike> | null;
+    ajv: true;
+    validation: true;
+    errors: ReadonlyArray<AjvErrorObjectLike>;
 };
-type AjvValidatorLike<T = unknown> = {
-    (value: unknown): boolean | Promise<T | boolean>;
+/**
+ * Structural AJV contract; AJV is not a runtime dependency of access-router.
+ * Sync validators return boolean verdicts and expose mutable errors, snapshotted
+ * in the same turn. Tagged `$async: true` validators resolve with data (even
+ * false/true/null), or reject with AJV ValidationError diagnostics.
+ *
+ * Untagged promises/thenables are unsupported. Migrate async boolean-verdict
+ * wrappers to RequestSchemaValidator, or return data/reject validation errors
+ * and retain the literal `$async: true` tag. Real AJV ValidateFunction and
+ * AsyncValidateFunction overloads infer output via their type guard without casts; a synchronous
+ * structural validator's output type can be supplied explicitly to fromAjv<T>.
+ * AJV can type inline async schemas through a sync overload; an AsyncSchema-typed
+ * schema selects its async compile/compileAsync overload. Runtime uses the tag.
+ */
+type AjvValidatorLike<T = unknown> = ({
+    (value: unknown): boolean;
+    $async?: false;
+} | {
+    (value: unknown): PromiseLike<T>;
+    $async: true;
+}) & {
     errors?: ReadonlyArray<AjvErrorObjectLike> | null;
-    $async?: boolean;
 };
 type ValibotPathItemLike = {
     key?: unknown;
@@ -447,17 +515,221 @@ interface RequestComplexityOptions {
     maxBulkItems?: number;
     maxIncludeCount?: number;
     maxSubQueryCount?: number;
+    /**
+     * Defaults to 10. Shared request-and-runtime-owned ceiling on awaited model-service
+     * adapter/document persistence operations, including nested includes/root entries.
+     * Recursive orchestration holds no permit; internal map/run bounds are per call.
+     * One operation may issue multiple driver commands via Mongoose middleware/populate;
+     * direct DB/network calls from trusted application hooks are outside this ceiling.
+     * Not a process-wide connection limit or protection against competing edits.
+     */
     maxBulkConcurrency?: number;
     maxHookConcurrency?: number;
+    /** Cumulative correlated target executions per request/runtime (default 100); permit release does not refund this budget. */
     maxCorrelatedQueries?: number;
+    /** Correlated template nesting bound (default 5), independent of persistence concurrency. */
     maxCorrelatedDepth?: number;
 }
 
+type OpenApiMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+type OpenApiSchema = Record<string, unknown>;
+type OpenApiSchemaSource = unknown;
+type OpenApiParameter = {
+    name: string;
+    in: 'path' | 'query';
+    required?: boolean;
+    description?: string;
+    schema?: OpenApiSchema;
+};
+type OpenApiResponse = {
+    description: string;
+    content?: Record<string, {
+        schema: OpenApiSchema;
+    }>;
+};
+type OpenApiResponses = Record<string, OpenApiResponse>;
+type OpenApiRouteDescriptor = {
+    method: OpenApiMethod;
+    path: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    acl?: string;
+    deprecated?: boolean;
+    query?: OpenApiSchemaSource;
+    body?: OpenApiSchemaSource;
+    pathParams?: Record<string, OpenApiSchemaSource>;
+    responses?: OpenApiResponses;
+    /**
+     * When true, replaces an existing registration with the same method/path
+     * even when the descriptors differ. When false (default), conflicting
+     * registrations throw at registration time so consumers can detect
+     * accidental route shadowing.
+     */
+    allowReplace?: boolean;
+    /**
+     * When true, this exact descriptor is idempotent and registering the same
+     * method/path with an equivalent descriptor again is silently accepted.
+     * Differing re-registrations still throw unless {@link allowReplace} is set.
+     * Additionally, an idempotent descriptor may share its operationId with
+     * another idempotent descriptor mounted at a different path on the same
+     * registry, so reserved operations (e.g. the root batch route) can be
+     * exposed from multiple base paths without triggering strict-mode
+     * duplicate-operationId rejection.
+     */
+    idempotent?: boolean;
+};
+type OpenApiRegistryOptions = {
+    /**
+     * Throw when the same method/path is registered twice with differing
+     * descriptors, instead of silently replacing. Default: true (strict).
+     * The {@link AccessRuntime} registry is constructed in strict mode by
+     * default; construct {@link OpenApiRegistry} directly with
+     * `rejectConflicts: false` for legacy replacement semantics.
+     */
+    rejectConflicts?: boolean;
+    /**
+     * Throw when the same operationId is registered more than once, including
+     * when {@link OpenApiRouteDescriptor.allowReplace} is set. Default: true.
+     */
+    rejectDuplicateOperationIds?: boolean;
+};
+type OpenApiDocumentOptions = {
+    title: string;
+    version: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+};
+type OpenApiRouterOptions = Partial<OpenApiDocumentOptions> & {
+    jsonPath?: string;
+    docsPath?: string | false;
+    swaggerUiCssUrl?: string;
+    swaggerUiBundleUrl?: string;
+};
+
+type ModelReferenceMap = {
+    [key: string]: string | ModelReferenceMap;
+};
+declare class AccessRuntime {
+    private readonly allowGlobalModelLookup;
+    constructor(options?: {
+        allowGlobalModelLookup?: boolean;
+    });
+    private readonly globalOptions;
+    private readonly defaultModelOptions;
+    private readonly modelOptions;
+    private readonly modelJsonSchemas;
+    private readonly dataOptions;
+    private readonly modelRefs;
+    private readonly modelSubs;
+    private readonly modelAtts;
+    private readonly modelInstances;
+    private readonly openApiRegistry;
+    private openApiPathPrefix;
+    registerModelInstance<TModel>(modelName: string, model: mongoose.Model<TModel>): void;
+    hasModelInstance(modelName: string): boolean;
+    getModelInstance<TModel = unknown>(modelName: string): mongoose.Model<TModel> | null;
+    registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
+    /**
+     * Compose OpenAPI paths while synchronously constructing mounted routers.
+     * Prefixes apply before collision checks; prior descriptors and Express paths
+     * are unchanged. Nested calls compose and the prior scope is restored even on
+     * failure. The callback must finish registration synchronously (no async work).
+     */
+    withOpenApiPathPrefix<T>(prefix: string, build: () => T): T;
+    /**
+     * Enable strict OpenAPI collision detection for the remainder of this
+     * runtime's lifetime. After this call, conflicting method/path
+     * registrations and duplicate operationIds throw {@link OpenApiCollisionError}
+     * instead of silently replacing. Existing already-registered routes are
+     * not retroactively re-validated.
+     */
+    enableOpenApiCollisionDetection(): void;
+    getOpenApiRoutes(): OpenApiRouteDescriptor[];
+    clearOpenApiRoutes(): void;
+    getOpenApiSpec(info: OpenApiDocumentOptions): {
+        openapi: string;
+        info: Omit<OpenApiDocumentOptions, "servers">;
+        servers?: OpenApiDocumentOptions["servers"];
+        paths: Record<string, Record<string, {
+            [key: `x-${string}`]: unknown;
+            operationId?: string;
+            summary?: string;
+            description?: string;
+            tags?: string[];
+            deprecated?: boolean;
+            parameters?: OpenApiParameter[];
+            requestBody?: {
+                required?: boolean;
+                content: Record<string, {
+                    schema: OpenApiSchema;
+                }>;
+            };
+            responses: OpenApiResponses;
+        }>>;
+    };
+    createBootstrapSnapshot(): {
+        globalOptions: GlobalOptions;
+        defaultModelOptions: DefaultModelRouterOptions;
+        modelOptions: Record<string, ModelRouterOptions>;
+        dataOptions: Record<string, DataRouterOptions>;
+        modelInstances: Record<string, mongoose.Model<unknown>>;
+        modelJsonSchemas: Record<string, Record<string, unknown>>;
+        modelRefs: Record<string, ModelReferenceMap>;
+        modelSubs: Record<string, string[]>;
+        modelAtts: Record<string, string[]>;
+        openApi: {
+            routes: OpenApiRouteDescriptor[];
+            options: Required<OpenApiRegistryOptions>;
+        };
+    };
+    restoreBootstrapSnapshot(snapshot: ReturnType<AccessRuntime['createBootstrapSnapshot']>): void;
+    setGlobalOptions(options: GlobalOptions): void;
+    setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
+    getGlobalOptions(): GlobalOptions;
+    getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
+    setDefaultModelOptions(options: DefaultModelRouterOptions): void;
+    setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
+    getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
+    getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
+    private createModelOptions;
+    private getOrCreateModelOptions;
+    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];
+    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;
+    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];
+    getExactDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string): ExtendedDataRouterOptions<TData>[K];
+    getDataNames(): string[];
+    ensureModelMeta(modelName: string): void;
+    getModelRef(modelName: string, refPath: string): string | null;
+    getModelSub(modelName: string): string[];
+    getModelAtt(modelName: string): string[];
+}
+declare const defaultRuntime: AccessRuntime;
+
 declare class 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';
@@ -468,6 +740,7 @@ interface CorrelatedExecState {
 declare class Base<TModel = unknown> {
     protected req: ModelRequest;
     protected modelName: string;
+    protected readonly requestRuntime: AccessRuntime;
     constructor(req: ModelRequest, modelName: string);
     decorate<T>(doc: T, access: DecorateAccess, context: ModelHookContext): Promise<T>;
     decorateAll<T>(docs: T[], access: DecorateAllAccess, context: ModelHookContext): Promise<T[]>;
@@ -507,6 +780,8 @@ declare class Base<TModel = unknown> {
         includePaths: string[];
         correlatedReferenceFields: string[];
     };
+    private validateIncludeOutputPath;
+    private assertIncludeOutputPaths;
     private getForeignKeyValues;
     private getForeignKey;
     private buildForeignKeyIndex;
@@ -712,6 +987,7 @@ interface PublicReadOptions {
     populateAccess?: PopulateAccess;
     lean?: boolean;
     includePermissions?: boolean;
+    /** Retry an authorized read miss with list access (default true); requires list operation access. Forbidden/BadRequest never retry. */
     tryList?: boolean;
 }
 
@@ -724,6 +1000,7 @@ interface PublicUpsertArgs extends PublicUpdateArgs {
 }
 interface UpdateOneArgs<T = unknown> extends Omit<PublicUpdateArgs, 'select' | 'tasks'> {
     overrides?: {
+        /** Trusted replacement: nullish generates row policy; false returns Forbidden without filter generation or persistence. */
         filter?: Filter<T>;
         populate?: Populate[] | string;
     };
@@ -731,6 +1008,7 @@ interface UpdateOneArgs<T = unknown> extends Omit<PublicUpdateArgs, 'select' | '
 interface UpdateByIdArgs<T = unknown> extends Omit<UpdateOneArgs<T>, 'overrides'> {
     overrides?: {
         populate?: Populate[] | string;
+        /** Nullish resolves the identifier; false denies without ID/filter generation or persistence. Objects still receive row policy. */
         idFilter?: Filter<T>;
     };
 }
@@ -861,10 +1139,21 @@ type TypedFilterObject<T> = {
 };
 type TypedFilter<T> = false | TypedFilterObject<WithDefaultId<T>>;
 type Filter<T = unknown> = IsUnknown<T> extends true ? LooseFilter : TypedFilter<T>;
+/**
+ * Batched related-data join. Count uses one grouped aggregate per execution,
+ * counting distinct authorized target documents independently of list pagination.
+ * The target schema casts authorized filters/foreign operands; invalid casts return
+ * BadRequest. Query casting does not execute countDocuments middleware/plugins.
+ */
 interface LegacyInclude {
     mode?: 'legacy';
     model: string;
     op: 'list' | 'read' | 'count';
+    /**
+     * Output path; must not overlap the receiving model's documentPermissionField
+     * (equal, ancestor or descendant, including equivalent bracket paths).
+     * Nested receiving-model settings apply. Rejected before target persistence.
+     */
     path: string;
     filter?: Filter;
     localField: string;
@@ -895,6 +1184,11 @@ interface CorrelatedIncludeBase {
     mode: 'correlated';
     model: string;
     op: 'list' | 'read' | 'count';
+    /**
+     * Output-only field path. Must not equal, contain or descend from the receiving
+     * model's documentPermissionField (default `_permissions`). The include tree is
+     * preflighted before target persistence; violations return BadRequest.
+     */
     path: string;
     args?: CorrelatedIncludeArgs;
     options?: Record<string, never>;
@@ -921,6 +1215,7 @@ interface CorrelatedCountInclude extends CorrelatedIncludeBase {
     id?: never;
 }
 type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
+/** Related output cannot overwrite authorization metadata at any supported nested level. */
 type Include = LegacyInclude | CorrelatedInclude;
 type FindAccess = 'list' | 'read';
 type PopulateAccess = 'list' | 'read';
@@ -1218,6 +1513,7 @@ interface FindArgs<T = unknown> {
     page?: string | number;
     pageSize?: string | number;
     overrides?: {
+        /** Trusted replacement: nullish generates row policy; false returns Forbidden without filter generation or persistence. */
         filter?: Filter<T>;
         select?: Projection;
         populate?: Populate[] | string;
@@ -1236,6 +1532,7 @@ interface FindOneArgs<T = unknown> {
     populate?: Populate[] | string;
     include?: Include | Include[];
     overrides?: {
+        /** Trusted replacement: nullish generates row policy; false returns Forbidden without filter generation or persistence. */
         filter?: Filter<T>;
         select?: Projection;
         populate?: Populate[] | string;
@@ -1255,14 +1552,18 @@ interface FindByIdArgs<T = unknown> {
     overrides?: {
         select?: Projection;
         populate?: Populate[] | string;
+        /** Nullish resolves the identifier; false denies without ID/filter generation or persistence. Objects still receive row policy. */
         idFilter?: Filter<T>;
     };
 }
 interface FindByIdOptions extends FindOneOptions {
 }
 
+/** Terminal false row policy returns Forbidden in either result mode, before adapter dispatch. */
 interface ExistsOptions {
+    /** Row-policy access, defaulting to read. */
     access?: BaseFilterAccess;
+    /** Return an `{ _id }` record or null instead of a match/miss boolean. Denial is an ErrorResult, never a miss. */
     includeId?: boolean;
 }
 
@@ -1380,6 +1681,7 @@ interface RootRouterOptions {
     operationAccess?: Validation;
     maxBatchEntries?: number;
     maxOrderGroups?: number;
+    /** Whole root operations per order group; separate from requestComplexity.maxBulkConcurrency persistence admission. */
     maxConcurrentOperations?: number;
 }
 interface OperationAccess {
@@ -1404,6 +1706,7 @@ interface DocPermissions {
 }
 interface DefaultModelRouterOptions<TModel = unknown> {
     listHardLimit?: number;
+    /** Authorization metadata path (default `_permissions`); include output cannot equal, contain or descend from it. */
     documentPermissionField?: string;
     idParam?: string;
     idField?: string;
@@ -1413,6 +1716,19 @@ interface DefaultModelRouterOptions<TModel = unknown> {
     mutationRouteSegment?: string;
     operationAccess?: Validation | OperationAccess;
     modelPermissionPrefix?: string;
+    /**
+     * Extra fields allowed in `sort` regardless of `list`/`read` field policy.
+     * Merged as a union with permission-derived allowed fields (`id`/`_id` are
+     * always allowed). Does not grant output visibility, only sortability.
+     */
+    sortableFields?: string[];
+    /**
+     * When `true`, disallowed `sort` keys are omitted from the sort sent upstream
+     * (Mongoose) instead of returning `BadRequest`. Malformed sort syntax still
+     * returns `BadRequest`. If every key is stripped, no sort is applied.
+     * Defaults to `false` (strict: disallowed sort returns `BadRequest`).
+     */
+    stripDisallowedSort?: boolean;
 }
 interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
     'operationAccess.default'?: Validation;
@@ -1430,6 +1746,11 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
 interface ModelRouterOptions<TModel = unknown> 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.
+     */
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
     alwaysSelectFields?: string[];
     docPermissions?: DocPermissions | ModelDocPermissionsHook;
@@ -1438,7 +1759,19 @@ interface ModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions
     decorate?: ModelHook<TModel> | Record<string, ModelHook<TModel>>;
     decorateAll?: ModelListHook<TModel> | Record<string, ModelListHook<TModel>>;
     validate?: ValidateRule | ModelValidateHook | Record<string, ValidateRule | ModelValidateHook>;
+    /**
+     * Trusted model hook after validation of selected client data; output is not
+     * re-filtered and may add protected/server-only fields. During update, supplied
+     * children at partial policy ancestors apply without deleting omitted siblings.
+     * Explicit null/undefined can clear/unset a parent; no output means no assignments.
+     * Use transform document setters for deliberate whole-parent replacement.
+     */
     prepare?: ModelHook<TModel> | Record<string, ModelHook<TModel>>;
+    /**
+     * Trusted live-document hook after update assignment and before save. May replace
+     * protected state explicitly with document setters; do not blindly reintroduce
+     * unfiltered context.originalData. Model hooks are not added to subdocument writes.
+     */
     transform?: ModelDocumentHook<TModel> | Record<string, ModelDocumentHook<TModel>>;
     afterPersist?: ModelDocumentHook<TModel> | Record<string, ModelDocumentHook<TModel>>;
     onChange?: Record<string, ModelChangeHook>;
@@ -1623,11 +1956,22 @@ declare function fromJoi<TSchema extends JoiSchemaLike>(schema: TSchema): Reques
  * diagnostics via mutable `validator.errors`; those errors are snapshotted
  * synchronously before any suspension so concurrent same-turn validations do
  * not observe another input's diagnostics. Asynchronous AJV schemas
- * (`$async: true`) return a promise that resolves with validated data on
- * success or rejects with a `ValidationError` carrying an `errors` array on
- * failure; rejection-carried errors are normalized, while any other rejection
- * propagates unchanged as an operational exception.
+ * (`$async: true`) resolve with validated data, including false/true/null.
+ * AJV `ValidationError` rejections (`ajv: true`, `validation: true`, `errors`
+ * array) are normalized; other throws/rejections preserve operational identity.
+ * Async paths never read shared `validator.errors`.
+ *
+ * Untagged promises/thenables throw TypeError and are observed to prevent
+ * unhandled rejection. Migrate async boolean-verdict wrappers to a custom
+ * RequestSchemaValidator, or retain `$async: true` and return data/reject AJV
+ * validation errors. Sync validators must return boolean verdicts. Real AJV
+ * sync/async validators are accepted without casts; no runtime AJV import is used.
+ * Output is inferred from genuine AJV's type-guard overload (including its async
+ * subtype); structural async output is inferred from the promise. Pass TValue
+ * explicitly for a structural sync boolean validator without a type guard.
  */
+declare function fromAjv<TValue>(validator: AjvValidatorLike<TValue> & ((value: unknown) => value is TValue)): RequestSchemaValidator<TValue>;
+/** Adapts structural AJV validators with the same sync-verdict / tagged-async-data contract. */
 declare function fromAjv<TValue = unknown>(validator: AjvValidatorLike<TValue>): RequestSchemaValidator<TValue>;
 declare function fromValibot<TSchema, TOutput = unknown>(schema: TSchema, safeParse: ValibotSafeParseLike): RequestSchemaValidator<TOutput>;
 /**
@@ -1649,4 +1993,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 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, DataService as cR, Service as cS, PublicService as cT, type AccessRouterPermissionMap as cU, type AccessRouterPermissions as cV, type Permissions as cW, 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 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 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 };