@web-ts-toolkit/access-router 0.44.0 → 0.46.0

package/{parsers-B5dbVmjm.d.mts → parsers-BKF7VX2-.d.mts}

@@ -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;
@@ -53,18 +54,46 @@ 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>;
     distinct(field: string, args?: DistinctArgs<TModel>): Promise<ListResult<unknown> | ErrorResult>;
     count(filter: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<number> | ErrorResult>;
+    /**
+     * Trusted count for correlated includes (ACI-03): the caller already
+     * resolved parent references, revalidated expanded operands, and applied
+     * explicit `count` access via `genFilter`. This skips client-filter
+     * 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;
@@ -86,8 +115,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>;
@@ -121,6 +170,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;
@@ -237,12 +291,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;
@@ -440,21 +514,232 @@ 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';
+interface CorrelatedExecState {
+    totalQueries: number;
+    scheduler: RequestConcurrencyScheduler;
+}
 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[]>;
@@ -488,10 +773,14 @@ declare class Base<TModel = unknown> {
     protected throwClientRequestError(code: ErrorResult['code'], detail: string): never;
     protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation): Promise<PublicService<unknown>>;
     protected processInclude(include: Include | Include[]): {
-        includes: Include[];
+        includes: LegacyInclude[];
+        correlatedIncludes: CorrelatedInclude[];
         includeLocalFields: string[];
         includePaths: string[];
+        correlatedReferenceFields: string[];
     };
+    private validateIncludeOutputPath;
+    private assertIncludeOutputPaths;
     private getForeignKeyValues;
     private getForeignKey;
     private buildForeignKeyIndex;
@@ -503,6 +792,13 @@ declare class Base<TModel = unknown> {
     private includeDocsRead;
     private includeDocsList;
     private includeDocsCount;
+    protected getCorrelatedExecState(): CorrelatedExecState;
+    protected claimCorrelatedQuerySlot(): void;
+    private sanitizeCorrelatedArgs;
+    protected includeCorrelatedDocs<TDoc>(docs: TDoc[], correlatedIncludes: CorrelatedInclude[], snapshots?: unknown[], depth?: number): Promise<TDoc[]>;
+    private includeCorrelatedRead;
+    private includeCorrelatedList;
+    private includeCorrelatedCount;
     protected parseClientData<TValue>(filter: TValue, scheduler?: RequestConcurrencyScheduler, scheduled?: boolean): Promise<TValue>;
     private handleSubQuery;
     private handleDate;
@@ -690,6 +986,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;
 }
 
@@ -702,6 +999,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;
     };
@@ -709,6 +1007,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>;
     };
 }
@@ -839,9 +1138,21 @@ type TypedFilterObject<T> = {
 };
 type TypedFilter<T> = false | TypedFilterObject<WithDefaultId<T>>;
 type Filter<T = unknown> = IsUnknown<T> extends true ? LooseFilter : TypedFilter<T>;
-interface Include {
+/**
+ * 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;
@@ -849,6 +1160,62 @@ interface Include {
     args?: unknown;
     options?: unknown;
 }
+/**
+ * Explicit structural marker referencing a field of the immediate parent
+ * document (ACI-01 D2.1). Recognized only in filter/id value positions of
+ * correlated includes; magic `$field` strings are never markers.
+ */
+interface ParentRef {
+    $parent: string;
+}
+/** Filter template for correlated includes; values may carry {@link ParentRef} markers. */
+type CorrelatedFilter = Record<string, unknown>;
+interface CorrelatedIncludeArgs {
+    select?: Projection;
+    sort?: Sort;
+    skip?: number | string;
+    limit?: number | string;
+    page?: number | string;
+    pageSize?: number | string;
+    include?: Include | Include[];
+}
+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>;
+}
+/** Identifier read: exactly one of `id` / `filter` must be present. */
+interface CorrelatedReadByIdInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    id: string | ParentRef;
+    filter?: never;
+}
+interface CorrelatedReadByFilterInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedListInclude extends CorrelatedIncludeBase {
+    op: 'list';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedCountInclude extends CorrelatedIncludeBase {
+    op: 'count';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
+/** Related output cannot overwrite authorization metadata at any supported nested level. */
+type Include = LegacyInclude | CorrelatedInclude;
 type FindAccess = 'list' | 'read';
 type PopulateAccess = 'list' | 'read';
 interface Populate {
@@ -1056,10 +1423,11 @@ interface SubQueryEntry {
         compact?: boolean;
     };
 }
+type TaskType = 'COPY_AND_DEPOPULATE' | 'COPY' | 'MOVE' | 'SLICE' | 'COUNT' | 'MASK' | string;
 interface Task {
-    type: string;
+    type: TaskType;
     args: unknown;
-    options: Record<string, unknown>;
+    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>;
@@ -1144,6 +1512,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;
@@ -1162,6 +1531,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;
@@ -1181,14 +1551,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;
 }
 
@@ -1306,6 +1680,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 {
@@ -1330,6 +1705,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;
@@ -1356,6 +1732,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;
@@ -1364,7 +1745,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>;
@@ -1549,11 +1942,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>;
 /**
@@ -1575,4 +1979,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 ExtendedModelRouterOptions as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, DATA_MIDDLEWARE as D, type DataFindOneArgs as E, type DataFindOneOptions as F, type DataFindOptions as G, type DataHook as H, type DataHookContext as I, type DataIdentifierHook as J, type DataListHook as K, type DataOverrideFilterHook as L, type DataRequest as M, type DataRequestSchemas as N, type DataRouterOptions as O, type DecorateAccess as P, type DecorateAllAccess as Q, type DeepFieldPath as R, type DefaultModelRouterOptions as S, type Defaults as T, type DistinctArgs as U, type DistinctBody as V, type DocPermissionsAccess as W, type ErrorResult as X, type ExistsOptions as Y, type ExtendedDataRouterOptions as Z, type ExtendedDefaultModelRouterOptions as _, type AccessRouterFieldKey as a, type RequestSchemaAdapter as a$, type Filter as a0, FilterOperator as a1, type FindAccess as a2, type FindArgs as a3, type FindByIdArgs as a4, type FindByIdOptions as a5, type FindOneArgs as a6, type FindOneOptions as a7, type FindOptions as a8, type GlobalOptions as a9, type ModelRouterOptions as aA, type ModelValidateHook as aB, PERMISSIONS as aC, PERMISSION_KEYS as aD, type PathValue as aE, type PermissionSchema as aF, type Populate as aG, type PopulateAccess as aH, type PrepareAccess as aI, type Projection as aJ, type PublicCreateArgs as aK, type PublicCreateOptions as aL, type PublicErrorResult as aM, type PublicListArgs as aN, type PublicListOptions as aO, type PublicListResult as aP, type PublicOutput as aQ, type PublicReadArgs as aR, type PublicReadOptions as aS, type PublicServiceResult as aT, type PublicSingleResult as aU, type PublicUpdateArgs as aV, type PublicUpdateOptions as aW, type PublicUpsertArgs as aX, type PublicUpsertOptions as aY, type ReadQueryInput as aZ, type Request as a_, type GlobalPermissionValue as aa, type GuardHook as ab, type IdentifierHook as ac, type Include as ad, type IoTsContextEntryLike as ae, type IoTsDecodeErrorLike as af, type IoTsDecoderLike as ag, type JoiSchemaLike as ah, type JoiValidationErrorDetailLike as ai, type KeyValueProjection as aj, type ListQueryInput as ak, type ListResult as al, MIDDLEWARE as am, type MaybePromise as an, type ModelBaseFilterHook as ao, type ModelChangeHook as ap, type ModelDeleteHook as aq, type ModelDocPermissionsHook as ar, type ModelDocument as as, type ModelDocumentHook as at, type ModelHook as au, type ModelHookContext as av, type ModelIdentifierHook as aw, type ModelListHook as ax, type ModelOverrideFilterHook as ay, type ModelRequest as az, type AccessRouterLogger as b, type SubdocumentReadOptions as b$, type RequestSchemaFailure as b0, type RequestSchemaIssue as b1, type RequestSchemaLike as b2, type RequestSchemaOptions as b3, type RequestSchemaResult as b4, type RequestSchemaSuccess as b5, type RequestSchemaValidator as b6, type RequestSchemas as b7, type RootDataListQueryEntry as b8, type RootDataOperation as b9, type SelectedPopulatedPublicOutput as bA, type SelectedPublicOutput as bB, type ServiceResult as bC, type SingleResult as bD, type Sort as bE, type SortOrder as bF, type StandardSchemaFailure as bG, type StandardSchemaInferOutput as bH, type StandardSchemaIssue as bI, type StandardSchemaPathSegment as bJ, type StandardSchemaResult as bK, type StandardSchemaSuccess as bL, type StandardSchemaV1 as bM, StatusCodes as bN, type SubListBody as bO, type SubPopulate as bP, type SubQueryEntry as bQ, type SubReadBody as bR, type SubdocumentBulkRecord as bS, type SubdocumentBulkUpdateInput as bT, type SubdocumentCreateInput as bU, type SubdocumentCreateOptions as bV, type SubdocumentId as bW, type SubdocumentListOptions as bX, type SubdocumentName as bY, type SubdocumentParentArgs as bZ, type SubdocumentParentOptions as b_, type RootDataReadByFilterQueryEntry as ba, type RootDataReadByIdQueryEntry as bb, type RootModelCountQueryEntry as bc, type RootModelCreateQueryEntry as bd, type RootModelDeleteQueryEntry as be, type RootModelDistinctQueryEntry as bf, type RootModelListQueryEntry as bg, type RootModelNewQueryEntry as bh, type RootModelOperation as bi, type RootModelReadByFilterQueryEntry as bj, type RootModelReadByIdQueryEntry as bk, type RootModelSubBulkUpdateQueryEntry as bl, type RootModelSubCreateQueryEntry as bm, type RootModelSubDeleteQueryEntry as bn, type RootModelSubListQueryEntry as bo, type RootModelSubReadQueryEntry as bp, type RootModelSubUpdateQueryEntry as bq, type RootModelUpdateQueryEntry as br, type RootModelUpsertQueryEntry as bs, type RootOperationResult as bt, type RootQueryEntry as bu, type RootRouterOptions as bv, type RootSubOperation as bw, type RootTarget as bx, type RouteGuardAccess as by, type SelectAccess as bz, type AccessRouterRequest as c, type SubdocumentRecord as c0, type SuperstructFailureLike as c1, type SuperstructValidateLike as c2, type Task as c3, type TransformAccess as c4, type TypedFilter as c5, type UpdateByIdArgs as c6, type UpdateByIdOptions as c7, type UpdateOneArgs as c8, type UpdateOneOptions as c9, fromYup as cA, fromZod as cB, parseBody as cC, parseBodyWithSchema as cD, parseNestedBodyWithSchema as cE, parsePathParam as cF, parseQuery as cG, DataService as cH, Service as cI, PublicService as cJ, type AccessRouterPermissionMap as cK, type AccessRouterPermissions as cL, type Permissions as cM, type UpdateQueryInput as ca, type UpsertArgs as cb, type UpsertOptions as cc, type UpsertQueryInput as cd, type ValibotIssueLike as ce, type ValibotPathItemLike as cf, type ValibotSafeParseLike as cg, type ValibotSafeParseResult as ch, type ValidateAccess as ci, type ValidateRule as cj, type Validation as ck, type ValidationError as cl, type VineValidationErrorLike as cm, type VineValidationMessageLike as cn, type VineValidatorLike as co, type YupSchemaLike as cp, type YupValidationErrorLike as cq, defineRequestSchema as cr, fromAjv as cs, fromArkType as ct, fromIoTs as cu, fromJoi as cv, fromStandardSchema as cw, fromSuperstruct as cx, fromValibot as cy, fromVine 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 CountBody as s, type CreateArgs as t, type CreateOptions as u, type CreateQueryInput as v, CustomHeaders as w, type DataBaseFilterHook as x, type DataFilter as y, type DataFindArgs 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 };